MCP Ai Hub

🚀 MCP AI Hub

MCP AI Hub 是一個模型上下文協議（MCP）服務器，它藉助 LiteLM 實現對各種 AI 供應商的統一訪問。通過單一、一致的接口，你可以與 OpenAI、Anthropic 等 100 多種 AI 模型進行交互。

🚀 快速開始

1. 安裝

選擇你喜歡的安裝方式：

# 選項 A：從 PyPI 安裝
pip install mcp-ai-hub

# 選項 B：使用 uv 安裝（推薦）
uv tool install mcp-ai-hub

# 選項 C：從源代碼安裝
pip install git+https://github.com/your-username/mcp-ai-hub.git

安裝說明：

• uv 是一個快速的 Python 包安裝器和解析器。
• 該包需要 Python 3.10 或更高版本。
• 所有依賴項會自動解析和安裝。

2. 配置

在 ~/.ai_hub.yaml 創建一個配置文件，並填入你的 API 密鑰和模型配置：

model_list:
  - model_name: gpt-4  # 在 MCP 工具中使用的友好名稱
    litellm_params:
      model: openai/gpt-4  # LiteLM 供應商/模型標識符
      api_key: "sk-your-openai-api-key-here"  # 你的實際 OpenAI API 密鑰
      max_tokens: 2048  # 最大響應令牌數
      temperature: 0.7  # 響應創造性（0.0 - 1.0）

  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: "sk-ant-your-anthropic-api-key-here"
      max_tokens: 4096
      temperature: 0.7

配置指南：

• API 密鑰：將佔位符密鑰替換為你的實際 API 密鑰。
• 模型名稱：使用你能記住的描述性名稱（例如，gpt-4，claude-sonnet）。
• LiteLM 模型：使用 LiteLM 的供應商/模型格式（例如，openai/gpt-4，anthropic/claude-3-5-sonnet-20241022）。
• 參數：配置 max_tokens、temperature 和其他 LiteLM 支持的參數。
• 安全性：使用適當的文件權限（chmod 600）確保你的配置文件安全。

3. 連接到 Claude Desktop

通過編輯配置文件，將 Claude Desktop 配置為使用 MCP AI Hub：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ai-hub": {
      "command": "mcp-ai-hub"
    }
  }
}

4. 連接到 Claude Code

claude mcp add -s user ai-hub mcp-ai-hub

✨ 主要特性

• 統一接口：為所有 AI 供應商提供單一 API。
• 100 多個供應商：涵蓋 OpenAI、Anthropic、Google、Azure、AWS Bedrock 等。
• MCP 協議：與 Claude Desktop 和 Claude Code 進行原生集成。
• 靈活配置：基於 YAML 的配置，並通過 Pydantic 進行驗證。
• 多種傳輸方式：支持 stdio、SSE 和 HTTP 傳輸選項。
• 自定義端點：支持代理服務器和本地部署。

💻 使用示例

基礎用法

# 主聊天工具
chat(model_name: str, message: str | list[dict]) -> str

• model_name：已配置模型的名稱（例如，"gpt-4"，"claude-sonnet"）。
• message：字符串消息或 OpenAI 風格的消息列表。
• 返回值：AI 模型的響應字符串。

# 模型發現工具
list_models() -> list[str]

• 返回值：所有已配置模型名稱的列表。

get_model_info(model_name: str) -> dict

• model_name：已配置模型的名稱。
• 返回值：模型配置詳細信息，包括供應商、參數等。

📚 詳細文檔

高級用法

CLI 選項和傳輸類型

MCP AI Hub 支持多種傳輸機制，以滿足不同的使用場景：

# 默認的 stdio 傳輸（適用於像 Claude Desktop 這樣的 MCP 客戶端）
mcp-ai-hub

# 服務器發送事件傳輸（適用於 Web 應用程序）
mcp-ai-hub --transport sse --host 0.0.0.0 --port 3001

# 可流式傳輸的 HTTP 傳輸（適用於直接 API 調用）
mcp-ai-hub --transport http --port 8080

# 自定義配置文件和調試日誌
mcp-ai-hub --config /path/to/config.yaml --log-level DEBUG

傳輸類型詳情

CLI 參數

• --transport {stdio,sse,http}：傳輸協議（默認：stdio）。
• --host HOST：SSE/HTTP 的主機地址（默認：localhost）。
• --port PORT：SSE/HTTP 的端口號（默認：3001；如果需要不同端口可覆蓋）。
• --config CONFIG：自定義配置文件路徑（默認：~/.ai_hub.yaml）。
• --log-level {DEBUG,INFO,WARNING,ERROR}：日誌詳細程度（默認：INFO）。

配置

MCP AI Hub 通過 LiteLM 支持 100 多種 AI 供應商。在 ~/.ai_hub.yaml 中配置你的模型，並填入 API 密鑰和自定義參數。

