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. No available API keys
   • 檢查環境變量：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