MCP Ai Bridge

🚀 MCP AI Bridge

MCP AI Bridgeは、Claude CodeをOpenAIおよびGoogle Gemini APIと接続する、安全なModel Context Protocol (MCP)サーバーです。これにより、複数のAIモデルに安全かつ効率的にアクセスできます。

🚀 クイックスタート

MCP AI Bridgeを使用することで、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、および最新機能を備えたビジョンモデルにアクセスできます。
• セキュリティ機能：
  • 入力検証の強化：サニタイズを伴う多層検証。
  • コンテンツフィルタリング：露骨な、有害な、違法なコンテンツをブロックします。
  • プロンプトインジェクション検出：操作試みを識別してブロックします。
  • レート制限：設定可能な制限でAPIの乱用を防止します。
  • 安全なエラーハンドリング：機密情報を露出させません。
  • APIキー検証：APIキーの形式を検証します。
  • セキュリティレベルの設定：基本、中程度、厳格なモードが選択可能です。
• 堅牢なエラーハンドリング：詳細なメッセージを伴う特定のエラータイプ。
• 構造化ロギング：設定可能なレベルでWinstonベースのロギングを行います。
• 柔軟な設定：各リクエストの温度とモデル選択を制御できます。

📦 インストール

1. mcp-ai-bridgeディレクトリを好みの場所にクローンまたはコピーします。
2. 依存関係をインストールします。

cd mcp-ai-bridge
npm install

3. 以下のいずれかの方法を使用して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
     

   • このローカル.envファイルにAPIキーを追加します。

   オプション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     # "ignore instructions"の試みを検出
   
   # 入力サニタイズ（細かい制御）
   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=                  # 許可する正規表現パターンをカンマ区切りで指定
   

📚 ドキュメント

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 Desktop：~/.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（必須）：送信する質問またはプロンプト（最大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）。
• セキュリティ機能：
  • プロンプトの長さとタイプの入力検証。
  • 温度範囲の検証。
  • モデルの検証。
  • レート制限（デフォルトで1分あたり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）。
• セキュリティ機能：
  • プロンプトの長さとタイプの入力検証。
  • 温度範囲の検証。
  • モデルの検証。
  • レート制限（デフォルトで1分あたり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サーバーのデバッグモードを有効にして詳細なエラー情報を取得
claude --mcp-debug

# MCPサーバーの状態とツールを確認
claude
# その後、/mcpスラッシュコマンドを使用してサーバーの詳細を表示

🔧 技術詳細

テスト

このプロジェクトには包括的な単体テストとセキュリティテストが含まれています。テストを実行するには：

# すべてのテストを実行（セキュリティテストを含む）
npm test

# ウォッチモードでテストを実行
npm run test:watch

# カバレッジレポート付きでテストを実行
npm run test:coverage

テストカバレッジ

• すべてのサーバー機能の単体テスト。
• 入力検証とレート制限のセキュリティテスト。
• API相互作用の統合テスト。
• エラーハンドリングのテスト。
• 実際のAPI呼び出しを避けるためのモックベースのテスト。

トラブルシューティング

一般的な問題

1. "API key not configured"エラー：.envファイルまたはClaude Codeの設定に正しいAPIキーを追加していることを確認してください。
2. "Invalid OpenAI API key format"エラー：OpenAIのキーは'sk-'で始まる必要があります。
3. "Rate limit exceeded"エラー：レート制限のウィンドウがリセットされるまで待ってください（デフォルト：1分）。
4. "Prompt too long"エラー：プロンプトを10,000文字以内に保ってください。
5. Module not foundエラー：mcp-ai-bridgeディレクトリでnpm installを実行してください。
6. Permissionエラー：index.jsファイルに実行権限があることを確認してください。
7. ロギングの問題：LOG_LEVEL環境変数を設定してください（error、warn、info、debug）。

Claude Code固有のトラブルシューティング

8. MCPサーバーが読み込まれない：
   • claude --mcp-de，bugを使用して詳細なエラーメッセージを表示します。
   • /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。
    • すべての依存関係がインストールされていることを確認します。
    • サーバーディレクトリのファイル権限を確認します。

