MCP用户界面+WebMCP
AI助手和嵌入式web应用程序之间的双向集成
______________________________________________________________________
现场试用
在线聊天界面： mcp-ui.mcp-b.ai 完整应用程序演示： beatthelankers.com
访问 beatthelankers.com 查看带有嵌入式iframe的完整应用程序。使用 MCP-B Chrome扩展程序.
______________________________________________________________________
这有什么作用
流量：
- AI呼叫
showTicTacToeGame - MCP服务器返回带有iframe的UI资源
- 游戏加载和注册
tictactoe_move,tictactoe_reset等等。 - AI现在可以使用动态注册的工具玩游戏
此模式适用于任何嵌入式应用程序：表单、可视化、交互式演示、配置UI。
快速开始
创建新应用程序（推荐）
使用我们的交互式CLI构建新项目：
npx @mcp-b/create-webmcp-app从以下选项中选择：
- 香草 -纯HTML/CSS/JavaScript（无构建步骤！）
- 反应 -React+TypeScript+Vite（功能齐全）
然后：
cd your-project
pnpm dev或者运行演示
# Install dependencies
pnpm install
# Run both apps (MCP server + Chat UI)
pnpm dev打开http://localhost:5173然后让人工智能给你看一个TicTacToe游戏。
需求
- Node.js 24.3.0+（参见
.nvmrc) - pnpm 10.14.0+
建筑
关键原则：解耦架构
聊天UI和嵌入式应用程序之间没有自定义知识。 它们仅通过标准协议进行通信：
- 聊天界面 通过MCP协议（HTTP/SSE）发现工具
- 嵌入式应用程序 通过WebMCP协议注册工具（postMessage）
- 提示和工具 在MCP服务器中声明的内容会自动被发现，并在UI中可用
没有硬编码，没有配置文件。只是基于标准的协议，支持动态组合。
WebMCP与MCP-B
WebMCP 是浏览器中双向工具注册的W3C标准规范，定义了 navigator.modelContext API MCP-B 是使WebMCP今天可用的参考实现和polyfill。
- WebMCP：基于标准的API规范（W3C网络机器学习社区小组）
- MCP-B：参考实施情况，提供：
- Polyfill用于 navigator.modelContext 浏览器支持之前 - WebMCP协议与WebMCP协议之间的转换桥梁 - 用于测试的浏览器扩展
系统架构
flowchart TB
subgraph ChatUI["Chat UI Browser Context"]
UI[AI Chat Interface]
HTTP_CLIENT["HTTP MCP Client
@modelcontextprotocol/sdk"]
WEBMCP_MGR["WebMCP Integration
useWebMCPIntegration"]
IFRAME["Iframe Container
Side Panel"]
UI --> HTTP_CLIENT
UI --> WEBMCP_MGR
WEBMCP_MGR --> IFRAME
end
subgraph MCPServer["MCP Server - Cloudflare Worker"]
TOOLS["Tool Registry
showTicTacToeGame, etc."]
ASSETS["Static Asset Server
Serves mini-apps"]
TOOLS -.->|Returns UI Resource| ASSETS
end
subgraph EmbeddedApp["Embedded App Iframe Context"]
APP["Mini-App React
TicTacToe, etc."]
WEBMCP_INIT["MCP-B Polyfill
@mcp-b/global"]
HOOKS["useWebMCP Hooks
@mcp-b/react-webmcp"]
TRANSPORT_CHILD["IframeChildTransport
@mcp-b/transports"]
APP --> HOOKS
HOOKS --> WEBMCP_INIT
WEBMCP_INIT --> TRANSPORT_CHILD
end
HTTP_CLIENT |HTTP/SSE MCP Protocol| TOOLS
ASSETS -->|iframe src| APP
WEBMCP_MGR |IframeParentTransport postMessage| TRANSPORT_CHILD
style WEBMCP_INIT fill:#e1f5ff
style HOOKS fill:#e1f5ff
style TRANSPORT_CHILD fill:#e1f5ff
style WEBMCP_MGR fill:#e1f5ff完整流程：双向沟通的工具调用
sequenceDiagram
participant User
participant AI as AI Assistant
participant HTTP as HTTP MCP Client
participant Server as MCP Server
participant Iframe as Iframe Container
participant App as Embedded App
participant WebMCP as WebMCP Manager
%% Initial tool call that returns UI
User->>AI: "Show me TicTacToe"
AI->>HTTP: callTool(showTicTacToeGame)
HTTP->>Server: HTTP Request
Server-->>HTTP: UI Resource (externalUrl)
HTTP-->>AI: Tool Result
AI->>Iframe: Render UI Resource
%% Iframe loads and WebMCP connection established
Note over Iframe,App: Iframe loads mini-app
Iframe->>App: Load src URL
App->>App: initializeWebModelContext
(@mcp-b/global)
App->>WebMCP: postMessage(iframe-ready)
WebMCP->>App: postMessage(parent-ready)
%% MCP-B Transport Setup
Note over WebMCP,App: MCP-B Transport Layer
WebMCP->>WebMCP: Create IframeParentTransport
(@mcp-b/transports)
App->>App: IframeChildTransport ready
(auto-created by @mcp-b/global)
WebMCP->>App: MCP: listTools()
App-->>WebMCP: Tools: [tictactoe_move, tictactoe_reset, ...]
WebMCP->>WebMCP: registerWebMcpTools(tools, sourceId)
%% Tool registration complete
Note over AI,App: Embedded tools now available
AI->>AI: Merge HTTP tools + WebMCP tools
%% User invokes WebMCP tool
User->>AI: "Make a move at position 4"
AI->>WebMCP: callTool(tictactoe_move, {position: 4})
WebMCP->>App: MCP: callTool via IframeParentTransport
App->>App: useWebMCP handler executes
App->>App: Update game state
App-->>WebMCP: Tool Result (markdown + state)
WebMCP-->>AI: Tool Result
AI-->>User: "Moved to position 4..."
%% Dynamic tool updates
Note over App,WebMCP: Tool list can change dynamically
App->>WebMCP: MCP: notifications/tools/list_changed
WebMCP->>App: MCP: listTools()
App-->>WebMCP: Updated tool list
WebMCP->>WebMCP: registerWebMcpTools(newTools, sourceId)关键组件
聊天UI（父上下文）
- HTTP MCP客户端 (
@modelcontextprotocol/sdk)：通过HTTP/SSE连接到远程MCP服务器以获取初始工具 - WebMCP集成 (使用WebMPCIntegration。ts)：从iframe管理WebMCP客户端和工具
- Iframe生命周期 (useIframeLifecycle.ts)：为每个iframe设置MCP-B传输
- 刀具路径：根据源ID将调用路由到HTTP MCP或WebMCP客户端
- IframeParentTransport (
@mcp-b/transports)：与嵌入式应用程序的双向通信渠道
嵌入式应用程序（Iframe上下文）
- MCP-B聚合物填充物 (
@mcp-b/global)：实施navigator.modelContextAPI - 使用WebMCP钩子 (
@mcp-b/react-webmcp)：使用自动生命周期管理注册工具 - Iframe儿童交通 (
@mcp-b/transports)：通过postMessage接收家长的工具调用 - 家长沟通 (useParentCommunication.ts)：准备协议和通知
MCP服务器
- 工具注册表：显示以下工具
showTicTacToeGame返回UI资源 - UI资源类型：支持
externalUrl,rawHtml，以及remoteDom - 静态资产：为iframe嵌入提供捆绑的迷你应用程序
MCP UI资源
支持三种资源类型(了解更多):
| 类型 | 用例 | 实现 |
|---|---|---|
externalUrl | 嵌入式迷你应用程序 | 带URL的iframe |
rawHtml | 简单标记 | 山宁泰HTML |
remoteDom | 动态内容 | JavaScript生成的DOM |
→ MCP-UI服务器SDK | → MCP-UI客户端SDK
WebMCP工具注册
import { useWebMCP } from '@mcp-b/react-webmcp';
useWebMCP({
name: "tictactoe_move",
description: "Make a move at position",
schema: z.object({
position: z.number().min(0).max(8)
}),
handler: async ({ position }) => {
// Execute move
return {
content: [{
type: "text",
text: `Moved to position ${position}`
}]
};
}
});AI可以立即调用 tictactoe_move 就好像它是一个本地MCP工具。
MCP-B包：
→ MCP-B快速入门 | → MCP-B示例 |
包裹
应用
聊天用户界面
React聊天界面与MCP客户端和WebMCP集成。通过HTTP连接到MCP服务器，显示UI资源，处理动态工具注册。
技术： React 19、Vite、顺风CSS 4、Vercel AI SDK
mcp服务器
Cloudflare Workers上的MCP服务器实现。提供静态迷你应用程序，通过UI扩展实现MCP协议。
技术： Cloudflare Workers，Hono，@modelcontextprotocol/sdk
创建webmcp应用程序
交互式CLI，用于通过模板选择构建新的WebMCP应用程序。
技术： Node.js、TypeScript
模板
反应
React+TypeScript+Vite模板，用于构建具有嵌入式UI的生产就绪MCP服务器。
香草
纯HTML/CSS/JavaScript模板，无需构建步骤，非常适合学习。
测试
e2e
Playwright测试套件验证聊天UI和MCP服务器之间的集成。
命令
# Development
pnpm dev # Run all apps (chat-ui + mcp-server)
pnpm --filter chat-ui dev # Chat UI only
pnpm --filter mcp-server dev # MCP server only
# Templates (run manually from template directories)
cd templates/react && pnpm dev
cd templates/vanilla && pnpm dev
# Build & Quality
pnpm build # Build all packages
pnpm typecheck # Type-check
pnpm lint # Lint all packages
pnpm check # Run lint + typecheck
# Testing
pnpm test # Run E2E tests
pnpm test:ui # Interactive Playwright UI
pnpm test:debug # Debug mode部署
MCP服务器→ Cloudflare Workers
cd apps/mcp-server
pnpm build
pnpm deploy # or: wrangler deploy配置 .prod.vars 使用您的工作URL。
聊天界面→ Cloudflare页面
cd apps/chat-ui
pnpm build
wrangler pages deploy dist配置 .env.production 使用您的MCP服务器URL。
看 环境设置.md 详细配置。
文档
入门指南
建筑
配置
技术栈
- Monorepo： Turborepo+pnpm工作区
- 前端： React 19、TypeScript 5.8、Vite 7
- MCP： @modelcontextprotocol/sdk、@mcp用户界面包
- WebMCP： @用于双向工具注册的mcp-b包
- 人工智能： Vercel AI SDK与Anthropic提供商合作
- 运行时间： Cloudflare Workers+持久对象
- 测试： 剧作家1.49
贡献
分叉、实验、报告问题、提交改进。
看 贡献.md 开发标准。
资源
MCP-UI（用户界面资源）
- MCP-UI简介 -MCP UI资源概述
- 协议细节 -资源类型和实施
- 服务器SDK（TypeScript） -构建具有UI支持的MCP服务器
- 客户端SDK -在客户端中渲染UI资源
- -源代码和示例
MCP-B（WebMCP/双向工具）
文档：
NPM包：
- 所有包 -完整的软件包存储库
实时演示和工具：
- beatthelankers.com -带有嵌入式iframe的完整应用程序
- mcp-ui.mcp-b.ai -实时聊天用户界面演示
- mcp-b.ai -交互式示例
- MCP-B Chrome扩展程序 -浏览器中的测试工具
规范：
模型上下文协议
部署和基础设施
- Cloudflare Workers -无服务器运行时
- Cloudflare持久对象 -有状态的协调
- 剧作家 -E2E测试框架
许可证
此项目使用多个许可证：
- 聊天界面 (应用程序/聊天用户界面/)：AGPL-3.0-参见 应用程序/聊天用户界面/许可证
- 所有其他套餐：Apache-2.0-参见 许可证
版权所有2025 Alex Nahas（MCP-B创始人）