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 个请求。
• 可通过环境变量进行配置。
• 按会话跟踪。
• 提供带有重置时间信息的优雅错误消息。