MCP AI Bridge

MCP AI桥

一个安全的模型上下文协议（MCP）服务器，将Claude Code与OpenAI和Google Gemini API连接起来。

特性

• 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和vision型号
• 安全特性:

- 增强的输入验证：多层消毒验证 - 内容过滤：阻止明确、有害和非法内容 - 快速注射检测：识别并阻止操纵尝试 - 速率限制：通过可配置的限制防止API滥用 - 安全错误处理：无敏感信息泄露 - API密钥验证：API密钥的格式验证 - 可配置的安全级别：基本、中等和严格模式

• 稳健的错误处理：带有详细消息的特定错误类型
• 结构化日志记录：基于Winston的日志记录，级别可配置
• 灵活的配置：根据每个请求控制温度和型号选择

安装

1. 克隆或复制 mcp-ai-bridge 目录到您的首选位置

1. 安装依赖项：

cd mcp-ai-bridge
npm install

1. 使用以下方法之一配置API密钥：

选项A：在主目录中使用global.env文件 （推荐）

- 创建或编辑 ~/.env 文件 - 添加API密钥：

     OPENAI_API_KEY=your_openai_api_key_here
     GOOGLE_AI_API_KEY=your_google_ai_api_key_here

选项B：使用本地.env文件

- 创建一个 .env mcp-ai网桥目录中的文件：

     cp .env.example .env

- 将您的API密钥添加到此本地 .env 文件

选项C：在Claude Code配置中使用环境变量

- 直接在Claude Code设置中配置（请参阅配置部分）

服务器将按以下顺序检查环境变量：

1. ~/.env （您的主目录）

1. ./.env （本地到mcp ai网桥目录）

1. 系统环境变量

1. 可选配置变量:

   # Logging level (error, warn, info, debug)
   LOG_LEVEL=info

   # Server identification
   MCP_SERVER_NAME=AI Bridge
   MCP_SERVER_VERSION=1.0.0

   # Security Configuration
   SECURITY_LEVEL=moderate              # disabled, basic, moderate, strict

   # Content Filtering (granular controls)
   BLOCK_EXPLICIT_CONTENT=true         # Master content filter toggle
   BLOCK_VIOLENCE=true                  # Block violent content
   BLOCK_ILLEGAL_ACTIVITIES=true       # Block illegal activity requests
   BLOCK_ADULT_CONTENT=true             # Block adult/sexual content

   # Injection Detection (granular controls)
   DETECT_PROMPT_INJECTION=true        # Master injection detection toggle
   DETECT_SYSTEM_PROMPTS=true           # Detect system role injections
   DETECT_INSTRUCTION_OVERRIDE=true     # Detect "ignore instructions" attempts

   # Input Sanitization (granular controls)
   SANITIZE_INPUT=true                  # Master sanitization toggle
   REMOVE_SCRIPTS=true                  # Remove script tags and JS
   LIMIT_REPEATED_CHARS=true            # Limit DoS via repeated characters

   # Performance & Flexibility
   ENABLE_PATTERN_CACHING=true          # Cache compiled patterns for speed
   MAX_PROMPT_LENGTH_FOR_DEEP_SCAN=1000 # Skip deep scanning for long prompts
   ALLOW_EDUCATIONAL_CONTENT=false      # Whitelist educational content
   WHITELIST_PATTERNS=                  # Comma-separated regex patterns to allow

Claude代码中的配置

方法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设置中。配置文件的位置取决于您的环境：

• 克劳德代码CLI：用途 settings.json 在配置目录中（通常 ~/.claude/ 或 $CLAUDE_CONFIG_DIR)
• 克劳德桌面版：用途 ~/.claude/claude_desktop_config.json

对于Claude Desktop兼容性：

