docs(mcp): correct MCPServerPlugin's docblock to the canonical stdio switch (#15067)

* docs(mcp): correct MCPServerPlugin's docblock to the canonical stdio switch

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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

* docs(mcp): add changeset for the MCPServerPlugin docblock correction

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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

---------

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

Author: os-trump

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

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)