金大哥 - mcp-nexus MCP 详情

article

README

🚀 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 客户端提供以下工具。 | 工具名称 | 供应商 | 描述 | | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | tavily_search | Tavily | 在网络上搜索任何主题的最新信息。用于新闻、事实或超出你知识截止日期的数据。返回摘要和源 URL。 | | tavily_extract | Tavily | 从 URL 中提取内容。以 Markdown 或文本格式返回原始页面内容。 | | tavily_crawl | Tavily | 从一个 URL 开始爬取网站。以可配置的深度和广度提取页面内容。 | | tavily_map | Tavily | 映射网站结构。返回从基础 URL 开始找到的 URL 列表。 | | tavily_research | Tavily | 对给定主题或问题进行全面研究。根据研究结果返回详细响应。 | | brave_web_search | Brave | 使用 Brave Search API 进行网络搜索。用于一般网络信息、事实和当前主题的搜索。返回结果的 JSON 数组。 | | brave_local_search | Brave | 使用 Brave Search API 搜索本地企业和地点。如果本地结果不可用，通常会回退到网络搜索。返回结果的 JSON 数组。 |

配置

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

核心配置

| 变量 | 描述 | 默认值 | | --------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- | | DATABASE_URL | 数据库的连接字符串。对于本地设置，建议使用基于文件的 SQLite 数据库。 | file:./tavily_bridge.db | | KEY_ENCRYPTION_SECRET | 用于加密和解密存储在数据库中的上游 API 密钥的 32 字节（256 位）密钥。 | （示例中生成） | | ADMIN_API_TOKEN | 用于访问管理 API 的承载令牌。 | （示例中生成） | | HOST | 服务器监听的主机地址。 | 0.0.0.0 | | PORT | 服务器监听的端口。 | 8787 | | ENABLE_QUERY_AUTH | 如果为 true，还允许通过查询字符串（?tavilyApiKey=... / ?token=...）而不是 Authorization: Bearer ... 传递 MCP 客户端令牌。（不建议在生产环境中使用） | false |

速率限制

| 变量 | 描述 | 默认值 | | -------------------------------- | --------------------------------------------------------------------------- | ------- | | MCP_RATE_LIMIT_PER_MINUTE | 每个客户端令牌每分钟的最大请求数。 | 60 | | MCP_GLOBAL_RATE_LIMIT_PER_MINUTE | 所有客户端每分钟的最大请求数。 | 600 | | ADMIN_KEY_REVEAL_RATE_LIMIT_PER_MINUTE | 管理用户界面中每分钟的最大密钥显示尝试次数。 | 20 | | MCP_MAX_RETRIES | 上游请求失败后的最大重试次数。 | 2 | | MCP_COOLDOWN_MS | 上游 API 密钥失败后的冷却时间（毫秒）。 | 60000 |

搜索和密钥策略

这些设置也可以在 管理用户界面 → 设置 页面中实时配置。 | 变量 | 描述 | 默认值 | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | SEARCH_SOURCE_MODE | 定义搜索行为：tavily_only、brave_only、combined（并行查询）或 brave_prefer_tavily_fallback（优先使用 Brave，出错时使用 Tavily）。注意：offset>0 的组合模式返回仅 Brave 的结果，以避免 Tavily 重复。 | brave_prefer_tavily_fallback | | TAVILY_KEY_SELECTION_STRATEGY | 当有多个活动的上游 Tavily 密钥时选择密钥的策略：round_robin（默认）或 random。 | round_robin |

组合模式

当 SEARCH_SOURCE_MODE=combined 时：

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

Tavily 配置

| 变量 | 描述 | 默认值 | | ------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------- | | TAVILY_USAGE_LOG_MODE | Tavily 工具使用的日志级别：none、hash（仅查询哈希）、preview（编辑后的查询）或完整查询。 | preview | | TAVILY_USAGE_HASH_SECRET | 用于创建查询的键控 HMAC-SHA256 哈希而不是普通 SHA256 的可选密钥。建议用于隐私保护。 | "" | | TAVILY_USAGE_SAMPLE_RATE | 用于记录使用事件的可选采样率（0.0 到 1.0）。空字符串表示记录所有事件。 | "" | | TAVILY_USAGE_RETENTION_DAYS | 使用日志的可选保留期。如果设置，旧日志将定期清理。 | "" | | TAVILY_USAGE_CLEANUP_PROBABILITY | 新使用事件触发清理旧使用日志的概率（0.0 到 1.0）。 | 0.001 | | TAVILY_CREDITS_MIN_REMAINING | Tavily 密钥自动进入 冷却 状态的信用阈值。 | 1 | | TAVILY_CREDITS_COOLDOWN_MS | 低于最小信用阈值的密钥的冷却持续时间。 | 300000（5 分钟） | | TAVILY_CREDITS_REFRESH_LOCK_MS | 防止同一密钥并发刷新信用的锁定持续时间。 | 15000 | | TAVILY_CREDITS_REFRESH_TIMEOUT_MS | 上游 Tavily 信用 API 请求的超时时间。 | 5000 | | TAVILY_CREDITS_CACHE_TTL_MS | Tavily 信用信息在被视为过期之前的缓存持续时间。 | 60000 |

Brave 配置

如果未配置 Brave 密钥，Brave 工具将回退到使用 Tavily。 | 变量 | 描述 | 默认值 | | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------- | | BRAVE_API_KEY | 一个 Brave Search API 密钥。如果设置，将使用此单个密钥。对于多密钥支持，请通过管理用户界面添加密钥。 | "" | | BRAVE_MAX_QPS | 为了保持在速率限制内，向 Brave API 每秒的最大请求数。 | 1 | | BRAVE_MIN_INTERVAL_MS | 用固定的最小请求间隔覆盖 BRAVE_MAX_QPS。 | "" | | BRAVE_MAX_QUEUE_MS | 请求在队列中等待失败或回退到 Tavily 之前的最大时间。 | 30000 | | BRAVE_OVERFLOW | 请求队列满时的行为：fallback_to_tavily（默认）、queue（等待）或 error。 | fallback_to_tavily | | BRAVE_HTTP_TIMEOUT_MS | Brave API 的每个请求的 HTTP 超时时间。 | 20000 |

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

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

前提条件

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

npm login
npm whoami

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

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

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

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

手动发布

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

mcp-nexus

README

🚀 mcp-nexus

🚀 快速开始

本地快速开始

Docker Compose（推荐）

本地 Node.js

✨ 主要特性

📦 安装指南

部署

Cloudflare Workers（推荐 - 免费）

Docker Compose（自托管）

💻 使用示例

连接 MCP 客户端

HTTP

stdio

📚 详细文档

工作区

管理用户界面

MCP 工具

配置

核心配置

速率限制

搜索和密钥策略

组合模式

Tavily 配置

Brave 配置

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

前提条件

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

手动发布

运行方式说明

托管运行

本地运行 / 其它方式

mcp-nexus

README

🚀 mcp-nexus

🚀 快速开始

本地快速开始

Docker Compose（推荐）

本地 Node.js

✨ 主要特性

📦 安装指南

部署

Cloudflare Workers（推荐 - 免费）

Docker Compose（自托管）

💻 使用示例

连接 MCP 客户端

HTTP

stdio

📚 详细文档

工作区

管理用户界面

MCP 工具

配置

核心配置

速率限制

搜索和密钥策略

组合模式

Tavily 配置

Brave 配置

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

前提条件

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

手动发布

运行方式说明

托管运行

本地运行 / 其它方式

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