MCP小部件
用于在ChatGPT等AI助手中呈现MCP（模型上下文协议）工具响应的UI小部件。
概述
当MCP工具返回数据时，AI助手可以使用自定义UI小部件而不是纯文本来显示它。此软件包提供了可以通过简单的 `` 标签。
安装
npm install mcp-widgets
# or
pnpm add mcp-widgets小部件
| 小部件 | 框架 | 大小 | 描述 |
|---|---|---|---|
data-card | Web小部件 | ~3KB | 简单键值数据显示 |
rich-data-card | React | ~148KB | 增强的卡片，带有部分、图标和页脚 |
用法
CDN嵌入（用于MCP工具）
通过CDN加载小部件并将其用作自定义HTML元素：
作为React库
import { RichDataCard } from 'mcp-widgets'
function MyWidget() {
return (
)
}嵌入是如何工作的
MCP工具响应流程
- 用户提问 在ChatGPT中（例如，“天气怎么样？”）
- ChatGPT调用您的MCP工具 返回结构化数据
- 您的工具响应包括HTML 带着一个 `` 指向CDN托管小部件的标签
- ChatGPT呈现HTML 在沙盒iframe中
- 小部件加载并显示 数据可视化
MCP工具响应示例
当您的MCP服务器处理工具调用时，返回嵌入小部件的HTML：
// In your MCP server tool handler
function handleWeatherTool(location) {
const data = fetchWeather(location)
return {
content: [
{
type: 'text',
text: `
`,
},
],
}
}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
小部件参考
``
一个轻量级的Web小部件（不依赖于React）。
| 属性 | 类型 | 描述 | |||
|---|---|---|---|---|---|
title | string | 卡片标题 | |||
data | JSON字符串 | 要显示的键值对 | |||
status | success | error | warning | info | 状态指示器样式 |
``
一个基于React的小部件，具有更多功能。
| 属性 | 类型 | 描述 | |||
|---|---|---|---|---|---|
title | string | 卡片标题 | |||
description | string | 字幕文本 | |||
icon | 字符串 | 表情符号或图标字符 | |||
data | JSON字符串 | 主数据段 | |||
sections | JSON字符串 | 数组 {title, data} 章节 | |||
footer | string | 页脚文本 | |||
status | success | error | warning | info | 状态样式 |
发展
# Install dependencies
pnpm install
# Start Storybook
pnpm dev
# Run tests
pnpm test
# Build everything
pnpm build
# Build CDN bundles only
pnpm build:cdn创建新小部件
- 在中创建文件夹
src/widgets/{widget-name}/ - 添加所需文件：
- WidgetName.ts （Web小部件）或 WidgetName.tsx （反应） - manifest.json -小部件元数据 - cdn.ts 或 cdn.tsx -CDN入口点 - index.ts -库导出
- 出口自
src/widgets/index.ts - 跑
pnpm build生成捆绑包
叉车和定制系列
这个存储库是为分叉而设计的！您有两个选择：
选项1：私人小部件集合
分叉此仓库以创建您自己的私有小部件库：
- 分叉 将此存储库添加到您的GitHub帐户/组织
- 添加您的小部件 遵循上述结构
- 私人主持 通过发布到私有npm注册表或从您自己的基础设施提供CDN捆绑包
- 在MCP工具中使用 通过指向您的私有CDN URL
这非常适合：
- 具有自定义品牌的专有UI小部件
- 具有敏感设计的内部工具
- 与私有API集成的小部件
选项2：回馈
我们欢迎社区捐款！如果你构建了一个可以使他人受益的小部件：
- 分叉 此存储库
- 创建您的小部件 遵循现有模式
- 添加测试和故事书故事
- 提交拉取请求 带有您的小部件的描述
社区小部件的好候选者：
- 通用数据可视化（图表、表格、地图）
- 常见的工具响应模式（搜索结果、确认）
- 可访问性改进
- 性能优化
托管自己的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工具响应中引用您的托管包：
许可证
麻省理工学院