Tavily MCP Loadbalancer

v2.2.0 (2025-08-15)

• 🧬 マルチアーキテクチャイメージ: linux/amd64とlinux/arm64の両プラットフォーム用イメージをリリース；latestは2.2.0を指すようになりました。

v2.1.0 (2025-08-14)

• 🌐 streamableHTTPサポート: 新しくHTTP POST /mcpエンドポイントを追加し、直接的なMCPリクエスト - レスポンスモードをサポートします。
• 🔄 マルチプロトコル対応: SSEとstreamableHTTPの両方をサポートし、さまざまなクライアントのニーズを満たします。
• 📝 ドキュメント更新: streamableHTTPインターフェイスの使用方法とサンプルを追加しました。

v2.0.0 (2025-08-12)

• 🔄 アーキテクチャの再構築: supergateway依存から、ネイティブSSE実装に変更しました。
• 🛠️ ツールの更新: 最新のTavily MCPツールセットを同期し、tavily-crawlとtavily-mapを新たに追加しました。
• 📊 監視機能の強化: 詳細なAPIキーの使用ログと輪番状態を追加しました。
• 🔒 セキュリティの向上: レスポンスデータのクリーニングと文字エンコーディングの処理を強化しました。
• 📝 ドキュメントの書き直し: READMEを完全に書き直し、プロジェクト構造を最適化しました。

v1.0.0 (2025-08-05)

• 🚀 初期バージョン: supergatewayをベースにしたTavily MCP負荷分散装置を提供します。
• 🔄 負荷分散: 複数のAPIキーを輪番で使用するメカニズムを実装しました。
• 🛡️ フェイルオーバー: 無効なキーを自動的に無効化する機能を備えています。

Docker Compose でのデプロイ

# 1. プロジェクトをクローン
git clone https://github.com/yatotm/tavily-mcp-loadbalancer.git
cd tavily-mcp-loadbalancer

# 2. 環境変数を設定
cp .env.example .env
# .envファイルを編集

# 3. サービスを起動
docker-compose up -d

# 4. ログを確認
docker-compose logs -f

カスタム Docker イメージの構築

# イメージを構築
docker build -t tavily-mcp-loadbalancer .

# コンテナを実行
docker run -d \
  --name tavily-mcp-lb \
  -p 60002:60002 \
  -e TAVILY_API_KEYS="your-key1,your-key2,your-key3" \
  tavily-mcp-loadbalancer

開発モード

# 開発モードで実行（ホットリロード）
npm run dev

# ステップごとに実行
npm run build
npm run start-gateway

# スクリプトを使用して起動
./start.sh

インターフェイスの説明

SSEインターフェイス: http://localhost:60002/sse メッセージインターフェイス: http://localhost:60002/message streamableHTTPインターフェイス: http://localhost:60002/mcp ヘルスチェック: http://localhost:60002/health

streamableHTTPの使用例

# 接続を初期化
curl -X POST http://localhost:60002/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'

# ツールリストを取得
curl -X POST http://localhost:60002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# 検索ツールを呼び出す
curl -X POST http://localhost:60002/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {
        "query": "OpenAI GPT-4",
        "max_results": 3
      }
    }
  }'

ツールパラメータの詳細

1. search / tavily-search - ウェブ検索

{
  "name": "search",
  "arguments": {
    "query": "OpenAI GPT-4",
    "search_depth": "basic",
    "topic": "general",
    "max_results": 10,
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "country": "US",
    "include_favicon": false
  }
}

2. tavily-extract - ウェブページのコンテンツ抽出

{
  "name": "tavily-extract",
  "arguments": {
    "urls": ["https://example.com/article"],
    "extract_depth": "basic",
    "format": "markdown",
    "include_favicon": false
  }
}

3. tavily-crawl - ウェブサイトクローラー

