Openai MCP App Boilerplate

OpenAI MCP应用程序沸腾板

注： 这是一个基于OpenAI的MCP应用程序示例的社区维护的样板。包括自定义挂钩和增强的文档 window.openai API

使用模型上下文协议（MCP）构建ChatGPT应用程序的干净、最小的样板。

概述

此样板提供：

• 基于Vite的React组件包系统
• 使用官方TypeScript SDK的Node.js MCP服务器
• 满的 window.openai API集成 用于与ChatGPT进行双向通信
• 简单、干净的项目结构

window.openai API集成

此样板演示了如何使用ChatGPT应用程序SDK window.openai 用于构建交互式小部件的API。这 window.openai API使您的React组件能够：

主要特点

• 从MCP服务器读取数据：访问 toolOutput 和 toolInput 从您的MCP服务器
• 保持小部件状态：使用以下命令保存ChatGPT可见的状态 setWidgetState
• 呼叫服务器工具：使用以下命令从组件触发服务器操作 callTool
• 发送后续消息：在ChatGPT对话中插入消息
• 请求布局更改：在内联、画中画和全屏模式之间切换
• 访问主题/布局信息：获取ChatGPT的主题、设备类型和布局约束

使用示例

import { 
  useToolOutput, 
  useWidgetState, 
  useCallTool, 
  useSendFollowUpMessage 
} from './hooks/useOpenAI';

function MyComponent() {
  // Get data from MCP server
  const toolOutput = useToolOutput();
  const todos = toolOutput?.todos || [];
  
  // Persist state visible to ChatGPT
  const [favorites, setFavorites] = useWidgetState({ items: [] });
  
  // Call server tools
  const { callTool, isLoading } = useCallTool();
  const refreshData = () => callTool('refresh-todos', { userId: '123' });
  
  // Send messages to ChatGPT
  const sendMessage = useSendFollowUpMessage();
  const notifyCompletion = () => sendMessage('All tasks completed!');
  
  return (
    

      {todos.map(todo => 
{todo.title}
)}
      
        Refresh
      
    

  );
}

可用挂钩

• useToolOutput() -从MCP服务器工具响应中读取数据
• useToolInput() -读取传递给MCP工具的参数
• useWidgetState(initialState) -ChatGPT可见的持久状态
• useCallTool() -从组件调用MCP服务器工具
• useSendFollowUpMessage() -向ChatGPT对话发送消息
• useRequestDisplayMode() -请求布局更改（内联/pip/全屏）
• useOpenAIGlobals() -访问主题、设备和布局信息

服务器工具

MCP服务器包括几个演示组件到服务器通信的工具：

• show-todo -显示带有示例数据的todo小部件的主工具
• refresh-todos -由组件调用以从服务器刷新数据
• save-todo-state -由组件调用，将更改持久化回服务器

这些工具展示了如何：

• 通过以下方式将数据传递给组件 structuredContent
• 处理组件发起的工具调用
• 在ChatGPT和小部件之间实现双向数据流

项目结构

app/
├── web/                  # Component bundle source
│   ├── src/
│   │   ├── components/   # React widget components
│   │   └── index.css     # Global Tailwind styles
│   ├── dist/             # Build output
│   ├── package.json
│   └── tsconfig.json
│
└── server/               # MCP server (Node.js)
    ├── src/
    │   └── server.ts     # Main server file with MCP handlers
    ├── package.json
    └── tsconfig.json

文件夹

web/ -React组件包系统

• src/components/ -React小部件组件（todo示例）
• src/hooks/ -自定义React挂钩 window.openai API集成
• src/index.css -全球顺风CSS样式
• dist/ -构建输出（由构建脚本生成的HTML/JS/CSS文件）
• package.json -Web依赖（React、Vite、Tailwind等）
• tsconfig.json -React组件的TypeScript配置（JSX、DOM类型）
• vite.config.ts -Vite-dev服务器配置
• build.mts -构建将组件捆绑到独立资产中的脚本

