Groqcloud MCP Server

🚀 Groq MCP 服務器

這是一個功能完備且智能的 模型上下文協議 (MCP) 服務器，旨在將您的應用程序與強大的 Groq API 集成，為您提供對世界上最快的人工智能模型的優化訪問。

它就像一座智能橋樑，允許兼容的客戶端（如 Claude Desktop）使用 Groq 的各種模型進行文本補全、音頻轉錄、視覺分析和批量處理。

✨ 主要特性

🧠 支持的模型

該服務器配置為管理並將請求路由到多種 Groq 模型，包括：

• 文本補全 (LLMs)：
  • llama-3.1-8b-instant
  • llama-3.3-70b-versatile
  • deepseek-r1-distill-llama-70b
  • qwen/qwen3-32b（以及用於數學計算的 qwen-qwq-32b）
  • compound-beta、compound-beta-mini
  • allam-2-7b、gemma2-9b-it、llama3-70b-8192、llama3-8b-8192
  • mistral-saba-24b
• 安全防護 (提示/內容防護)：
  • meta-llama/llama-guard-4-12b
  • meta-llama/llama-prompt-guard-2-22m、meta-llama/llama-prompt-guard-2-86m
• 視覺 (多模態)：
  • meta-llama/llama-4-maverick-17b-128e-instruct
  • meta-llama/llama-4-scout-17b-16e-instruct
• 音頻 (語音轉文本)：
  • whisper-large-v3、whisper-large-v3-turbo
  • distil-whisper-large-v3-en
• 文本轉語音：
  • playai-tts、playai-tts-arabic

⚡ 高級功能

• 智能路由 (ModelRouter)： 根據優先級（速度、質量、成本、推理能力、數學計算能力、多語言支持）、提示覆雜度和特定功能（視覺、音頻）動態選擇最佳模型。
• 可控速率限制： 為每個模型智能管理可配置的請求速率和每分鐘令牌限制（RPM/TPM），優化 API 使用效率。
• 優化緩存： 內存緩存系統，可配置 TTL（生存時間），用於存儲大語言模型的響應，減少延遲和對 API 的冗餘調用。
• 詳細指標： 全面收集使用指標、性能指標（延遲、吞吐量）、錯誤信息和模型分佈情況，便於分析和監控。
• 強大的錯誤處理： 集中式錯誤處理系統，具備自動重試機制，提高 API 請求的彈性。
• 批量處理： 支持 Groq 的批量處理工具，可高效發送大量請求並節省成本。
• 結構化日誌和調試： 使用 Winston 實現專業的日誌系統，生成結構化日誌，並在開發過程中將彩色輸出定向到 stderr，便於調試和監控。

📦 安裝指南

先決條件

• Node.js：版本 v20.17.0 或更高版本，或 v22.9.0 或更高版本。建議使用 NVM（或適用於 Windows 的 nvm-windows）來管理 Node.js 版本。
• npm：Node.js 包管理器（通常隨 Node.js 一起安裝，且與推薦版本兼容）。
• TypeScript：版本 5 或更高版本。
• Groq API 密鑰：用於對 Groq API 請求進行身份驗證。您可以在 https://console.groq.com/keys 獲取。

快速安裝

