MCP Server Hub / Gateway

MCP 服务中心 / 网关

用途： 本项目提供一个中央网关，用于管理多个 MCP（Model Context Protocol）服务并公开网关原生工具，无需为每个 LLM 客户端（如 Cline、Cursor 等）配置和运行重复的服务进程。它支持动态重新加载配置，无需重启主网关服务即可更新受管理的服务以及网关工具和服务。将 LLM 客户端连接到本项目提供的单一 gateway-client 端点，即可通过一个接口访问所有受管理的 MCP 服务和网关自身提供的工具。

架构

本仓库中的系统由两个主要组件构成：

1. 网关服务（src/server.ts）：

   • 持续运行的核心网关进程。
   • 启动时读取初始配置文件（mcp_hub_config.json）。重要的是，构建过程会将此文件复制到 dist/ 目录，运行中的服务会监视 dist/mcp_hub_config.json 文件的更改。
   • 动态管理 mcpServers 配置部分中定义的底层 MCP 服务的生命周期（启动、停止、监控、重启）。
   • 动态加载/卸载/更新 hubTools 配置部分中定义的网关原生工具。
   • 支持可配置的内部服务（例如 exampleService），这些服务会响应配置更改。
   • 监听来自网关客户端的 WebSocket 连接（默认端口为 8081）。
   • 从受管理的服务中发现工具，并以 serverId__toolName 命名空间公开这些工具。
   • 以 hub__toolName 命名空间公开网关原生工具。
   • 将网关客户端发来的工具调用路由到相应的受管理服务或内部网关工具处理程序。

2. 网关客户端（src/client/client.ts）：

   • 作为代理服务，LLM 客户端通过 STDIO 连接到该服务。
   • 通过 WebSocket 连接到正在运行的网关服务（支持自动重连）。
   • 将 MCP 请求（例如 mcp_listTools、mcp_callTool）从 LLM 客户端转发到网关服务。
   • 将网关服务的响应返回给 LLM 客户端。
   • 定期轮询网关服务以获取工具列表更新，从而处理动态更改（可通过 CLIENT_TOOL_REFRESH_INTERVAL_MS 环境变量配置，默认为 5 分钟）。（在 Claude Desktop 中不起作用）
   • 重启 MCP 客户端进程以刷新工具列表。

工作流图：

flowchart LR
    subgraph "User Machine"
        LLM_Client1["LLM Client (e.g., Cline)"]
        LLM_Client2["LLM Client (e.g., Cursor)"]

        subgraph "Gateway Client Process"
            style GatewayClientProcess fill:#f9f,stroke:#333,stroke-width:2px
            GatewayClient["Gateway Client App\n(client.ts)"]
        end

        subgraph "Gateway Server Process"
            style GatewayServerProcess fill:#ccf,stroke:#333,stroke-width:2px
            GatewayServer["Gateway Server\n(server.ts)"]
            ConfigFile["dist/mcp_hub_config.json"] --- Watcher["File Watcher"]
            Watcher -- "Triggers Reload" --> GatewayServer
            MCPServer1["Managed MCP Server 1"]
            MCPServer2["Managed MCP Server 2"]
            HubTool["Hub Tool\n(e.g., exampleHubTool.ts)"]
            HubService["Hub Service\n(e.g., ExampleConfigurableService.ts)"]
        end
    end

    LLM_Client1 -- "STDIO" --> GatewayClient
    LLM_Client2 -- "STDIO" --> GatewayClient
    GatewayClient -- "WebSocket" --> GatewayServer
    GatewayServer -- "Manages/Proxies" --> MCPServer1
    GatewayServer -- "Manages/Proxies" --> MCPServer2
    GatewayServer -- "Loads/Runs" --> HubTool
    GatewayServer -- "Uses" --> HubService
    GatewayServer -- "Reads/Watches" --> ConfigFile

开始使用

1. 前置条件

• Node.js（推荐 v20+）
• npm
• 必须已安装/可访问你要管理的底层 MCP 服务。

2. 安装与构建

# Clone the repository (if you haven't already)
# git clone ...
# cd mcp-server-hub-server

# Install dependencies
npm install

# Build the Gateway Server and Client code
# This compiles TypeScript AND copies mcp_hub_config.json to dist/
npm run build

3. 配置（mcp_hub_config.json）

编辑项目根目录中的 mcp_hub_config.json 文件来配置 hub。npm run build 命令会将此文件复制到 dist/ 目录。运行中的服务会监视 dist/ 目录中的文件，以实时应用更改。

mcp_hub_config.json 示例：

{
  "mcpServers": {
    "thought-server": {
      "command": "node",
      "args": ["D:\\Projects\\mcp-thought-server\\build\\index.js"],
      "env": {},
      "autoRestart": true
    },
    "file-ops": {
      "command": "node",
      "args": ["D:/Projects/mcp-servers/Cline/MCP/file-operations-server/build/index.js"]
    }
    // Add entries for other managed MCP servers here...
  },
  "hubTools": {
    "example": {
      "description": "An example tool provided by the hub itself.",
      "modulePath": "./exampleHubTool.js", // Path relative to dist/tools/
      "handlerExport": "default", // Optional, defaults to 'default'
      "enabled": true // Optional, defaults to true
    }
    // Add entries for other hub-native tools here...
  },
  "exampleService": {
    "featureFlag": false,
    "messagePrefix": "INITIAL"
    // Add other settings specific to ExampleConfigurableService
  },
  "settings": {
    "logLevel": "info", // Optional: 'error', 'warn', 'info', 'debug'
    "wsPort": 8081,     // Port for Gateway Clients (WebSocket)
    "ssePort": null     // SSE interface port (null to disable)
  }
}

主要配置部分：

