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許可證。