MCP Ai Bridge

🚀 MCP AI 橋接器

MCP AI 橋接器是一個安全的模型上下文協議（MCP）服務器，它能夠將 Claude Code 與 OpenAI 和 Google Gemini 的 API 進行橋接，實現多種模型的便捷訪問。

🚀 快速開始

要使用 MCP AI 橋接器，你需要完成以下幾個步驟：

1. 克隆或複製項目：將 mcp-ai-bridge 目錄克隆或複製到你喜歡的位置。
2. 安裝依賴：在項目目錄下，通過以下命令安裝所需的依賴：

cd mcp-ai-bridge
npm install

3. 配置 API 密鑰：你可以通過以下三種方式之一配置 API 密鑰：
   • 選項 A：使用主目錄下的全局 .env 文件（推薦）：創建或編輯 ~/.env 文件，並添加你的 API 密鑰：

     OPENAI_API_KEY=your_openai_api_key_here
     GOOGLE_AI_API_KEY=your_google_ai_api_key_here
     

   • 選項 B：使用本地 .env 文件：在 mcp-ai-bridge 目錄下創建 .env 文件：

     cp .env.example .env
     

     然後將 API 密鑰添加到這個本地 .env 文件中。
   • 選項 C：在 Claude Code 配置中使用環境變量：直接在 Claude Code 設置中進行配置（詳見配置部分）。 服務器將按以下順序檢查環境變量：
     1. ~/.env（主目錄）
     2. ./.env（mcp-ai-bridge 目錄本地）
     3. 系統環境變量
4. 可選配置變量：你可以根據需要配置以下可選變量：

   # 日誌級別 (error, warn, info, debug)
   LOG_LEVEL=info
   
   # 服務器標識
   MCP_SERVER_NAME=AI Bridge
   MCP_SERVER_VERSION=1.0.0
   
   # 安全配置
   SECURITY_LEVEL=moderate              # disabled, basic, moderate, strict
   
   # 內容過濾 (細粒度控制)
   BLOCK_EXPLICIT_CONTENT=true         # 主內容過濾開關
   BLOCK_VIOLENCE=true                  # 阻止暴力內容
   BLOCK_ILLEGAL_ACTIVITIES=true       # 阻止非法活動請求
   BLOCK_ADULT_CONTENT=true             # 阻止成人/色情內容
   
   # 注入檢測 (細粒度控制)
   DETECT_PROMPT_INJECTION=true        # 主注入檢測開關
   DETECT_SYSTEM_PROMPTS=true           # 檢測系統角色注入
   DETECT_INSTRUCTION_OVERRIDE=true     # 檢測 "忽略指令" 嘗試
   
   # 輸入清理 (細粒度控制)
   SANITIZE_INPUT=true                  # 主清理開關
   REMOVE_SCRIPTS=true                  # 移除腳本標籤和 JS
   LIMIT_REPEATED_CHARS=true            # 限制通過重複字符進行的 DoS 攻擊
   
   # 性能與靈活性
   ENABLE_PATTERN_CACHING=true          # 緩存編譯模式以提高速度
   MAX_PROMPT_LENGTH_FOR_DEEP_SCAN=1000 # 長提示跳過深度掃描
   ALLOW_EDUCATIONAL_CONTENT=false      # 白名單教育內容
   WHITELIST_PATTERNS=                  # 允許的逗號分隔的正則表達式模式
   

✨ 主要特性

• OpenAI 集成：可訪問 GPT - 4o、GPT - 4o Mini、GPT - 4 Turbo、GPT - 4 以及推理模型（o1、o1 - mini、o1 - pro、o3 - mini）。
• Gemini 集成：可訪問 Gemini 1.5 Pro、Gemini 1.5 Flash 以及具備最新功能的視覺模型。
• 安全特性：
  • 增強的輸入驗證：多層驗證與清理機制。
  • 內容過濾：阻止明確、有害和非法的內容。
  • 提示注入檢測：識別並阻止操縱嘗試。
  • 速率限制：通過可配置的限制防止 API 濫用。
  • 安全的錯誤處理：不暴露敏感信息。
  • API 密鑰驗證：對 API 密鑰進行格式驗證。
  • 可配置的安全級別：提供基本、中等和嚴格三種模式。
• 強大的錯誤處理：特定的錯誤類型帶有詳細的消息。
• 結構化日誌記錄：基於 Winston 的日誌記錄，具有可配置的級別。
• 靈活的配置：可控制每個請求的溫度和模型選擇。

📦 安裝指南

克隆項目

將 mcp-ai-bridge 目錄克隆或複製到你指定的位置。

安裝依賴

cd mcp-ai-bridge
npm install

配置 API 密鑰

