巧妙之处、边界与代码地图
本章是“带走的精华 + 导航索引”。前五章读过后,这里帮你沉淀和跳转。
1. 巧妙之处(可借鉴的技术)
① 把握手次序做成可观测的护栏,而非沉默的 bug。 早调用出站方法、晚注册一次性事件,都会被 _assertInitialized(app.ts:368)和 _assertHandlerTiming(app.ts:414)抓出 来告警。妙在它有 strict 旋钮:默认只 warn(兼容现状),未来默认转抛。这是“为已知线上事故(claude-ai-mcp#61/#149)写一道护栏”的范例。
② DOM 模型的双通道事件。 ProtocolWithEvents(src/events.ts)在 MCP Protocol 的“一方法一处理器”之上,加了 on*(替换)+ addEventListener(追加)两条通道,派发顺序固定(events.ts:113-121),还做了双重注册保护:直接 setRequestHandler 撞已注册方法就抛(events.ts:268-278),把误覆盖变成显式错误。
③ 自动尺寸里两处“反直觉但正确”的测量。 高度用 max-content 而非 fit-content(避免被视口高夹住产生内滚),宽度用 window.innerWidth 而非测量(避免 fit-content 在 0px 触发重排清零横向滚动)。两段注释(app.ts:1873-1888)本身就是一篇踩坑笔记。
④ 新旧元数据格式双向互填。 registerAppTool 让服务器只写新格式就自动兼容老宿主(server/index.ts:241-252),把“协议演进的兼容负担”收进 SDK 一处。
⑤ schema 不绑 Zod。 通过 Standard Schema(src/standard-schema.ts)支持 Zod v4 / ArkType / Valibot,且对 zod v3.25 留了 z.toJSONSchema 的惰性回落(standard-schema.ts:50-69),为未来切到 SDK v2 铺路(到时这文件可整体删掉)。
⑥ 差量上下文推送。 setHostContext 只推变了的字段(app-bridge.ts:1524),省带宽也让 View 的 onhostcontextchanged 语义清晰(收到即变更)。
2. 边界与局限(诚实)
- 不支持 Tasks。 两端都硬抛
"Tasks are not supported in MCP Apps"(app.ts:1188、app-bridge.ts:1434)。 - 本仓库没有“产品级 Host 实现”。 只有
examples/basic-host这个参考实现;真实宿主(含双层沙箱、CSP 注入)由各客户端自己实现,或用 MCP-UI 这类客户端 SDK(README §Using the SDK)。所以 05 章描述的是协议契约,不是某段具体的宿主渲染代码——后者不在此仓库。 - 几处能力断言是 TODO。
AppBridge.assertCapabilityForMethod/assertNotificationCapability等还是空壳(app-bridge.ts:1410-1428),Host 侧的能力校验目前较松。 - 部分工具输入是缝合 JSON。
toolinputpartial可能截断(app.ts:786-795),只能用于预览。 ui/message的 role 只支持"user"(spec.types.ts:211)。on*设置器全面@deprecated,迁移方向是addEventListener;但当前示例仍大量用on*,过渡期并存。- 版本/许可不一致:
package.json写 MIT(package.json:9),README 徽章写 Apache 2.0(未深究哪个权威)。
3. 横向对比(同 shelf / 同领域)
| 方案 | 它是什么 | 与 MCP Apps 的关系 |
|---|---|---|
| 核心 MCP | 工具返回文本/结构化数据的基础协议 | MCP Apps 是它的扩展(SEP-1865),复用其 tools/call、resources/read 等;UI 消息加 ui/ 前缀以区分 |
| MCP-UI(idosal/mcp-ui) | 第三方的“全功能 MCP Apps 客户端框架” | README 明说:客户端可选用 MCP-UI 或自己实现宿主侧;本 SDK 给的是协议 + View/Host/Server 三端的官方实现 |
| OpenAI Apps SDK | OpenAI 自家的应用 UI 方案 | 本仓库提供 migrate-oai-app 技能帮迁移(README §Build with Agent Skills);二者概念相近(工具配 UI),协议不同 |
一句话定位:MCP Apps = 在 MCP 之上、标准化“工具带交互式 UI”这件事,并给出三端官方 SDK;宿主渲染留给客户端自己或 MCP-UI。
4. 代码地图(导航索引)
agent 可用符号名 grep 定位(比行号抗漂移)。
| 主题 | 文件路径 | 符号名 |
|---|---|---|
| View 入口类 | src/app.ts | App |
| View 握手 | src/app.ts | App.connect |
| 握手护栏(出站) | src/app.ts | _assertInitialized |
| 握手护栏(事件晚注册) | src/app.ts | _assertHandlerTiming、ONE_SHOT_EVENTS |
| 代调服务器工具 | src/app.ts | callServerTool |
| 发消息 / 上下文 | src/app.ts | sendMessage、updateModelContext |
| 自动尺寸 | src/app.ts | setupSizeChangedNotifications |
| View 注册工具 | src/app.ts | App.registerTool |
| Host 桥类 | src/app-bridge.ts | AppBridge |
| Host 握手应答 | src/app-bridge.ts | _oninitialize |
| Host 自动转发 | src/app-bridge.ts | AppBridge.connect |
| 推工具数据 | src/app-bridge.ts | sendToolInput、sendToolResult、sendToolCancelled |
| 差量上下文 | src/app-bridge.ts | setHostContext、deepEqual |
| 拆除 | src/app-bridge.ts | teardownResource |
| 读工具 UI URI | src/app-bridge.ts | getToolUiResourceUri |
| 可见性判定 | src/app-bridge.ts | isToolVisibilityModelOnly、isToolVisibilityAppOnly |
| 权限→allow 属性 | src/app-bridge.ts | buildAllowAttribute |
| 内部沙箱消息 | src/app-bridge.ts | onsandboxready、sendSandboxResourceReady |
| 传输层 | src/message-transport.ts | PostMessageTransport |
| 事件系统 | src/events.ts | ProtocolWithEvents |
| 服务器注册助手 | src/server/index.ts | registerAppTool、registerAppResource |
| 能力协商 | src/server/index.ts | getUiCapability、EXTENSION_ID |
| 协议类型 | src/spec.types.ts | McpUiInitializeRequest、McpUiHostContext、McpUiResourceCsp、McpUiToolMeta |
| 方法名常量 | src/spec.types.ts | TOOL_INPUT_METHOD、INITIALIZE_METHOD 等 |
| Standard Schema | src/standard-schema.ts | standardSchemaToJsonSchema、validateStandardSchema |
| 主题/样式 | src/styles.ts | applyHostStyleVariables、getDocumentTheme |
| React 钩子 | src/react/useApp.tsx | useApp |
| 协议规范(权威) | specification/2026-01-26/apps.mdx | (沙箱代理 §、时序图) |
| 最小示例 | examples/quickstart/server.ts、examples/quickstart/src/mcp-app.ts | createServer |