Land the shared peer contracts: types, error mapping, transport trait, fake transport and fixtures, registry/proxy/health skeletons, the AppState.peers and Config.peers seams, the ping and peers route stubs, and unit plus integration tests. No loops, no network, feature off by default.
8.2 KiB
WS-D: MCP surface
Part of Phase 5: Consolidator. Contracts: contracts.md sections 3, 4 and 7.
| Field | Value |
|---|---|
| Status | In progress (spike done) |
| 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
peerstring 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_peersandget_peer { name }; withpeers.enabled = falsethe tool list is exactly today's 8 (snapshot test has both variants). Risk from the plan:rmcpmay 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://statusresource and extendcontainer_health_report/diagnose_unitwith an optionalpeer.
Inputs
- Contracts section 7 (tool signatures), 3 (registry API), 4 (error mapping to
CallToolResulterrors). - Fakes:
registry_with(FakeTransport, ...)scripted with peer JSON for each tool's path;static_registryforlist_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.
-
2026-10-19: D0 rmcp conditional-tools spike: supported natively, no fallback needed. Tested against pinned
rmcp3.5.1.ToolRouterexposesdisable_route,enable_routeandwith_disabled;list_all()filters disabled names,get()returnsNoneandcall()rejects them withinvalid_params("tool not found"). The#[tool_handler]macro routeslist_toolsthroughrouter.list_all()andcall_toolthroughrouter.call(), andTrackerServicealready stores its router in a field built bynew().StreamableHttpServiceconstructsTrackerServiceper session, so the visible set is computed per session fromAppStatewith no restart.disable_routealso records names that have no route yet, so gating can be written before the two tools exist or in either order.Throwaway proof (run as
cargo test --lib mcp::tests::spike_conditional_tool_list, then removed;src/unchanged):#[test] fn spike_conditional_tool_list() { use rmcp::handler::server::router::tool::ToolRoute; use rmcp::model::Tool; let peer_route = |name: &'static str| { ToolRoute::new_dyn( Tool::new(name, name, Arc::new(Default::default())), |_ctx| Box::pin(async { Ok(CallToolResult::default().into()) }), ) }; let mut router = TrackerService::tool_router(); router.add_route(peer_route("list_peers")); router.add_route(peer_route("get_peer")); assert_eq!(router.list_all().len(), 10); router.disable_route("list_peers"); router.disable_route("get_peer"); assert_eq!(router.list_all().len(), 8); assert!(router.get("list_peers").is_none()); assert!(!router.has_route("get_peer")); router.enable_route("list_peers"); router.enable_route("get_peer"); assert_eq!(router.list_all().len(), 10); }Result: passed; 10 visible -> 8 after disabling the two peer tools -> 10 after re-enabling.
Recommendation for D2:
- Keep all ten
#[tool]methods on one impl (one#[tool_router]). InTrackerService::new, afterSelf::tool_router(), doif state.peers.is_none() { tool_router.disable_route("list_peers"); tool_router.disable_route("get_peer"); }. This yields exactly 8 tools by default and 10 when peers are enabled. Do not adopt the plan's fallback (always list 10, error when disabled); it is unnecessary and changes the contract. - Rewrite the snapshot test to build services, not the static router: peers-disabled variant via
TrackerService::new(fake_state(...))asserts 8; peers-enabled variant viafake_state_with_peers(...)asserts 10.TrackerService::tool_router()alone always returns all 10 and would no longer guard the gated list. - Schema caveat:
disable_routehides a tool but cannot alter its staticToolattr. Addingpeer: Option<String>to the eight params structs therefore changes theirinput_schemaeven when peers are disabled, which contracts section 7 forbids. Recommended fix: a small helper inTrackerService::newthat, whenstate.peers.is_none(), removes the"peer"property from each of the eightinput_schemas (ToolRouter.mapandToolRoute.attrare public;Arc::make_mut(&mut route.attr.input_schema).remove("peer")); the field is optional sorequiredis untouched. This is deterministic and covered by asserting the two snapshot variants' property sets. It relies on public fields of the pinned rmcp version, so keep the pin and the snapshot test. If that is judged too brittle, the alternative is a contracts section 7 change to always advertisepeer(optional, ignored when peers are disabled); ask the contract owner first. - Not a risk for the rest of D3:
list_resources,list_promptsandget_info/instructions are hand-written in this repo, sopeers://status, the peer-aware prompt argument and the conditional instructions text are plainstate.peers.is_some()branches, not router features. - Runtime toggling is not required (peers are declared at startup; SIGHUP rotates tokens, not
enabled), butdisable_route/enable_routecan emitnotifications/tools/list_changedviabind_peer_notifierif a later phase needs it.
- Keep all ten
-
2026-10-19: Handoff (D0 complete). Deliverable: the spike answer and recommendation above. Verdict:
rmcp3.5.1 supports the 8/10 conditional tool list natively viaToolRouter::disable_route, so D2 can proceed without a contract change; the only follow-up is stripping the optionalpeerproperty from the eight schemas when peers are disabled (point 3 above). Nosrc/production code was changed; the throwaway test was removed after running and the tree is clean apart from this Log. Verification:cargo fmt --check,cargo clippy --all-targets -- -D warningsandcargo testall pass. Commits: findingsc168551, this handoff. Next: D1/D2 once A0 (AppState.peers,registry_with,static_registry,fake_state_with_peers) is merged; rewrite the snapshot test to useTrackerService::newfor both variants. -
2026-10-19 (A0): contract stubs landed.
PeerRegistry(snapshot,status,contains,config,get) andProxyOptsare available,AppState.peers: Option<Arc<PeerRegistry>>exists, andtesting::{fake_peers_config, registry_with, static_registry, fake_state_with_peers, FakeTransport}let MCP tests run without sockets.PeerRegistry::getis the single proxy path to call.