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 提供详细的复现步骤。
• 相关时包含配置示例。
• 在创建新问题之前检查现有问题。
• 适当地标记问题。