JinDaGe - tavily-mcp-loadbalancer MCP Details

article

README

🚀 Tavily MCP 负载均衡器

Tavily MCP 负载均衡器是一个支持多 API 密钥负载均衡的服务器，它提供了 SSE 和 streamableHTTP 接口。该服务器能够自动轮询使用多个 API 密钥，不仅提供了高可用性，还提升了请求限制。

项目状态

语言选择: English | 中文

📋 更新日志

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 密钥轮询机制
🛡️ 故障转移：自动禁用失效密钥功能

✨ 主要特性

🔄 智能负载均衡：自动轮询多个 API 密钥，提升并发能力。
🛡️ 自动故障转移：智能检测并禁用失效密钥。
🌐 多协议支持：同时支持 SSE 和 streamableHTTP 接口。
🧬 多架构镜像：同一镜像同时支持 linux/amd64 与 linux/arm64。
🛠️ 完整工具集：支持搜索、提取、爬虫、地图等全套 Tavily 工具。
📊 实时监控：提供详细的密钥使用日志和性能统计。
🔒 数据安全：自动清理和验证响应数据。
⚡ 高性能：基于 TypeScript 和现代 Node.js 架构。

🚀 快速开始

Docker 部署（推荐）

# 使用 Docker Hub 镜像快速启动（自动匹配本机架构，支持 amd64/arm64）
docker run -d \
  --name tavily-mcp-lb \
  -p 60002:60002 \
  -e TAVILY_API_KEYS="your-key1,your-key2,your-key3" \
  yatotm1994/tavily-mcp-loadbalancer:latest

本地开发

# 1. 克隆并安装
git clone https://github.com/yatotm/tavily-mcp-loadbalancer.git
cd tavily-mcp-loadbalancer
npm install

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，添加你的 API 密钥

# 3. 启动服务
npm run build-and-start

服务启动后访问：

SSE 接口：http://localhost:60002/sse
streamableHTTP 接口：http://localhost:60002/mcp
健康检查：http://localhost:60002/health

📦 更多部署方式

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

🛠️ 可用工具

本服务器提供 5 个 Tavily 工具，支持搜索、内容提取、网站爬虫等功能： | 工具名称 | 功能描述 | 主要参数 | |---------|---------|---------| | search / tavily-search | 网络搜索 | query, max_results, search_depth | | tavily-extract | 网页内容提取 | urls, extract_depth, format | | tavily-crawl | 网站爬虫 | url, max_depth, limit | | tavily-map | 网站地图生成 | url, max_depth, max_breadth |

📖 详细工具文档

接口说明

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 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

⚙️ 配置

环境变量

| 变量名 | 描述 | 默认值 | |--------|------|---------| | TAVILY_API_KEYS | API 密钥列表（逗号分隔） | 必填 | | TAVILY_API_KEY | 单个 API 密钥 | 可选 | | SUPERGATEWAY_PORT | 服务端口 | 60002 |

配置示例

# .env 文件
TAVILY_API_KEYS=tvly-dev-key1,tvly-dev-key2,tvly-dev-key3
SUPERGATEWAY_PORT=60002

🔧 高级配置

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 消息发送和接收
✅ 响应数据安全性验证
✅ 控制字符和特殊字符处理
✅ 大数据响应处理
✅ 错误处理和日志记录

🔧 故障排除

常见问题

| 问题 | 解决方案 | |------|---------| | 无可用 API 密钥 | 检查 TAVILY_API_KEYS 环境变量 | | 连接超时 | 检查网络和防火墙设置 | | 端口被占用 | 使用 lsof -i :60002 检查端口 | | SSE 连接失败 | 运行 node test_sse_validation.cjs |

快速诊断

# 检查服务状态
curl http://localhost:60002/health

# 测试连接
node check_stats_direct.cjs

# 查看日志
docker logs tavily-mcp-lb

🔍 详细故障排除

本地运行问题

No available API keys
- 检查环境变量：echo $TAVILY_API_KEYS
- 确保密钥格式正确（以 tvly - 开头）
- 使用 node check_stats_direct.cjs 测试连接
API 密钥错误或被禁用
- 查看服务器日志中的错误信息
- 使用 ./manage.sh weather 批量测试所有密钥
- 检查密钥配额是否用完
连接超时或网络问题
- 检查网络连接和防火墙设置
- 确认 Tavily API 服务是否正常
- 尝试减少并发请求数量
SSE 连接问题
- 使用 node test_sse_validation.cjs 测试 SSE 连接
- 检查端口 60002 是否被占用：lsof -i :60002
- 确认服务器已正常启动

Docker 相关问题

| 问题 | 解决方案 | |------|---------| | 构建失败 | docker system prune -f 清理缓存 | | 容器启动失败 | docker logs tavily-mcp-lb 查看日志 | | 环境变量无效 | 检查 .env 文件格式 | | 健康检查失败 | curl http://localhost:60002/health |

Docker 调试命令

# 查看容器日志
docker logs -f tavily-mcp-lb

# 进入容器调试
docker exec -it tavily-mcp-lb sh

# 检查环境变量
docker exec tavily-mcp-lb env | grep TAVILY

📄 许可证

MIT License

⭐ 如果这个项目对你有帮助，请给个 Star！