Super MCP Router

关键词

路由器多包聚合工具发现OAuth 集成远程接口

使用说明 (Markdown 格式)

  • 项目简介

    • 这是一个基于 Model Context Protocol (MCP) 的服务器实现，用于对外提供统一的上下文服务接口。它能托管和管理资源、注册并执行工具、定义并渲染 Prompt 模板，并通过 JSON-RPC 与 LLM 客户端通信。支持标准 MCP 的 STDIO 与 HTTP 传输，以及安全策略、热重载、OAuth 认证等特性，便于将多个 MCP 源聚合成一个可扩展的后端。

  • 主要功能点

    • 支持 STDIO 与 HTTP 两种传输模式，适配本地 Claude 集成和远程/并行部署
    • 注册、发现和执行来自不同包的工具（Tools），并对工具输入进行模式化验证
    • 资源（Resources）读取能力的对外暴露与转发（当前阶段提供基础实现，后续可扩展）
    • 安全策略：对工具和包进行允许/阻止策略、正则表达式匹配、热重载等
    • 身份验证与 OAuth 支持：对需要认证的包提供浏览器端认证流程及令牌管理
    • 工具发现与信息缓存：对包内工具进行枚举、摘要、参数骨架和模式校验
    • Prompt/模板相关能力：支持摘要与参数骨架的渲染，辅助 LLM 交互
    • 健康检查：对所有配置的 MCP 包进行健康检测，提供诊断信息
    • 统一配置加载：支持多配置文件合并、configPaths 引用、旧格式向新格式的兼容
    • 热_reload 配置：安全策略等变更可热更新，无需重启服务器
    • 兼容 http 与 SSE 的传输模式，以及对注入的 HTTP 头、鉴权头部的扩展支持
    • 伺服端工具库暴露：提供 list_tool_packages、list_tools、use_tool、health_check 等 MCP 工具以供客户端查询与调用

  • 安装与运行

    • 本项目设计为“无安装要求”的本地使用方式：使用 npx 直接启动即可
    • 启动示例（传输模式可选）
      • STDIO 模式（默认，用于本地 Claude Desktop 集成）
        • npx super-mcp-router@latest
      • HTTP 模式（远程/并行部署）
        • npx super-mcp-router@latest --transport http --port 3000
    • 启动后会在本地创建默认配置目录 ~/.super-mcp，并生成初始配置文件，后续可编辑该配置来添加 MCP 服务

  • 服务器配置（MCP 客户端需要的配置信息，说明性描述）

    配置是一个 JSON 文件，包含一个 mcpServers 字段，键是服务器标识（如 filesystem、github、notion-api 等），值是对应 MCP 服务器的启动参数。字段示例说明如下：

    • name/description：人类可读名称与描述
    • command：启动 MCP 服务器的命令，例如 npx 或 node
    • args：启动命令的参数数组，如需要指定包名与入口版本等
    • env：环境变量配置，支持变量展开，例如 GITHUB_TOKEN
    • cwd：工作目录
    • type：传输类型，stdio 或 http（若使用 http，请提供 http 相关的 url）
    • url/base_url：HTTP 服务器地址（如 http://localhost:3000/mcp）
    • headers/extra_headers：HTTP 请求头，用于鉴权等场景
    • visibility：default 或 hidden，用于工具列表展示
    • oauth：是否对该包开启 OAuth 认证
    • timeout：单个工具执行的超时（毫秒）

    具体配置示例（描述性文本，不以代码块展现）：

    • filesystem：使用本地文件系统 MCP，command 为 npx，args 为 ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]，描述为“本地磁盘目录访问工具集合”
    • github：使用 GitHub 相关 MCP，command 为 npx，args 为 ["-y", "@modelcontextprotocol/server-github"]，可选包含 GITHUB_PERSONAL_ACCESS_TOKEN 的环境变量
    • notion-api：通过 HTTP 传输连接 notion 的 MCP，type 为 http，url 为 https://mcp.notion.com/mcp，启用 OAuth、名称为 Notion Integration、描述为“访问和管理 Notion 工作区”，如需要鉴权则配置 OAuth
    • 以上示例在实际配置文件中以 json 结构呈现，键值对按仓库实际情况填写，注释用于说明字段用途

  • 基本使用方法

    • 使用 MCP 客户端与服务器建立连接的基本流程：
      1. 通过 list_tool_packages() 查看可用的 MCP 包及其能力
      2. 通过 list_tools(package_id) 查看某个包下的工具及其输入参数 Schema
      3. 通过 use_tool(package_id, tool_id, args) 调用具体工具并获取返回结果（可设置 dry_run、max_output_chars 控制输出）
      4. 如需要鉴权，使用 authenticate(package_id) 启动 OAuth 流程并完成认证
      5. health_check_all() 或 health_check(package_id) 进行健康检查和状态获取
    • 服务器管理和热重载：
      • 支持多配置文件和 configPaths 引用，修改配置后可热加载安全策略和禁用工具等设置
      • 使用 restart_package(package_id) 重新加载某个包的配置信息和凭证
    • 安全性与诊断：
      • 系统提供错误码和帮助文档，通过 get_help() 获取针对错误码的解决方案
      • 支持环境变量注入与令牌保护，日志中对敏感信息进行脱敏处理

  • 额外说明

    • 本实现包含 REST/JSON-RPC 风格的 MCP 请求处理、工具执行、资源读取等核心能力，并集成了工具发现、健康检查、认证与错误处理等成熟特性，目标是成为一个可扩展的后端 MCP 服务，为 LLM 客户端提供稳定、可扩展的上下文服务。

服务器信息

访问项目