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