适合谁
- 希望学习 Apps SDK/MCP 组件化开发模式的前端与后端开发者
- 计划为 ChatGPT 构建自定义连接器应用的团队
- 需要参考真实代码示例（Node 与 Python 双语言）来理解 widget 渲染与状态同步机制的工程师
O
59FMRS · C
OpenAI 官方维护的 Apps SDK/MCP 示例仓库，提供多个可运行的 Node/Python 服务器示例（Pizzaz、Kitchen Sink Lite、Solar System、Authenticated、Shopping Cart），配合前端组件构建脚手架，用于教学与二次开发，而非直接面向最终用户的生产服务。
这是 OpenAI 官方仓库，收录了一系列示例 MCP 服务器与配套 UI 组件（widget），用于展示如何为 ChatGPT 构建基于 Apps SDK 的应用。仓库包含多个可独立运行的示例服务器：Pizzaz（Node 与 Python 双实现，展示列表、轮播、地图等视图及购物结账流程）、Kitchen Sink Lite（Node 与 Python，演示 window.openai 全部宿主 API，包括读取/写入 widget 状态、从组件内调用工具、请求切换显示模式等）、Solar System（Python，3D 太阳系可视化）、Authenticated（Python，演示不同级别的 OAuth 鉴权工具调用）、Shopping Cart（Python，演示如何用 widgetSessionId 在多轮工具调用间保持购物车状态）。仓库还提供 Vite 构建脚手架，将组件源码打包为可被 MCP 服务器直接引用的静态 HTML/JS/CSS 资源。定位是开发者学习和二次开发的起点，而非面向最终用户的生产服务。
工具能力
暂未整理工具清单。
安装接入
- 克隆仓库并安装依赖：
pnpm install && pre-commit install（也可用 npm/yarn）。 - 构建组件资源包：
pnpm run build，产物输出到assets/目录。 - 启动静态资源服务：
pnpm run serve（默认监听 http://localhost:4444，已启用 CORS）。 - 根据需要启动某个示例 MCP 服务器，例如 Pizzaz Node 版：
cd pizzaz_server_node && pnpm start；或 Python 版服务器（如 Pizzaz、Kitchen Sink、Solar System、Authenticated、Shopping Cart）需先创建虚拟环境并安装对应requirements.txt，再用uvicorn <module>:app --port 8000启动。 - 如需接入 ChatGPT，需先在设置中开启开发者模式（Developer Mode），然后在 Settings > Connectors 中添加连接器；若服务器运行在本地，可用 ngrok 等工具暴露公网地址（如
https://<endpoint>.ngrok-free.app/mcp）。 - 使用 ngrok 等隧道时，Python MCP SDK 会做 DNS 重绑定保护，需要提前设置环境变量
MCP_ALLOWED_HOSTS与MCP_ALLOWED_ORIGINS为隧道域名。 - 部署到云端时需设置环境变量
BASE_URL（用于生成引用静态资源的 widget HTML）和API_BASE_URL（供客户端 widget 构造完整 API 请求地址）。
选型与风险
不适合谁
- 需要开箱即用的生产级 MCP 服务（这是示例/脚手架代码，非托管服务）
- 只想直接使用某个具体业务功能而不涉及开发的最终用户
- 需要非 ChatGPT 宿主（如 Claude Desktop）官方支持的场景，本仓库示例围绕 Apps SDK/ChatGPT 设计
所需权限
- 运行本地 HTTP 服务（默认端口 4444 用于静态资源，8000 用于各 MCP 服务器）
- Authenticated 示例服务器需要配置 OAuth 相关凭据以演示鉴权工具调用
- 若通过 ngrok 等工具将本地服务暴露到公网，需要授权隧道访问并设置允许的 Host/Origin
风险与副作用
- 示例代码定位为学习起点，未包含生产级的持久化、鉴权强化等能力（如购物车状态仅演示机制，未做服务端持久化）
- 通过 ngrok 暴露本地服务到公网时，若配置不当（如未限制 MCP_ALLOWED_HOSTS/ORIGINS）可能带来未授权访问风险
- Python Pizzaz 服务器使用 functools.lru_cache 缓存 widget HTML，重新构建或修改 assets 后需重启服务器，否则可能提供过期界面
常见排障
- 若使用 Chrome 142 及以上版本看不到 widget 界面，需要在 chrome://flags 中禁用 local-network-access-check 并重启浏览器
- 确保先执行 `pnpm run build` 并用 `pnpm run serve` 启动静态资源服务，再启动 MCP 服务器，否则 widget 无法加载
- 修改或重新构建 assets 后，需重启 Python Pizzaz 服务器以清除 lru_cache 缓存
- 通过 ngrok 等隧道连接 ChatGPT 时，若报 DNS 重绑定保护错误，需设置 MCP_ALLOWED_HOSTS 与 MCP_ALLOWED_ORIGINS 环境变量为隧道域名
使用场景
学习 Apps SDK 与 MCP 协议如何协同为 ChatGPT 渲染富交互界面
以 Pizzaz、Kitchen Sink、Solar System 等示例为起点，开发自定义的 ChatGPT 连接器应用
参考购物车示例学习如何用 widgetSessionId 在多轮工具调用间维护共享状态
参考鉴权示例学习如何为工具调用配置不同级别的 OAuth 权限
支持客户端
ChatGPT完整支持