mcp-nexus

关键词

上下文服务跨服务代理API密钥管理云端代理JSON-RPC

使用说明（简要概览，便于快速落地）

  • 项目简介

    • mcp-nexus 是一个围绕 MCP（Model Context Protocol）的服务器端实现生态，包含核心后端（MCP 服务器实现、工具接入、密钥轮换、告警与统计等）以及桥接与管理界面模块。核心通过 JSON-RPC 接口向 MCP 客户端暴露能力，支持“读取工具、执行工具、获取结果”等常用 MCP 操作，并提供 Admin UI 以集中管理 API 密钥、客户端令牌、使用统计等。

  • 主要功能点

    • MCP 核心能力暴露
      • 提供工具列表、执行工具、渲染文本化结果，支持 Tavily 和 Brave 两家 upstream 的工具集合。
      • 通过 JSON-RPC /mcp 接口处理 initialize、tools/list、tools/call 等常见 MCP 请求。
    • 上游 API 与密钥管理
      • 多供应商（Tavily、Brave）密钥池，按策略选取、轮换、冷却与失效处理。
      • Admin UI 提供密钥、令牌、使用统计等运维能力。
    • 服务器与部署模式
      • 可本地 Node 环境部署、Docker Compose 自托管部署，亦可 Cloudflare Workers 部署（无状态、边缘化）。
    • 拓展能力
      • 支持多种传输模式（如 HTTP/stdio 桥接、SSE 等），便于与不同客户端对接。
      • 流水线化的工具执行、合并与去重的结果聚合逻辑。

  • 安装步骤（简化版）

    • 依赖准备
      • 需要 Node.js 环境（建议版本 18+），以及 Docker/C docker-compose 等运行环境（如要使用 Docker 部署）。
    • 本地运行（开发/测试场景）
      • 参阅仓库中的 Docker Compose 部署脚本和环境变量示例，拷贝 .env.example 为 .env，并按需修改 ADMIN_API_TOKEN、KEY_ENCRYPTION_SECRET 等关键变量后执行 docker compose up --build。
    • Cloudflare Workers 部署
      • 根据 README 与 worker 目录中的示例，构建并部署到 Cloudflare Workers，MCP 服务以夜端 API 形式暴露。
    • 以 stdio→HTTP 桥接方式接入 MCP
      • 通过 stdio 客户端桥接并暴露到 HTTP，便于本地开发联调。

  • 服务器配置（MCP 客户端连接信息） MCP 客户端需要知道要连接的 MCP 服务器端点信息与认证信息。下面给出基于仓库中提供的桥接方案的示例配置（JSON 格式，便于粘贴到 MCP 客户端配置中）： 服务器配置（示例 JSON，需替换实际 token 与地址） { "mcpServers": { "mcp-nexus": { "command": "npx", "args": ["-y", "@mcp-nexus/stdio-http-bridge"], "env": { "TAVILY_BRIDGE_BASE_URL": "http://localhost:8787", "TAVILY_BRIDGE_MCP_TOKEN": "<client_token>" } } } }

    配置字段说明（便于理解）

    • serverName: MCP 服务器在客户端识别的名称（此处为 mcp-nexus，示例中的 mcp-nexus 表示桥接到的 MCP 服务实例）。
    • command: 启动桥接的执行命令（此处使用 npx 启动 @mcp-nexus/stdio-http-bridge）。
    • args: 启动命令的参数集合，用于指定桥接包和默认行为。
    • env: 环境变量，用于配置桥接连接的 MCP 端点、认证令牌等。
    • TAVILY_BRIDGE_BASE_URL: MCP 服务器对外暴露的基地址，桥接端点通常挂在 /mcp。
    • TAVILY_BRIDGE_MCP_TOKEN: 客户端令牌，用于 Authorization: Bearer <token> 进行鉴权。

  • 基本使用方法

    • MCP 客户端通过 /mcp 端点发送 JSON-RPC 请求，实现 initialize、tools/list、tools/call 等操作，服务器返回对应的 JSON-RPC 响应。
    • Admin UI 提供密钥、令牌、使用统计等管理入口，帮助你维护上游密钥、访问控制与服务器设置。
    • 若使用 stdio-HTTP 桥接，确保桥接能访问 MCP 端点，浏览器或其它客户端通过桥接将 JSON-RPC 脚本发送给 MCP 服务器并接收响应。

  • 运行与维护要点

    • 环境变量要妥善设定，尤其 ADMIN_API_TOKEN、KEY_ENCRYPTION_SECRET、BRAVE_API_KEY 等，用于鉴权和密钥管理。
    • 若采用 Brave 做上游，需正确配置 Brave API Key、最大 QPS、排队方式等，确保稳定性与成本控制。
    • 定期查看 Admin UI 的使用统计、密钥状态及 cooldown/ cooldown 逻辑，确保上游密钥健康。

  • 参考实现与技术栈要点

    • MCP 核心能力通过 Model Context Protocol 的 Server 实现（MCP 的 JSON-RPC 请求/响应格式、tools/list、tools/call 等接口）。
    • 提供 Tavily/Brave 的工具集成、格式化输出，方便 LLM 客户端直接消费。
    • 支持多种部署模式（本地、Docker、Cloudflare Workers），并含有 stdio-HTTP 桥接组件以便本地整合。

服务器信息

访问项目