系統提示

你可以在兩個級別定義系統提示：

• global_system_prompt：默認應用於所有模型。
• 每個模型的 system_prompt：覆蓋該模型的全局提示。 優先級：特定於模型的提示 > 全局提示。如果某個模型的 system_prompt 設置為空字符串，則會禁用該模型的全局提示。

global_system_prompt: "你是一個有用的 AI 助手，請簡潔作答。"

model_list:
  - model_name: gpt-4
    system_prompt: "你是一個精確的編碼助手。"
    litellm_params:
      model: openai/gpt-4
      api_key: "sk-your-openai-api-key"

  - model_name: claude-sonnet
    # 空字符串禁用該模型的全局提示
    system_prompt: ""
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: "sk-ant-your-anthropic-api-key"

注意：

• 服務器會將配置的系統提示添加到發送給供應商消息列表的前面。
• 如果你傳遞一個已經包含 system 消息的顯式消息列表，兩個系統消息將按順序包含（配置的提示在前）。

支持的供應商

主要 AI 供應商：

• OpenAI：GPT-4、GPT-3.5-turbo、GPT-4-turbo 等。
• Anthropic：Claude 3.5 Sonnet、Claude 3 Haiku、Claude 3 Opus。
• Google：Gemini Pro、Gemini Pro Vision、Gemini Ultra。
• Azure OpenAI：Azure 託管的 OpenAI 模型。
• AWS Bedrock：Claude、Llama、Jurassic 等。
• Together AI：Llama、Mistral、Falcon 等開源模型。
• Hugging Face：各種開源模型。
• 本地模型：Ollama、LM Studio 等本地部署。

配置參數：

• api_key：你的供應商 API 密鑰（必需）。
• max_tokens：最大響應令牌數（可選）。
• temperature：響應創造性（0.0 - 1.0，可選）。
• api_base：自定義端點 URL（用於代理/本地服務器）。
• 其他：所有 LiteLM 支持的參數。

配置示例

基本配置：

global_system_prompt: "你是一個有用的 AI 助手，請簡潔作答。"

model_list:
  - model_name: gpt-4
    system_prompt: "你是一個精確的編碼助手。"  # 覆蓋全局提示
    litellm_params:
      model: openai/gpt-4
      api_key: "sk-your-actual-openai-api-key"
      max_tokens: 2048
      temperature: 0.7

  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: "sk-ant-your-actual-anthropic-api-key"
      max_tokens: 4096
      temperature: 0.7

自定義參數：

model_list:
  - model_name: gpt-4-creative
    litellm_params:
      model: openai/gpt-4
      api_key: "sk-your-openai-key"
      max_tokens: 4096
      temperature: 0.9  # 更高的創造性
      top_p: 0.95
      frequency_penalty: 0.1
      presence_penalty: 0.1

  - model_name: claude-analytical
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: "sk-ant-your-anthropic-key"
      max_tokens: 8192
      temperature: 0.3  # 較低的創造性，適用於分析任務
      stop_sequences: ["\n\n", "Human:"]

本地 LLM 服務器配置：

model_list:
  - model_name: local-llama
    litellm_params:
      model: openai/llama-2-7b-chat
      api_key: "dummy-key"  # 本地服務器通常接受任何 API 密鑰
      api_base: "http://localhost:8080/v1"  # 本地 OpenAI 兼容服務器
      max_tokens: 2048
      temperature: 0.7

更多供應商信息，請參考 LiteLLM 文檔：https://docs.litellm.ai/docs/providers。

開發

環境設置

# 安裝所有依賴項，包括開發依賴項
uv sync

# 以開發模式安裝包
uv pip install -e ".[dev]"

# 添加新的運行時依賴項
uv add package_name

# 添加新的開發依賴項
uv add --dev package_name

# 更新依賴項
uv sync --upgrade

運行和測試

# 運行 MCP 服務器
uv run mcp-ai-hub

# 使用自定義配置運行
uv run mcp-ai-hub --config ./custom_config.yaml --log-level DEBUG

# 使用不同的傳輸方式運行
uv run mcp-ai-hub --transport sse --port 3001

# 運行測試（當添加測試套件時）
uv run pytest

# 運行測試並生成覆蓋率報告
uv run pytest --cov=src/mcp_ai_hub --cov-report=html

代碼質量

# 使用 ruff 格式化代碼
uv run ruff format .

# 代碼檢查
uv run ruff check .

# 使用 mypy 進行類型檢查
uv run mypy src/

# 運行所有質量檢查
uv run ruff format . && uv run ruff check . && uv run mypy src/

故障排除

配置問題

配置文件問題：