{
  "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 Desktop导入

如果您已经在Claude Desktop中配置了此配置，则可以导入配置：

claude mcp add-from-claude-desktop

可用工具

1. ask_openai

查询具有完整验证和安全功能的OpenAI模型。

参数：

• prompt （必填）：要发送的问题或提示（最多10000个字符）
• model （可选）：从“gpt-4o”、“gpt-40-mini”、“gpt-4-turbo”、“gps-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 （必填）：要发送的问题或提示（最多10000个字符）
• model （可选）：从“gemini-1.5-pro-latest”、“gemini.1.5-pro-002”、“gemini-1.5-pro”、“双子座-1.5-flash-llatest”、
• temperature （可选）：控制随机性（0-1，默认值：0.7）

安全功能：

• 提示长度和类型的输入验证
• 温度范围验证
• 模型验证
• 速率限制（默认情况下每分钟100个请求）

3. server_info

获取全面的服务器状态和配置信息。

退货：

• 服务器名称和版本
• 每种服务的可用型号
• 安全设置（速率限制、验证状态）
• 每个API的配置状态

使用示例

在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服务器

如果遇到MCP服务器的问题，可以使用Claude Code的调试功能：

# Enable MCP debug mode for detailed error information
claude --mcp-debug

# Check MCP server status and tools
claude
# Then use the /mcp slash command to view server details

测试

该项目包括全面的单元测试和安全测试。要运行测试，请执行以下操作：

# Run all tests (including security tests)
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

测试覆盖率

• 所有服务器功能的单元测试
• 输入验证和速率限制的安全测试
• API交互的集成测试
• 错误处理测试
• 基于模型的测试，以避免真正的API调用

故障排除

常见问题

1. “API密钥未配置”错误：请确保已将正确的API密钥添加到 .env 文件或Claude代码配置
2. “无效的OpenAI API密钥格式”错误：OpenAI密钥必须以“sk-”开头
3. “超出速率限制”错误：等待速率限制窗口重置（默认值：1分钟）
4. “提示时间过长”错误：将提示保持在10000个字符以内
5. 未找到模块错误：运行 npm install 在mcp-ai桥目录中
6. 权限错误：确保index.js文件具有执行权限
7. 日志记录问题：设置LOGLEVEL环境变量（错误、警告、信息、调试）

Claude代码特定故障排除

1. MCP服务器未加载:

- 使用 claude --mcp-debug 查看详细的错误消息 - 使用检查服务器配置 /mcp 斜杠命令 - 验证服务器路径是否正确且可访问 - 确保Node.js已安装并位于您的PATH中

1. 配置问题:

- 使用 claude mcp add 用于交互式设置 - 检查 CLAUDE_CONFIG_DIR 使用自定义配置位置时的环境变量 - 对于超时，请配置 MCP_TIMEOUT 和 MCP_TOOL_TIMEOUT 环境变量

1. 服务器启动失败:

- 检查服务器进程是否可以独立启动： node /path/to/mcp-ai-bridge/src/index.js - 验证是否已安装所有依赖项 - 检查服务器目录上的文件权限

安全特性

增强的安全保护

• 多层输入验证：类型、长度和内容验证
• 内容过滤：阻止露骨、暴力、非法和有害内容
• 快速注射检测：识别并防止操纵企图，包括：

- 指令覆盖尝试（“忽略以前的指令”） - 系统角色注入（“系统：充当…”） - 模板注入（{{system}}，\，\[INST\]） - 可疑模式检测

• 输入消毒：删除控制字符、脚本和恶意模式
• 速率限制：默认每分钟100个请求，以防止API滥用
• API密钥验证：使用前对API密钥进行格式验证
• 安全错误处理：错误消息中没有堆栈跟踪或敏感信息
• 结构化日志记录：所有操作都以适当的级别记录

安全级别

• 基础：最小过滤，允许大多数内容
• 适度 （默认）：平衡保护与合理限制
• 严格：最大程度的保护，阻止边缘内容

精细的安全配置

安全级别：

• disabled -无安全检查（最大性能）
• basic -仅提供基本保护（性能良好）
• moderate -平衡保护（默认，良好平衡）
• strict -最大程度的保护（可能影响性能）

单个功能控件：

# Master toggles
SECURITY_LEVEL=moderate
BLOCK_EXPLICIT_CONTENT=true
DETECT_PROMPT_INJECTION=true
SANITIZE_INPUT=true

# Granular content filtering
BLOCK_VIOLENCE=true                  # "how to kill", violence
BLOCK_ILLEGAL_ACTIVITIES=true       # "how to hack", illegal acts
BLOCK_ADULT_CONTENT=true            # Sexual/adult content

# Granular injection detection
DETECT_SYSTEM_PROMPTS=true           # "system: act as admin"
DETECT_INSTRUCTION_OVERRIDE=true     # "ignore previous instructions"

# Granular sanitization
REMOVE_SCRIPTS=true                  # Remove  tags
LIMIT_REPEATED_CHARS=true           # Prevent character flooding

# Performance optimization
ENABLE_PATTERN_CACHING=true         # Cache patterns for speed
MAX_PROMPT_LENGTH_FOR_DEEP_SCAN=1000 # Skip intensive checks on long prompts

# Flexibility options
ALLOW_EDUCATIONAL_CONTENT=true      # Whitelist "research about", "explain"
WHITELIST_PATTERNS="educational,academic" # Custom regex patterns

性能考虑因素：

• 模式缓存减少了正则表达式编译开销
• 长提示（>1000个字符）在基本模式下扫描更轻松
• 提前终止在发现问题后停止检查
• 精细控制允许您禁用不必要的检查

最佳实践

• 永远不要承诺你的 .env 文件到版本控制
• 确保API密钥的安全并定期轮换
• 考虑对API帐户设置使用限制
• 监控日志以发现异常活动
• 使用速率限制功能来控制成本
• 使用验证服务器配置 server_info 工具

速率限制

服务器实现滑动窗口速率限制：

• 默认值：每分钟100个请求
• 可通过环境变量进行配置
• 每次会话跟踪
• 带有重置时间信息的优美错误消息