# ChatGPT 应用程序生成器使用 mcp-use 框架和 OpenAI Apps SDK 构建具有交互式小部件的生产就绪型 ChatGPT 应用程序。这项技能提供了具有自动注册和内置 React hook 的零配置小部件开发。 ## 快速入门 **始终使用 MCP 应用程序模板进行引导：** npx create-mcp-use-app my-chatgpt-app --template mcp-apps cd my-chatgpt-app 纱线安装纱线开发这将创建一个项目结构：我的chatgpt应用程序/ ├── resources/ # React 小部件（自动注册！） │ ├── display-weather.tsx # 示例小部件 │ └── product-card.tsx # 另一个小部件 ├── public/ # 静态资产 │ └── 图片/ ├── index.ts # MCP 服务器条目 ├── package.json ├── tsconfig.json └── 自述文件.md ## 为什么 ChatGPT 应用程序使用 mcp？传统的 OpenAI Apps SDK 需要大量的手动设置： * 单独的项目结构（server/ 和 web/ 文件夹） * 手动esbuild/webpack配置 * 自定义useWidgetState钩子实现 * 手动React安装代码 * 手动CSP配置 * 手动小部件注册 **mcp-use 简化了一切：** * ✅ 单一命令设置 * ✅ 将小部件放入“resources/”文件夹中 - 自动注册 * ✅ 内置 `useWidget()` 钩子，带有状态、道具、工具调用 * ✅ 自动捆绑热重载 * ✅ 自动 CSP 配置 * ✅ 内置 Inspector 用于测试 * ✅ 双协议支持（与 ChatGPT 和 MCP 应用程序客户端配合使用） ## MCP 应用程序与 ChatGPT 应用程序 SDK mcp-use 支持多种小部件协议，为您提供最大的兼容性：协议|使用案例|兼容性 |状态 ---|---|---|--- **MCP 应用程序**（`类型：“mcpApps”`）|最大兼容性| ✅ ChatGPT + MCP 应用程序客户端 | **推荐** **ChatGPT Apps SDK**（`类型：“appsSdk”`）|仅限 ChatGPT 的功能 | ✅ 仅限 ChatGPT |支持 **MCP-UI** |简单、静态的内容 | ✅ 仅限 MCP 客户 |专业化 ### 为什么选择 MCP 应用程序？ MCP Apps 是模型上下文协议中交互式小部件的**官方标准** (SEP-1865)： * **通用**：适用于 ChatGPT、Claude Desktop、Goose 和所有 MCP Apps 客户端 * **面向未来**：基于开放规范，确保长期兼容性 * **安全** ：具有精细 CSP 控制的双 iframe 沙箱 * **零配置** ：使用 `type: "mcpApps"`，mcp-use 自动生成两个协议的元数据 **要点**：当您在服务器配置中使用“type:”mcpApps”`时，您的小部件会自动与 ChatGPT（Apps SDK 协议）和 MCP Apps 客户端配合使用。您编写一次小部件，然后 mcp-use 处理协议转换。 ## 创建小部件 ### 简单小部件（单个文件）创建 `resources/weather-display.tsx`：从“mcp-use/react”导入 { McpUseProvider, useWidget, type WidgetMetadata }; 从“zod”导入{z}； // 定义小部件元数据导出常量 widgetMetadata: WidgetMetadata = { 描述：“显示一个城市的当前天气”，道具： z.object({ city: z.string().describe("城市名称"), 温度： z.number().describe("摄氏温度"), 条件： z.string().describe("天气条件"), 湿度： z.number().describe("湿度百分比"), }), }; const WeatherDisplay: React.FC = () => { const { props, isPending } = useWidget(); // 始终首先处理加载状态如果（正在等待）{ 返回（

正在加载天气...

）； } 返回（

{props.city}

{props.温度}°C

{props.conditions}

湿度：{props.humidity}%

）； }; 导出默认WeatherDisplay；就是这样！小部件会自动： * 注册为MCP工具“天气显示” * 注册为 MCP 资源 `ui://widget/weather-display.html` * 捆绑应用程序 SDK 兼容性 * 可在 ChatGPT 中使用 ### 复杂小部件（文件夹结构）对于具有多个组件的小部件：资源/ └── 产品搜索/ ├── widget.tsx # 入口点（必填名称） ├── 组件/ │ ├── 产品卡.tsx │ └── FilterBar.tsx ├── 挂钩/ │ └── useFilter.ts ├── 类型.ts └── 常量.ts **入口点（`widget.tsx`）：** 从“mcp-use/react”导入 { McpUseProvider, useWidget, type WidgetMetadata }; 从“zod”导入{z}；从“./components/ProductCard”导入{ProductCard}；从“./components/FilterBar”导入{FilterBar}；导出常量 widgetMetadata: WidgetMetadata = { 描述：“显示带有过滤功能的产品搜索结果”，道具： z.object({ 产品： z.array( z. 对象({ id: z.string(), 名称： z.string(), 价格：z.number(), 图片：z.string(), }) ), 查询：z.string(), }), }; const ProductSearch: React.FC = () => { const { props, isPending, state, setState } = useWidget(); 如果（正在等待）{ 返回（

