feat(mcp): #3167 PR-B — stdio/HTTP off-switch split + os dev connect UX + exposure-policy docs

[os-zhuang]

What & why

#3167 的 PR-B,方向已拍定的非重叠部分。

范围调整(重要):开发期间 #3228 已在 main 落地了 HTTP 身份准入的 e2e 证明(基于 showcase、标 HIGH-RISK,并重指了 mcp-http-identity 矩阵行)。因此本 PR rebase 到 main 之上,撤掉了我原来那份重复的 cbp 证明(#3228 的更强),只保留 #3228没做的部分。

审计确认:serve-side 插件早已默认接线(serve.ts:isMcpServerEnabled() → requires.push('mcp')),HTTP 面早已准入且现已被 #3228 的 e2e 证明钉死。本 PR 补齐剩下的收口 + 可发现性 + 政策成文。

改动(单 commit)

• Decision 2(off-switch 语义):HTTP 面与 stdio 传输此前共用一个开关——OS_MCP_SERVER_ENABLED=true 开 HTTP 的同时静默启动无 principal 的裸权限 stdio 桥。拆开:
  • @objectstack/types 新增 resolveMcpStdioAutoStart();stdio 归 OS_MCP_STDIO_ENABLED(默认关),OS_MCP_SERVER_ENABLED 只管 HTTP。旧 =true 触发 stdio 保留一 release + deprecation 警告;=false 语义不变。
  • @objectstack/mcpplugin.start() 改走新开关,legacy alias 触发时 warn 一次。未动bridgeResources(...)(mcp-stdio-authority 探针键);矩阵该行 env 引用已同步。
• Decision 3(dev 亲和):os dev 启动打印 MCP endpoint / skill URL / 可直接粘贴的 claude mcp add 命令(gate 在 isMcpServerEnabled(),opt-out 零广告)。
• Decision 4(暴露政策):现行默认(非系统对象 + ai.exposed action、~10 工具脊柱)在 connect-mcp.mdx 写成 v1 承诺政策 + metadata 可著述的后续方向。
• 附:env-var 文档拆分 + deprecation callout;blank 脚手架 README serve 侧说明;单测钉住三态开关语义;changeset(types/mcp/cli minor + create-objectstack patch)。

验证(rebase 后,本地)

• packages/types env 20/20;packages/mcp plugin 14/14(向后兼容);dogfood authz-conformance + feat(cli): make optional-plugin loading intent-driven, fail-fast on declared-but-missing (#1597) #3228 的 showcase-mcp-http-identity(回归) 合计 13/13 —— 我的 plugin.ts stdio 改动对 HTTP 面无回归,矩阵 ledger 仍 sound。
• eslint 干净;turbo build(types/mcp/cli/verify/showcase 闭包,含 tsc)绿。

不在本 PR(明确 defer)

• stdio principal 线程化(把长驻 bridge 升级为 principal-bound)——安全改动,单独 PR;
• showcase 自连接 demo——dogfood gate 不能变 timing-sensitive,单独 PR。

Refs #3167(PR-B)、#3228(HTTP 证明,已合)、#3202(PR-A)、ADR-0096、ADR-0097。

🤖 Generated with Claude Code

https://claude.ai/code/session_0115eg8dAaCfWaDYYAm3ma36

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 18, 2026 5:11pm

[github-actions]

📓 Docs Drift Check

This PR changes 5 package(s): @objectstack/cli, create-objectstack, @objectstack/mcp, packages/qa, @objectstack/types.

30 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/actions-as-tools.mdx(via @objectstack/mcp)
• content/docs/ai/agents.mdx(via @objectstack/mcp)
• content/docs/ai/index.mdx(via @objectstack/mcp)
• content/docs/ai/natural-language-queries.mdx(via @objectstack/mcp)
• content/docs/ai/skills-reference.mdx(via packages/cli, create-objectstack)
• content/docs/ai/skills.mdx(via create-objectstack)
• content/docs/api/client-sdk.mdx(via @objectstack/cli)
• content/docs/api/data-flow.mdx(via @objectstack/cli)
• content/docs/api/environment-routing.mdx(via @objectstack/cli)
• content/docs/api/error-catalog.mdx(via @objectstack/cli)
• content/docs/api/index.mdx(via @objectstack/mcp)
• content/docs/automation/hook-bodies.mdx(via packages/cli)
• content/docs/deployment/backup-restore.mdx(via @objectstack/cli)
• content/docs/deployment/environment-variables.mdx(via @objectstack/mcp)
• content/docs/deployment/self-hosting.mdx(via @objectstack/cli)
• content/docs/getting-started/cli.mdx(via @objectstack/cli)
• content/docs/getting-started/index.mdx(via create-objectstack)
• content/docs/getting-started/your-first-project.mdx(via @objectstack/cli, create-objectstack)
• content/docs/kernel/runtime-services/data-service.mdx(via packages/cli)
• content/docs/kernel/runtime-services/index.mdx(via packages/cli)
• content/docs/permissions/authentication.mdx(via @objectstack/cli)
• content/docs/permissions/authorization.mdx(via packages/qa)
• content/docs/permissions/delegated-administration.mdx(via packages/qa)
• content/docs/plugins/packages.mdx(via @objectstack/cli, create-objectstack, @objectstack/mcp, @objectstack/types)
• content/docs/protocol/kernel/plugin-spec.mdx(via @objectstack/cli)
• content/docs/protocol/kernel/realtime-protocol.mdx(via @objectstack/cli)
• content/docs/protocol/knowledge.mdx(via @objectstack/mcp)
• content/docs/releases/implementation-status.mdx(via @objectstack/cli, @objectstack/mcp)
• content/docs/releases/v15.mdx(via create-objectstack)
• content/docs/releases/v9.mdx(via create-objectstack)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.