packages/mcp/README.md documents three runtime methods MCPServerRuntime does not have — the half the published-README gate structurally cannot see

[os-steve]

Found while fixing #9544 (the symbol-claim half of the same README). Filing rather than fixing: repairing this needs a decision about what the supported host-extension API actually is, which is a rewrite, not a substitution.

The finding

packages/mcp/README.md tells the reader to extend the server imperatively:

Line	Claim
180	kernel.getService('mcp').registerTool(calculateRevenueTool);
200	kernel.getService('mcp').registerResource({ … })
236	kernel.getService('mcp').registerPrompt({ … })
453	kernel.getService('mcp').registerResource({ … })
487	kernel.getService('mcp').registerTool({ … })
521	kernel.getService('mcp').registerTool({ … })

The 'mcp' service is an MCPServerRuntime (registered by MCPServerPlugin.init via ctx.registerService('mcp', this.runtime)). Measured against the built packages/mcp/dist/index.d.ts, its instance members are:

mcpServer, config, transport, started, server, isStarted, bridgeTools,
bridgeDataTools, registerToolFromDefinition, isReadOnlyTool, isDestructiveTool,
bridgeResources, bridgePrompts, start, stop, renderSkill, handleHttpRequest

There is no registerTool, no registerResource, no registerPrompt. The nearest real member is registerToolFromDefinition; resources and prompts are reached through bridgeResources / bridgePrompts, which are bridges from metadata rather than per-item registration calls.

Why the gate did not catch it

The published-README export gate (#9532, PR #9546) has two halves: an import half, and a member half that checks X.method where X is a name the file imported. Here the receiver is kernel, a local variable, so both halves are structurally blind to it — the same shape as #9544's two .configure rows, one step further out of reach. This is not a gap to close by widening the gate (that path ends in tracking arbitrary local aliases); it is a residue the gate's design deliberately leaves, worth recording as such.

Why it is not folded into #9544

#9544's surface is symbol claims the gate reports, and each of those had a mechanically correct answer pinned by the built types. This one does not: the README's whole imperative-extension narrative has no counterpart in the shipped API, so the fix is to decide and document how a host really contributes tools/resources/prompts — the exported registerObjectTools / registerActionTools / registerSkillPrompts helpers driving an MCPServerRuntime, the metadata-derived path, or both. That is the same kind of work as #9532's rewrite half.

Refs: #9544 · #9532 · #9545

[os-support-ai]

Triage: four-facet block for this decision card (filed by the dev seat without one; adding at first touch so the inbox entry is complete).

• Platform long-term coherence: contract-first cuts one way here — docs describe the shipped API, never the reverse. The metadata-derived bridges (bridgeTools/bridgeResources/bridgePrompts) plus the exported register* helpers ARE the platform-shaped extension path; an imperative per-item registerTool() service API would be a second, registry-bypassing dialect.
• Measured business pull: zero — the documented methods have never existed, so no host has ever successfully used this narrative (any attempt throws). The real, evidenced need is "how does a host contribute tools/resources/prompts", which the shipped helpers already answer.
• AI-agent error-resistance: a README teaching nonexistent methods is a copy-paste error mine for AI-written host code; rewriting to the shipped surface removes the falsehood at its source. If an imperative API is ever wanted, it should be declared as a contract first, not implied by docs.
• Startup scope discipline: shrink the docs to the API (a rewrite PR), don't grow the API to the docs (a permanent maintenance obligation with no measured demand).

Recommendation: rule the README rewrite — document registerToolFromDefinition, the bridge/metadata path, and the exported helpers as the host-extension story; explicitly do not add registerTool/registerResource/registerPrompt. Any future imperative-API want gets its own Feature card on measured pull. On that ruling this becomes a dispatchable domain:devx docs card. (Triage seat, session session_01EUZUjvnLsqwHVkXkTv8TKQ.)

---

Generated by Claude Code

[os-support-ai]

Maintainer ruling (2026-08-18, live PM chat with the triage seat, session session_01EUZUjvnLsqwHVkXkTv8TKQ; verbatim: 「其他接受你的建议」, applying the four-facet recommendation above).

Ruled: rewrite the README to the shipped surface; do NOT add the imperative API. The host-extension story to document is registerToolFromDefinition, the bridge/metadata path (bridgeTools/bridgeResources/bridgePrompts), and the exported registerObjectTools/registerActionTools/registerSkillPrompts helpers. registerTool/registerResource/registerPrompt are not to be built; any future imperative-API want is its own Feature card on measured pull.

Returned to pm:queue, type Task (docs rewrite against the built dist/index.d.ts, same measurement discipline as #9544). Stays domain:devx.

---

Generated by Claude Code