# 将 UI 添加到 MCP 服务器使用 MCP Apps SDK (`@modelcontextprotocol/ext-apps`) 通过交互式 UI 丰富现有 MCP 服务器的工具。 ## 它是如何工作的现有工具与在主持人对话中内联呈现的 HTML 资源配对。该工具继续适用于纯文本客户端——UI 是一种增强，而不是替代。每个受益于 UI 的工具都通过“_meta.ui.resourceUri”链接到资源，并且当调用该工具时，主机会在沙盒 iframe 中呈现该资源。 ## 获取参考代码克隆 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`、`getUiCapability`、工具可见性选项 `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` 挂钩 ### 关键示例（混合工具模式）这些示例演示了具有应用程序增强工具和普通工具的服务器 - 您要添加的确切模式：示例|图案 ---|--- `示例/地图服务器/` | `show-map`（应用程序工具）+ `geocode`（普通工具） `示例/pdf-server/` | `display_pdf`（应用程序工具）+ `list_pdfs`（普通工具）+ `read_pdf_bytes`（仅限应用程序工具） `示例/系统监控服务器/` | `get-system-info`（应用程序工具）+ `poll-system-stats`（仅限应用程序的轮询工具） ### 框架模板从 `/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` ## 步骤 1：分析现有工具在编写任何代码之前，请分析服务器的现有工具并确定哪些工具可以从 UI 中受益。 1.读取服务器源码并列出所有注册的工具 2. 对于每个工具，评估它是否会受益于 UI（返回可可视化的数据、涉及用户交互等）与纯文本（简单查找、实用功能） 3. 确定可以成为**仅应用程序助手**的工具（UI 需要轮询/获取但模型不需要直接调用的数据） 4. 向用户展示分析结果并确认需要增强哪些工具 ### 决策框架刀具输出类型| UI福利|示例 ---|---|--- 结构化数据/列表/表格|高——交互式表格、搜索、过滤|项目列表、搜索结果随时间变化的指标/数字 |高 — 图表、仪表、仪表板 |系统统计、分析媒体/丰富内容 |高 — 查看器、播放器、渲染器 |地图、PDF、图像、视频简单的文字/确认|低——文字很好| “文件已创建”、“设置已更新” 其他工具的数据 |考虑仅应用程序 |轮询端点、块加载器 ## 步骤 2：添加依赖项 npm 安装@modelcontextprotocol/ext-apps npm install -D vite vite-plugin-singlefile 如果需要的话，加上特定于框架的依赖项（例如，React 的“react”、“react-dom”、“@vitejs/plugin-react”）。使用“npm install”添加依赖项，而不是手动编写版本号。这可以让 npm 解析最新的兼容版本。切勿从内存中指定版本号。 ## 步骤 3：设置构建管道 ### 投票配置使用“vite-plugin-singlefile”创建“vite.config.ts”，将 UI 捆绑到单个 HTML 文件中：从“vite”导入{defineConfig}；从“vite-plugin-singlefile”导入{ viteSingleFile }；导出默认的defineConfig({ 插件：[viteSingleFile()]，构建：{ outDir: "距离", 汇总选项：{ input: "mcp-app.html", // 每个 UI 一个，或一个共享条目 }, }, }); ### HTML 入口点创建 `mcp-app.html` （如果工具需要不同的视图，则为每个不同的 UI 创建一个）： <头> <元字符集=“UTF-8”/> <标题>MCP应用程序 <正文>

