AI导哈

MCP UI组件库

用于在AI助手（如ChatGPT）中渲染MCP工具响应的UI组件库，提供轻量级和丰富的数据展示功能。

  • by chatbotkit
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 chatbotkit/mcp-widgets

使用说明

MCP小部件

用于在ChatGPT等AI助手中呈现MCP（模型上下文协议）工具响应的UI小部件。

概述

当MCP工具返回数据时，AI助手可以使用自定义UI小部件而不是纯文本来显示它。此软件包提供了可以通过简单的 <script> 标签。

安装

npm install mcp-widgets
# or
pnpm add mcp-widgets

小部件

小部件 框架 大小 描述
data-card Web小部件 ~3KB 简单键值数据显示
rich-data-card React ~148KB 增强的卡片，带有部分、图标和页脚

用法

CDN嵌入（用于MCP工具）

通过CDN加载小部件并将其用作自定义HTML元素：

<!-- Load the widget -->
<script src="https://unpkg.com/mcp-widgets/cdn/data-card.js"></script>

<!-- Use it -->
<mcp-data-card
  title="Weather"
  data='{"temperature": "72°F", "conditions": "Sunny"}'
  status="success"
></mcp-data-card>

作为React库

import { RichDataCard } from 'mcp-widgets'

function MyWidget() {
  return (
    <RichDataCard
      title="Order Summary"
      icon="🛒"
      data={{ orderId: '#12345', total: '$89.99' }}
      sections={[{ title: 'Shipping', data: { method: 'Express' } }]}
      status="success"
    />
  )
}

嵌入是如何工作的

MCP工具响应流程

  1. 用户提问 在ChatGPT中（例如，“天气怎么样？”）
  2. ChatGPT调用您的MCP工具 返回结构化数据
  3. 您的工具响应包括HTML 带着一个 <script> 指向CDN托管小部件的标签
  4. ChatGPT呈现HTML 在沙盒iframe中
  5. 小部件加载并显示 数据可视化

MCP工具响应示例

当您的MCP服务器处理工具调用时，返回嵌入小部件的HTML：

// In your MCP server tool handler
function handleWeatherTool(location) {
  const data = fetchWeather(location)

  return {
    content: [
      {
        type: 'text',
        text: `
        <script src="https://unpkg.com/mcp-widgets/cdn/data-card.js"></script>
        <mcp-data-card
          title="Weather in ${location}"
          data='${JSON.stringify(data)}'
          status="success"
        ></mcp-data-card>
      `,
      },
    ],
  }
}

OpenAI天桥API

加载器通过以下方式处理与ChatGPT主机的通信 window.openai小部件本身不应该直接调用这些API——加载器管理高度通知和道具提取。

可用的主机API（由加载器使用）：

// Notify ChatGPT of widget height (takes a number)
window.openai.notifyIntrinsicHeight(document.body.scrollHeight)

// Access tool response metadata for props
window.openai.toolResponseMetadata._meta

请参阅 OpenAI应用SDK文档 对于完整 window.openai API参考。

安全考虑

  • 小部件在功能有限的沙盒iframe中运行
  • 数据通过HTML属性传递（必须是JSON字符串化的）
  • 无法直接访问父页面或用户会话
  • CDN URL应使用HTTPS

小部件参考

<mcp-data-card>

一个轻量级的Web小部件（不依赖于React）。

属性 类型 描述
title string 卡片标题
data JSON字符串 要显示的键值对
status success error

<mcp-rich-data-card>

一个基于React的小部件，具有更多功能。

属性 类型 描述
title string 卡片标题
description string 字幕文本
icon 字符串 表情符号或图标字符
data JSON字符串 主数据段
sections JSON字符串 数组 {title, data} 章节
footer string 页脚文本
status success error

发展

# Install dependencies
pnpm install

# Start Storybook
pnpm dev

# Run tests
pnpm test

# Build everything
pnpm build

# Build CDN bundles only
pnpm build:cdn

创建新小部件

  1. 在中创建文件夹 src/widgets/{widget-name}/
  2. 添加所需文件：
    • WidgetName.ts （Web小部件）或 WidgetName.tsx （反应）
    • manifest.json -小部件元数据
    • cdn.ts 或 cdn.tsx -CDN入口点
    • index.ts -库导出
  3. 出口自 src/widgets/index.ts
  4. 跑 pnpm build 生成捆绑包

叉车和定制系列

这个存储库是为分叉而设计的！您有两个选择：

选项1：私人小部件集合

分叉此仓库以创建您自己的私有小部件库：

  1. 分叉 将此存储库添加到您的GitHub帐户/组织
  2. 添加您的小部件 遵循上述结构
  3. 私人主持 通过发布到私有npm注册表或从您自己的基础设施提供CDN捆绑包
  4. 在MCP工具中使用 通过指向您的私有CDN URL

这非常适合：

  • 具有自定义品牌的专有UI小部件
  • 具有敏感设计的内部工具
  • 与私有API集成的小部件

选项2：回馈

我们欢迎社区捐款！如果你构建了一个可以使他人受益的小部件：

  1. 分叉 此存储库
  2. 创建您的小部件 遵循现有模式
  3. 添加测试和故事书故事
  4. 提交拉取请求 带有您的小部件的描述

社区小部件的好候选者：

  • 通用数据可视化（图表、表格、地图）
  • 常见的工具响应模式（搜索结果、确认）
  • 可访问性改进
  • 性能优化

托管自己的CDN

如果您分叉并希望自托管CDN捆绑包：

# Build the CDN bundles
pnpm build:cdn

# The cdn/ directory contains all bundles
# Upload to your preferred hosting:
# - GitHub Pages
# - Cloudflare R2/Pages
# - AWS S3 + CloudFront
# - Vercel/Netlify

然后在MCP工具响应中引用您的托管包：

<script src="https://your-cdn.example.com/widgets/my-widget.js"></script>

许可证

麻省理工学院

相关 MCP