MCP Apps (ext-apps)

项目定位#

MCP Apps 是 Model Context Protocol (MCP) 的扩展协议，定义了一套标准协议允许 AI 模型通过 MCP 服务器返回交互式的 HTML UI，而不仅仅是文本或 Markdown。它包含正式的协议规范、TypeScript SDK 以及丰富的示例库。

核心价值：解决了传统 AI 聊天界面交互能力受限的问题。使得用户可以在对话流中直接操作图表、填写表单、拖拽设计画布或播放视频，并将这些交互数据回传给模型，实现"对话式操作"闭环。

扩展标识符：io.modelcontextprotocol/ui

核心特性#

UI 资源机制#

• 资源标识：使用 ui:// URI scheme 在 MCP Server 上声明 UI 资源
• 专用 MIME 类型：text/html;profile=mcp-app，用于区分普通网页与 MCP 应用
• Tool-UI 绑定：通过 _meta.ui.resourceUri 字段关联特定 UI 资源
• 可见性控制：visibility: ["model", "app"] 或 ["app"]（仅前端可见，避免污染模型上下文）

通信与生命周期#

• 通信机制：基于 window.postMessage 的 MCP JSON-RPC 2.0 消息传递
• 生命周期消息：
  • ui/initialize / ui/notifications/initialized
  • ui/notifications/tool-input / tool-result / tool-cancelled
  • ui/notifications/size-changed
  • ui/resource-teardown

显示与样式#

• 显示模式：inline（嵌入对话流）、fullscreen（全屏）、pip（画中画）
• 主题注入：通过 HostContext.styles.variables 传递 CSS 变量（背景、文字、边框、字体、阴影、半径等）
• 支持明暗主题自动适配与自定义字体注入
• HostContext 传递：theme / styles / containerDimensions / locale / timeZone / safeAreaInsets

安全与沙箱#

• 强沙箱隔离：强制在 <iframe> 中运行，包含 allow-scripts 和 allow-same-origin
• CSP 配置：可声明 connectDomains / resourceDomains / frameDomains / baseUriDomains 白名单
• 默认严格 CSP，Host 不得放行未声明的域名
• Web Host 代理模式：双重 Iframe（Sandbox Proxy）架构，确保 Host 与 App 的源隔离

SDK 模块#

• @modelcontextprotocol/ext-apps：核心 SDK，包含 App 类与 PostMessageTransport
• @modelcontextprotocol/ext-apps/react：React hooks（useApp、useHostStyles 等）
• @modelcontextprotocol/ext-apps/app-bridge：在聊天客户端中嵌入与通信 View 的桥接库
• @modelcontextprotocol/ext-apps/server：在 MCP server 上注册工具与资源

快速开始#

安装 SDK#

npm install -S @modelcontextprotocol/ext-apps

本地运行示例#

git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps
npm install
npm start
# 访问 http://localhost:8080/ 查看所有示例

集成到 MCP 客户端（如 Claude Desktop）#

{
  "mcpServers": {
    "map-example": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-map", "--stdio"]
    }
  }
}

Agent Skills (构建工具)#

• create-mcp-app：快速创建新应用
• migrate-oai-app：迁移 OpenAI 应用
• add-app-to-server：将应用添加到现有 MCP Server
• convert-web-app：将普通 Web 应用转换为 MCP App

示例生态#

可视化类：Map (Leaflet)、Three.js、ShaderToy、Cohort Heatmap 工具/编辑器：Sheet Music、Wiki Explorer、Scenario Modeler、Budget Allocator、Customer Segmentation 媒体类：Video Resource、PDF Server、System Monitor、Transcript、QR Code (Python) 多框架示例：React、Vue、Svelte、Preact、Solid、Vanilla JS

架构组件#

• Host：运行 AI 对话的客户端（如 Claude Desktop、VS Code 插件或 Web 页面）
• MCP Server：提供工具逻辑与 UI 资源（HTML/JS/CSS）
• UI View (App)：运行在 Iframe 沙箱中的前端应用，充当 MCP Client 角色