Files
skyg-linux-tracker/plan/phase-5-consolidator/ws-d-mcp.md
T
2026-10-19 16:43:35 -04:00

45 lines
2.9 KiB
Markdown

# WS-D: MCP surface
Part of [Phase 5: Consolidator](README.md). Contracts: [contracts.md](contracts.md) sections 3, 4 and 7.
| Field | Value |
|---|---|
| Status | Not started |
| Owner | |
| Depends on | B (and C2 client call shared, not duplicated). In practice: A0 for compiling; `PeerRegistry::get` from A0 (unhardened forwarder) until C2 lands; develop against `FakeTransport` + `registry_with` |
| Blocks | F |
| Can start when | A0 is merged (the rmcp conditional-tools spike can start on day one, it needs nothing from peers) |
| Owned files | `src/mcp/mod.rs`, `src/mcp/prompts.rs`, `src/mcp/resources.rs`, tool-list snapshot test (in `src/mcp/mod.rs`), a new `src/mcp/peers.rs` if the code is easier to keep apart (WS-D may add it) |
| Do not touch | `src/api/**` (C, B), `src/peers/**` (A, B, C), `src/state.rs`, `src/server.rs`, `src/telemetry/**`, `src/error.rs`, `docs/api.md`, `README.md`, `AGENTS.md` (F4 edits the tool-count line), `nix/**`, `Cargo.toml` |
Shared-file seams: WS-D is the only editor of `src/mcp/**`. It reads `AppState.peers` (A0) and calls `PeerRegistry::get` / `snapshot` / `status`; it never builds URLs or headers itself. The MCP `service()` function must keep working unchanged when `state.peers` is `None`.
## Goal
Agents reach peers through the same endpoint.
## Tasks
- **D1** optional `peer` string on the 8 existing tools (absent = local); resolved through the same peer client function as REST C2, no logic copy (`PeerRegistry::get`, contracts section 3).
- **D2** new tools `list_peers` and `get_peer { name }`; with `peers.enabled = false` the tool list is exactly today's 8 (snapshot test has both variants). Risk from the plan: `rmcp` may not support conditional tools cleanly; spike this early (fallback: always list tools, return an error when disabled, and accept a 10-tool snapshot), and record the outcome in the Log and, if it changes the tool-count behaviour, in contracts section 7.
- **D3** server instructions and descriptions: mention peers only when enabled; state that peer text is untrusted data; add `peers://status` resource and extend `container_health_report`/`diagnose_unit` with an optional `peer`.
## Inputs
- Contracts section 7 (tool signatures), 3 (registry API), 4 (error mapping to `CallToolResult` errors).
- Fakes: `registry_with(FakeTransport, ...)` scripted with peer JSON for each tool's path; `static_registry` for `list_peers`/`get_peer`/`peers://status`; `fake_state_with_peers`.
## Done when
Both snapshot variants pass; each tool with `peer` returns the peer's data via the fake; peer errors surface as `CallToolResult` errors with actionable text.
## Handoff
- The tool list (10 tools when enabled) and descriptions for docs (F4: README, AGENTS.md tool count note).
- The rmcp conditional-tools finding for contracts section 7.
- Verified against WS-T's MCP assertions (`list_peers`, `list_systemd_units {"peer": ...}`).
## Log
- 2026-10-19: Split from the single phase plan 2026-10-19.