From 60b958029f3683cc0bad8e01156fb9157fea877c Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 3 Sep 2026 19:11:09 +0000 Subject: [PATCH 1/2] docs(mcp): correct MCPServerPlugin's docblock to the canonical stdio switch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The class docblock still taught the pre-split trigger: step 2 said the long-lived stdio transport starts "only when `autoStart` is enabled or `OS_MCP_SERVER_ENABLED` is explicitly `true`", and the Environment Variables block said explicit `true` "additionally auto-starts the stdio transport". Neither named `OS_MCP_STDIO_ENABLED` — the canonical switch `resolveMcpStdioAutoStart()` reads first — about 100 lines above a runtime warning telling the operator that exact trigger is DEPRECATED. Comments only; no behaviour change. The deprecation sentence is copied verbatim from the runtime warning below it so the two cannot drift into two phrasings of the same rule. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza --- packages/mcp/src/plugin.ts | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/packages/mcp/src/plugin.ts b/packages/mcp/src/plugin.ts index cc779440f4..538e94ac66 100644 --- a/packages/mcp/src/plugin.ts +++ b/packages/mcp/src/plugin.ts @@ -111,15 +111,21 @@ export interface MCPServerPluginOptions { * 1. **init** — Creates {@link MCPServerRuntime} and registers as `'mcp'` service. * 2. **start** — Bridges ToolRegistry, MetadataService, DataEngine, and Agents * to the MCP server. Starts the long-lived transport (stdio) only when - * `autoStart` is enabled or `OS_MCP_SERVER_ENABLED` is explicitly `true` — + * `autoStart` is enabled or `OS_MCP_STDIO_ENABLED` is truthy — * the HTTP surface needs no start: the runtime dispatcher serves it * per-request at `/api/v1/mcp` (default-on; `OS_MCP_SERVER_ENABLED=false` * opts out — see `isMcpServerEnabled` in `@objectstack/types`). * 3. **destroy** — Stops the MCP transport. * * Environment Variables: - * - `OS_MCP_SERVER_ENABLED` — HTTP surface default-on; `false` disables it, - * explicit `true` additionally auto-starts the stdio transport + * - `OS_MCP_SERVER_ENABLED` — gates the default-on HTTP surface only; `false` + * disables it (see `isMcpServerEnabled` in `@objectstack/types`) + * - `OS_MCP_STDIO_ENABLED` — the long-lived stdio transport's own switch, + * default OFF (see `resolveMcpStdioAutoStart` in `@objectstack/types`). + * Starting the stdio transport via `OS_MCP_SERVER_ENABLED=true` is + * DEPRECATED — that var now only gates the default-on HTTP surface. Use + * `OS_MCP_STDIO_ENABLED=true` (or the plugin `autoStart` option) for the + * long-lived stdio transport. * - `OS_MCP_SERVER_NAME` — Override server name * - `OS_MCP_SERVER_TRANSPORT` — Override transport ('stdio' | 'http') * (legacy `MCP_SERVER_*` names still honoured with a deprecation warning) From 9544e659bbd9883d8d0ea08cc928c581574a469a Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 3 Sep 2026 19:31:07 +0000 Subject: [PATCH 2/2] docs(mcp): add changeset for the MCPServerPlugin docblock correction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docblock is a published surface, measured rather than assumed: `MCPServerPlugin` is exported from the package entry, root tsup config has `dts` emit on, and packages/mcp's `files` ships `dist` — so the comment reaches consumers as `dist/index.d.ts` and renders in editor IntelliSense. That makes it user-visible, so a changeset is owed and `skip-changeset` does not apply. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza --- .../mcp-plugin-docblock-stdio-switch.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 .changeset/mcp-plugin-docblock-stdio-switch.md diff --git a/.changeset/mcp-plugin-docblock-stdio-switch.md b/.changeset/mcp-plugin-docblock-stdio-switch.md new file mode 100644 index 0000000000..ebea364753 --- /dev/null +++ b/.changeset/mcp-plugin-docblock-stdio-switch.md @@ -0,0 +1,38 @@ +--- +"@objectstack/mcp": patch +--- + +docs(mcp): correct `MCPServerPlugin`'s docblock to the canonical stdio switch (#14473) + +The class docblock still taught the **pre-split** stdio trigger. Step 2 said the +long-lived transport starts "only when `autoStart` is enabled or +`OS_MCP_SERVER_ENABLED` is explicitly `true`", and the Environment Variables +block said explicit `true` "additionally auto-starts the stdio transport". +Neither named `OS_MCP_STDIO_ENABLED` — the canonical switch — anywhere. + +About 100 lines below it, the code says the opposite. `resolveMcpStdioAutoStart()` +reads `OS_MCP_STDIO_ENABLED` first and returns it clean; `OS_MCP_SERVER_ENABLED=true` +falls through to a legacy branch flagged `viaDeprecatedAlias`, and `start()` warns +that this trigger is DEPRECATED. So an author following the docblock got a working +transport **plus a deprecation warning at every boot**, with no way from this file +to learn the right spelling. + +This is a published surface, not an internal note: `MCPServerPlugin` is exported +from the package entry, `dts` emit is on, and `files` ships `dist` — so the +docblock reaches consumers as `dist/index.d.ts` and renders in editor +IntelliSense. It had already cost something once: the published +`skills/objectstack-ai` MCP section was written from this docblock and inherited +the same error, caught in contract review and fixed in PR #14463. + +Now: + +- **step 2** — starts "only when `autoStart` is enabled or `OS_MCP_STDIO_ENABLED` + is truthy"; +- **Environment Variables** — `OS_MCP_SERVER_ENABLED` is described as the + default-on **HTTP** gate only; `OS_MCP_STDIO_ENABLED` is listed as the stdio + transport's own switch (default OFF); and the legacy trigger is marked + deprecated **in the runtime warning's own words**, copied verbatim from the + `ctx.logger.warn` below rather than paraphrased, so the two cannot drift into + two phrasings of one rule. + +Comments only — no behaviour change.