gptapp-MCP with ui for vercel-boilerplate

OpenAI MCP待办事项列表

一个干净的、生产就绪的样板，用于使用模型上下文协议（MCP）、Express、React和Vercel构建ChatGPT应用程序。

概述

此样板提供：

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

特性

待办事项列表小部件

• 查看所有待办事项及其完成状态
• 添加新的所有
• 切换待办事项完成
• 删除待办事项
• 从服务器刷新待办事项
• 通过ChatGPT SDK实时更新

MCP工具

• todos.show_todo_list -打开待办事项列表小部件
• todos.refresh_todos -从服务器刷新待办事项
• todos.add_todo -添加新的待办事项
• todos.toggle_todo -切换待办事项完成状态
• todos.delete_todo -删除幼儿项目
• todos.save_todo_state -保存todo状态（用于持久化）

window.openai API集成

样板包括用于与ChatGPT交互的自定义React挂钩：

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

项目结构

openai-mcp-todo-boilerplate/
├── src/
│   ├── server/              # MCP server (Node.js/Express)
│   │   ├── create-server.ts # MCP server factory
│   │   ├── index.ts         # Express server entry point
│   │   └── services/
│   │       └── todos.ts    # Todo service (in-memory storage)
│   └── widgets/             # React component bundle source
│       ├── components/
│       │   └── todo-list/   # Todo list widget component
│       ├── hooks/
│       │   └── useOpenAI.ts # ChatGPT SDK hooks
│       └── index.css        # Global styles
├── build/                   # Compiled server code
├── dist/                    # Built widget assets
├── package.json
├── tsconfig.json
├── vite.config.js
└── README.md

先决条件

• Node.js 18+
• pnpm（推荐）或npm/yarn
• Vercel帐户（用于部署）
• ngrok或Cloudflare隧道（用于使用ChatGPT进行本地测试）

入门指南

1.安装

pnpm install

2.环境变量

创建一个 .env 根目录中的文件：

# Create .env file
touch .env

重要： 当使用ChatGPT进行测试时， BASE_URL 必须是您的隧道URL（ngrok/Cloudflare隧道），而不是localhost。ChatGPT的iframe无法访问本地主机URL。

编辑 .env 并添加：

# Base URL for your deployment
# For local testing with ChatGPT: Use your tunnel URL (e.g., https://abc123.ngrok-free.app)
# For Vercel: https://your-domain.vercel.app
BASE_URL=https://your-tunnel-url.ngrok-free.app

# Server port (default: 8000)
PORT=8000

# Optional: Custom domain for CSP
# CONNECT_DOMAIN=https://your-custom-domain.com

使用ChatGPT进行本地测试：

# Use your tunnel URL here (NOT localhost!)
BASE_URL=https://abc123.ngrok-free.app
PORT=8000

对于Vercel部署：

BASE_URL=https://your-project.vercel.app
# Note: Do NOT set PORT for Vercel - Vercel automatically sets it

3.构建Widget组件

pnpm run build

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

4.启动服务器（本地开发）

pnpm run dev

这将同时启动服务器和小部件开发服务器。

或者单独运行它们：

# Terminal 1: Server
pnpm run dev:server

# Terminal 2: Widgets (for UI debugging)
pnpm run dev:widgets

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

发展

UI调试（本地开发）

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

pnpm run dev:widgets

这将：

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

要查看组件，请执行以下操作：

• 打开 http://localhost:3000/components/todo/index.html 在浏览器中
• 每个组件都有自己的 index.html 用于开发测试的目录中的文件

重要提示：