• mcpServers：定义由 hub 管理的外部 MCP 服务。
  • 键：唯一的 serverId（用于工具命名空间，例如 thought-server）。
  • command、args、env、workingDir、autoRestart、maxRestarts：标准进程配置。
• hubTools：定义直接在此 hub 项目中实现的工具（位于 src/tools/ 中）。
  • 键：工具的基本名称（例如 example）。
  • description：工具描述。
  • modulePath：编译后 JS 文件的路径（相对于 dist/tools/）。
  • handlerExport（可选）：包含工具处理函数的命名导出（默认为 default）。模块还应导出一个 inputSchema（Zod 架构）。
  • enabled（可选）：true 或 false（默认为 true）。
• exampleService：专用于 ExampleConfigurableService 的配置。可在此处为其他可配置的 hub 服务添加配置部分。
• settings：通用网关设置。
  • wsPort：gateway-client 使用的 WebSocket 接口端口。
  • logLevel：日志详细级别。
  • ssePort：服务器发送事件接口的端口（若已启用）。

**动态重新加载：**服务器运行期间，保存到 dist/mcp_hub_config.json 的更改会自动检测并应用。

• mcpServers 中的更改会导致相应的服务进程停止、启动或重启。
• hubTools 中的更改会加载、卸载或重新加载指定的工具模块。
• settings 或服务专属配置部分（例如 exampleService）中的更改会触发相关组件监听的事件。

4. 运行网关服务

在项目根目录（mcp-server-hub-server）中打开终端并运行：

# Ensure you have built the project first!
npm run build

# Start the server
npm start

此操作会读取 dist/mcp_hub_config.json、启动受管理的服务、加载 hub 工具、启动 WebSocket 监听器、监视配置文件，并持续运行，直到手动停止（Ctrl+C）。

5. 配置 LLM 客户端（例如 Cline）

你的 LLM 客户端只需配置一个 MCP 服务：gateway-client。

将以下条目添加到客户端的 MCP 服务设置文件中（例如 Cline 的 cline_mcp_settings.json），确保使用此项目的正确绝对路径：

{
  "mcpServers": {
    // Remove configurations for individual servers like thought-server, file-operations, etc.
    "gateway-client": {
      "command": "node",
      "args": [
        // Use the FULL, absolute path to the compiled client script
        "d:/Projects/mcp-server-hub-server/dist/client/client.js"
      ],
      "options": {
        // CWD should be the project root
        "cwd": "d:/Projects/mcp-server-hub-server"
      },
      "env": {
        // Optional: Configure client polling interval (default is 5 minutes)
        // "CLIENT_TOOL_REFRESH_INTERVAL_MS": "60000" // e.g., 60 seconds
      },
      "disabled": false,
      "autoApprove": []
    }
    // Only the gateway-client entry is needed here
  }
}

LLM 客户端连接到 gateway-client 时，会自动启动客户端进程（node dist/client/client.js），随后该进程会通过 WebSocket 连接到已运行的网关服务。

6. 使用工具

网关服务运行且 LLM 客户端连接到 gateway-client 后：

• 在 LLM 客户端中列出工具。你应该会看到带命名空间的工具名称：
  • 受管理服务的工具：serverId__toolName（例如 thought-server__integratedThinking）
  • hub 原生工具：hub__toolName（例如 hub__example）
• 使用这些完整的命名空间名称调用工具。
• **注意：**由于配置是动态的，工具列表可能会随时间变化。gateway-client 会定期轮询更新（默认间隔为 5 分钟，可通过客户端进程的 CLIENT_TOOL_REFRESH_INTERVAL_MS 环境变量配置）。服务端发生更改后，客户端可能需要稍作等待才能获知。详情请参阅 docs/client-dynamic-tools-guide.md。

故障排查

• 在 LLM 客户端中启动 gateway-client 时出现 ENOENT 错误： 确保 LLM 客户端 MCP 设置中的 command（node）、args（dist/client/client.js 的绝对路径）和 options.cwd（项目根目录的绝对路径）适用于你的系统。
• 工具名称验证错误（String should match pattern...）： 确保 mcp_hub_config.json 中的 serverId 键和 hubTools 键仅包含 a-zA-Z0-9_-。
• 网关客户端无法连接到服务： 确认网关服务（npm start）正在运行。检查 dist/mcp_hub_config.json 中的 wsPort 是否与客户端使用的 URL 匹配（默认值为 ws://localhost:8081）。检查防火墙设置。
• LLM 客户端中的初始 listTools 调用失败或超时： 如果 LLM 客户端在 gateway-client 进程完全连接到网关服务的 WebSocket 之前发送请求，就可能发生这种情况。客户端会将请求排队，后续调用应该可以正常工作。查看网关客户端日志中的排队消息（你可能需要在单独的终端中手动运行 node dist/client/client.js 才能查看日志）。
• 托管服务错误（[serverId/ERR]）： 带有特定服务 ID 前缀的错误表示底层托管服务出现问题，而非网关本身的问题。请直接排查该服务。
• 动态配置未重新加载： 确保在服务运行时修改 dist/mcp_hub_config.json。查看网关服务日志中的文件监视器消息，以及重新加载时可能出现的验证错误。确保构建过程已将你预期的配置从根目录成功复制到 dist/。

开发

• 运行开发服务： npm run dev（使用 nodemon 在 src 发生更改时自动重启网关服务）。注意：这不会自动重新构建或复制配置，也不会重启客户端或托管服务。配置或客户端发生更改后，你需要运行 npm run build 并手动重启。
• Lint/格式化： npm run lint、npm run format（也会通过 pre-commit hook 运行）。
• 测试： npm test（目前测试范围有限，参见 tests/）。