MCP Nexus

🚀 mcp-nexus

mcp-nexus 是一个强大的多供应商模型上下文协议（MCP）服务器，它充当 Tavily 和 Brave Search API 的桥梁。它提供了一个统一的工具界面，通过全面的管理用户界面（Admin UI）管理上游 API 密钥池，并在其中进行轮换。

🚀 快速开始

本地快速开始

Docker Compose（推荐）

cp .env.example .env
# 编辑 .env 文件，设置你的 ADMIN_API_TOKEN 和其他配置
docker compose up --build

SQLite 数据存储在挂载到 /data 的 Docker 卷中。

然后打开：

• 管理用户界面（Admin UI）：http://localhost:8787/admin
• MCP 端点：http://localhost:8787/mcp

本地 Node.js

需要设置 .env.example 中的环境变量。

npm install
npx prisma migrate deploy --schema packages/db/prisma/schema.prisma
npm run dev:bridge-server

✨ 主要特性

• 统一搜索 API：通过单个 MCP 端点为 Tavily 和 Brave Search 提供工具。
• API 密钥管理：轻松添加、管理和轮换多个 Tavily 和 Brave API 密钥，以分配负载并处理速率限制。
• 客户端认证：使用可通过管理用户界面创建和撤销的承载令牌来保护 MCP 端点。
• Web 管理用户界面：一个用户友好的界面，用于管理 API 密钥、客户端令牌、查看使用统计信息和配置服务器设置。
• 使用监控：跟踪工具使用情况，检查查询历史记录，并获取最常用工具和查询的摘要。
• 灵活的搜索策略：无需重启服务器即可动态配置搜索源（tavily_only、brave_only、combined 等）和密钥选择策略（round_robin、random）。
• 速率限制：为 MCP 客户端和上游 API 调用内置速率限制，以防止滥用并管理成本。
• 灵活部署：可以使用 Node.js 在本地运行，也可以使用提供的 Docker Compose 设置在任何地方部署。

📦 安装指南

部署

Cloudflare Workers（推荐 - 免费）

一键部署到 Cloudflare 的免费层，并使用 D1 数据库。详情请参阅 packages/worker/README.md。

Docker Compose（自托管）

包含的 docker-compose.yml 和 Dockerfile 为自托管提供了生产就绪的设置。

💻 使用示例

连接 MCP 客户端

HTTP

• MCP 端点：POST /mcp
• 认证：Authorization: Bearer <client_token>

stdio

建议通过 npx 运行一个轻量级的 stdio 包装器，它可以连接到 HTTP MCP 端点。这样可以将密钥保存在 env 中，而不是命令行参数中。

设置 TAVILY_BRIDGE_BASE_URL 为你的部署 URL（对于本地 Docker Compose：http://localhost:8787）。

{
  "mcpServers": {
    "mcp-nexus": {
      "command": "npx",
      "args": ["-y", "@nexus-mcp/stdio-http-bridge"],
      "env": {
        "TAVILY_BRIDGE_BASE_URL": "http://localhost:8787",
        "TAVILY_BRIDGE_MCP_TOKEN": "<client_token>"
      }
    }
  }
}

📚 详细文档

工作区

• packages/core：Tavily/Brave 客户端、密钥管理和 MCP 工具模式的核心逻辑。
• packages/bridge-server：主 HTTP 服务器，提供 MCP 端点和管理 API/用户界面。
• packages/bridge-stdio：用于本地客户端集成的轻量级 stdio 服务器。
• packages/stdio-http-bridge：用于将 stdio 客户端连接到 HTTP 服务器的辅助包。
• packages/db：用于所有数据持久化的 Prisma 模式和数据库客户端。
• packages/admin-ui：基于 React 的管理用户界面前端。

管理用户界面

管理用户界面提供了一个集中管理 mcp-nexus 实例的地方。

• 密钥：管理你的上游 Tavily 和 Brave API 密钥池。你可以添加、删除、更新状态（活动、禁用）并监控 Tavily 密钥的剩余信用额度。
• 令牌：创建和撤销用于与 MCP 端点进行身份验证的客户端令牌。
• 使用情况：查看详细的工具使用统计信息和查询历史记录，并可以按日期范围、工具和客户端进行过滤。
• 设置：配置实时服务器设置，如上游密钥选择策略和搜索源模式。

MCP 工具

服务器向 MCP 客户端提供以下工具。

配置

配置通过环境变量进行管理。将 .env.example 复制到 .env 开始配置。

核心配置

速率限制

搜索和密钥策略

这些设置也可以在 管理用户界面 → 设置 页面中实时配置。

组合模式

当 SEARCH_SOURCE_MODE=combined 时：

• 需要 Tavily 和 Brave Search 的活动 API 密钥。
• 并行执行查询以最小化延迟。
• 按 URL 合并和去重结果。
• 注意：每个搜索请求会消耗 两个 供应商的配额（成本加倍）。
• 分页：当 offset>0 时，仅返回 Brave 的结果（Tavily 不支持偏移）。

Tavily 配置

Brave 配置

如果未配置 Brave 密钥，Brave 工具将回退到使用 Tavily。

维护者：发布 @nexus-mcp/stdio-http-bridge

此仓库是一个 npm 工作区单仓库。仅 @nexus-mcp/stdio-http-bridge 打算发布到 npm。

前提条件

• 你必须拥有 @nexus-mcp 范围的 npm 发布权限（或者更改包名称/范围）。
• 登录并验证：

npm login
npm whoami

发布（推荐：标签触发的 CI）

1. 提升工作区版本并创建标签：

npm version patch -w @nexus-mcp/stdio-http-bridge --tag-version-prefix stdio-http-bridge-v
git push --follow-tags

2. 配置 GitHub Actions 秘密 NPM_TOKEN（具有发布权限的 npm 访问令牌）。
3. 工作流 .github/workflows/publish-stdio-http-bridge.yml 将在匹配 stdio-http-bridge-v* 的标签上发布。

手动发布

npm publish -w @nexus-mcp/stdio-http-bridge