<脚本类型=“模块”src=“./src/mcp-app.ts”> ### 构建脚本将构建脚本添加到“package.json”。 UI 必须在服务器代码捆绑之前构建： { “脚本”：{ "build:ui": "vite 构建", “构建：服务器”：“tsc”， "build": "npm run build:ui && npm run build:server", “服务”：“tsx 服务器.ts” } } ## 步骤 4：将工具转换为应用程序工具将普通 MCP 工具转变为带有 UI 的应用程序工具。 **之前**（普通 MCP 工具）： server.tool("my-tool", { param: z.string() }, async (args) => { const data = 等待 fetchData(args.param); 返回 { 内容：[{ 类型：“文本”，文本：JSON.stringify(data) }] }; }); **之后**（带 UI 的应用程序工具）：从“@modelcontextprotocol/ext-apps/server”导入{registerAppTool，registerAppResource，RESOURCE_MIME_TYPE}； const resourceUri = "ui://my-tool/mcp-app.html"; registerAppTool(服务器, "我的工具", { 描述：“用交互式用户界面显示数据”， inputSchema: { 参数: z.string() }, _meta: { ui: { resourcesUri } }, }，异步（参数）=> { const data = 等待 fetchData(args.param); 返回{ content: [{ type: "text", text: JSON.stringify(data) }], // 非 UI 主机的文本回退 StructuredContent: { data }, // UI 的结构化数据 }; }); 重点指导： * **始终保留“内容”数组**，并为纯文本客户端提供文本后备 * 为 UI 需要渲染的数据添加“structuralContent” * 通过 `_meta.ui.resourceUri` 将工具链接到其资源 * 保持不受益于 UI 的工具不变——它们仍然是普通工具 ## 步骤5：注册资源注册 HTML 资源以便主机可以获取它：从“node:fs/promises”导入 fs；从“节点：路径”导入路径； const resourceUri = "ui://my-tool/mcp-app.html"; 注册应用程序资源（服务器，{ uri：资源Uri， name: "我的工具用户界面", mime类型：RESOURCE_MIME_TYPE， }, 异步 () => { const html = 等待 fs.readFile( path.resolve(import.meta.dirname, "dist", "mcp-app.html"), “utf-8”，）；返回 { 内容：[{ uri：resourceUri，mimeType：RESOURCE_MIME_TYPE，文本：html }] }; }); 如果多个工具共享相同的 UI，它们可以引用相同的“resourceUri”和相同的资源注册。 ## 第 6 步：构建 UI ### 处理程序注册在调用 `app.connect()` 之前注册所有处理程序：从“@modelcontextprotocol/ext-apps”导入{App，PostMessageTransport，applyDocumentTheme，applyHostStyleVariables，applyHostFonts}； const app = new App({ name: "我的应用程序", 版本: "1.0.0" }); app.ontoolinput = (参数) => { // 使用 params.arguments 和/或 params.structedContent 渲染 UI }; app.ontoolresult = (结果) => { // 使用最终工具结果更新 UI }; 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()); ### 主机造型使用主机 CSS 变量进行主题集成： .容器{ 背景：var(--颜色背景-次要); 颜色：var(--颜色文本-primary); 字体系列：var(--font-sans); 边框半径：var(--border-radius-md); } 关键变量组：`--color-background-*`、`--color-text-*`、`--color-border-*`、`--font-sans`、`--font-mono`、`--font-text-*-size`、`--font-heading-*-size`、`--border-radius-*`。有关完整列表，请参阅“src/spec.types.ts”。对于 React 应用程序，请使用 `useApp` 和 `useHostStyles` 挂钩 - 请参阅 `basic-server-react/` 了解模式。 ## 可选增强功能 ### 仅应用程序辅助工具 UI 调用但模型不需要直接调用的工具（轮询、分页、块加载）： registerAppTool(服务器, "轮询数据", { 描述：“轮询 UI 的最新数据”， _meta: { ui: { resourcesUri, 可见性: ["app"] } }, }, 异步 () => { const data = 等待 getLatestData(); 返回 { 内容：[{ 类型：“文本”，文本：JSON.stringify(data) }] }; }); UI 通过 app.callServerTool("poll-data", {})` 调用这些。 ### CSP 配置如果 UI 需要加载外部资源（字体、API、CDN），请声明域：注册应用程序资源（服务器，{ uri：资源Uri， name: "我的工具用户界面", mime类型：RESOURCE_MIME_TYPE， _元：{ 用户界面：{ connectDomains: ["api.example.com"], // 获取/XHR 目标 resourceDomains: ["cdn.example.com"], // 脚本、样式、图像 frameDomains: ["embed.example.com"], // 嵌套 iframe }, }, }, async () => { /* ... */ }); ### 流式传输部分输入对于大型工具输入，显示 LLM 生成期间的进度： app.ontoolinputpartial = (params) => { const args = params.arguments; // 修复部分 JSON - 始终有效 // 使用部分数据渲染预览 }; app.ontoolinput = (参数) => { // 最终完整输入 - 切换到完整渲染 }; ### 使用 `getUiCapability()` 进行优雅降级仅当客户端支持 UI 时有条件地注册 App 工具，回退到纯文本工具：从“@modelcontextprotocol/ext-apps/server”导入{ getUiCapability，registerAppTool，RESOURCE_MIME_TYPE }； server.server.oninitialized = () => { const clientCapability = server.server.getClientCapability(); const uiCap = getUiCapability(clientCapability); if (uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE)) { // 客户端支持UI——注册App工具 registerAppTool(服务器, "我的工具", { 描述：“通过交互式用户界面显示数据”， _meta: { ui: { resourcesUri } }, }、appToolHandler); } 否则{ // 纯文本客户端——注册普通工具 server.tool("my-tool", "显示数据", { param: z.string() }, plainToolHandler); } }; ### 全屏模式允许 UI 扩展到全屏： 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 }); 当前模式=结果.模式； } ## 要避免的常见错误 1. **忘记文本`content`后备** - 对于非 UI 主机，始终将 `content` 数组包含在文本中 2. **在`connect()`之后注册处理程序** — 在调用`app.connect()`之前注册所有处理程序 3. **缺少`vite-plugin-singlefile`** — 没有它，资源将无法加载到沙盒 iframe 中 4. **忘记资源注册** - 该工具引用必须具有匹配资源的“resourceUri” 5. **硬编码样式** — 使用宿主 CSS 变量 (`var(--color-*)`) 进行主题集成 6. **不处理安全区域插入** — 始终在 `onhostcontextchanged` 中应用 `ctx.safeAreaInsets` ## 测试 ### 使用基本主机使用 basic-host 示例测试增强型服务器： # 终端 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. 普通工具仍然可以工作并返回文本输出 2. 应用工具在 iframe 中渲染 UI 3. `ontoolinput` 处理程序使用工具参数触发 4. `ontoolresult` 处理程序触发工具结果 5. 主机样式（主题、字体、颜色）正确应用

添加应用程序到服务器

包含技能