# 将 MCP 应用程序支持添加到 Web 应用程序将 MCP 应用程序支持添加到现有 Web 应用程序，以便它既可以作为独立的 Web 应用程序**也可以作为 MCP 应用程序运行，在支持 MCP 的主机（如 Claude Desktop）中从单个代码库进行内联渲染。 ## 它是如何工作的现有的网络应用程序保持不变。薄初始化层检测应用程序是在 MCP 主机内运行还是作为常规网页运行，并从适当的源获取参数。新的 MCP 服务器将应用程序的捆绑 HTML 包装为资源，并注册一个工具来显示它。独立：浏览器加载页面 → 应用程序读取 URL 参数/API → 渲染 MCP App：主机调用工具→服务器返回结果→主机在iframe中渲染应用程序→应用程序读取MCP生命周期→渲染应用程序的渲染逻辑是共享的——只有数据源发生变化。 ## 获取参考代码克隆 SDK 存储库以获取工作示例和 API 文档： git clone --branch "v$(npm view @modelcontextprotocol/ext-apps 版本)" --深度 1 https://github.com/modelcontextprotocol/ext-apps.git /tmp/mcp-ext-apps ### API 参考（源文件）直接从 `/tmp/mcp-ext-apps/src/` 阅读 JSDoc 文档：文件|内容 ---|--- `src/app.ts` | `App` 类、处理程序（`ontoolinput`、`ontoolresult`、`onhostcontextchanged`、`onteardown`）、生命周期 `src/server/index.ts` | `registerAppTool`、`registerAppResource`、工具可见性选项 `src/spec.types.ts` |所有类型定义：`McpUiHostContext`、CSS 变量键、显示模式 `src/styles.ts` | `applyDocumentTheme`、`applyHostStyleVariables`、`applyHostFonts` `src/react/useApp.tsx` | React 应用程序的 `useApp` 钩子 `src/react/useHostStyles.ts` | `useHostStyles`、`useHostStyleVariables`、`useHostFonts` 挂钩 ### 框架模板从 `/tmp/mcp-ext-apps/examples/basic-server-{framework}/` 学习和适应：模板|关键文件 ---|--- `basic-server-vanillajs/` | `server.ts`、`src/mcp-app.ts`、`mcp-app.html` `基本服务器反应/` | `server.ts`、`src/mcp-app.tsx` （使用 `useApp` 挂钩） `基本服务器-vue/` | `server.ts`、`src/App.vue` `基本服务器-svelte/` | `server.ts`、`src/App.svelte` `基本服务器-preact/` | `server.ts`、`src/mcp-app.tsx` `基本服务器固体/` | `server.ts`、`src/mcp-app.tsx` ### 参考示例示例|相关模式 ---|--- `示例/地图服务器/` |外部 API 集成 + CSP（`connectDomains`、`resourceDomains`） `示例/乐谱服务器/` |加载外部资源（声音字体）的库 `示例/pdf-server/` |二进制内容处理+仅限应用程序的帮助工具 ## 第 1 步：分析现有 Web 应用程序在编写任何代码之前，请检查现有的 Web 应用程序以计划需要更改的内容。 ### 调查什么 1. **数据源** — 应用程序如何获取数据？（URL 参数、API 调用、道具、硬编码、本地存储） 2. **外部依赖** — CDN 脚本、字体、API 端点、iframe 嵌入、WebSocket 连接 3. **构建系统** - 当前捆绑器（Webpack、Vite、Rollup、无）、框架（React、Vue、vanilla）、入口点 4. **用户交互** - 应用程序是否具有应映射到工具参数的输入/表单？ 5. **运行时检测** - 如何判断应用程序是否在 MCP 主机内运行（例如，检查当前来源、查询参数或是否 `window.parent !== window`）向用户展示发现并确认该方法。 ### 数据源映射在混合模式下，应用程序保留其现有数据源以供独立使用，并添加 MCP 等效项：独立数据源 | MCP 应用程序等效项 ---|--- URL查询参数| `ontoolinput` / `ontoolresult` `arguments` 或 `structedContent` REST API 调用 | `app.callServerTool()` 到服务器端工具，或使用 CSP `connectDomains` 保持直接 API 调用道具/组件输入| `ontoolinput` `参数` 本地存储/会话存储 |在沙盒 iframe 中不可用 — 通过“结构化内容”或服务器端状态传递 WebSocket 连接 |与 CSP `connectDomains` 保持一致，或通过仅限应用程序的工具转换为轮询硬编码数据 |移至工具“结构化内容”以使其动态化 ## 步骤 2：调查 CSP 要求 MCP Apps HTML 在沙盒 iframe 中运行，没有同源服务器。 **每个**外部来源都必须在 CSP 中声明 - 缺少来源会默默失败。 **在编写任何代码之前**，构建应用程序并调查它引用的所有来源： 1. 使用现有的构建命令构建应用程序 2. 在生成的 HTML、CSS 和 JS 中搜索**每个**来源（不仅仅是“外部”来源 - 每个网络请求都需要 CSP 批准） 3. 对于找到的每个起源，追溯到源头： * 如果它来自常量 → 通用（在 dev 和 prod 中相同） * 如果它来自环境变量或条件 → 请注意该机制并识别 dev 和 prod 值 4. 检查可能提出自己的请求（分析、错误跟踪等）的第三方库 **将您的发现**记录为三个列表，并注意每个来源是否是通用的、仅开发的或仅产品的： * **resourceDomains** ：提供图像、字体、样式、脚本的源 * **connectDomains** ：API/获取请求的来源 * **frameDomains** ：嵌套 iframe 的起源如果未找到源，则应用程序可能不需要自定义 CSP 域。 ## 步骤 3：设置 MCP 服务器使用工具和资源注册创建新的 MCP 服务器。这包装了 MCP 主机的现有 Web 应用程序。 ### 依赖关系 npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk zod npm install -D tsx vite vite-plugin-singlefile 使用“npm install”添加依赖项，而不是手动编写版本号。这可以让 npm 解析最新的兼容版本。切勿从内存中指定版本号。 ### 服务器代码创建`server.ts`：从“@modelcontextprotocol/sdk/server/mcp.js”导入{McpServer}；从“@modelcontextprotocol/sdk/server/stdio.js”导入{ StdioServerTransport }；从“@modelcontextprotocol/ext-apps/server”导入{registerAppTool，registerAppResource，RESOURCE_MIME_TYPE}；从“node:fs/promises”导入 fs；从“节点：路径”导入路径；从“zod”导入{z}； const server = new McpServer({ name: "my-app", version: "1.0.0" }); const resourceUri = "ui://my-app/mcp-app.html"; // 注册工具 - inputSchema 映射到应用程序的数据源 registerAppTool（服务器，“显示应用程序”，{ 描述：“显示具有给定参数的应用程序”， inputSchema: { query: z.string().describe("搜索查询") }, _meta: { ui: { resourcesUri } }, }，异步（参数）=> { // 如果需要，在服务器端处理 args 返回{ 内容：[{ 类型：“文本”，文本：`显示应用程序：${args.query}` }]，结构化内容：{查询：args.query}， }; }); // 注册HTML资源注册应用程序资源（服务器，{ uri：资源Uri，名称：“我的应用程序用户界面”， mime类型：RESOURCE_MIME_TYPE， // 如果需要，添加步骤 2 中的 CSP 域： // _meta: { ui: { connectDomains: ["api.example.com"], resourceDomains: ["cdn.example.com"] } }, }, 异步 () => { const html = 等待 fs.readFile( path.resolve(import.meta.dirname, "dist", "mcp-app.html"), “utf-8”，）；返回 { 内容：[{ uri：resourceUri，mimeType：RESOURCE_MIME_TYPE，文本：html }] }; }); // 启动服务器 const 传输 = new StdioServerTransport(); 等待服务器.connect(传输); ### 打包脚本添加到 `package.json`: { “脚本”：{ "build:ui": "vite 构建", “构建：服务器”：“tsc”， "build": "npm run build:ui && npm run build:server", “服务”：“tsx 服务器.ts” } } ## 步骤 4：调整构建管道 MCP 应用程序构建必须使用“vite-plugin-singlefile”生成单个 HTML 文件。独立 Web 应用程序构建保持不变。 ### 投票配置创建或更新`vite.config.ts`。如果应用程序已使用 Vite，请添加“vite-plugin-singlefile”和 MCP 应用程序构建的单独入口点。如果它使用另一个捆绑器，请仅为 MCP 应用程序构建添加 Vite 配置。从“vite”导入{defineConfig}；从“vite-plugin-singlefile”导入{ viteSingleFile }；导出默认的defineConfig({ 插件：[viteSingleFile()]，构建：{ outDir: "距离", 汇总选项：{ 输入：“mcp-app.html”， }, }, }); 根据需要添加特定于框架的 Vite 插件（例如，React 为“@vitejs/plugin-react”，Vue 为“@vitejs/plugin-vue”）。 ### HTML 入口点创建“mcp-app.html”作为 MCP 应用程序构建的单独入口点。这可以指向相同的应用程序代码 - 运行时检测会处理其余部分： <头> <元字符集=“UTF-8”/> <标题>MCP应用程序 <正文>