{
  "name": "tavily-crawl",
  "arguments": {
    "url": "https://example.com",
    "max_depth": 2,
    "max_breadth": 20,
    "limit": 50,
    "instructions": "Focus on technical content",
    "select_paths": ["/docs", "/api"],
    "select_domains": ["example.com"],
    "allow_external": false,
    "categories": ["technology"],
    "extract_depth": "basic",
    "format": "markdown",
    "include_favicon": false
  }
}

4. tavily-map - ウェブサイトマップ生成

{
  "name": "tavily-map",
  "arguments": {
    "url": "https://example.com",
    "max_depth": 1,
    "max_breadth": 20,
    "limit": 50,
    "instructions": "Map the main structure",
    "select_paths": ["/"],
    "select_domains": ["example.com"],
    "allow_external": false,
    "categories": ["general"]
  }
}

直接的なMCPの使用

# 直接MCPプロトコルを使用する（stdio）
node dist/index.js

管理スクリプト

# サーバーの接続ステータスをテスト
./manage.sh stats

# すべてのツールの機能をテスト
./manage.sh test

# 天気検索を一括でテスト（すべてのAPIキーをテスト）
./manage.sh weather

# ヘルプ情報を表示
./manage.sh help

Node.js テストスクリプト

# サーバーの接続をテスト
node check_stats_direct.cjs

# ツールのテストを実行
node test_tools_direct.cjs

# 天気検索の一括テスト
node test_weather_search.cjs

# SSE接続とデータセキュリティをテスト
node test_sse_validation.cjs

監視出力例

サーバーステータスのチェック

✅ 接続成功
📊 Tavily MCP 負荷分散装置のステータス:
✅ 検索機能正常
検索結果の長さ: 2847 文字

APIキーの輪番ログ

[INFO] Using API key: tvly-dev-T... (Key 1/10)
[INFO] API key tvly-dev-T... request successful
[INFO] Using API key: tvly-dev-Y... (Key 2/10)
[INFO] API key tvly-dev-Y... request successful

Docker の環境変数

# Docker実行時に設定
docker run -e "TAVILY_API_KEYS=key1,key2,key3" \
           -e "SUPERGATEWAY_PORT=60002" \
           yatotm1994/tavily-mcp-loadbalancer:latest

開発環境の設定

# 開発環境の変数を設定
export TAVILY_API_KEYS="tvly-dev-key1,tvly-dev-key2"
export SUPERGATEWAY_PORT=60002

# または.envファイルを使用
cp .env.example .env
# .envファイルを編集

SSE接続のテスト

SSE接続とデータセキュリティを検証します。

# SSE接続テストを実行
node test_sse_validation.cjs

テスト内容:

• ✅ SSE接続の確立とセッション管理
• ✅ JSON-RPCメッセージの送受信
• ✅ レスポンスデータのセキュリティ検証
• ✅ 制御文字と特殊文字の処理
• ✅ 大量データのレスポンス処理
• ✅ エラー処理とログ記録

ローカル実行時の問題

1. 利用可能なAPIキーがない

   • 環境変数を確認: echo $TAVILY_API_KEYS
   • キーの形式が正しいことを確認（tvly- で始まる）
   • node check_stats_direct.cjs で接続をテストする

2. APIキーが誤っているか、無効になっている

   • サーバーのログに記載されているエラーメッセージを確認
   • ./manage.sh weather ですべてのキーを一括でテスト
   • キーのクォータが使い果たされていないことを確認

3. 接続がタイムアウトする、またはネットワークに問題がある

   • ネットワーク接続とファイアウォールの設定を確認
   • Tavily APIサービスが正常に動作していることを確認
   • 並行リクエストの数を減らしてみる

4. SSE接続に問題がある

   • node test_sse_validation.cjs でSSE接続をテスト
   • ポート60002が使用中でないことを確認: lsof -i :60002
   • サーバーが正常に起動していることを確認

Docker関連の問題

Dockerのデバッグコマンド

# コンテナのログを確認
docker logs -f tavily-mcp-lb

# コンテナに入ってデバッグ
docker exec -it tavily-mcp-lb sh

# 環境変数を確認
docker exec tavily-mcp-lb env | grep TAVILY