4.3 KiB
4.3 KiB
WS-F — MCP server
| Field | Value |
|---|---|
| Status | Done |
| 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.
- F1
TrackerServiceholdingAppState, 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
DeserializeandJsonSchema.
- F2
tail_journalclampssecondstolimits.max_follow_secsand stops early at an entry cap, for examplelimits.max_lines. It returns whatever it collected and never streams indefinitely. - F3
get_container_logsclampstailtolimits.max_tail. - F4
ServerHandler::get_infosets 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)
- active/sub states (
- 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/failedanddocker://containers. Implement list and read, resolved live on each read, with no subscriptions (DEC-5). - F8
mcp::service(state)buildsStreamableHttpService::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.
AppErrormaps to MCP errors.tail_journalrespects its time cap.
Done when
- F9 passes.
- With P3 wiring, Verification #4 passes. MCP Inspector at
http://localhost:1984/mcpwith 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 callsources/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-writtenServerHandlermethods (helpers inprompts.rs/resources.rsare testable without a request context).tail_journalfollows with a 10-entry backlog, stops atmax_follow_secsormax_lines. Origin validation is enforced (enforce_origin_validation) with loopback and bind origins onserver.portplus configured extras. Tests use real time (1s cap) because tokiotest-utilis not enabled in Cargo.toml. - 2026-10-15: Review fixes. Tool handlers return source errors as
CallToolResult::error(is_error) with an actionable message; prompts/resources keep protocol errors. Log tools return{entries, truncated, note}capped at 256 KiB.tail_journalnotes reader-closed, shutdown and entry-cap stops;secondsdefaults to 10 (schema 0-3600, server clamps tomax_follow_secs). Log content is documented as untrusted data;diagnose_unitvalidatesname. Notes: rmcp accepts requests with noOriginheader, so bearer auth is the real gate; Origin/Host checks defend against browser DNS-rebinding. Withserver.bind = 0.0.0.0, LAN clients need their Host names inserver.allowed_hosts(a startup warning is logged otherwise).