doc updates

This commit is contained in:
ari committed 2026-10-19 14:14:29 -04:00
1 parent 7e1bd4a9a4
commit a511ff532e
26 files changed
+573 -770

No files matched your search

+62
View File
@@ -0,0 +1,62 @@
# 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`](../../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).