# MCP 应用程序开发 MCP 应用程序允许 MCP 工具在聊天中呈现交互式 HTML UI。 UI 在沙盒 iframe 中运行，并通过 JSON-RPC postMessage 进行通信。 ## 外部参考 * **规格**： * **博客**： * **VS Code impl** ：（搜索 `chatMcpAppModel.ts`） ## 快速入门 ### 1\.注册用户界面资源服务器.资源( “我的用户界面”， "ui://my-server/my-tool", // ui:// 需要方案 { mimeType: "text/html;profile=mcp-app" }, // 需要配置文件异步（uri）=>（{ 内容：[{ uri：uri.href， mimeType: "text/html;profile=mcp-app", // 必须匹配文本：MY_UI_HTML() }] }) ）； ### 2\.使用 UI 链接注册工具 server.registerTool("my_tool", { inputSchema: { 查询: z.string() }, _meta: { ui: { resourcesUri: "ui://my-server/my-tool" } } }, 异步 ({ 查询 }) => ({ 内容：[{ 类型：“文本”，文本：`结果：${query}` }]， StructuredContent: { query, result: "..." } // 发送到 UI })); ### 3\. UI 模板（静态 HTML）导出函数 MY_UI_HTML(): string { 返回 ` <正文>

正在加载...

<脚本> 常量挂起=新地图（）；让下一个Id = 1; 函数请求（方法，参数）{ 常量 id = nextId++; 返回新的 Promise((解决, 拒绝) => { 挂起.set(id, { 解决, 拒绝 }); window.parent.postMessage({ jsonrpc: '2.0', id, method, params }, '*'); }); } window.addEventListener('消息', (e) => { const msg = e.data; if (!msg?.jsonrpc) 返回； // 处理响应 if (msg.id &&ending.has(msg.id)) { const { 解析，拒绝 } =ending.get(msg.id); 待处理.删除(msg.id); 消息错误？拒绝(msg.error) : 解决(msg.result); 返回； } // 处理通知 if (msg.method === 'ui/notifications/tool-input') { const { 参数：args } = msg.params; document.getElementById('content').textContent = JSON.stringify(args); } }); // 初始化握手 request('ui/initialize', { 协议版本: '2025-11-21' }).then(() => { window.parent.postMessage({ jsonrpc: '2.0', method: 'ui/notifications/initialized' }, '*'); }); <\/脚本> `; } ## 关键要求要求|错误|右 ---|---|--- MIME 类型 | `文本/html` | `text/html;profile=mcp-app` URI 方案 | `https://`、`文件://` | `ui://` 工具注册| `server.tool()` | `server.registerTool()` 和 `_meta` 数据传递|模板参数| `ui/通知/工具输入` 外部获取/CDN |只需调用 `fetch()` |在 `_meta.ui.csp` 中声明域 VS 代码设置 |只需启用 |启用 `chat.mcp.apps.enabled` \+ **重新启动** ## 用户界面生命周期 UI → 主机：ui/初始化（请求）主机 → UI：响应 { hostContext } UI → 主机：ui/notifications/initialized（通知）主机 → UI：ui/notifications/tool-input { 参数，结构化内容 } 主机 → UI：ui/notifications/tool-result { 内容，结构化内容 } **关键**：在等待数据之前完成“ui/initialize”握手。 ## 主机通知（UI 接收）方法|当 |参数 ---|---|--- `ui/通知/工具输入` |工具参数准备就绪 | `{ 参数 }` `ui/通知/工具输入部分` |流媒体 |部分参数 `ui/通知/工具结果` |工具齐全 | `{ 内容，结构化内容 }` `ui/通知/工具已取消` |取消 | `{原因}` `ui/通知/主机上下文更改` |主题/尺寸更改 |上下文对象 ## UI 请求（UI 发送）方法|目的|参数 ---|---|--- `ui/初始化` |开始握手 | `{ 协议版本，功能 }` `ui/消息` |发送文本到聊天输入 | `{ 内容：[{ 类型：'文本'，文本 }] }` `工具/调用` |调用另一个 MCP 工具 | `{名称，参数}` `资源/阅读` |阅读 MCP 资源 | `{ uri }` ## 常见模式 ### 主题整合函数 applyHostContext(ctx) { if (ctx.theme) document.documentElement.style.colorScheme = ctx.theme; if (ctx.styles?.variables) { for (const [k, v] of Object.entries(ctx.styles.variables)) { document.documentElement.style.setProperty(k, v); } } } ### 将结果发送到聊天异步函数 sendToChat(text) { 等待请求（'用户界面/消息'，{ 内容：[{类型：'文本'，文本}] }); } ### XSS预防函数转义Html（文本）{ const div = document.createElement('div'); div.textContent = 文本；返回div.innerHTML； } ## 高级模式对于基本工具→UI 数据流之外的复杂 UI 交互，请加载 [references/patterns.md]()。主题包括：图案|何时使用 ---|--- **等待用户输入** |工具在返回之前需要等待用户交互（表单、选择、确认） **调用其他工具** | UI需要调用额外的MCP工具 **资源元数据** |边框偏好、尺寸提示 **加载外部资源** |通过 `_meta.ui.csp` 配置 CSP 以允许外部 API、CDN、字体、嵌入 **参考示例** |来自 ext-apps 存储库的生产模式（图表、图形、React、vanilla JS） ## 陷阱 1. **模板是静态的** \- 不要通过模板字符串插值传递数据。数据通过“工具输入”通知到达。 2. **VS Code 功能检测** \- VS Code 使用 `chat.mcp.apps.enabled` 设置，而不是协议功能协商。不要依赖 `extensions["io.modelcontextprotocol/ui"]`。 3. **脚本转义** \- 在模板字符串中使用 `<\/script>` 以避免破坏外部脚本。 4. **重建 + 重新启动** \- 代码更改后：`npm run build` 然后在 VS Code 中重新启动 MCP 服务器。 5. **MIME 类型重复** \- 必须在资源选项和内容数组中设置 `text/html;profile=mcp-app`。缺少任何一个都会导致静默失败。 6. **默认情况下阻止外部资源** \- UI 以严格的 CSP 运行。要使用外部 API/CDN，您必须在“_meta.ui.csp”中声明允许的域。请参阅 [patterns.md]()。 ## 调试检查服务器日志文件（例如`/tmp/mcp-server.log`）： * `📱 资源/读取` → VS Code 获取 UI（工作） * 仅`🔧调用的工具` → 设置未启用或需要重新启动请参阅 [references/debugging.md]() 了解日志记录设置和[references/troubleshooting.md]() 了解常见问题。 ## 文件结构源代码/ index.ts # 服务器：工具+资源注册用户界面/ my-tool.ts # 导出函数返回 HTML 字符串 ### 参考文件 * [references/patterns.md]() \- 高级模式（等待用户输入、调用工具、CSP、示例） * [references/debugging.md]() \- 日志记录设置 * [references/troubleshooting.md]() \- 常见问题和修复

麦克普应用程序

包含技能