1. 克隆倉庫：

   git clone [https://github.com/AyrtonFelipe/GroqCloud-MCP_server.git]
   cd groq-mcp-server
   

2. 安裝項目依賴：

   npm install
   # 同時安裝將 Zod 模式轉換為 JSON 模式的庫
   npm install zod-to-json-schema
   

3. 配置環境變量： 在項目根目錄創建一個 .env 文件（如果不存在，可從 .env.example 複製，前提是有提供）：

   cp .env.example .env
   

   編輯 .env 文件，添加您的 Groq API 密鑰：

   GROQ_API_KEY="您的 Groq API 密鑰"
   

   （可選：根據需要配置其他變量，如 LOG_LEVEL。）

4. 更新 src/config/models.json： 該文件定義了服務器將使用和公開的 Groq 模型。

   • 移除 不再可用或不想使用的模型條目（請查閱 Groq 控制檯的最新列表）。
   • 添加 “支持的模型” 列表中尚未存在的所有模型。對於每個新模型，您必須 填寫其所有屬性（名稱、描述、功能、costPer1kTokens、rateLimits 等），可參考 Groq 官方文檔 獲取準確值。
   • 調整 models.json 中的 modelSelectionRules 和 complexityThresholds 部分，以反映您擁有的模型和所需的選擇邏輯（例如，針對 reasoning、mathematical、multilingual 優先級）。

5. 更新 src/config/constants.ts：

   • 將常量 RATE_LIMITS 與 models.json 中的模型同步。確保 models.json 中的每個模型在 RATE_LIMITS 中都有對應的條目，包含準確的 rpm（每分鐘請求數）和 tpm（每分鐘令牌數）（請查閱 Groq 文檔獲取最新值）。
   • 同時更新工具文件（src/tools/*.ts）中的 z.enum，以包含您希望向客戶端公開的新模型。

6. 編譯項目：

   npm run build
   

7. 啟動服務器：

   npm start
   

   服務器將啟動並通過 stdin/stdout 等待連接。

💻 使用示例

與 Claude Desktop 配合使用

當您的 MCP 服務器在本地運行後，Claude Desktop 應該能夠發現並使用其工具：

1. 啟動 Claude Desktop。
2. 檢查工具： Groq 工具（groq_text_completion、groq_audio_transcription、groq_vision_analysis、groq_batch_processing）應在 Claude Desktop 界面中顯示為已啟用（通常在工具菜單或集成菜單中）。
3. 開始交互： 開始與 Claude 對話，並要求它使用這些工具。例如：
   • 使用 groq_text_completion 生成一篇關於 Groq 人工智能能力的文本。
   • 使用 groq_text_completion 工具分析財務數據 { 數據: [100, 250, 80, 400] }，並使用模型：llama-3.3-70b-versatile
   • groq_audio_transcription: 使用 'whisper-large-v3-turbo' 轉錄文件 '路徑/到/您的/音頻.mp3'。
   • groq_vision_analysis: 使用 'meta-llama/llama-4-scout-17b-16e-instruct' 描述圖片 'https://example.com/您的圖片.jpg'。

📚 詳細文檔

項目結構

.
├── src/
│   ├── config/
│   │   ├── constants.ts         # 系統常量 (RATE_LIMITS, API_ENDPOINTS 等)
│   │   └── models.json          # Groq 模型的詳細定義
│   ├── tools/
│   │   ├── audio-transcription.ts # 音頻轉錄工具
│   │   ├── batch-processing.ts    # 批量處理工具
│   │   ├── model-router.ts        # 模型選擇的核心邏輯
│   │   ├── text-completion.ts     # 文本補全工具
│   │   └── vision-analysis.ts     # 視覺分析工具
│   │   └── ... (如果實現了其他工具，如文本轉語音)
│   ├── types/
│   │   └── groq-types.ts          # Groq 模型的 TypeScript 類型定義
│   ├── utils/
│   │   ├── cache-manager.ts       # 緩存管理器
│   │   ├── error-handler.ts       # 集中式錯誤處理和重試機制
│   │   ├── logger.ts              # 使用 Winston 配置日誌記錄
│   │   ├── metrics-tracker.ts     # 收集使用和性能指標
│   │   └── rate-limiter.ts        # 速率限制實現
│   └── server.ts                  # MCP 服務器的主要入口點
├── dist/                          # TypeScript 編譯輸出
├── logs/                          # 應用程序日誌
├── .env                           # 環境變量 (如 GROQ_API_KEY)
├── .gitignore                     # Git 忽略的文件和文件夾
├── package.json                   # 項目元數據和依賴項
├── tsconfig.json                  # TypeScript 編譯器配置
└── README.md                      # 本文件

🔧 技術細節

未來規劃 (擴展到 Web)

本項目目前配置為使用 StdioServerTransport 進行本地使用。要擴展到 Web 服務器環境（例如生產環境），以下考慮因素至關重要：

• 通信傳輸： 從 StdioServerTransport 遷移到 Web 傳輸方式，如 服務器發送事件 (SSE) 或 WebSockets，以便與 Web 客戶端進行通信。
• 啟動機制： 調整服務器的生命週期，以適應 Web 框架（如 Express、Fastify），使其能夠監聽 HTTP/HTTPS 端口。
• 協議實現： 實現 HTTP 路由，映射到 MCP 的 JSON-RPC 調用。
• 安全措施： 添加身份驗證（如 JWT）、授權、HTTPS 和 CORS 配置，以保護服務器。
• 可擴展性： 實施策略以處理多個客戶端和高流量（例如負載均衡、Node.js 集群、使用分佈式緩存如 Redis 用於 CacheManager 和 RateLimiter）。

開發者：Ayrton Felipe