正在加载...

）； } 返回（

搜索：{props.query}

setState({filters})}/>

{props.products.map((p) => ( ))}

）； }; 导出默认的ProductSearch； ## 小部件元数据自动注册所需的元数据：导出常量 widgetMetadata: WidgetMetadata = { // 必需：人类可读的描述描述：“显示天气信息”， // 必需：小部件 props 的 Zod 架构道具： z.object({ city: z.string().describe("城市名称"), 温度：z.number(), }), // 可选：禁用自动工具注册 hideAsTool: true, // 默认 // 可选：统一元数据（适用于 ChatGPT 和 MCP 应用程序）元数据：{ 客户服务提供商：{ connectDomains: ["https://api.weather.com"], 资源域：[“https://cdn.weather.com”]， }, 偏好边框：true，自动调整大小：真， widgetDescription: "交互式天气显示", }, }; **重要：** * `description`: 用于工具和资源描述 * `props`：Zod schema 定义小部件输入参数 * `exposeAsTool`：如果仅通过自定义工具使用小部件，则设置为`false` * `metadata`：适用于两种协议的统一配置（推荐） ## 内容安全策略 (CSP) 使用 CSP 配置控制您的小部件可以访问哪些外部资源：导出常量 widgetMetadata: WidgetMetadata = { 描述：“天气小部件”，道具： z.object({ city: z.string() }), 元数据：{ 客户服务提供商：{ // 你的widget需要调用的API connectDomains: ["https://api.weather.com", "https://weather-backup.com"], // 静态资源（图像、字体、样式表）资源域：[“https://cdn.weather.com”]， // 要嵌入到 iframe 中的外部内容框架域：[“https://embed.weather.com”]， // 编写 CSP 指令脚本（小心使用！） scriptDirectives: ["'不安全内联'"], }, }, }; **CSP 字段参考：** * **`connectDomains`** ：通过 fetch、WebSocket、XMLHttpRequest 调用的 API * **`resourceDomains`** ：加载图像、字体、样式表、视频 * **`frameDomains`** ：在 iframe 中嵌入外部内容 * **`scriptDirectives`** ：Script-src CSP 指令（避免生产中的“unsafe-eval”） **安全最佳实践：** * ✅ 指定确切的域名：`https://api.weather.com` * ❌ 避免使用通配符：`https://*.weather.com`（安全性较低） * ❌ 除非绝对必要，否则切勿使用“unsafe-eval” * ✅ 在部署之前测试开发中的 CSP ## 元数据配置选项 ### 现代统一方法（推荐）使用“元数据”字段来支持双协议：导出常量 widgetMetadata: WidgetMetadata = { 描述：“天气小部件”，道具：propSchema，元数据：{ // 适用于 MCP 应用程序和 ChatGPT 客户服务提供商：{ connectDomains: ["https://api.weather.com"], 资源域：[“https://cdn.weather.com”]， }, 偏好边框：true，自动调整大小：真， widgetDescription: "显示当前天气", }, }; ### 旧版应用程序 SDK 方法（已弃用）旧的 ChatGPT-only 格式（仍然支持但不推荐）：导出常量 widgetMetadata: WidgetMetadata = { 描述：“天气小部件”，道具：propSchema， appsSdk元数据：{ // 仅 ChatGPT - 带有 openai/ 前缀的 Snake_case “openai/widgetCSP”：{ connect_domains: ["https://api.weather.com"], 资源域：[“https://cdn.weather.com”]， }, “openai/widgetPrefersBorder”：true， "openai/toolInspiration/invoking": "正在加载...", "openai/toolInspiration/invoked": "已加载", }, }; **迁移注意**：旧格式使用带有“openai/”前缀和snake_case的“appsSdkMetadata”（例如“connect_domains”）。新格式使用带有驼峰命名法的“元数据”（例如“connectDomains”），并且适用于两种协议。 ### 将两者用于自定义 ChatGPT 功能您可以组合这两个字段以使用标准元数据以及特定于 ChatGPT 的覆盖：导出常量 widgetMetadata: WidgetMetadata = { 描述：“天气小部件”，道具：propSchema， // 统一元数据（双协议）元数据：{ csp: { connectDomains: ["https://api.weather.com"] }, 偏好边框：true， }, // ChatGPT 特定的覆盖/添加 appsSdk元数据：{ "openai/widgetDescription": "ChatGPT 特定描述", "openai/customFeature": "some-value", // 任何自定义 OpenAI 元数据 "openai/locale": "en-US", }, }; **用例**：当您需要传递统一格式中不存在的自定义 OpenAI 特定元数据时，请将其添加到 `appsSdkMetadata` 中。这些字段将使用“openai/”前缀直接传递到 ChatGPT ## useWidget 钩子 `useWidget` 钩子提供了您需要的一切：常量{ // 来自工具输入的小部件道具道具， // 加载状态（true = 工具仍在执行）正在等待， // 持久化小部件状态状态，设置状态， // 主机主题（浅色/深色）主题, // 调用其他MCP工具调用工具， // 显示模式控制显示模式, 请求显示模式， // 附加工具输出输出， } = useWidget(); ### 道具和加载状态 **关键：** 小部件在工具执行完成之前渲染。始终处理“isPending”： const { props, isPending } = useWidget(); // 模式1：提前返回如果（正在等待）{ 返回

