应用SDK示例库
此存储库展示了与Apps SDK一起使用的示例UI组件，以及将一组组件作为工具公开的示例MCP服务器。 它旨在作为一个起点和灵感来源，为ChatGPT构建自己的应用程序。
MCP+Apps SDK概述
模型上下文协议（MCP）是一个开放规范，用于将大型语言模型客户端连接到外部工具、数据和用户界面。MCP服务器公开模型在对话期间可以调用的工具，并根据工具契约返回结果。这些结果可能包括额外的元数据，如内联HTML，Apps SDK使用这些元数据来呈现丰富的UI组件（小部件）以及辅助消息。
在Apps SDK中，MCP使服务器、模型和UI保持同步。通过标准化连线格式、身份验证和元数据，ChatGPT可以像对内置工具一样对连接器进行推理。Apps SDK的最小MCP集成实现了三个功能：
- 列出工具 –您的服务器宣传它支持的工具，包括它们的JSON模式输入/输出契约和可选注释（例如，
readOnlyHint). - 呼叫工具 –当模型选择工具时，它会发出
call_tool带有与用户意图匹配的参数的请求。您的服务器执行操作并返回模型可以解析的结构化内容。 - 返回小部件 除了结构化内容外，在响应元数据中返回嵌入式资源，以便Apps SDK可以在Apps SDK客户端（ChatGPT）中内联呈现接口。
由于该协议与传输无关，您可以通过服务器发送事件或流式HTTP承载服务器——Apps SDK支持这两种方式。
此演示中的MCP服务器强调了每个工具如何通过将结构化有效负载与 _meta.openai/outputTemplate 从MCP服务器返回的元数据。
特性
✨ 丰富的UI小部件 –AT&T产品、服务和商店定位器的交互式组件\ 🔐 OAuth 2.0身份验证 –内置OAuth提供程序，用于安全访问控制\ 🚀 生产就绪 –Cloudflare隧道支持持久域\ 📱 响应式设计 –现代、移动友好的UI组件\ 🛠️ 开发者友好 –使用全面的文档轻松设置
存储库结构
src/–每个小部件示例的源代码。assets/–运行构建步骤后生成HTML、JS和CSS包。att_server_python/–返回AT&T产品小部件的Python MCP服务器（支持OAuth）。instructions/–设置、部署、OAuth和故障排除的全面指南。build-all.mts–Vite构建编排器，为每个小部件入口点生成哈希包。
技术栈
该项目采用现代全栈架构，将Python后端服务与基于React的UI小部件相结合。
前端（UI小部件）
| 技术 | 版本 | 目的 |
|---|---|---|
| 反应 | 19.x | 用于构建交互式小部件的核心UI框架 |
| TypeScript | 5.9+ | 类型安全的JavaScript，改善开发人员体验 |
| 维特 | 7.x | 闪电快速构建工具和开发服务器 |
| TailwindCSS | 4.x | 实用的CSS样式框架 |
| 帧运动 | 12.x | 用于平滑UI过渡的动画库 |
| Mapbox GL | 3.x | 商店定位器小部件的交互式地图 |
| 传单 | 1.9+ | 替代映射库 |
| Lucide反应 | 0.536+ | 图标库 |
| Embla旋转木马 | 8.x | 用于产品浏览的旋转木马组件 |
| 佐德 | 4.x | 模式验证 |
| React路由器 | 7.x | 客户端路由 |
| React国际 | 7.x | 国际化支持 |
后端（MCP服务器）
| 技术 | 版本 | 目的 |
|---|---|---|
| python | 3.10+ | 后端运行时 |
| 快速API | 0.115+ | 高性能异步web框架 |
| FastMCP | 0.1+ | Python模型上下文协议SDK |
| Uvicorn | 0.30+ | FastAPI的ASGI服务器 |
| 派丹蒂克 | 2.x | 使用Python类型提示进行数据验证 |
| Jinja2 | 3.1+ | OAuth同意页面的HTML模板 |
| HTTPX | 0.27+ | 异步HTTP客户端 |
| python dotenv | 1.0+ | 环境变量管理 |
OAuth 2.0实现
服务器包括 自定义OAuth 2.0提供程序 支持：
- 动态客户端注册 –ChatGPT自动注册为OAuth客户端
- 使用PKCE的授权码流 –安全的身份验证流程
- 许可证管理 –访问令牌、刷新令牌和撤销
- 持久化存储 基于JSON的OAuth数据存储（客户端、令牌、身份验证码）
- 多提供商支持 –自定义、Google OAuth和Azure Entra ID
构建和开发工具
| 工具 | 目的 |
|---|---|
| pnpm | 快速、磁盘高效的包管理器 |
| TSX | 构建脚本的TypeScript执行 |
| esb构建 | 快速JavaScript打包器（通过Vite） |
| 快速地球仪 | 多条目构建的文件模式匹配 |
| 服务 | 用于预览构建资产的静态文件服务器 |
架构概述
┌─────────────────────────────────────────────────────────────────┐
│ ChatGPT Client │
└──────────────────────────────┬──────────────────────────────────┘
│ MCP Protocol (HTTP/SSE)
▼
┌─────────────────────────────────────────────────────────────────┐
│ MCP Server (FastAPI + FastMCP) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Tool Handlers │ │ OAuth Provider │ │ Static Assets │ │
│ │ (Widgets) │ │ (Auth Flow) │ │ (/assets/) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└──────────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Widget HTML/JS/CSS Bundles │
│ (React components compiled with Vite + TailwindCSS) │
└─────────────────────────────────────────────────────────────────┘关键设计模式
- 多入口构建系统 –每个小部件都是作为一个独立的捆绑包构建的，有自己的HTML、JS和CSS
- 小部件元数据协议 –MCP响应包括
_meta.openai/outputTemplate用于ChatGPT小部件渲染 - CSP合规性 –用于在ChatGPT中嵌入安全小部件的内容安全策略标头
- 工厂模式 –通过工厂创建OAuth提供程序以实现可扩展性
- 持久令牌存储 –具有自动过期清理功能的线程安全JSON存储
先决条件
- Node.js 18+
- pnpm（推荐）或npm/yarn
- Python 3.10+（适用于Python MCP服务器）
安装依赖项
克隆存储库并安装工作区依赖项：
pnpm install使用npm还是yarn？使用首选客户端安装根依赖项，并相应地调整以下命令。
构建组件库
这些组件被捆绑到MCP服务器作为可重用UI资源的独立资产中。
pnpm run build此命令运行 build-all.mts，生成版本 .html, .js，以及 .css 内部文件 assets/每个小部件都用它需要的CSS包装，这样你就可以直接托管捆绑包，或者用你自己的服务器运送它们。
要在本地迭代组件，您还可以启动Vite-dev服务器：
pnpm run dev为静态资产提供服务
如果您想在没有MCP服务器的情况下预览生成的捆绑包，请在运行构建后启动静态文件服务器：
pnpm run serve资产暴露于 http://localhost:4444 启用CORS，以便本地工具（包括MCP检查员）可以获取它们。
运行MCP服务器
该存储库附带了一个MCP服务器，突出显示了以AT&T为中心的小部件包：
- AT&T产品（Python） –带有交互式地图的AT&T商店、产品和服务定位器
每个工具响应都包括纯文本内容、结构化JSON和 _meta.openai/outputTemplate 元数据，以便Apps SDK可以水合匹配的小部件。
AT&T产品Python服务器
python -m venv .venv
source .venv/bin/activate
pip install -r att_server_python/requirements.txt
uvicorn att_server_python.main:app --port 8000或者直接运行：
cd att_server_python
python main.py在ChatGPT中进行测试
要将这些应用程序添加到ChatGPT，请启用 开发者模式，然后在“设置”>“连接器”中添加应用程序。
要添加本地服务器而不进行部署，可以使用以下工具 吸烟 将您的本地服务器暴露到互联网。
例如，一旦您的MCP服务器运行，您可以运行：
ngrok http 8000您将获得一个公共URL，可用于在“设置”>“连接器”中将本地服务器添加到ChatGPT。
例如： https://.ngrok-free.app/mcp
添加连接器后，您可以在ChatGPT对话中使用它。
您可以通过在“更多”选项中选择应用程序，将其添加到对话上下文中。
然后，您可以通过询问相关问题来调用工具。例如，对于AT&T产品应用程序，您可以问：
- “查找我附近的AT&T商店”
- “显示AT&T无线计划”
- “at&T有哪些手机？”
- “我在哪里可以获得AT&T光纤互联网？”
- “你给我推荐什么？”或“显示个性化优惠”
- “告诉我有关Internet备份的信息”或“您提供Internet备份服务吗？”
OAuth身份验证（可选）
AT&T MCP服务器内置OAuth 2.0身份验证，用于安全访问控制。
快速开始
# 1. Enable OAuth in .env
cd att_server_python
cp .env.example .env
# Edit .env: Set OAUTH_ENABLED=true
# 2. Install dependencies (includes jinja2)
pip install -r requirements.txt
# 3. Start server
python main.py
# 4. Test OAuth
curl https://your-domain.com/oauth/stats | jq特性
- ✅ 动态客户端注册 –ChatGPT自动注册为客户端
- ✅ 授权码流 –标准OAuth 2.0和PKCE
- ✅ 自定义同意UI –现代授权页面
- ✅ 灵活的范围 –细粒度访问控制
- ✅ 许可证管理 –访问令牌、刷新令牌和撤销
文档
配置
OAuth是通过以下环境变量配置的 .env:
OAUTH_ENABLED=true
OAUTH_ISSUER_URL=https://att-mcp.jpaulo.io
OAUTH_VALID_SCOPES=read,write,payment,account
OAUTH_DEFAULT_SCOPES=read看 OAUTH_SETUP_GUIDE.md 了解详细的配置选项。
下一步行动
- 自定义小部件数据：在中编辑处理程序
att_server_python/main.py从您的系统中获取数据。 - 创建自己的组件并将其添加到库中：将新条目放入
src/它们将由构建脚本自动拾取。
部署您的MCP服务器
您可以使用您选择的云环境来部署MCP服务器。
将其包含在环境变量中：
BASE_URL=https://your-server.com这将用于为小部件生成HTML，以便它们可以从该托管url提供静态资产。
贡献
欢迎您打开问题或提交PR来改进此应用程序，但是请注意，我们可能不会审核所有建议。
许可证
该项目根据MIT许可证获得许可。看 许可证 了解详情。