セキュリティ機能

強化されたセキュリティ保護

• 多層入力検証：タイプ、長さ、およびコンテンツの検証。
• コンテンツフィルタリング：露骨な、暴力的な、違法な、有害なコンテンツをブロックします。
• プロンプトインジェクション検出：操作試みを識別して防止します。
  • 命令上書き試み（"ignore previous instructions"）。
  • システムロールのインジェクション（"system: act as..."）。
  • テンプレートインジェクション（{{system}}、<|system|>、[INST]）。
  • 疑わしいパターンの検出。
• 入力サニタイズ：制御文字、スクリプト、および悪意のあるパターンを削除します。
• レート制限：デフォルトで1分あたり100リクエストでAPIの乱用を防止します。
• APIキー検証：使用前にAPIキーの形式を検証します。
• 安全なエラーハンドリング：エラーメッセージにスタックトレースや機密情報を含めません。
• 構造化ロギング：すべての操作が適切なレベルでログに記録されます。

セキュリティレベル

• 基本：最小限のフィルタリングで、ほとんどのコンテンツを許可します。
• 中程度（デフォルト）：適切な制限を伴うバランスの取れた保護。
• 厳格：最大限の保護で、境界的なコンテンツをブロックします。

細かいセキュリティ構成

セキュリティレベル：

• disabled - セキュリティチェックを行わない（最大のパフォーマンス）。
• basic - 必須の保護のみ（良好なパフォーマンス）。
• moderate - バランスの取れた保護（デフォルト、良好なバランス）。
• strict - 最大限の保護（パフォーマンスに影響を与える可能性があります）。

個別の機能制御：

# メイントグル
SECURITY_LEVEL=moderate
BLOCK_EXPLICIT_CONTENT=true
DETECT_PROMPT_INJECTION=true
SANITIZE_INPUT=true

# 細かいコンテンツフィルタリング
BLOCK_VIOLENCE=true                  # "how to kill"、暴力
BLOCK_ILLEGAL_ACTIVITIES=true       # "how to hack"、違法行為
BLOCK_ADULT_CONTENT=true            # 性的/成人向けコンテンツ

# 細かいインジェクション検出
DETECT_SYSTEM_PROMPTS=true           # "system: act as admin"
DETECT_INSTRUCTION_OVERRIDE=true     # "ignore previous instructions"

# 細かいサニタイズ
REMOVE_SCRIPTS=true                  # <script>タグを削除
LIMIT_REPEATED_CHARS=true           # 文字の洪水を防止

# パフォーマンス最適化
ENABLE_PATTERN_CACHING=true         # パターンをキャッシュして高速化
MAX_PROMPT_LENGTH_FOR_DEEP_SCAN=1000 # 長いプロンプトの集中的なチェックをスキップ

# 柔軟性オプション
ALLOW_EDUCATIONAL_CONTENT=true      # "research about"、"explain"をホワイトリストに登録
WHITELIST_PATTERNS="educational,academic" # カスタム正規表現パターン

パフォーマンスに関する考慮事項：

• パターンキャッシュにより正規表現のコンパイルオーバーヘッドが削減されます。
• 長いプロンプト（>1000文字）は、基本モードでは軽いスキャンが行われます。
• 問題が見つかった後は早期終了してチェックを停止します。
• 細かい制御により、不要なチェックを無効にできます。

ベストプラクティス

• .envファイルをバージョン管理にコミットしないでください。
• APIキーを安全に保管し、定期的にローテーションしてください。
• APIアカウントに使用制限を設定することを検討してください。
• ログを監視して異常な活動を確認してください。
• レート制限機能を使用してコストを管理してください。
• server_infoツールを使用してサーバーの構成を検証してください。

レート制限

サーバーはスライディングウィンドウ方式のレート制限を実装しています。

• デフォルト：1分あたり100リクエスト。
• 環境変数で設定可能です。
• セッションごとに追跡されます。
• リセット時間情報を含む丁寧なエラーメッセージが表示されます。