AI导哈

ChatGPT应用SDK集成工具

一个基于Next.js的ChatGPT应用SDK集成工具，用于构建与ChatGPT兼容的MCP服务器，支持小部件渲染。

  • by PaulCailly
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 PaulCailly/mcp

使用说明

ChatGPT 应用程序SDK Next.js 初始模板

一个最简的Next.js应用程序，演示如何构建一个 OpenAI 应用程序开发工具包 (Apps SDK) 与ChatGPT兼容的带有小部件渲染功能的MCP服务器。

概述

这个项目展示了如何使用模型上下文协议（MCP）将一个Next.js应用程序与ChatGPT Apps SDK集成。它包含了一个可运行的MCP服务器，该服务器提供了可从ChatGPT调用的工具和资源，并且响应会在ChatGPT中原生渲染。

关键组件

1. MCP服务器路由（app/mcp/route.ts)

核心的MCP服务器实现，为ChatGPT提供工具和资源访问。

主要特点：

  • 工具注册 带有OpenAI特定的元数据
  • 资源注册 为iframe渲染提供HTML内容
  • 交联 通过工具和资源之间的（途径/方式） templateUri

OpenAI特定的元数据：

{
  "openai/outputTemplate": widget.templateUri,      // Links to resource
  "openai/toolInvocation/invoking": "Loading...",   // Loading state text
  "openai/toolInvocation/invoked": "Loaded",        // Completion state text
  "openai/widgetAccessible": false,                 // Widget visibility
  "openai/resultCanProduceWidget": true            // Enable widget rendering
}

完整的配置选项： OpenAI 应用程序 SDK MCP 文档

2. 资产配置（next.config.ts)

关键： 设置 assetPrefix 以确保 /_next/ 静态资源从正确的源获取：

const nextConfig: NextConfig = {
  assetPrefix: baseURL,  // Prevents 404s on /_next/ files in iframe
};

如果没有这个，Next.js 将尝试从 iframe 的 URL 加载资源，从而导致 404 错误。

3. CORS 中间件（middleware.ts)

处理客户端导航期间跨域RSC（React服务器组件）获取所需的浏览器OPTIONS预检请求：

export function middleware(request: NextRequest) {
  if (request.method === "OPTIONS") {
    // Return 204 with CORS headers
  }
  // Add CORS headers to all responses
}

4. SDK 引导程序（Bootstrapapp/layout.tsx）

这个（或：该） <NextChatSDKBootstrap> 组件补丁用于使浏览器API在ChatGPT的iframe内正常工作：

它修复的内容：

  • history.pushState / history.replaceState - 防止在历史记录中显示完整的原始URL
  • window.fetch - 重写同源请求以使用正确的基础URL
  • <html> 属性 observer - 防止 ChatGPT 修改根元素

所需配置：

<html lang="en" suppressHydrationWarning>
  <head>
    <NextChatSDKBootstrap baseUrl={baseURL} />
  </head>
  <body>{children}</body>
</html>

注： suppressHydrationWarning 当前之所以需要这样做，是因为ChatGPT在Next.js应用进行水合（hydration）之前修改了初始HTML，从而导致水合不匹配。

入门指南/开始使用

安装

npm install
# or
pnpm install

发展

npm run dev
# or
pnpm dev

开放 http://localhost:3000 翻译为中文是：“本地主机：3000 端口”。不过，通常我们不会直接翻译网址的格式，而是理解为访问本地计算机上运行在 3000 端口上的服务或应用 查看该应用程序。

测试MCP服务器

MCP服务器的访问地址为：

http://localhost:3000/mcp

通过ChatGPT连接

  1. 将您的应用部署到Vercel
  2. 在ChatGPT中，导航至 设置 → 连接器 → 创建 并将您的MCP服务器URL添加到其中 /mcp 路径（例如。， https://your-app.vercel.app/mcp)

注： 要将MCP服务器连接到ChatGPT，需要启用开发者模式访问。请参阅 连接指南 用于设置说明。

项目结构

app/
├── mcp/
│   └── route.ts          # MCP server with tool/resource registration
├── layout.tsx            # Root layout with SDK bootstrap
├── page.tsx              # Homepage content
└── globals.css           # Global styles
middleware.ts             # CORS handling for RSC
next.config.ts            # Asset prefix configuration

它是如何工作的

  1. 工具调用ChatGPT调用了一个在（某处）注册的工具 app/mcp/route.ts
  2. 资源参考工具响应包括 templateUri 指向一个已注册的资源
  3. 小部件渲染ChatGPT获取资源HTML并在iframe中渲染它
  4. **客户端水合作用（或“客户端预渲染后初始化”）**Next.js 在 iframe 内部通过修补后的 API 来“水合”（即初始化）应用程序
  5. 导航客户端导航使用了修补程序 fetch 装载RSC有效载荷

了解更多

部署

这个项目旨在与（其他系统/项目）无缝协作 Vercel 部署。该 baseUrl.ts 配置会自动检测Vercel环境变量，并设置正确的资源URL。

该配置会自动处理：

  • 通过生成生产环境URL VERCEL_PROJECT_PRODUCTION_URL
  • 通过预览/分支查看URL VERCEL_BRANCH_URL
  • 在iframe中为资源加载正确设置资产前缀

相关 MCP