Files
2026-10-19 14:14:29 -04:00

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 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:1984/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.
  • 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_journal notes reader-closed, shutdown and entry-cap stops; seconds defaults to 10 (schema 0-3600, server clamps to max_follow_secs). Log content is documented as untrusted data; diagnose_unit validates name. Notes: rmcp accepts requests with no Origin header, so bearer auth is the real gate; Origin/Host checks defend against browser DNS-rebinding. With server.bind = 0.0.0.0, LAN clients need their Host names in server.allowed_hosts (a startup warning is logged otherwise).