diff --git a/docs/api.md b/docs/api.md index 963da7f..b30f499 100644 --- a/docs/api.md +++ b/docs/api.md @@ -4,7 +4,7 @@ Full endpoint and MCP client reference. The short version is in the [README](../ ## Generated reference (OpenAPI) -[`openapi.json`](openapi.json) is a committed OpenAPI 3.1 description of everything this binary serves: every REST route with its parameters and response schemas, the error shape, `POST /mcp`, and an `x-mcp-tools` extension listing each MCP tool with the description and input JSON Schema the tool router reports (eight tools, or ten with `[peers] enabled = true`). `tests/openapi.rs` keeps it true: it fails if a route of the real router is undocumented, if a tool is missing from `x-mcp-tools`, or if the file is stale. +[`openapi.json`](openapi.json) is a committed OpenAPI 3.1 description of everything this binary serves: every REST route with its parameters and response schemas, the error shape, the MCP endpoint (`POST`, the standalone `GET` stream and the session `DELETE`), and an `x-mcp-tools` extension listing each MCP tool with the description and input JSON Schema the tool router reports (eight tools, or ten with `[peers] enabled = true`). `tests/openapi.rs` keeps it true: it fails if a route of the real router is undocumented, if a tool is missing from `x-mcp-tools`, or if the file is stale. - `GET /api/v1/openapi.json` returns the document for the running instance, behind the same bearer token as the rest of `/api/v1`. Peer routes appear only when peers are enabled. - `slinuxm openapi [--peers]` prints the same document offline: no config file, no token, no server, no port. `--peers` describes a consolidator; without it you get the peer-less instance. @@ -70,7 +70,7 @@ curl -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/peers/beta/ ## MCP -Endpoint: `http://127.0.0.1:1984/mcp` (Streamable HTTP). Eight tools (`list_systemd_units`, `get_systemd_unit`, `list_systemd_timers`, `get_journal_logs`, `tail_journal`, `list_containers`, `get_container`, `get_container_logs`), two prompts (`diagnose_unit`, `container_health_report`) two resources (`systemd://units/failed`, `docker://containers`) and two resource templates (`systemd://unit/{name}`, `docker://container/{name}`, same JSON as `get_systemd_unit` and `get_container`; percent-encode unusual characters in the name). Log content is untrusted data and is labelled as such in tool results. +Endpoint: `http://127.0.0.1:1984/mcp` (Streamable HTTP). `POST /mcp` carries the JSON-RPC messages; the default session mode also serves `GET /mcp` (standalone `text/event-stream` for server-to-client messages) and `DELETE /mcp` (end the session named by `Mcp-Session-Id`; 202 on success). Eight tools (`list_systemd_units`, `get_systemd_unit`, `list_systemd_timers`, `get_journal_logs`, `tail_journal`, `list_containers`, `get_container`, `get_container_logs`), two prompts (`diagnose_unit`, `container_health_report`) two resources (`systemd://units/failed`, `docker://containers`) and two resource templates (`systemd://unit/{name}`, `docker://container/{name}`, same JSON as `get_systemd_unit` and `get_container`; percent-encode unusual characters in the name). Log content is untrusted data and is labelled as such in tool results. Generic client config (header-capable clients): diff --git a/docs/openapi.json b/docs/openapi.json index d70cb00..c7d7a5e 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -900,6 +900,68 @@ } }, "/mcp": { + "get": { + "tags": [ + "mcp" + ], + "summary": "MCP server-to-client stream", + "description": "Standalone `text/event-stream` for messages the server sends outside a request. The default session mode requires the `Mcp-Session-Id` returned by `initialize`; an unknown or terminated session is 404. Send `Accept: text/event-stream`.", + "operationId": "mcp_stream", + "parameters": [ + { + "name": "Mcp-Session-Id", + "in": "header", + "description": "Session id returned by the `initialize` response", + "required": false, + "schema": { + "type": [ + "string", + "null" + ] + } + } + ], + "responses": { + "200": { + "description": "SSE stream of server-to-client messages", + "content": { + "text/event-stream": {} + } + }, + "400": { + "description": "`Mcp-Session-Id` is missing or `Mcp-Protocol-Version` is invalid" + }, + "401": { + "description": "Missing or unknown bearer token", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorBody" + } + } + } + }, + "403": { + "description": "`Host` or `Origin` not allowed (DNS-rebinding guard)" + }, + "404": { + "description": "Unknown or terminated session" + }, + "406": { + "description": "`Accept` does not include `text/event-stream`" + }, + "503": { + "description": "The token database is unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorBody" + } + } + } + } + } + }, "post": { "tags": [ "mcp" @@ -960,6 +1022,56 @@ "description": "`Content-Type` is not `application/json`" } } + }, + "delete": { + "tags": [ + "mcp" + ], + "summary": "End an MCP session", + "description": "Closes the session named by `Mcp-Session-Id` and frees its in-memory state. This ends an MCP session only; it never changes systemd, Docker or a peer.", + "operationId": "mcp_delete_session", + "parameters": [ + { + "name": "Mcp-Session-Id", + "in": "header", + "description": "Session id returned by the `initialize` response", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "202": { + "description": "Session closed" + }, + "400": { + "description": "`Mcp-Session-Id` is missing or `Mcp-Protocol-Version` is invalid" + }, + "401": { + "description": "Missing or unknown bearer token", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorBody" + } + } + } + }, + "403": { + "description": "`Host` or `Origin` not allowed (DNS-rebinding guard)" + }, + "503": { + "description": "The token database is unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorBody" + } + } + } + } + } } } }, diff --git a/src/openapi.rs b/src/openapi.rs index 87724d5..62fb7cd 100644 --- a/src/openapi.rs +++ b/src/openapi.rs @@ -62,6 +62,8 @@ pub const BEARER_SCHEME: &str = "bearer_auth"; crate::api::peers::pass, crate::api::openapi_json, mcp_endpoint, + mcp_stream, + mcp_delete_session, ), components(schemas( crate::api::peers::PeerList, @@ -178,6 +180,61 @@ fn build(peers: bool) -> OpenApi { )] pub fn mcp_endpoint() {} +/// `GET /mcp` in the default session mode: the standalone SSE stream for +/// server-to-client messages. rmcp serves it, so there is no axum handler to +/// annotate. +#[utoipa::path( + get, + path = "/mcp", + operation_id = "mcp_stream", + tag = "mcp", + summary = "MCP server-to-client stream", + description = "Standalone `text/event-stream` for messages the server sends outside a request. \ + The default session mode requires the `Mcp-Session-Id` returned by `initialize`; \ + an unknown or terminated session is 404. Send `Accept: text/event-stream`.", + params(( + "Mcp-Session-Id" = Option, + Header, + description = "Session id returned by the `initialize` response" + )), + responses( + (status = 200, + description = "SSE stream of server-to-client messages", + content_type = "text/event-stream"), + (status = 400, description = "`Mcp-Session-Id` is missing or `Mcp-Protocol-Version` is invalid"), + (status = 401, body = ErrorBody, description = "Missing or unknown bearer token"), + (status = 403, description = "`Host` or `Origin` not allowed (DNS-rebinding guard)"), + (status = 404, description = "Unknown or terminated session"), + (status = 406, description = "`Accept` does not include `text/event-stream`"), + (status = 503, body = ErrorBody, description = "The token database is unavailable"), + ) +)] +pub fn mcp_stream() {} + +/// `DELETE /mcp`: ends a session in the default session mode. +#[utoipa::path( + delete, + path = "/mcp", + operation_id = "mcp_delete_session", + tag = "mcp", + summary = "End an MCP session", + description = "Closes the session named by `Mcp-Session-Id` and frees its in-memory state. \ + This ends an MCP session only; it never changes systemd, Docker or a peer.", + params(( + "Mcp-Session-Id" = String, + Header, + description = "Session id returned by the `initialize` response" + )), + responses( + (status = 202, description = "Session closed"), + (status = 400, description = "`Mcp-Session-Id` is missing or `Mcp-Protocol-Version` is invalid"), + (status = 401, body = ErrorBody, description = "Missing or unknown bearer token"), + (status = 403, description = "`Host` or `Origin` not allowed (DNS-rebinding guard)"), + (status = 503, body = ErrorBody, description = "The token database is unavailable"), + ) +)] +pub fn mcp_delete_session() {} + fn info() -> Info { InfoBuilder::new() .title("skyg-linux-tracker") @@ -793,12 +850,19 @@ mod tests { fn mcp_endpoint_is_documented_in_both_modes() { for peers in [false, true] { let doc = document(peers); - let operation = &doc.paths.paths["/mcp"].post.as_ref().expect("POST /mcp"); + let item = &doc.paths.paths["/mcp"]; + let operation = item.post.as_ref().expect("POST /mcp"); assert_eq!(operation.operation_id.as_deref(), Some("mcp")); let responses = serde_json::to_value(&operation.responses).unwrap(); let content = responses["200"]["content"].as_object().unwrap(); assert!(content.contains_key("application/json")); assert!(content.contains_key("text/event-stream")); + // The default session mode also serves the standalone stream and + // the session DELETE. + let stream = item.get.as_ref().expect("GET /mcp"); + assert_eq!(stream.operation_id.as_deref(), Some("mcp_stream")); + let delete = item.delete.as_ref().expect("DELETE /mcp"); + assert_eq!(delete.operation_id.as_deref(), Some("mcp_delete_session")); } } diff --git a/tests/openapi.rs b/tests/openapi.rs index be3b69b..3221e94 100644 --- a/tests/openapi.rs +++ b/tests/openapi.rs @@ -494,11 +494,10 @@ fn every_operation_is_read_only() { ("patch", item.patch.is_some()), ] { if present { - assert_eq!( - (method, path.as_str()), - ("post", "/mcp"), - "{method} {path} is a write path" - ); + // `DELETE /mcp` ends an MCP session, a server-local session + // only; it is not a write path to the host. + let session = matches!((method, path.as_str()), ("post" | "delete", "/mcp")); + assert!(session, "{method} {path} is a write path"); } } }