<脚本类型=“模块”src=“./src/main.ts”> ### 两阶段构建 1. Vite 捆绑 UI → `dist/mcp-app.html` （内联所有资产的单个文件） 2. 服务器单独编译（TypeScript → JavaScript）独立 Web 应用程序继续像以前一样构建和部署。 ## 步骤 5：在现有逻辑旁边添加 MCP 应用程序初始化这是核心步骤。不要替换应用程序的数据源，而是为 MCP 模式添加替代初始化路径。该应用程序在启动时检测其环境并从正确的来源读取参数。 ### 混合模式从“@modelcontextprotocol/ext-apps”导入{App，PostMessageTransport}； // 检测我们是否在 MCP 主机内运行。 // 选择适合应用程序的检测方法： // - 来源检查：window.location.origin !== 'https://myhost.com' // - 空原点（沙盒 iframe）：window.location.origin === 'null' // - 查询参数：new URL(location.href).searchParams.has('mcp') const isMcpApp = window.location.origin === "null"; 异步函数 getParameters(): Promise> { 如果（isMcpApp）{ // 作为 MCP 应用程序运行 — 从工具生命周期获取参数 const app = new App({ name: "我的应用程序", 版本: "1.0.0" }); // 在 connect() 之前注册处理程序 const params = 等待新 Promise>((resolve) => { app.ontoolresult = (结果) => 解析(结果.structedContent ?? {}); }); 等待 app.connect(new PostMessageTransport()); 返回参数； } 否则{ // 作为独立的 Web 应用程序运行 — 从 URL 获取参数 return Object.fromEntries(new URL(location.href).searchParams); } } 异步函数 main() { const params = 等待 getParameters(); 渲染应用程序（参数）； // 两种模式的渲染逻辑相同 } main().catch(console.error); ### URL 参数（混合） // 之前（仅限独立）： const query = new URL(location.href).searchParams.get("q"); 渲染应用程序（查询）； // 之后（混合）：异步函数 getQuery(): Promise { 如果（isMcpApp）{ const app = new App({ name: "我的应用程序", 版本: "1.0.0" }); 返回新的 Promise((resolve) => { app.ontoolinput = (params) => 解析(params.arguments?.q ?? ""); app.connect(new PostMessageTransport()); }); } 返回新的 URL(location.href).searchParams.get("q") ?? “”； } const 查询 = 等待 getQuery(); 渲染应用程序（查询）； // 渲染逻辑不变 ### API 调用（混合） // 之前（仅限独立）： const data = wait fetch("/api/data").then(r => r.json()); // 之后（混合）：异步函数 fetchData(): Promise { 如果（isMcpApp）{ const result = wait app.callServerTool("fetch-data", {}); 返回结果.结构化内容； } return fetch("/api/data").then(r => r.json()); } 或者使用 CSP `connectDomains` 在两种模式下保持直接 API 调用： // 如果 API 是外部的并且 CSP 声明了域，则 API 调用可以保持不变 // 在资源注册中声明connectDomains: ["api.example.com"] ### 本地存储/会话存储（混合） // 之前（仅限独立）： const 已保存 = localStorage.getItem("设置"); // 之后（混合）- localStorage 在沙盒 iframe 中不可用：函数 getSettings(): 任意 { 如果（isMcpApp）{ // 将通过工具结果提供返回空值； // 或默认值 } 返回 JSON.parse(localStorage.getItem("settings") ?? "null"); } ### 完整的混合示例从“@modelcontextprotocol/ext-apps”导入{App，PostMessageTransport，applyDocumentTheme，applyHostStyleVariables，applyHostFonts}； const isMcpApp = window.location.origin === "null"; 异步函数 initMcpApp(): Promise> { const app = new App({ name: "我的应用程序", 版本: "1.0.0" }); // 在 connect() 之前注册所有处理程序 const params = 等待新 Promise>((resolve) => { app.ontoolinput = (输入) => 解析(input.arguments ?? {}); }); app.onhostcontextchanged = (ctx) => { if (ctx.theme) applyDocumentTheme(ctx.theme); if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables); if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts); if (ctx.safeAreaInsets) { const { 上、右、下、左 } = ctx.safeAreaInsets; document.body.style.padding = `${top}px ${right}px ${bottom}px ${left}px`; } }; app.onteardown = async () => { 返回{}； }; 等待 app.connect(new PostMessageTransport()); 返回参数； } 异步函数 initStandaloneApp(): Promise> { return Object.fromEntries(new URL(location.href).searchParams); } 异步函数 main() { 常量参数 = isMcpApp ？等待 initMcpApp() : 等待 initStandaloneApp(); 渲染应用程序（参数）； // 相同的渲染逻辑——不需要 fork } main().catch(console.error); ## 步骤 6：添加主机样式集成（仅限 MCP 模式）作为 MCP 应用程序运行时，与主机样式集成以实现主题一致性。使用 CSS 变量后备，使应用程序在两种模式下看起来都正确。 **Vanilla JS** — 使用辅助函数：从“@modelcontextprotocol/ext-apps”导入{ applyDocumentTheme，applyHostStyleVariables，applyHostFonts }； app.onhostcontextchanged = (ctx) => { if (ctx.theme) applyDocumentTheme(ctx.theme); if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables); if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts); }; **React** — 使用钩子：从“@modelcontextprotocol/ext-apps/react”导入{ useApp，useHostStyles }； const { app } = useApp({ appInfo, 功能, onAppCreated }); useHostStyles(应用程序); **在 CSS 中使用变量** — 使用带有后备的 var() ，因此独立模式看起来仍然正确： .容器{ 背景：var（--颜色背景次要，#f5f5f5）；颜色：var(--color-text-primary, #333); 字体系列：var(--font-sans, system-ui); 边框半径：var(--border-radius-md, 8px); } 关键变量组：`--color-background-*`、`--color-text-*`、`--color-border-*`、`--font-sans`、`--font-mono`、`--font-text-*-size`、`--font-heading-*-size`、`--border-radius-*`。有关完整列表，请参阅“src/spec.types.ts”。 ## 可选增强功能 ### 仅应用程序辅助工具对于 UI 需要轮询或获取模型不需要直接调用的数据： registerAppTool(服务器, "刷新数据", { 描述：“获取 UI 的最新数据”， _meta: { ui: { resourcesUri, 可见性: ["app"] } }, }, 异步 () => { const data = 等待 getLatestData(); 返回 { 内容：[{ 类型：“文本”，文本：JSON.stringify(data) }] }; }); UI 通过 app.callServerTool("refresh-data", {})` 调用这些。 ### 流式传输部分输入对于大型工具输入，请使用“ontoolinputpartial”来显示 LLM 生成过程中的进度： app.ontoolinputpartial = (params) => { const args = params.arguments; // 修复部分 JSON - 始终有效渲染预览（参数）； }; app.ontoolinput = (参数) => { renderFull(params.arguments); }; ### 全屏模式 app.onhostcontextchanged = (ctx) => { if (ctx.availableDisplayModes?.includes("全屏")) { fullscreenBtn.style.display = "块"; } if (ctx.displayMode) { container.classList.toggle("全屏", ctx.displayMode === "全屏"); } }; 异步函数toggleFullscreen() { const newMode = currentMode ===“全屏”？ "inline" : "全屏"; const result = wait app.requestDisplayMode({ mode: newMode }); 当前模式=结果.模式； } ### 文本后备始终为非 UI 主机提供 `content` 数组：返回{ content: [{ type: "text", text: "结果的后备描述" }], StructuredContent: { /* UI 数据 */ }, }; ## 要避免的常见错误 1. **忘记外部来源的 CSP 声明** — 在沙盒 iframe 中默默失败 2. **在 MCP 模式下使用 `localStorage` / `sessionStorage` – 在沙盒 iframe 中不可用；使用后备或通过“结构化内容”传递 3. **缺少`vite-plugin-singlefile`** — 外部资源不会在 iframe 中加载 4. **在`connect()`之后注册处理程序** — 在调用`app.connect()`之前注册所有处理程序 5. **没有后备的硬编码样式** - 使用带有 `var(..., Fallback)` 的主机 CSS 变量，因此两种模式看起来都是正确的 6. **不处理安全区域插入** — 始终在 `onhostcontextchanged` 中应用 `ctx.safeAreaInsets` 7. **忘记文本`content`后备** - 始终为非UI主机提供`content`数组 8. **忘记资源注册** - 该工具引用必须具有匹配资源的“resourceUri” 9. **替换独立逻辑而不是分支**——保持原始数据源完整；在它们旁边添加 MCP 路径 ## 测试 ### 使用基本主机使用 basic-host 示例测试 MCP 应用程序模式： # 终端 1：构建并运行您的服务器 npm 运行构建 && npm 运行服务 # 终端 2：运行 basic-host （来自克隆的存储库） cd /tmp/mcp-ext-apps/examples/basic-host npm 安装 SERVERS='["http://localhost:3001/mcp"]' npm run start # 打开http://localhost:8080 使用服务器 URL 的 JSON 数组配置“SERVERS”（默认值：“http://localhost:3001/mcp”）。 ### 验证 1. **MCP模式**：应用程序在基本主机中加载，没有控制台错误 2. `ontoolinput` 处理程序使用工具参数触发 3. `ontoolresult` 处理程序触发工具结果 4. 主机样式（主题、字体、颜色）正确应用 5. 外部资源加载（如果配置了CSP域） 6. **独立模式**：直接在浏览器中打开应用程序仍然可以工作

转换网络应用程序

包含技能