AI导哈

ChatGPT应用开发模板

一个基于React和Node.js的ChatGPT应用开发模板，提供完整的window.openai API集成和MCP服务器支持，适用于快速构建交互式ChatGPT插件和组件。

  • by nestorvc
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 nestorvc/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 (
    <div>
      {todos.map(todo => <div key={todo.id}>{todo.title}</div>)}
      <button onClick={refreshData} disabled={isLoading}>
        Refresh
      </button>
    </div>
  );
}

可用挂钩

  • 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/.

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

  3. 发展：运行 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生产

环境 入口点 目的 URL
发展 src/index.tsx 热重载UI调试 localhost:5173
生产 src/components/*/index.jsx ChatGPT集成 localhost:8000

要使用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将使用的。

  2. 启动MCP服务器：

    pnpm run server

  3. 启用 开发者模式

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

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

    # Using ngrok
ngrok http 8000

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

  6. 将隧道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

许可证

麻省理工学院

相关 MCP