Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YShymaPrXmc3KYRUg2HMSs
62 lines
3.6 KiB
Markdown
62 lines
3.6 KiB
Markdown
# WS-F — MCP server
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Status | Backlog |
|
|
| Owner | — |
|
|
| Phase | 2 (parallel) |
|
|
| Depends on | P0 to start (fakes, spike findings). A, B, C, D to finish. |
|
|
| Blocks | P3 |
|
|
| Owned files | `src/mcp/mod.rs`, `src/mcp/prompts.rs`, `src/mcp/resources.rs` |
|
|
|
|
## Goal
|
|
|
|
Build an `rmcp` Streamable HTTP server exposing the same data as REST, plus agent-facing context: instructions, rich descriptions, prompts and resources. `mcp::service(state)` returns the Tower service that P3 mounts at `/mcp`.
|
|
|
|
## Tasks
|
|
|
|
Tick these in [`TODO.md`](../../TODO.md).
|
|
|
|
- **F1** `TrackerService` holding `AppState`, with `#[tool_router]`. There are 8 tools (review R5):
|
|
- `list_systemd_units { state? }`
|
|
- `get_systemd_unit { name }`
|
|
- `list_systemd_timers {}`
|
|
- `get_journal_logs { unit?, priority?, lines }`
|
|
- `tail_journal { unit, seconds }`
|
|
- `list_containers {}`
|
|
- `get_container { name }`
|
|
- `get_container_logs { name, tail }`
|
|
- Parameter structs derive `Deserialize` and `JsonSchema`.
|
|
- **F2** `tail_journal` clamps `seconds` to `limits.max_follow_secs` and stops early at an entry cap, for example `limits.max_lines`. It returns whatever it collected and never streams indefinitely.
|
|
- **F3** `get_container_logs` clamps `tail` to `limits.max_tail`.
|
|
- **F4** `ServerHandler::get_info` sets server name/version, capabilities for tools, prompts and resources, and **instructions**. The instructions describe the workflow: start with failed units or unhealthy containers, then pull logs for the specific unit or container, and use timers to explain scheduled jobs.
|
|
- **F5** `#[tool(description = …)]` strings explain:
|
|
- active/sub states (`failed`, `activating`, `auto-restart`)
|
|
- journal priority numbers and names
|
|
- Docker health states (`starting`, `healthy`, `unhealthy`, `none`)
|
|
- **F6** Prompts in `prompts.rs`:
|
|
- `diagnose_unit { name }`: status, then recent err+ logs, then restart count, then a suggested next look.
|
|
- `container_health_report {}`: list, then unhealthy and restarting containers, then their logs.
|
|
- **F7** Resources in `resources.rs`: `systemd://units/failed` and `docker://containers`. Implement list and read, resolved live on each read, with no subscriptions (DEC-5).
|
|
- **F8** `mcp::service(state)` builds `StreamableHttpService::new(|| Ok(TrackerService::new(state.clone())), LocalSessionManager::default().into(), config)`. Apply Origin validation per DEC-8.
|
|
- **F9** Tests against fake sources:
|
|
- A snapshot of the tool list (names + schemas), so description changes are reviewed deliberately.
|
|
- Each tool's happy path.
|
|
- `AppError` maps to MCP errors.
|
|
- `tail_journal` respects its time cap.
|
|
|
|
## Done when
|
|
|
|
- F9 passes.
|
|
- With P3 wiring, Verification #4 passes. MCP Inspector at `http://localhost:9109/mcp` with a bearer header lists 8 tools, 2 prompts and 2 resources, and every tool returns data. Without the header the client receives 401.
|
|
|
|
## Notes
|
|
|
|
- Tool handlers must not duplicate logic from `api/`. Both call `sources/` directly.
|
|
- Keep tool output JSON-shaped (serialized DTOs) so agents can parse it, with a short text summary line where it helps.
|
|
|
|
## Log
|
|
|
|
- 2026-10-15: Card created.
|
|
- 2026-10-15: Implemented on branch `ws-f/mcp-server`. Prompts and resources are hand-written `ServerHandler` methods (helpers in `prompts.rs`/`resources.rs` are testable without a request context). `tail_journal` follows with a 10-entry backlog, stops at `max_follow_secs` or `max_lines`. Origin validation is enforced (`enforce_origin_validation`) with loopback and bind origins on `server.port` plus configured extras. Tests use real time (1s cap) because tokio `test-util` is not enabled in Cargo.toml.
|