• 这仅用于本地调试-ChatGPT从未见过这种情况
• 开发服务器使用 src/widgets/components/*/index.jsx 文件作为入口点
• 生产使用来自的构建文件 dist/widgets/ 相反

开发vs生产

在ChatGPT中进行测试

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

1. 首先建立生产资产：

   pnpm run build

1. 启动MCP服务器：

   pnpm run dev:server

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

   # Using ngrok
   ngrok http 8000

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

1. 使用隧道URL更新.env文件：

   # CRITICAL: Use the tunnel URL, not localhost!
   BASE_URL=https://your-subdomain.ngrok-free.app
   PORT=8000

为什么？ ChatGPT的iframe无法访问 localhost URL。小部件需要对服务器进行API调用，因此它必须使用ChatGPT可以访问的隧道URL。

1. 重新启动服务器 要获取新的BASE_URL，请执行以下操作：

   pnpm run dev:server

1. 将隧道URL添加到ChatGPT：

- 前往“设置”>“连接器” - 添加您的隧道URL（别忘了添加“/mcp”）：

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

1. 测试小部件：

- 在ChatGPT中，问：“显示我的待办事项列表” - 小部件应显示示例待办事项

重要提示：

• 始终运行 pnpm run build 在使用ChatGPT进行测试之前，对组件进行更改！
• 始终使用隧道URL BASE_URL 使用ChatGPT测试时，切勿使用localhost！

部署到Vercel

1.安装Vercel CLI（如果尚未安装）

npm i -g vercel

2.部署

vercel

按照提示链接您的项目。

重要提示：框架预设配置

部署后，您 必须 手动将框架预设设置为 快速 在Vercel项目设置中：

1. 转到Vercel仪表板中的项目
2. 引导到 设置 > 将军 > 框架预设
3. 选择 快速 从下拉列表中
4. 保存更改

为什么？ 这个项目有一个 vite.config.js 根目录中的文件，这会导致Vercel错误地将其自动检测为VitePress。然而，这实际上是一个Express应用程序。将框架预设设置为Express可确保Vercel使用正确的构建和运行时配置。

3.设置环境变量

在Vercel仪表板中：

1. 转到项目设置
2. 导航到环境变量
3. 添加 BASE_URL 和 CONNECT_DOMAIN 使用您的Vercel部署URL：

   BASE_URL=https://your-project.vercel.app
   CONNECT_DOMAIN=https://your-project.vercel.app

4.配置ChatGPT

1. 转到ChatGPT设置>连接器
2. 添加您的Vercel部署URL：

   https://your-project.vercel.app/mcp

5.调动

设置环境变量后，触发新的部署：

vercel --prod

创建新小部件

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

- 添加资源注册 - 添加工具注册

1. 重建与 pnpm run build

部件结构

每个组件应具有：

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

例子：

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

API终点

服务器为直接访问提供REST API端点（可选）：

• GET /api/todos -获取所有待办事项
• POST /api/todos -创建新待办事项
• PUT /api/todos/:id -更新待办事项
• DELETE /api/todos/:id -删除待办事项
• POST /api/todos/:id/toggle -切换待办事项完成

定制

添加数据库

更换中的内存存储 src/server/services/todos.ts 使用您选择的数据库：

// Example with a database
import { db } from './database';

export function getAllTodos(): Promise {
  return db.todos.findMany();
}

export function createTodo(title: string): Promise {
  return db.todos.create({ data: { title, completed: false } });
}

样式

该小部件使用Tailwind CSS和自定义CSS。修改：

• src/widgets/index.css -全球风格
• src/widgets/components/todo-list/todo-list.css -组件特定样式
• tailwind.config.js -顺风配置

添加新的MCP工具

在中添加新工具 src/server/create-server.ts:

server.registerTool(
  "todos.your_new_tool",
  {
    title: "Your Tool Title",
    description: "Tool description",
    inputSchema: {
      // Zod schema
    },
  },
  async (rawParams) => {
    // Tool implementation
  }
);

故障排除

ChatGPT中未加载小部件

1. 确保您已经构建了资产： pnpm run build
2. 检查一下 dist/widgets/ 包含 .js 和 .css 文件
3. 验证您的MCP端点URL是否包括 /mcp
4. 检查BASE_URL是否设置为您的隧道URL，而不是localhost
5. 检查服务器日志是否有错误

CORS错误

服务器包括CORS中间件。如果您遇到CORS问题：

1. 检查 src/server/index.ts CORS配置
2. 确保您的 BASE_URL 环境变量设置正确（使用隧道URL进行ChatGPT测试）

构建错误

1. 确保安装了所有依赖项： pnpm install
2. 检查TypeScript错误： pnpm run build:server
3. 检查Vite构建错误： pnpm run build:widgets

小工具无法连接到API

最常见的问题： BASE_URL 设置为 localhost 而不是隧道URL。

• ChatGPT的iframe无法访问 localhost 网址
• 始终在中使用您的隧道URL（ngrok/Cloudflare隧道） BASE_URL 使用ChatGPT进行测试时
• 例子： BASE_URL=https://abc123.ngrok-free.app ✅
• 不是： BASE_URL=http://localhost:8000 ❌

Vercel 404

如果在项目中使用vercel.json，请将其删除。 这是一个Express应用程序，如果您手动将框架预设更改为Express，我们就不需要它。

框架预设配置

部署后，您 必须 手动将框架预设设置为 快速 在Vercel项目设置中：

1. 转到Vercel仪表板中的项目
2. 引导到 设置 > 将军 > 框架预设
3. 选择 快速 从下拉列表中
4. 保存更改

为什么？ 这个项目有一个 vite.config.js 根目录中的文件，这会导致Vercel错误地将其自动检测为VitePress。然而，这实际上是一个Express应用程序。将框架预设设置为Express可确保Vercel使用正确的构建和运行时配置。

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。