docs(mcp): rewrite the published README to the shipped host-extension surface (#9579) (#9868)

The page told the reader to extend the server imperatively —
`kernel.getService('mcp').registerTool/registerResource/registerPrompt` at six
call sites. `MCPServerRuntime` has never had any of those members, and the
receiver is a local variable, so both halves of check:published-readme-exports
are structurally blind to it.

Ruled 2026-08-18: document the shipped surface, do not grow the API to match
the docs. The imperative narrative is replaced by what actually ships — the
bridge methods, handleHttpRequest / renderSkill, and the exported
registerObjectTools / registerActionTools / registerSkillPrompts helpers. Every
row is probed against the built dist/index.d.ts and the host-extension example
compiles clean against it.

⚠️ The ruling also named `registerToolFromDefinition` as the story to document.
It is `private` on the built type (TS2341 for any consumer), so it is NOT
documented — writing it down would recreate this card's own defect in a new
spelling. Its public counterparts (bridgeDataTools, registerObjectTools,
registerActionTools) carry that story instead.

Neighbouring fabrications corrected in the same pass: an entire invented
`objectstack_*` tool family; a missing `aggregate_records`; two wrong
`objectstack://` resource URI shapes plus two omitted ones; an invented
capability block claiming subscribe/listChanged/streaming when the server
derives capabilities and hand-declares only `logging`; the undocumented
OS_MCP_STDIO_ENABLED / OS_MCP_STDIO_API_KEY pair without which stdio refuses to
boot; and a relative link resolving above the repo root.

Docs only — no runtime code changed, and no API was added.


Claude-Session: https://claude.ai/code/session_01XqDQYVU5smx29ts9pAErja

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-steve

.changeset/mcp-readme-shipped-surface.md

@@ -0,0 +1,68 @@
+---
+"@objectstack/mcp": patch
+---
+
+docs(mcp): rewrite the published README to the shipped host-extension surface (#9579)
+
+`packages/mcp/README.md` is in the package's `files` array with `private` unset,
+so it is the page npm renders. It told the reader to extend the server
+imperatively at six call sites:
+
+```ts
+kernel.getService('mcp').registerTool(calculateRevenueTool);
+kernel.getService('mcp').registerResource({ … });
+kernel.getService('mcp').registerPrompt({ … });
+```
+
+`MCPServerRuntime` has never had any of those members. Measured against the
+built `dist/index.d.ts`, a consumer who copies those lines gets three
+`TS2339 Property … does not exist on type 'MCPServerRuntime'`. The receiver is a
+local variable, so `check:published-readme-exports` is structurally blind to
+them — both of its halves key on a name the fence *imported*, and this one is
+neither imported nor a bare identifier.
+
+Ruled 2026-08-18: **document the shipped surface; do not grow the API to match
+the docs.** So the imperative narrative is gone and the page now documents what
+actually ships — the bridge methods (`bridgeTools`, `bridgeDataTools`,
+`bridgeResources`, `bridgePrompts`), `handleHttpRequest` / `renderSkill`, and the
+exported `registerObjectTools` / `registerActionTools` / `registerSkillPrompts`
+helpers driving an `McpServer`. Every row is probed against the built type entry
+the `exports` map resolves, and the page's one host-extension example compiles
+clean against it.
+
+Neighbouring fabrications the audit turned up, all corrected in the same pass —
+each of them was reachable only through prose or an unimported receiver, which is
+why nothing had read them:
+
+- **A tool family that does not exist.** The page listed
+  `objectstack_find` / `objectstack_findOne` / `objectstack_create` /
+  `objectstack_update` / `objectstack_delete` / `objectstack_describeObject` /
+  `objectstack_listObjects` / `objectstack_listFields` as "auto-registered". No
+  such tool name occurs anywhere in the repo. The real names are the
+  `list_objects` … `run_action` set the page listed separately, one section down.
+- **`aggregate_records` was missing** from the list that *was* correct, along
+  with the fact that it registers only when the bridge implements `aggregate`.
+- **Resource URIs were wrong in both directions.** The page taught
+  `objectstack://objects/{name}/records` (no such resource) and
+  `objectstack://objects/{name}/{id}` (real shape is
+  `…/{name}/records/{id}`), and omitted `objectstack://objects` and
+  `objectstack://metadata/types` entirely.
+- **The advertised capability block was invented.** It claimed
+  `tools.listChanged`, `resources.subscribe`, `resources.listChanged`,
+  `prompts.listChanged` and `experimental.streaming`. The server hand-declares
+  only `logging`; everything else is *derived* from what was actually registered,
+  which is the ADR-0076 D12 contract the README was contradicting. The
+  "Streaming Support" feature bullet and the streaming-resource example went with
+  it — neither names anything that ships.
+- **The stdio transport could not be started by following the page.** Neither
+  `OS_MCP_STDIO_ENABLED` nor `OS_MCP_STDIO_API_KEY` was documented, and stdio
+  auto-start refuses to boot without the key (ADR-0101, fail-closed). The three
+  client config blocks now carry both. The Debugging section also taught
+  `OS_MCP_SERVER_ENABLED=true` as the stdio switch, which is the deprecated path
+  that logs a warning.
+- **A broken relative link.** `../../spec/src/ai/` resolves above the repo root
+  from `packages/mcp/`; the target is `../spec/src/ai/`.
+
+Docs only — no runtime code changed, and no API was added. `registerTool` /
+`registerResource` / `registerPrompt` remain unbuilt by ruling; a future
+imperative API is its own card on measured pull.