G: F5 document the MCP stream and session delete
This commit is contained in:
1 parent
abd5b12cd0
commit
a1117da01d
4 files changed
+183
-8
No files matched your search
+2
-2
@@ -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):
|
||||
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
+65
-1
@@ -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<String>,
|
||||
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"));
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
+4
-5
@@ -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");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in new issue
Block a user