Tavily MCP 负载均衡与上下文服务服务器
项目简介
- 该仓库实现了一个 MCP 服务器端应用，支持通过 MCP 标准的 JSON-RPC 交互进行工具调用、工具列表获取等操作，并提供 stdio、SSE、以及 streamableHTTP 三种通信方式以实现与 LLM 客户端的集成。
- 服务端包含工具路由器、密钥池和使用统计等模块，具备日志持久化、配额管理、错误分类与重试等机制，便于在多密钥环境下进行高可用的上下文服务提供。
主要功能点
- MCP 协议支持
- 处理 MCP 标准请求：初始化、工具列表、工具调用等，通过 MCP 标准的 JSON-RPC 流进行响应。
- 支持多种传输方式：stdio、SSE、streamableHTTP，方便不同场景的客户端接入。
- 工具与路由
- ToolRouter 提供 listTools 和 callTool 能力，能够对外暴露 tavily-search、tavily-extract、tavily-crawl、tavily-map 等工具的调用接口。
- 针对不同工具实现了参数清洗、默认参数合并、时间范围规范化等逻辑，确保调用 Tavily 服务的稳定性。
- 会话与治理
- 支持会话、能力声明和错误处理，提供日志记录与告警能力。
- 具备简单的密钥池管理（KeyPool），按权重和可用性进行密钥选择与冷却管理，实现多密钥负载均衡。
- 数据与监控
- 使用 SQLite 持久化存储 API Key、配额、日志等数据，支持简单的 Web 界面（在配置开关开启时可用）。
- 提供健康端点、统计广播、WebSocket 通道等，方便运维监控。
- 安全与可扩展性
- 对 MCP 客户端的请求在服务端进行日志化与错误分类，支持重试、限流以及禁用不可用 Key 的机制。
- 设计上模块化，便于未来扩展更多工具、更多传输协议和更多的身份鉴权机制。
安装与运行
- 项目简介
- 该实现包含 MCP 服务器核心、工具路由、HTTP 服务、SSE/streamableHTTP 端点、以及后台调度与日志系统等完整组件。
- 主要依赖与运行环境
- Node.js 环境，SQLite 数据库，依赖的 MCP 库用于处理 JSON-RPC 请求。
- 安装步骤
- 克隆仓库并进入项目目录
- 安装依赖：npm install
- 根据需要配置环境变量（如数据库密钥、初始 API Key、管理员密码等）
- 启动服务：根据仓库提供的快速开始说明，使用 npm 脚本启动网关/API 服务与 MCP 服务器组件
- 服务器配置（MCP 客户端需要）
- 说明：MCP 客户端在连接到 MCP 服务器前，需要知道服务器的启动信息以便正确连接并进行初始化交互。下面给出符合仓库实现的配置示例描述。
- 服务器名称（server name）：tavily-mcp-loadbalancer
- 启动命令（command）：node
- 启动参数（args）示例：dist/index.js（若直接使用源码运行，请改为实际打包后的入口，例如 dist/index.js；若使用 Docker 镜像，请使用镜像启动命令）
- 注释：该配置用于 MCP 客户端在首次连接时了解服务器标识，并通过初始化、工具列表、工具调用等交互完成对接。具体环境变量（数据库密钥、初始密钥等）需要在部署时一并提供。
- 基本使用方法
- 客户端连接 MCP 服务器后发送初始化请求以获取协议版本与服务能力
- 调用 tools/list 获取可用工具清单，使用 tools/call 调用具体工具
- 也可以通过 streamableHTTP 的 /mcp 接口进行按需请求，或通过 /sse 订阅状态和统计更新
- 服务器提供健康与状态端点，便于运维检测服务健康状况
运行示例要点（简述）
- MCP stdio 服务器通过工具路由暴露工具能力
- streamableHTTP 提供基于 JSON-RPC 的请求/响应模式
- SSE/WebSocket 提供状态和统计的实时推送
- 支持多密钥负载均衡、限流与错误处理，确保高可用性
运行后可观察的关键端点
- MCP stdio 服务入口（通过 MCP 客户端连接）：通过工具清单与调用接口进行交互
- SSE 接口：/sse
- streamableHTTP：/mcp
- 健康检查：/health
- 管理后台（若开启 Web UI）：基于配置在 Web UI 中进行密钥与日志管理
维护与扩展
- 服务器端以插件式方式组织工具与路由，便于新增工具或修改参数映射
- 日志与监控机制可在部署时按需扩展，便于大规模密钥池管理与审计