正在加载...

; } // 现在 props 可以安全使用了 // 模式2：条件渲染返回

{isPending ? :

{props.city}

}

; // 模式 3：可选链（部分 UI）返回（

{props.city ?? “正在加载...”}

）； ### 小部件状态在小部件交互中保留数据： const { 状态, setState } = useWidget(); // 保存状态（保存在 ChatGPT localStorage 中） const addFavorite = async (city: string) => { 等待设置状态（{ 收藏夹：[...（州？.收藏夹 || []），城市]， }); }; // 使用函数更新等待 setState((上一个) => ({ ...上一页，计数：（上一个？.计数 || 0）+ 1， })); ### 调用 MCP 工具小部件可以调用其他工具： const { callTool } = useWidget(); const刷新数据 = async () => { 尝试{ const 结果 = 等待 callTool("获取天气", { 城市：“东京”， }); console.log("结果：", result.content); } 捕获（错误）{ console.error("工具调用失败：", error); } }; ### 显示模式控制请求不同的显示模式： const { displayMode, requestDisplayMode } = useWidget(); const goFullscreen = async () => { 等待 requestDisplayMode("全屏"); }; // 当前模式：'内联' | '点' | “全屏” 控制台.log(显示模式); ## 带小部件的自定义工具创建返回具有双协议支持的小部件的工具：从“mcp-use/server”导入 { MCPServer, widget, text }; 从“zod”导入{z}；常量服务器 = 新 MCPServer({ 名称：“天气应用程序”，版本：“1.0.0”， }); 服务器.工具( { 名称：“获取天气”，描述：“获取某个城市的当前天气”，架构： z.object({ city: z.string().describe("城市名称"), }), // 小部件配置（注册时元数据）小部件：{ name: "weather-display", // 必须匹配资源中的小部件/ 调用：“正在获取天气...”，调用：“天气数据已加载”， }, }, 异步（{城市}）=> { // 从API获取数据 const data = 等待 fetchWeatherAPI(city); // 返回带有运行时数据的小部件返回小部件（{ 道具：{ 城市, 温度：数据.temp，条件：数据.条件，湿度：data.humidity， }, 输出：text(`${city} 天气：${data.temp}°C`), message: `${city}的当前天气`, }); } ）；服务器.listen(); **要点：** * 服务器配置中的“baseUrl”可实现正确的资源加载 * Widget 自动与 ChatGPT 和 MCP Apps 客户端配合使用 * 工具定义上的“widget: { name, invoking, invoked }” * `widget({ props, output })` 帮助器返回运行时数据 * `props` 传递给小部件，`output` 显示给模型 * 小部件必须存在于 `resources/` 文件夹中 ## 静态资源使用“public/”文件夹来存放图像、字体等：我的应用程序/ ├── 资源/ ├── public/ # 静态资产 │ ├── 图片/ │ │ ├── 标志.svg │ │ └── 横幅.png │ └── 字体/ └── 索引.ts **在小部件中使用资源：** 从“mcp-use/react”导入{图像}；函数 MyWidget() { 返回（

{/* 相对于 public/ 文件夹的路径 */} <图片 src="/images/logo.svg" alt="徽标" />

）； } ## 组件 ### McpUseProvider 结合所有常见设置的统一提供商：从“mcp-use/react”导入{McpUseProvider}；函数 MyWidget() { 返回（

