AI导哈

UI增强工具库

LeafyGreen MCP-UI概念验证项目，展示如何通过@lg-mcp-ui/core包为MCP服务器工具响应添加UI资源，适用于需要增强工具响应界面的开发场景。

  • by tsck
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 tsck/mcp-ui

使用说明

LeafyGreen MCP-UI概念验证

此存储库是 概念证明 演示如何 @lg-mcp-ui/core 软件包可以根据用户界面资源来增强MCP服务器工具的响应 mcp用户界面规范.

🎯 目的

这个POC是一个工作示例，工程师可以克隆并运行它来理解：

  1. 如何 augmentWithUI() 用于将UI资源添加到MCP工具响应中
  2. 如何在iframe中托管和呈现可嵌入UI
  3. MCP客户端如何提取渲染数据并将其转发给可嵌入UI
  4. 从工具执行到UI渲染的完整端到端流程

备注：这是演示代码。生产实施将与 MongoDB MCP服务器.

📦 包装概述

此monorepo包含：

  • mcp-ui-core (@mcp-poc/core)-核心增强库包含 augmentWithUI()
  • mcp-server (@mcp-poc/mcp-server)-模拟MCP服务器演示工具集成
  • mcp-ui-app (@mcp-poc/mcp-ui-app)Next.js应用程序托管可嵌入的UI组件
  • mcp-client (@mcp-poc/mcp-client)-演示呈现MCP-UI资源的React客户端
  • mongodb-mcp-server -参考实现（MongoDB MCP服务器的克隆）

🚀 快速开始

先决条件

  • Node.js（v18+）
  • pnpm（v8+）

安装

# Install dependencies
pnpm install

运行POC

同时运行所有服务：

pnpm dev

这将开始：

  • MCP服务器 上 http://localhost:3000
  • MCP客户端 上 http://localhost:3001 （或下一个可用端口）
  • MCP UI应用程序 上 http://localhost:3003

个性化服务

您还可以单独运行服务：

# MCP Server only
pnpm mcp-server:dev

# MCP Client only
pnpm mcp-client:dev

# MCP UI App only
pnpm mcp-ui-app:dev

🧪 测试POC

  1. 打开MCP客户端：导航到 http://localhost:3001 在浏览器中
  2. 执行工具：点击任何可用的工具（例如，“Hello World”、“Cluster Metrics”、“List Databases”）
  3. 查看用户界面：工具响应将包括：
    • 文本内容（标准MCP响应）
    • 嵌入式UI组件（在iframe中呈现）

可用演示工具

  • hello_world -带有时间戳的简单问候语
  • cluster_metrics -模拟集群指标显示为时间序列图
  • list_databases -卡组件中显示的数据库列表

📁 项目结构

mcp-ui/
├── packages/
│   ├── mcp-ui-core/          # Core augmentation library
│   │   └── src/
│   │       ├── augmentWithUI.ts    # Main augmentation function
│   │       ├── schemas.ts          # Zod schemas for validation
│   │       └── index.ts            # Public exports
│   │
│   ├── mcp-server/           # Mock MCP server (demo only)
│   │   └── src/
│   │       └── index.ts            # Tool implementations
│   │
│   ├── mcp-ui-app/           # Next.js app hosting embeddable UIs
│   │   └── src/
│   │       ├── app/                # Route pages for each UI
│   │       └── hooks/
│   │           └── useRenderData.ts # Data extraction hook
│   │
│   ├── mcp-client/           # Demo React client
│   │   └── src/
│   │       └── components/
│   │           └── UIRenderer/     # MCP-UI resource renderer
│   │
│   └── mongodb-mcp-server/   # Reference implementation
│
└── README.md                 # This file

🔄 运作原理

1.工具执行

MCP服务器执行工具并创建 CallToolResult:

const toolResult: CallToolResult = {
  content: [{ type: "text", text: "Found 3 databases" }],
};

2.UI增强

服务器调用 augmentWithUI() 要添加UI资源，请执行以下操作：

return augmentWithUI(toolResult, {
  toolName: "list-databases",
  renderData: {
    databases: [...],
    totalCount: 3,
  },
});

3.UI资源创建

augmentWithUI() 创建a UIResource 与：

  • 指向可嵌入UI路由的外部URL
  • 渲染嵌入的数据 uiMetadata['initial-render-data']

4.客户端渲染

MCP客户端：

  • 从以下位置提取渲染数据 uiMetadata
  • 呈现指向UI路由的iframe
  • 通过以下方式将渲染数据发送到iframe postMessage

5.UI组件渲染

可嵌入的UI组件：

  • 通过以下方式接收渲染数据 useRenderData() 钩子
  • 根据Zod模式验证数据
  • 使用LeafyGreen组件渲染

📚 文档

🎓 关键概念

验证策略

两层验证确保数据完整性：

  1. 服务器端: augmentWithUI() 在创建UI资源之前验证渲染数据
  2. 组件级别：UI组件在渲染前验证道具

错误处理

UI增强是 无阻塞 和 非致命性:

  • 如果增强失败，原始 CallToolResult 原封不动地返回
  • 即使UI增强不可用，工具也会继续工作

通信协议

可嵌入UI通过以下方式与父客户端通信 postMessage:

  • 读取流程：客户端将渲染数据发送到iframe
  • 写入流程：Iframe向客户端发送操作请求

🔗 相关资源

⚠️ 重要说明

  • 这是 概念验证代码 用于演示目的
  • 模拟服务器和客户端是 非生产代码
  • 生产实施将与真正的MongoDB MCP服务器集成

📝 许可证

麻省理工学院

相关 MCP