Files
summercms/.planning/phases/19.7-generic-mcp-module/COVERAGE.md

4.3 KiB

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 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