golem15/summercms
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(19.7): add MCP API coverage matrix

Browse Source
This commit is contained in:
Jakub Zych
2026-10-24 00:16:16 +02:00
parent 4c20459d03
commit 1038034078
1 changed files with 37 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
.planning/phases/19.7-generic-mcp-module/COVERAGE.md Normal file
View File

@@ -0,0 +1,37 @@
# API Coverage — MCP server surface (pier, go-sdk v1.8.0)
> Full coverage by default. Opt-outs are explicit, reasoned decisions.
Phase 19.7 calls no third-party service at runtime. It implements an MCP server (`modules/pier`) on the official `github.com/modelcontextprotocol/go-sdk` v1.8.0 (D-24, `.planning/notes/2026-10-22-mcp-go-sdk.md`), compiled in only with the `summercms_mcp` build tag (D-33) and off by default (D-30). Authorization rides on the oauthserver plugin's MCP flavour from Phase 19.4. The matrix records which parts of the MCP protocol pier serves (INTEGRATE) and which it leaves out on purpose (OPT-OUT), so a client's expectations can be checked against it.
| capability | decision | reason |
|---|---|---|
| transport: streamable HTTP, stateful (`Mcp-Session-Id`, SSE responses) | INTEGRATE | D-25; sessions in Redis (or memory) with a sliding idle TTL (D-27) |
| transport: stateless streamable HTTP for 2026-07-28 clients | INTEGRATE | D-32; go-sdk v1.8.0 serves 2026-07-28 only statelessly |
| transport: version negotiation 2025-03-26, 2025-11-25, 2026-07-28 | INTEGRATE | `negotiatedVersion` mirrors the SDK rule; the header picks the path |
| transport: stdio | OPT-OUT | pier is a network service inside the application binary; there is no local process to spawn |
| transport: legacy HTTP+SSE (2024-11-05) | OPT-OUT | deprecated by the protocol; every supported client speaks streamable HTTP |
| transport: stream resumability (`Last-Event-ID`, event store) | OPT-OUT | tool calls are short HTTP route dispatches; a dropped stream is retried by the client |
| authorization: protected resource metadata (RFC 9728) | INTEGRATE | `prm.go`, through the SDK's `auth.ProtectedResourceMetadataHandler` |
| authorization: 401 with `WWW-Authenticate` (resource metadata, scope) | INTEGRATE | `pier.go`; scope hint `read` added when absent |
| authorization: bearer access-token verification (MCP grants, member `usr_` tokens) | INTEGRATE | D-20 to D-23; revocation ends or narrows sessions (D-27) |
| authorization: `read`/`write` ceiling and separate `backend` scope | INTEGRATE | D-20, D-21; permissions always filter on top |
| lifecycle: initialize, initialized, ping | INTEGRATE | SDK; `InitializedHandler` arms the session |
| server info: name and version | INTEGRATE | application name and the framework module version |
| tools: `tools/list`, `tools/call` | INTEGRATE | plugin-declared tools dispatched to their HTTP routes (D-12, D-23) |
| tools: annotations (`readOnlyHint` and the rest) | INTEGRATE | `annotationsFor`; `readOnlyHint` drives the `read` ceiling |
| tools: `outputSchema` and `structuredContent` | INTEGRATE | `catalog.go`, `dispatch.go` |
| tools: `notifications/tools/list_changed` | INTEGRATE | D-26; pushed over Redis pub/sub to the instance holding the session |
| prompts: `prompts/list`, `prompts/get` with arguments | INTEGRATE | D-28; filtered and prefixed like tools |
| prompts: `notifications/prompts/list_changed` | INTEGRATE | D-26 |
| resources: `resources/list`, `resources/read`, templates | OPT-OUT | D-28: the capability is shaped for them, a follow-up phase ships them (CONTEXT deferred ideas) |
| resources: `resources/subscribe`, `notifications/resources/updated` | OPT-OUT | follows resources (deferred) |
| completion: `completion/complete` | OPT-OUT | no resources and no enumerable prompt arguments yet; returns with resources |
| logging: `logging/setLevel`, `notifications/message` | OPT-OUT | the capability is not advertised; calls are audited server-side instead (`audit.go`) |
| progress notifications | OPT-OUT | route dispatches are bounded by `mcp.call_timeout`; no long-running tool exists |
| cancellation (`notifications/cancelled`) | INTEGRATE | handled by the SDK; the call context is cancelled and the dispatched request with it |
| client features: sampling (`sampling/createMessage`) | OPT-OUT | tools are plugin HTTP routes; the server never asks the client's model |
| client features: elicitation | OPT-OUT | consent and account linking happen in the browser (oauthserver consent, `/link-admin`), not in the agent |
| client features: roots | OPT-OUT | no filesystem semantics on a CMS server |
| tasks (2025-11-25 experimental) | OPT-OUT | experimental in the protocol; no long-running tool exists |
| pagination of list results | INTEGRATE | handled by the SDK |