📦 模型上下文协议 UI SDK

什么是 mcp-ui？ • 核心概念 • 安装 • 快速上手 • 使用指南 • 示例 • 支持的宿主 • 安全性 • 路线图 • 贡献 • 许可证

---

mcp-ui 首创了基于 MCP 的交互式 UI 概念，为 AI 工具提供了丰富的 Web 界面。与 Apps SDK 一起，这里开发的模式直接影响了 MCP Apps 规范，该规范标准化了通过协议传递 UI 的方式。

@mcp-ui/* 包实现了 MCP Apps 标准。@mcp-ui/client 是推荐用于 MCP Apps 宿主的 SDK。

@mcp-ui/* 包完全符合 MCP Apps 规范，可直接用于生产环境。

💡 什么是 mcp-ui？

mcp-ui 是一个实现 MCP Apps 标准的 SDK，用于在 MCP 上构建 UI。它提供：

• @mcp-ui/server (TypeScript)：使用 createUIResource 创建 UI 资源。可与 @modelcontextprotocol/ext-apps/server 中的 registerAppTool 和 registerAppResource 配合使用。
• @mcp-ui/client (TypeScript)：使用 AppRenderer（MCP Apps）或 UIResourceRenderer（旧版 MCP-UI 宿主）渲染工具 UI。
• mcp_ui_server (Ruby)：用 Ruby 创建 UI 资源。
• mcp-ui-server (Python)：用 Python 创建 UI 资源。

MCP Apps 模式通过 _meta.ui.resourceUri 将工具与其 UI 关联起来。宿主会获取并渲染 UI，同时显示工具的结果。

✨ 核心概念

MCP Apps 模式（推荐）

MCP Apps 标准通过 _meta.ui.resourceUri 将工具与其 UI 关联：

import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';

// 1. 创建 UI 资源
const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  content: { type: 'rawHtml', htmlString: '<h1>Widget</h1>' },
  encoding: 'text',
});

// 2. 注册资源处理器
registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
  contents: [widgetUI.resource]
}));

// 3. 注册带有 _meta 链接的工具
registerAppTool(server, 'show_widget', {
  description: '显示小部件',
  inputSchema: { query: z.string() },
  _meta: { ui: { resourceUri: widgetUI.resource.uri } }  // 将工具 → UI 链接
}, async ({ query }) => {
  return { content: [{ type: 'text', text: `查询: ${query}` }] };
});

宿主检测 _meta.ui.resourceUri，通过 resources/read 获取 UI，并使用 AppRenderer 渲染。

UIResource（数据格式）

UI 内容的底层有效载荷：

interface UIResource {
  type: 'resource';
  resource: {
    uri: string;       // 例如：ui://component/id
    mimeType: 'text/html;profile=mcp-app';
    text?: string;      // HTML 内容
    blob?: string;      // Base64 编码的 HTML 内容
  };
}

• uri：使用 ui:// 方案的唯一标识符
• mimeType：text/html;profile=mcp-app —— MCP Apps 标准 MIME 类型
• text vs. blob：纯文本或 Base64 编码的内容

客户端组件

AppRenderer（MCP Apps）

对于 MCP Apps 宿主，可以使用 AppRenderer 来渲染工具 UI：

import { AppRenderer } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  return (
    <AppRenderer
      client={client}
      toolName={toolName}
      sandbox={{ url: sandboxUrl }}
      toolInput={toolInput}
      toolResult={toolResult}
      onOpenLink={async ({ url }) => window.open(url)}
      onMessage={async (params) => console.log('消息:', params)}
    />
  );
}

关键属性：

• client：可选的 MCP 客户端，用于自动获取资源
• toolName：要渲染 UI 的工具名称
• sandbox：包含代理 URL 的沙盒配置
• toolInput / toolResult：工具的参数和结果
• onOpenLink / onMessage：处理 UI 请求的回调函数

UIResourceRenderer（旧版 MCP-UI）

对于将资源嵌入工具响应中的旧版宿主：

import { UIResourceRenderer } from '@mcp-ui/client';

<UIResourceRenderer
  resource={mcpResource.resource}
  onUIAction={(action) => console.log('动作:', action)}
/>

属性：

• resource：包含 uri、mimeType 和内容（text/blob）的资源对象
• onUIAction：用于处理工具、提示、链接、通知和意图等操作的回调函数

也可作为 Web 组件使用：

<ui-resource-renderer
  resource='{ "mimeType": "text/html", "text": "<h2>Hello!</h2>" }'
></ui-resource-renderer>

支持的资源类型

HTML (text/html;profile=mcp-app)

使用内部 <HTMLResourceRenderer /> 组件渲染，该组件会在 <iframe> 中显示内容。这适用于自包含的 HTML。

• mimeType：text/html;profile=mcp-app（MCP Apps 标准）

UI 行动

UI 片段必须能够与代理进行交互。在 mcp-ui 中，这是通过监听 UI 片段发送的事件并在宿主中作出响应来实现的（参见 onUIAction 属性）。例如，当用户点击按钮时，HTML 可能会触发工具调用，方法是发送一个事件，该事件会被客户端捕获并处理。

平台适配器

MCP-UI SDK 包含对特定宿主实现的适配器支持，使您的开放 MCP-UI 小部件能够在任何宿主环境下无缝运行。适配器会自动在 MCP-UI 的 postMessage 协议与宿主特定 API 之间进行转换。随着时间推移，当宿主逐渐兼容该开放规范时，这些适配器将不再需要。

可用适配器

Apps SDK 适配器

对于 Apps SDK 环境（例如 ChatGPT），此适配器会将 MCP-UI 协议转换为 Apps SDK API 调用（例如 window.openai）。

工作原理：

• 拦截来自您小部件的 MCP-UI postMessage 调用
• 将其转换为相应的 Apps SDK API 调用
• 处理双向通信（工具调用、提示词、状态管理）
• 透明运行——您现有的 MCP-UI 代码无需修改即可继续工作

使用示例：

import { createUIResource } from '@mcp-ui/server';

const htmlResource = await createUIResource({
  uri: 'ui://greeting/1',
  content: {
    type: 'rawHtml',
    htmlString: `
      <button onclick="window.parent.postMessage({ type: 'tool', payload: { toolName: 'myTool', params: {} } }, '*')">
        调用工具
      </button>
    `
  },
  encoding: 'text',
});

🏗️ 安装

TypeScript

# 使用 npm
npm install @mcp-ui/server @mcp-ui/client

# 或 pnpm
pnpm add @mcp-ui/server @mcp-ui/client

# 或 yarn
yarn add @mcp-ui/server @mcp-ui/client

Ruby

gem install mcp_ui_server

Python

# 使用 pip
pip install mcp-ui-server

# 或 uv
uv add mcp-ui-server

🚀 入门

您可以使用 GitMCP 让您的 IDE 访问 mcp-ui 的最新文档！

TypeScript（MCP Apps 模式）

1. 服务器端：使用 _meta.ui.resourceUri 创建带有 UI 的工具

   import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
   import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
   import { createUIResource } from '@mcp-ui/server';
   import { z } from 'zod';
   
   const server = new McpServer({ name: 'my-server', version: '1.0.0' });
   
   // 创建 UI 资源
   const widgetUI = await createUIResource({
     uri: 'ui://my-server/widget',
     content: { type: 'rawHtml', htmlString: '<h1>交互式小部件</h1>' },
     encoding: 'text',
   });
   
   // 注册资源处理器
   registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
     contents: [widgetUI.resource]
   }));
   
   // 注册带 _meta 链接的工具
   registerAppTool(server, 'show_widget', {
     description: '显示小部件',
     inputSchema: { query: z.string() },
     _meta: { ui: { resourceUri: widgetUI.resource.uri } }
   }, async ({ query }) => {
     return { content: [{ type: 'text', text: `查询: ${query}` }] };
   });
   

2. 客户端：使用 AppRenderer 渲染工具 UI

   import { AppRenderer } from '@mcp-ui/client';
   
   function ToolUI({ client, toolName, toolInput, toolResult }) {
     return (
       <AppRenderer
         client={client}
         toolName={toolName}
         sandbox={{ url: sandboxUrl }}
         toolInput={toolInput}
         toolResult={toolResult}
         onOpenLink={async ({ url }) => window.open(url)}
         onMessage={async (params) => console.log('消息:', params)}
       />
     );
   }
   

旧版 MCP-UI 模式

对于尚不支持 MCP Apps 的宿主：

import { UIResourceRenderer } from '@mcp-ui/client';

<UIResourceRenderer
  resource={mcpResource.resource}
  onUIAction={(action) => console.log('动作:', action)}
/>

Python

服务器端：构建您的 UI 资源

from mcp_ui_server import create_ui_resource

# 内联 HTML
html_resource = create_ui_resource({
  "uri": "ui://greeting/1",
  "content": { "type": "rawHtml", "htmlString": "<p>你好，来自 Python！</p>" },
  "encoding": "text",
})

# 外部 URL
external_url_resource = create_ui_resource({
  "uri": "ui://greeting/2",
  "content": { "type": "externalUrl", "iframeUrl": "https://example.com" },
  "encoding": "text",
})

Ruby

服务器端：构建您的 UI 资源

require 'mcp_ui_server'

# 内联 HTML
html_resource = McpUiServer.create_ui_resource(
  uri: 'ui://greeting/1',
  content: { type: :raw_html, htmlString: '<p>你好，来自 Ruby！</p>' },
  encoding: :text
)

# 外部 URL
external_url_resource = McpUiServer.create_ui_resource(
  uri: 'ui://greeting/2',
  content: { type: :external_url, iframeUrl: 'https://example.com' },
  encoding: :text
)

# remote-dom
remote_dom_resource = McpUiServer.create_ui_resource(
  uri: 'ui://remote-component/action-button',
  content: {
    type: :remote_dom,
    script: "
     const button = document.createElement('ui-button');
     button.setAttribute('label', '点击我，来自 Ruby！');
     button.addEventListener('press', () => {
       window.parent.postMessage({ type: 'tool', payload: { toolName: 'uiInteraction', params: { action: 'button-click', from: 'ruby-remote-dom' } } }, '*');
     });
     root.appendChild(button);
     ",
    framework: :react,
  },
  encoding: :text
)

🚶 演示教程

如需详细了解如何将 mcp-ui 集成到您自己的服务器中，请访问 mcp-ui 文档网站 上的完整服务器教程：

• TypeScript 服务器教程
• Ruby 服务器教程
• Python 服务器教程

这些指南将向您展示如何在现有服务器上添加 mcp-ui 端点、创建返回 UI 资源的工具，并使用 ui-inspector 测试您的设置！

🌍 示例

客户端示例

• Goose - 开源 AI 代理，支持 mcp-ui。
• LibreChat - 增强版 ChatGPT 克隆，支持 mcp-ui。
• ui-inspector - 检查本地启用 mcp-ui 的服务器。
• MCP-UI Chat - 使用 mcp-ui 客户端构建的交互式聊天。请查看托管版本！
• MCP-UI RemoteDOM 演示（examples/remote-dom-demo）- 用于测试 RemoteDOM 资源的本地演示应用。
• MCP-UI Web 组件演示（examples/wc-demo）- 用于测试宿主中 Web 组件集成的本地演示应用。

服务器示例

• TypeScript: 一个功能齐全的服务器，已部署到托管环境以便于测试。
  • typescript-server-demo：一个简单的 TypeScript 服务器，演示如何生成 UI 资源。
  • server: 一个功能齐全的 TypeScript 服务器，已部署到 Cloudflare 托管环境以方便测试。
    • HTTP 流式传输: https://remote-mcp-server-authless.idosalomon.workers.dev/mcp
    • SSE: https://remote-mcp-server-authless.idosalomon.workers.dev/sse
• Ruby: 一个基础的演示服务器，展示如何将 mcp_ui_server 和 mcp gem 结合使用。
• Python: 一个简单的演示服务器，展示如何使用 mcp-ui-server Python 包。
• XMCP - 带有 mcp-ui 入门示例的 TypeScript MCP 框架。

将这些 URL 放入任何兼容 MCP 的宿主中，即可查看 mcp-ui 的实际效果。如需支持的本地检查工具，请参阅 ui-inspector。

💻 支持的宿主

@mcp-ui/* 包既适用于 MCP Apps 宿主，也适用于旧版 MCP-UI 宿主。

MCP Apps 宿主

这些宿主实现了MCP Apps 规范，并支持带有 _meta.ui.resourceUri 的工具：

宿主	备注
Claude	✅
VSCode
Postman
Goose
MCPJam
LibreChat
mcp-use
Smithery

旧版 MCP-UI 宿主

这些宿主期望在工具响应中直接嵌入 UI 资源：

宿主	渲染	UI 操作	备注
Nanobot	✅	✅
MCPJam	✅	✅
Postman	✅	⚠️
Goose	✅	⚠️
LibreChat	✅	⚠️
Smithery	✅	❌
fast-agent	✅	❌

需要适配器的宿主

宿主	协议	备注
ChatGPT	Apps SDK	指南

图例: ✅ 支持 · ⚠️ 部分支持 · ❌ 尚未支持

🔒 安全性

宿主和用户的安全性是 mcp-ui 的首要关注点之一。在所有内容类型中，远程代码均在沙箱 iframe 中执行。

🛣️ 路线图

• 添加在线 Playground
• 扩展 UI 操作 API（超越工具调用）
• 支持 Web 组件
• 支持 Remote-DOM
• 添加组件库（进行中）
• 为其他编程语言添加 SDK（进行中；Ruby、Python 已可用）
• 支持更多前端框架
• 探索提供 UI SDK（除了客户端和服务器 SDK 之外）
• 添加声明式 UI 内容类型
• 支持生成式 UI？

核心团队

mcp-ui 是由 Ido Salomon 与 Liad Yosef 合作开展的项目。

🤝 贡献

欢迎贡献代码、提出想法以及报告问题！请参阅贡献指南开始参与。

📄 许可证

Apache 许可证 2.0 © MCP-UI 作者

免责声明

本项目按“原样”提供，不提供任何形式的保证。mcp-ui 的作者及贡献者对因使用本软件而产生的任何损害、损失或问题概不负责。请自行承担风险使用。

mcp-ui 快速上手指南

mcp-ui 是一个基于 MCP (Model Context Protocol) 标准的 SDK，旨在为 AI 工具提供丰富的交互式 Web 界面。它实现了 MCP Apps 规范，允许开发者将 UI 组件与后端工具关联，并在支持的主机（Host）中渲染。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Windows, macOS, 或 Linux
• 运行时依赖 (根据你选择的语言任选其一):
  • Node.js: v18+ (推荐用于 TypeScript/JavaScript 开发)
  • Python: v3.9+
  • Ruby: v3.0+
• 包管理器: npm, pnpm, yarn, pip, uv 或 gem
• 前置知识: 了解 MCP 协议基础概念及基本的 Web 开发知识 (HTML/JS)。

安装步骤

根据你的技术栈选择对应的安装命令。

TypeScript / JavaScript

推荐使用 pnpm 或 npm 安装服务端和客户端 SDK：

# 使用 npm
npm install @mcp-ui/server @mcp-ui/client

# 或使用 pnpm
pnpm add @mcp-ui/server @mcp-ui/client

# 或使用 yarn
yarn add @mcp-ui/server @mcp-ui/client

Python

# 使用 pip
pip install mcp-ui-server

# 或使用 uv (推荐)
uv add mcp-ui-server

Ruby

gem install mcp_ui_server

基本使用

mcp-ui 的核心工作流分为两步：服务端创建带 UI 的工具 和 客户端渲染 UI。以下是基于推荐的 MCP Apps 模式 的最简示例。

1. 服务端：创建关联 UI 的工具 (TypeScript)

在服务端，你需要创建一个 UI 资源，并将其 URI 通过 _meta.ui.resourceUri 绑定到工具定义中。

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';
import { z } from 'zod';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

// 1. 创建 UI 资源 (例如一个简单的 HTML 组件)
const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  content: { type: 'rawHtml', htmlString: '<h1>Interactive Widget</h1><button id="btn">Click Me</button>' },
  encoding: 'text',
});

// 2. 注册资源处理器，使主机可以获取该 UI
registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
  contents: [widgetUI.resource]
}));

// 3. 注册工具，并通过 _meta 链接到上述 UI
registerAppTool(server, 'show_widget', {
  description: 'Show an interactive widget',
  inputSchema: { query: z.string() },
  _meta: { ui: { resourceUri: widgetUI.resource.uri } } // 关键：建立工具与 UI 的链接
}, async ({ query }) => {
  return { content: [{ type: 'text', text: `Query received: ${query}` }] };
});

2. 客户端：渲染 UI (React/TypeScript)

在支持 MCP Apps 的主机应用中，使用 AppRenderer 组件自动获取并渲染工具关联的界面。

import { AppRenderer } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  return (
    <AppRenderer
      client={client}                // MCP 客户端实例
      toolName={toolName}            // 要渲染的工具名称
      sandbox={{ url: sandboxUrl }}  // 沙箱配置 (代理 URL)
      toolInput={toolInput}          // 工具输入参数
      toolResult={toolResult}        // 工具执行结果
      onOpenLink={async ({ url }) => window.open(url)} // 处理链接打开
      onMessage={async (params) => console.log('Message:', params)} // 处理 UI 消息
    />
  );
}

其他语言示例 (Python)

如果你使用 Python 编写服务端逻辑，创建 UI 资源的代码如下：

from mcp_ui_server import create_ui_resource

# 创建内联 HTML 资源
html_resource = create_ui_resource({
  "uri": "ui://greeting/1",
  "content": { "type": "rawHtml", "htmlString": "<p>Hello, from Python!</p>" },
  "encoding": "text",
})

# 或者引用外部 URL
external_url_resource = create_ui_resource({
  "uri": "ui://greeting/2",
  "content": { "type": "externalUrl", "iframeUrl": "https://example.com" },
  "encoding": "text",
})

交互说明

UI 组件内部可以通过 postMessage 与主机通信。例如，在 HTML 中触发工具调用：

<button onclick="window.parent.postMessage({ 
  type: 'tool', 
  payload: { toolName: 'myTool', params: {} } 
}, '*')">
  Call Tool
</button>

主机将通过 onMessage 回调捕获此事件并执行相应操作。