AI导哈

ChatGPT小部件开发工具

基于Fractal MCP SDK的ChatGPT交互式小部件开发套件，包含React组件构建、服务端注册和资源打包功能。

  • by truongducthuan
  • HTML
  • 本地部署
  • 更新于
在 GitHub 查看 truongducthuan/weather-mcp

使用说明

OpenAI应用SDK示例

此示例演示了如何使用Fractal MCP SDK为OpenAI的ChatGPT构建一个小部件。

这个例子是什么

此示例显示了创建交互式小部件的完整工作流程：

  1. React组件(ui/Component.tsx)它使用Fractal钩子来接收道具和管理状态
  2. 绑定步骤，使用React组件创建一个自包含的HTML文件
  3. MCP服务器(server/index.ts)注册小部件并将其提供给ChatGPT

使用的软件包

此示例使用三个Fractal MCP包：

  • @分形mcp/oai服务器 -创建MCP服务器，注册小部件，并启动HTTP服务器
  • @分形mcp/oai挂钩 -提供React挂钩(useWidgetProps, useWidgetState, useWebplusGlobal)用于构建小部件UI
  • @分形mcp/cli -将React组件捆绑到一个自包含的HTML文件中

项目结构

oai-apps/
├── server/
│   └── index.ts          # MCP server with widget registration
├── ui/
│   ├── Component.tsx     # React widget component
│   ├── main.tsx          # React entrypoint
│   ├── styles.css        # Widget styles
│   └── bundle/           # Output directory for bundled widget (generated)
├── package.json
└── README.md

如何跑步

1.安装依赖项

从SDK根目录：

npm install

2.捆绑小部件UI

将React组件打包成一个自包含的HTML文件，可以嵌入到小部件中：

npx @fractal-mcp/cli bundle \
  --entrypoint=ui/main.tsx \
  --out=ui/bundle \
  --root-only \
  --inline-js \
  --inline-css

这创造了 ui/bundle/index.html 所有JavaScript和CSS都内联。这 --root-only flag只生成根元素内容（否 <html>, <head>其适合嵌入到小部件中。

3.运行服务器

npm run dev:server

服务器启动于 http://localhost:8001 并准备接受来自ChatGPT的连接。

运作原理

小部件用户界面(ui/Component.tsx)

UI组件使用来自的钩子 @fractal-mcp/oai-hooks:

  • useWidgetProps<T>(defaults) -从服务器接收道具 structuredContent 响应
  • useWidgetState<T>(initialState) -管理跨小部件更新的持久状态
  • useWebplusGlobal("theme") -像当前主题一样访问ChatGPT上下文
const props = useWidgetProps<HelloProps>({ name: "World" });
const [state, setState] = useWidgetState<HelloState>({ clickCount: 0 });
const theme = useWebplusGlobal("theme");

服务器(server/index.ts)

服务器使用 @fractal-mcp/oai-server 致：

  1. 使用以下命令创建MCP服务器实例 new McpServer()
  2. 向注册小部件 registerOpenAIWidget():
    • 定义小部件元数据（id、标题、HTML）
    • 使用Zod定义输入模式
    • 提供一个返回内容和道具的处理函数
  3. 使用以下命令启动HTTP服务器 startOpenAIWidgetHttpServer()

当调用小部件工具时，处理程序返回：

  • content -聊天中显示的文本和UI资源
  • structuredContent -通过传递到小部件UI的道具 useWidgetProps()

开发工作流程

  1. 对以下内容进行更改 ui/Component.tsx
  2. 重新运行bundle命令进行更新 ui/bundle/index.html
  3. 开发服务器（带 tsx watch)将自动重新加载

生产大楼

npm run build

这将编译TypeScript服务器代码。您仍然需要使用上面的CLI命令单独捆绑UI。

后续步骤

  • 添加更多小部件以演示不同的UI模式
  • 在小部件旁边实现其他MCP工具
  • 自定义小部件样式和交互
  • 探索跨多个小部件调用的状态持久性

相关 MCP