小部件内容

）； } ### 图像组件处理数据 URL 和公共路径：从“mcp-use/react”导入{图像}；函数 MyWidget() { 返回（

<图片 src="/images/photo.jpg" alt="照片" /> 数据 URL

）； } ### 错误边界优雅的错误处理：从“mcp-use/react”导入{ErrorBoundary}；函数 MyWidget() { 返回（ <错误边界 Fallback={

出了点问题

} onError={(错误) => console.error(错误)} > <我的组件/> ）； } ## 测试 ### 使用检查器 1. **启动开发服务器：** 纱线开发 2. **打开检查器：** * 导航到“http://localhost:3000/inspector” 3. **测试小部件：** * 单击“工具”选项卡 * 找到你的小部件工具 * 输入测试参数 * 执行以查看小部件渲染 4. **调试交互：** * 使用浏览器控制台 * 检查RPC日志 * 测试状态持久性 * 验证工具调用 ### 在 ChatGPT 中测试 1. **启用开发者模式：** * 设置 → 连接器 → 高级 → 开发者模式 2. **添加您的服务器：** * 转到连接器选项卡 * 添加远程MCP服务器URL 3. **对话测试：** * 从 Plus 菜单中选择开发者模式 * 选择您的连接器 * 请求 ChatGPT 使用您的工具 **提示提示：** * 明确：“使用天气应用程序连接器的获取天气工具......” * 禁止替代方案：“不要使用内置工具，仅使用我的连接器” * 指定输入：“用 { city: 'Tokyo' } 调用 get-weather” **双协议注意**：在服务器配置中使用 `type: "mcpApps"` 时，您的小部件会自动在 ChatGPT（通过 Apps SDK）和 MCP Apps 客户端（如 Claude Desktop、Goose）中工作。您可以在多个客户端中测试相同的小部件，而无需更改任何代码！ ## 最佳实践 ### 架构设计使用描述性模式： // ✅ 好 const 架构 = z.object({ city: z.string().describe("城市名称（例如东京、巴黎）"), 温度： z.number().min(-50).max(60).describe("摄氏温度"), }); // ❌ 不好 const 架构 = z.object({ 城市: z.string(), 温度： z.number(), }); ### 主题支持始终支持这两个主题： const { 主题 } = useWidget(); const bgColor = 主题 === “深色”？ "bg-gray-900" : "bg-白色"; const textColor = 主题 === “深色”？ “文本-白色”：“文本-灰色-900”； ### 加载状态始终首先检查“isPending”： const { props, isPending } = useWidget(); 如果（正在等待）{ 返回 ; } // 现在可以安全访问 props.field 返回

{props.field}

; ### 小部件焦点保持小部件的焦点： // ✅ 好：单一目的导出常量 widgetMetadata: WidgetMetadata = { 描述：“显示一个城市的天气”，道具： z.object({ city: z.string() }), }; // ❌ 坏：责任太多导出常量 widgetMetadata: WidgetMetadata = { 描述：“天气、天气预报、地图、新闻等”，道具： z.object({ /* 许多字段 */ }), }; ### 错误处理优雅地处理错误： const { callTool } = useWidget(); const fetchData = async () => { 尝试{ const result = wait callTool("fetch-data", { id: "123" }); if (结果.isError) { console.error("工具返回错误"); } } 捕获（错误）{ console.error("工具调用失败：", error); } }; ## 配置 ### 生产设置设置生产的基本 URL：常量服务器 = 新 MCPServer({ 名称：“我的应用程序”，版本：“1.0.0”， baseUrl: process.env.MCP_URL || “https://myserver.com”， }); ### 环境变量 # 服务器地址 MCP_URL=https://myserver.com # 对于静态部署 MCP_SERVER_URL=https://myserver.com/api CSP_URLS=https://cdn.example.com,https://api.example.com **变量用法：** * `MCP_URL`：小部件资产和 CSP 的基本 URL * `MCP_SERVER_URL`：用于工具调用的 MCP 服务器 URL（静态部署） * `CSP_URLS`：内容安全策略的附加域 ## 部署 ### 部署到 mcp-use 云 # 登录 npx mcp-使用登录 # 部署纱线部署 ### 为生产而构建 # 构建纱线结构 # 开始纱线开始构建过程： * 编译 TypeScript * 捆绑 React 小部件 * 优化资产 * 生成生产 HTML ## 常见模式 ### 数据获取小部件 const DataWidget: React.FC = () => { const { props, isPending, callTool } = useWidget(); 如果（正在等待）{ 返回

正在加载...

