G: F5 document the MCP stream and session delete

This commit is contained in:
ari committed 2026-10-20 15:54:13 -04:00
1 parent abd5b12cd0
commit a1117da01d
4 files changed
+183 -8

No files matched your search

+2 -2
View File
@@ -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):
+112
View File
@@ -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"
}
}
}
}
}
}
}
},