你可以選擇以下三種方式之一來配置 API 密鑰：

• 選項 A：使用全局 .env 文件（推薦）
  • 創建或編輯 ~/.env 文件。
  • 添加 API 密鑰：

    OPENAI_API_KEY=your_openai_api_key_here
    GOOGLE_AI_API_KEY=your_google_ai_api_key_here
    

• 選項 B：使用本地 .env 文件
  • 在 mcp-ai-bridge 目錄下創建 .env 文件：

    cp .env.example .env
    

  • 將 API 密鑰添加到本地 .env 文件中。
• 選項 C：在 Claude Code 配置中使用環境變量
  • 直接在 Claude Code 設置中進行配置（詳見配置部分）。

可選配置

你可以根據需要配置一些可選變量，具體可參考快速開始部分的可選配置變量說明。

💻 使用示例

基礎用法

在 Claude Code 中，你可以使用以下工具進行查詢：

mcp__ai-bridge__ask_openai
  prompt: "Explain the concept of recursion in programming"
  model: "gpt-4o"
  temperature: 0.5

mcp__ai-bridge__ask_gemini
  prompt: "What are the key differences between Python and JavaScript?"
  model: "gemini-1.5-flash-latest"

mcp__ai-bridge__server_info

高級用法

如果你在使用 MCP 服務器時遇到問題，可以使用 Claude Code 的調試功能：

# 啟用 MCP 調試模式以獲取詳細的錯誤信息
claude --mcp-debug

# 檢查 MCP 服務器狀態和工具
claude
# 然後使用 /mcp 斜槓命令查看服務器詳細信息

📚 詳細文檔

在 Claude Code 中配置

方法 1：使用 Claude Code CLI（推薦）

使用交互式 MCP 設置嚮導：

claude mcp add

或者直接添加服務器配置：

claude mcp add-json ai-bridge '{"command": "node", "args": ["/path/to/mcp-ai-bridge/src/index.js"]}'

方法 2：手動配置

根據你的環境，將以下內容添加到 Claude Code MCP 設置中：

• Claude Code CLI：使用配置目錄（通常是 ~/.claude/ 或 $CLAUDE_CONFIG_DIR）中的 settings.json 文件。
• Claude 桌面版：使用 ~/.claude/claude_desktop_config.json 文件。

對於 Claude 桌面版兼容性：

{
  "mcpServers": {
    "ai-bridge": {
      "command": "node",
      "args": ["/path/to/mcp-ai-bridge/src/index.js"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key",
        "GOOGLE_AI_API_KEY": "your_google_ai_api_key"
      }
    }
  }
}

或者，如果你已經配置了 .env 文件，可以省略 env 部分：

{
  "mcpServers": {
    "ai-bridge": {
      "command": "node",
      "args": ["/path/to/mcp-ai-bridge/src/index.js"]
    }
  }
}

方法 3：從 Claude 桌面版導入

如果你已經在 Claude 桌面版中進行了配置，可以導入配置：

claude mcp add-from-claude-desktop

可用工具

1. ask_openai

使用完整的驗證和安全功能查詢 OpenAI 模型。

• 參數：
  • prompt（必需）：要發送的問題或提示（最大 10,000 個字符）。
  • model（可選）：從 'gpt - 4o'、'gpt - 4o - mini'、'gpt - 4 - turbo'、'gpt - 4'、'o1'、'o1 - mini'、'o1 - pro'、'o3 - mini'、'chatgpt - 4o - latest' 等可用模型中選擇（默認：'gpt - 4o - mini'）。
  • temperature（可選）：控制隨機性（0 - 2，默認：0.7）。
• 安全特性：
  • 對提示長度和類型進行輸入驗證。
  • 溫度範圍驗證。
  • 模型驗證。
  • 速率限制（默認每分鐘 100 個請求）。

2. ask_gemini

使用完整的驗證和安全功能查詢 Google Gemini 模型。

• 參數：
  • prompt（必需）：要發送的問題或提示（最大 10,000 個字符）。
  • model（可選）：從 'gemini - 1.5 - pro - latest'、'gemini - 1.5 - pro - 002'、'gemini - 1.5 - pro'、'gemini - 1.5 - flash - latest'、'gemini - 1.5 - flash'、'gemini - 1.5 - flash - 002'、'gemini - 1.5 - flash - 8b'、'gemini - 1.0 - pro - vision - latest'、'gemini - pro - vision' 中選擇（默認：'gemini - 1.5 - flash - latest'）。
  • temperature（可選）：控制隨機性（0 - 1，默認：0.7）。
• 安全特性：
  • 對提示長度和類型進行輸入驗證。
  • 溫度範圍驗證。
  • 模型驗證。
  • 速率限制（默認每分鐘 100 個請求）。