server/ -MCP（模型上下文协议）服务器

• src/server.ts -处理来自ChatGPT的MCP协议请求的主服务器文件
• package.json -服务器依赖关系（MCP SDK、Zod）
• tsconfig.json -Node.js服务器代码的TypeScript配置

根文件

• package.json -仅提供便利脚本（无依赖关系-每个子目录管理自己的子目录）
• README.md -这个文件！

运作原理

1. 构建过程: web/build.mts 查找中的所有组件 src/components/，将它们与Vite捆绑在一起，并将独立的HTML/CSS/JS文件输出到 dist/.

1. 服务器: server/src/server.ts 当调用工具时，通过MCP协议将构建的HTML文件提供给ChatGPT。

1. 发展：运行 pnpm run dev 用于组件的热重新加载，或 pnpm run build 捆绑生产。

先决条件

• Node.js 18+
• pnpm（推荐）

入门指南

安装依赖项

pnpm install           # Root dependencies
cd web && pnpm install # Web component dependencies
cd ../server && pnpm install # Server dependencies

或者使用便利脚本：

pnpm run install:all

构建小部件组件

pnpm run build

这会产生 .html, .js，以及 .css 文件在 web/dist/ 对于每个组件。

启动MCP服务器

pnpm run server

服务器将于启动 http://localhost:8000 MCP端点位于 http://localhost:8000/mcp.

发展

UI调试（本地开发）

对于具有热重新加载和调试的本地开发：

# Start the Vite dev server for UI debugging
pnpm run dev

这将：

• 启动Vite开发服务器 http://localhost:5173
• 启用热重新加载以进行即时更新
• 提供用于调试的源代码映射
• 直接提供React组件

重要提示：

• 这仅用于本地调试-ChatGPT从未见过这种情况
• 开发服务器使用 web/src/index.tsx 作为切入点
• 生产用途 web/src/components/*/index.jsx 文件代替

完整开发设置

对于UI调试和MCP服务器的完整开发：

# Terminal 1: Web component dev server (UI debugging)
pnpm run dev

# Terminal 2: MCP server (for ChatGPT testing)
pnpm run server

开发vs生产

要使用ChatGPT进行测试：

1. 建设生产资产： pnpm run build
2. 启动MCP服务器： pnpm run server
3. 使用隧道（ngrok、Cloudfare或其他）进行暴露 localhost:8000

创建新小部件

1. 在中创建新的组件目录 web/src/components/ 带着一个 index.jsx 文件
2. 运行时，构建脚本将自动拾取它 pnpm run build
3. 在中注册小部件 server/src/server.ts 在 widgets 数组
4. 重建与 pnpm run build

部件结构

每个组件应具有：

• index.jsx -导出组件的入口点
• 组件文件（例如。， MyWidget.jsx, my-widget.css)
• 任何数据文件（例如。， data.json)

例子：

web/src/components/my-widget/
├── index.jsx
├── MyWidget.jsx
└── my-widget.css

在ChatGPT中进行测试

要在ChatGPT中测试您的应用程序：

1. 首先建立生产资产：

   pnpm run build

这将在中创建捆绑文件 web/dist/ ChatGPT将使用的。

1. 启动MCP服务器：

   pnpm run server

1. 启用 开发者模式

1. 在“设置”>“连接器”中添加您的应用程序

1. 创建一个隧道以暴露您的本地服务器：

   # Using ngrok
   ngrok http 8000

   # Or using Cloudflare Tunnel
   cloudflared tunnel --url http://localhost:8000

1. 将隧道URL添加到ChatGPT （别忘了加上“/mcp”）：

   https://your-subdomain.ngrok-free.app/mcp

重要提示： 始终运行 pnpm run build 在使用ChatGPT进行测试之前，对组件进行更改！

部署

设置 BASE_URL 构建时的环境变量：

BASE_URL=https://your-domain.com pnpm run build

许可证

麻省理工学院