; } const 刷新 = async () => { 等待 callTool("fetch-data", { id: props.id }); }; 返回（

{props.title}

）； }; ### 有状态小部件 const CounterWidget: React.FC = () => { const { 状态, setState } = useWidget(); const 增量 = async () => { 等待设置状态（{ 计数：（状态？.计数 || 0）+ 1， }); }; 返回（

计数：{状态？.计数|| 0}

）； }; ### 主题小部件 const ThemedWidget: React.FC = () => { const { 主题 } = useWidget(); 返回（

内容

）； }; ## 故障排除 ### 小部件未出现 **问题：** Widget 文件存在，但工具未出现 **解决方案：** * 确保`.tsx`扩展名 * 导出`widgetMetadata`对象 * 导出默认的React组件 * 检查服务器日志是否有错误 * 验证小部件名称与文件/文件夹名称匹配 ### 未收到道具 **问题：** 组件接收到空的 props **解决方案：** * 首先检查`isPending`（待处理时道具为空） * 使用 `useWidget()` 钩子（不是 React props） * 验证 `widgetMetadata.props` 是有效的 Zod 模式 * 检查工具参数是否匹配模式 ### CSP 错误 **问题：** 小部件加载但资源失败 **解决方案：** * 在服务器配置中设置 `baseUrl` * 通过 `metadata.csp` （现代）或 `appsSdkMetadata['openai/widgetCSP']` （旧版）将域添加到 CSP * 所有资源均使用HTTPS * 检查浏览器控制台是否存在 CSP 违规 ### 生产中的 CSP 错误 **问题：** 生产中的资源被内容安全策略阻止 **解决方案：** 1. **检查浏览器控制台**是否有 CSP 违规消息 2. **将缺失的域**添加到您的 CSP 配置中：元数据：{ 客户服务提供商：{ connectDomains: ['https://api.example.com'], // 添加缺少的 API 域 resourceDomains: ['https://cdn.example.com'], // 添加缺少的 CDN 域名 } } 3. **使用精确的域** \- 避免在生产中使用通配符 4. **在部署之前在 Inspector 中进行测试**，以便及早发现 CSP 问题 5. **环境变量替代方案** : 使用逗号分隔的域设置`CSP_URLS`环境变量 ### 协议兼容性问题 **问题：** 小部件在 ChatGPT 中工作，但在 MCP Apps 客户端中不起作用（反之亦然） **解决方案：** * **使用`type: "mcpApps"`**实现双协议支持（推荐） * **检查服务器配置中的`baseUrl`**设置是否正确 * **验证元数据格式** ：对于双协议，使用 `metadata` (camelCase) 而不是 `appsSdkMetadata` (snake_case) * **在支持两种协议的 Inspector 中进行测试** **何时使用每种类型：** * `type: "mcpApps"` \- 最大兼容性（推荐） * `type: "appsSdk"` \- 仅 ChatGPT（如果您需要不在规范中的 ChatGPT 特定功能，请使用） ## 了解更多 * **文档**： * **MCP 应用程序标准** ：（双协议指南） * **小部件指南**： * **应用程序 SDK 教程**： * **模板** : * **ChatGPT 应用程序流程** ： * **检查器调试** : * **GitHub**： ## 快速参考 **命令：** * `npx create-mcp-use-app my-app --template mcp-apps` \- Bootstrap * `yarn dev` \- 热重载开发 * `yarn build` \- 为生产而构建 * `yarn start` \- 运行生产服务器 * `yarn deploy` \- 部署到 mcp-use 云 **小部件结构：** * `resources/widget-name.tsx` \- 单个文件小部件 * `resources/widget-name/widget.tsx` \- 基于文件夹的小部件条目 * `public/` \- 静态资产 **小部件元数据：** * `description` \- 小部件描述 * `props` \- 输入的 Zod 模式 * `exposeAsTool` \- 自动注册为工具（默认值：true） * `metadata` \- 统一配置（双协议，推荐） * `metadata.csp` \- 内容安全策略配置 * `appsSdkMetadata` \- ChatGPT 特定的覆盖（可选） **CSP 字段：** * `connectDomains` \- 要调用的 API * `resourceDomains` \- 要加载的静态资源 * `frameDomains` \- 要嵌入的 Iframe * `scriptDirectives` \- 脚本策略 **使用Widget挂钩：** * `props` \- 小部件输入参数 * `isPending` \- 加载状态标志 * `state, setState` \- 持久状态 * `callTool` \- 调用其他工具 * `theme` \- 当前主题（浅色/深色） * `displayMode, requestDisplayMode` \- 显示控制

Chatgpt 应用程序生成器

包含技能