3. server_info

獲取全面的服務器狀態和配置信息。

• 返回：
  • 服務器名稱和版本。
  • 每個服務可用的模型。
  • 安全設置（速率限制、驗證狀態）。
  • 每個 API 的配置狀態。

測試

項目包含全面的單元測試和安全測試。要運行測試，可以使用以下命令：

# 運行所有測試（包括安全測試）
npm test

# 以監視模式運行測試
npm run test:watch

# 運行測試並生成覆蓋率報告
npm run test:coverage

測試覆蓋範圍

• 對所有服務器功能進行單元測試。
• 對輸入驗證和速率限制進行安全測試。
• 對 API 交互進行集成測試。
• 進行錯誤處理測試。
• 使用基於模擬的測試以避免實際的 API 調用。

故障排除

常見問題

1. “API 密鑰未配置”錯誤：確保你已將正確的 API 密鑰添加到 .env 文件或 Claude Code 配置中。
2. “無效的 OpenAI API 密鑰格式”錯誤：OpenAI 密鑰必須以 'sk - ' 開頭。
3. “速率限制已超過”錯誤：等待速率限制窗口重置（默認：1 分鐘）。
4. “提示過長”錯誤：保持提示在 10,000 個字符以內。
5. 模塊未找到錯誤：在 mcp-ai-bridge 目錄下運行 npm install。
6. 權限錯誤：確保 index.js 文件具有執行權限。
7. 日誌記錄問題：設置 LOG_LEVEL 環境變量（error、warn、info、debug）。

Claude Code 特定的故障排除

8. MCP 服務器未加載：

• 使用 claude --mcp-debug 查看詳細的錯誤消息。
• 使用 /mcp 斜槓命令檢查服務器配置。
• 驗證服務器路徑是否正確且可訪問。
• 確保 Node.js 已安裝並在你的 PATH 中。

9. 配置問題：

• 使用 claude mcp add 進行交互式設置。
• 如果使用自定義配置位置，請檢查 CLAUDE_CONFIG_DIR 環境變量。
• 對於超時問題，配置 MCP_TIMEOUT 和 MCP_TOOL_TIMEOUT 環境變量。

10. 服務器啟動失敗：

• 檢查服務器進程是否可以獨立啟動：node /path/to/mcp-ai-bridge/src/index.js。
• 驗證所有依賴項是否已安裝。
• 檢查服務器目錄的文件權限。

安全特性

增強的安全保護

• 多層輸入驗證：對類型、長度和內容進行驗證。
• 內容過濾：阻止明確、暴力、非法和有害的內容。
• 提示注入檢測：識別並防止操縱嘗試，包括：
  • 指令覆蓋嘗試（“忽略先前的指令”）。
  • 系統角色注入（“system: act as...”）。
  • 模板注入（{{system}}、<|system|>、[INST]）。
  • 可疑模式檢測。
• 輸入清理：移除控制字符、腳本和惡意模式。
• 速率限制：默認每分鐘 100 個請求，防止 API 濫用。
• API 密鑰驗證：在使用前對 API 密鑰進行格式驗證。
• 安全的錯誤處理：錯誤消息中不包含堆棧跟蹤或敏感信息。
• 結構化日誌記錄：所有操作都以適當的級別進行日誌記錄。

安全級別

• 基本：最小過濾，允許大多數內容。
• 中等（默認）：平衡的保護，具有合理的限制。
• 嚴格：最大保護，阻止臨界內容。

細粒度的安全配置

• 安全級別：可以選擇 disabled（無安全檢查，最大性能）、basic（僅基本保護，性能良好）、moderate（平衡保護，默認，良好平衡）、strict（最大保護，可能影響性能）。
• 單個功能控制：可以對內容過濾、注入檢測、輸入清理等功能進行細粒度的控制，具體可參考安裝指南部分的可選配置變量說明。
• 性能考慮：
  • 模式緩存減少正則表達式編譯開銷。
  • 在基本模式下，長提示（>1000 字符）進行較輕的掃描。
  • 發現問題後提前終止檢查。
  • 細粒度控制允許你禁用不需要的檢查。

最佳實踐

• 永遠不要將 .env 文件提交到版本控制。
• 保持你的 API 密鑰安全，並定期輪換。
• 考慮在你的 API 賬戶上設置使用限制。
• 監控日誌以發現異常活動。
• 使用速率限制功能控制成本。
• 使用 server_info 工具驗證服務器配置。

速率限制

服務器實現了滑動窗口速率限制：

• 默認：每分鐘 100 個請求。
• 可通過環境變量進行配置。
• 按會話跟蹤。
• 提供帶有重置時間信息的優雅錯誤消息。