用途:把现有 MCP 服务器的工具增强为带内联交互 UI 的 App 工具,工具本身仍可服务纯文本客户端,UI 只是增强而非替代。每个工具通过 _meta.ui.resourceUri 关联一个 HTML 资源,宿主在调用工具时于沙箱 iframe 中渲染该资源。
主要能力与流程:先分析现有工具,判断哪些适合 UI(列表/表格、指标图表、媒体查看器等),呈现分析并与用户确认;再安装依赖 @modelcontextprotocol/ext-apps 及 vite、vite-plugin-singlefile;用 Vite 将 UI 打包为单个 HTML(配 mcp-app.html 入口);用 registerAppTool 将普通工具转为 App 工具,保留 content 文本回退并补充 structuredContent,用 registerAppResource 注册 HTML 资源;在 UI 端先注册全部处理器(ontoolinput、ontoolresult、onhostcontextchanged、onteardown)再调用 app.connect(new PostMessageTransport()),并使用宿主 CSS 变量(如 --color-background-secondary、--font-sans)适配主题与字体。
可选增强:app-only 辅助工具(visibility: ["app"],UI 通过 app.callServerTool 调用)、CSP 域名声明(connectDomains、resourceDomains、frameDomains)、ontoolinputpartial 流式部分输入预览、getUiCapability() 优雅降级、全屏显示模式。
适用场景:需要列表搜索筛选、图表仪表盘、地图/PDF/图片/视频查看器等等需交互渲染的 MCP 工具。
限制与注意:须始终保留文本回退;处理器必须在 connect() 前注册;须使用 vite-plugin-singlefile,否则沙箱 iframe 资源无法加载;工具引用的 resourceUri 必须有匹配资源注册;不要硬编码样式;须处理 ctx.safeAreaInsets;不建议对简单文本输出类工具加 UI。参考代码需克隆 SDK 仓库。测试用 basic-host,配置 SERVERS 为服务器 URL 的 JSON 数组。