• 文件位置：確保 ~/.ai_hub.yaml 存在於你的主目錄中。
• YAML 有效性：使用在線驗證器或 python -c "import yaml; yaml.safe_load(open('~/.ai_hub.yaml'))" 驗證 YAML 語法。
• 文件權限：使用 chmod 600 ~/.ai_hub.yaml 設置安全權限。
• 路徑解析：在自定義配置位置使用絕對路徑。

配置驗證：

• 必需字段：每個模型必須有 model_name 和 litellm_params。
• API 密鑰：驗證 API 密鑰是否正確引用且未過期。
• 模型格式：使用 LiteLM 兼容的模型標識符（例如，openai/gpt-4，anthropic/claude-3-5-sonnet-20241022）。

API 和認證錯誤

認證問題：

• 無效的 API 密鑰：檢查是否有拼寫錯誤、多餘空格或過期的密鑰。
• 權限不足：驗證 API 密鑰是否具有必要的模型訪問權限。
• 速率限制：監控 API 使用情況，並在需要時實現重試邏輯。
• 區域限制：某些模型可能並非在所有區域都可用。

特定於 API 的故障排除：

• OpenAI：檢查組織設置和模型可用性。
• Anthropic：驗證 Claude 模型的訪問權限和使用限制。
• Azure OpenAI：確保正確部署資源並配置端點。
• Google Gemini：檢查項目設置和 API 啟用情況。

MCP 連接問題

服務器啟動問題：

• 端口衝突：如果默認端口已被使用，請為 SSE/HTTP 傳輸使用不同的端口。
• 權限錯誤：確保 mcp-ai-hub 命令具有可執行權限。
• Python 路徑：驗證 Python 環境和包安裝情況。

客戶端配置問題：

• 命令路徑：確保 mcp-ai-hub 在 PATH 中，或者使用完整的絕對路徑。
• 工作目錄：某些 MCP 客戶端可能需要特定的工作目錄設置。
• 傳輸不匹配：Claude Desktop/Code 使用 stdio 傳輸。

性能和可靠性

響應時間問題：

• 網絡延遲：儘可能使用地理位置更近的 API 端點。
• 模型選擇：某些模型比其他模型更快（例如，GPT-3.5 與 GPT-4）。
• 令牌限制：較大的 max_tokens 值可能會增加響應時間。

可靠性改進：

• 重試邏輯：為臨時故障實現指數退避策略。
• 超時配置：為你的使用場景設置適當的超時時間。
• 健康檢查：監控服務器狀態，並在需要時重啟。
• 負載均衡：使用多個模型配置以實現冗餘。

🔧 技術細節

MCP AI Hub 作為 MCP 客戶端（如 Claude Desktop/Code）與多個 AI 供應商之間的橋樑，利用 LiteLM 的統一 API，實現對 100 多種 AI 模型的無縫訪問。它支持多種傳輸方式，包括 stdio、SSE 和 HTTP，以滿足不同的使用場景。通過基於 YAML 的配置文件，用戶可以靈活地配置模型和參數，並使用 Pydantic 進行驗證。在開發方面，使用 uv 工具進行依賴管理、運行和測試，同時採用 ruff 進行代碼格式化和檢查，mypy 進行類型檢查，以確保代碼質量。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

貢獻指南

我們歡迎貢獻！請遵循以下指南：

開發工作流程

1. Fork 和克隆：Fork 倉庫並克隆到本地。
2. 創建分支：創建一個功能分支（git checkout -b feature/amazing-feature）。
3. 開發環境設置：使用 uv sync 安裝依賴項。
4. 進行更改：實現你的功能或修復問題。
5. 測試：添加測試並確保所有測試通過。
6. 代碼質量：運行格式化、檢查和類型檢查。
7. 文檔更新：如有需要，更新文檔。
8. 提交 PR：創建一個包含詳細描述的拉取請求。

代碼標準

Python 風格：

• 遵循 PEP 8 風格指南。
• 為所有函數使用類型提示。
• 為公共函數和類添加文檔字符串。
• 保持函數功能單一且簡潔。

測試要求：

• 為新功能編寫測試。
• 確保現有測試繼續通過。
• 目標是實現良好的測試覆蓋率。
• 測試邊界情況和錯誤條件。

文檔：

• 為面向用戶的更改更新 README.md。
• 為複雜邏輯添加內聯註釋。
• 如有需要，更新配置示例。
• 清晰記錄重大更改。

質量檢查

在提交 PR 之前，請確保：

# 所有測試通過
uv run pytest

# 代碼格式化
uv run ruff format .

# 代碼檢查通過
uv run ruff check .

# 類型檢查通過
uv run mypy src/

# 文檔是最新的
# 配置示例有效

問題和功能請求

• 使用 GitHub Issues 進行 bug 報告和功能請求。
• 為 bug 提供詳細的復現步驟。
• 相關時包含配置示例。
• 在創建新問題之前檢查現有問題。
• 適當地標記問題。