gatewaystack-chatgpt-starter

🚀 安全地将内部工具暴露给大语言模型

本项目旨在为用户提供安全途径，使其能够从ChatGPT内部访问他们自己的数据。通过解决用户、大语言模型（LLM）和后端之间的信任与治理问题，实现了用户数据的安全访问。

🚀 快速开始

git clone https://github.com/davidcrowe/gatewaystack-chatgpt-starter
cd gatewaystack-chatgpt-starter
npm install
cp .env.example .env
# 用你的OAuth配置编辑.env文件
npm run dev

✨ 主要特性

• 解决三方问题：建立用户、大语言模型和后端之间的信任和治理层，解决用户身份验证和数据访问的安全问题。
• 安全的数据访问：确保用户只能访问他们自己的数据，避免数据泄露和滥用。
• 全面的功能支持：提供MCP JSON - RPC端点、OAuth发现端点、JWT验证、请求上下文对象、工具范围强制实施、工具执行代理和结构化日志记录等功能。
• 多部署选项：支持本地开发、通过Cloud Build进行Cloud Run部署以及任何Node兼容的容器运行时。
• 可定制性强：允许用户自定义工具注册表、身份映射和后端执行。

📦 安装指南

要安装本项目，请按照以下步骤操作：

git clone https://github.com/davidcrowe/gatewaystack-chatgpt-starter
cd gatewaystack-chatgpt-starter
npm install
cp .env.example .env
# 编辑.env文件，配置OAuth信息
npm run dev

💻 使用示例

基础用法

在本地开发环境中，可以直接运行以下命令启动项目：

npm run dev

启动后，你可以通过以下方式与项目进行交互：

• MCP端点：通过POST /mcp访问MCP JSON - RPC端点。
• OAuth发现端点：通过GET /.well-known/oauth-protected-resource和GET /.well-known/openid-configuration进行OAuth发现。

高级用法

如果你想将项目部署到生产环境，可以选择通过Cloud Build进行Cloud Run部署：

# 按照docs/deploy-your-own.md中的说明进行CI/CD设置和Cloud Run配置

部署完成后，你可以通过访问部署的URL来使用项目。

📚 详细文档

信任与治理层

现代AI应用涉及用户、大语言模型和后端三个参与者，但缺乏一个共享的身份层将它们绑定在一起，这导致了用户范围的数据、策略和审计差距。本项目通过实现一个解决方案来解决这个三方问题，构建MCP服务器，使工具和应用能够在ChatGPT内部以真实的用户范围访问。

实时演示

你可以通过连接ChatGPT到实时部署演示来体验OAuth和用户身份验证的端到端工作流程。该演示通过Cloud Build CI/CD在Cloud Run上运行此代码库，让你无需克隆、部署或配置即可体验完整的MCP + OAuth流程。

适用场景

本项目适用于构建代表真实用户操作的ChatGPT工具的团队，典型用例包括：

• 通过ChatGPT Enterprise为员工提供内部工具访问。
• 需要用户范围访问公司数据的AI代理。
• 需要单点登录（SSO）、审计和工具级权限的内部AI平台。
• 寻找参考OAuth + MCP实现的团队。

功能特性

本项目提供以下功能：

• MCP JSON - RPC端点：在POST /mcp提供initialize、tools/list、tools/call等端点。
• OAuth发现端点：提供/.well-known/*端点用于ChatGPT OAuth发现。
• JWT验证：通过@gatewaystack/identifiabl进行JWT验证（发行者/受众/JWKS）。
• 端到端请求上下文对象：通过@gatewaystack/request-context提供请求上下文对象。
• 工具范围强制实施：确保每个工具只能访问其授权范围内的数据。
• 工具执行代理：通过@gatewaystack/proxyabl进行工具执行代理。
• 结构化请求上下文日志记录：通过@gatewaystack/explicabl进行结构化日志记录。

工作原理

当ChatGPT调用MCP服务器时，服务器会验证JWT，强制实施工具范围，将sub映射到uid，并根据需要执行工具。OAuth令牌在整个流程中保持不变，确保端到端的安全性。

身份验证和身份提供者

本项目与任何能够颁发JWT访问令牌（JWS）的OAuth 2.0 / OIDC提供者兼容。提供了Auth0和其他身份提供者的设置指南。

端点说明

• MCP端点：POST /mcp
• OAuth发现端点：GET /.well-known/oauth-protected-resource、GET /.well-known/openid-configuration
• 调试端点：GET /（健康检查）、GET /debug-token（验证Bearer令牌并显示sub/aud/scope）

部署选项

本项目支持多种部署方式，包括本地开发、通过Cloud Build进行Cloud Run部署（推荐）和任何Node兼容的容器运行时。详细的部署说明请参考deploy-your-own.md。

演示工具

本项目提供两个演示工具：

• whoami：证明用户身份的流动（返回uid、sub、scopes）
• echo：回显消息 工具定义位于src/tools/tools.ts。

定制应用

通常，你只需要更改以下三个方面：

• 工具注册表：在src/tools/tools.ts中定义工具、所需范围和MCP描述符。
• 身份映射：在src/handlers/authHelpers.ts中实现subjectToUid(sub, email?)函数，将OAuth主题映射到内部用户ID。
• 后端执行（可选）：如果需要真正的后端，可以配置Proxyabl调用后端端点，转发OAuth令牌，并在后端验证JWT。

常见问题

• 401 + invalid_token：发行者/受众不匹配，或JWKS不可访问。
• ACCESS_TOKEN_IS_ENCRYPTED_JWE：身份提供者返回JWE，需要JWS访问令牌。
• tools/list一直提示OAuth：ChatGPT未看到有效的WWW - Authenticate头（检查/.well-known/oauth-protected-resource和buildWwwAuthenticate()）。

仓库布局

• src/gateway/toolGateway.ts：主要HTTP处理程序（MCP + well - known + REST工具）
• src/handlers/*：身份验证助手、MCP处理程序、well - known处理程序和其他辅助函数
• src/tools/tools.ts：工具包（范围 + 描述符 + 输出整形）
• src/server/expressServer.ts：本地开发服务器

文档说明

本仓库旨在被分叉和改编，它包含了经过生产测试的OAuth保护MCP工具模式，你无需自己重新探索困难的部分。如果你正在构建需要身份验证、授权和可审计性的严肃AI系统，这是我们自己使用的基础。

🔧 技术细节

OAuth序列图

工作流程

当ChatGPT调用MCP服务器时，具体流程如下：

1. ChatGPT使用Bearer令牌调用tools/list或tools/call。
2. 服务器验证JWT（JWKS / 发行者 / 受众），强制实施工具范围，将sub映射到uid。
3. 工具执行：简单工具可以在本地运行，复杂工具可以通过Proxyabl转发到后端。

身份验证和授权

• JWT验证：使用@gatewaystack/identifiabl进行JWT验证，确保令牌的发行者、受众和签名有效。
• 工具范围强制实施：确保每个工具只能访问其授权范围内的数据。
• 身份映射：通过subjectToUid(sub, email?)函数将OAuth主题映射到内部用户ID。

后端集成

如果需要将工具连接到后端，可以配置Proxyabl调用后端端点，转发OAuth令牌，并在后端验证JWT，使用sub或uid来限制数据访问范围。

📄 许可证

本项目遵循Apache - 2.0许可证。