MCP 服务器中心/网关

目的： 本项目提供一个中心网关来管理多个 MCP（模型上下文协议）服务器，并暴露中心原生工具，从而避免为每个 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 连接到正在运行的网关服务器（具有自动重新连接）。
   • 将来自 LLM 客户端的 MCP 请求（如 mcp_listTools、mcp_callTool）转发到网关服务器。
   • 将来自网关服务器的响应返回给 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. 安装 & 构建

# 克隆存储库（如果尚未克隆）
# git clone ...
# cd mcp-server-hub-server

# 安装依赖项
npm install

# 构建网关服务器和客户端代码
# 这会编译 TypeScript 并将 mcp_hub_config.json 复制到 dist/
npm run build

3. 配置 (mcp_hub_config.json)

通过编辑项目根目录中的 mcp_hub_config.json 文件来配置中心。 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"]
    }
    // 在此处添加其他托管 MCP 服务器的条目...
  },
  "hubTools": {
    "example": {
      "description": "中心本身提供的示例工具。",
      "modulePath": "./exampleHubTool.js", // 相对于 dist/tools/ 的路径
      "handlerExport": "default", // 可选，默认为 'default'
      "enabled": true // 可选，默认为 true
    }
    // 在此处添加其他中心原生工具的条目...
  },
  "exampleService": {
    "featureFlag": false,
    "messagePrefix": "INITIAL"
    // 添加特定于 ExampleConfigurableService 的其他设置
  },
  "settings": {
    "logLevel": "info", // 可选：'error'、'warn'、'info'、'debug'
    "wsPort": 8081,     // 网关客户端的端口 (WebSocket)
    "ssePort": null     // SSE 接口端口（禁用时为 null）
  }
}

主要配置部分：

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

动态重载： 在服务器运行时保存到 dist/mcp_hub_config.json 的更改将被自动检测并应用。

• mcpServers 中的更改将导致相应的服务器进程停止/启动/重启。
• hubTools 中的更改将加载/卸载/重新加载指定的工具模块。
• settings 或特定于服务的 sections（如 exampleService）中的更改将触发相关组件侦听的事件。

4. 运行网关服务器

在项目根目录 (mcp-server-hub-server) 中打开一个终端并运行：

# 确保您已首先构建项目！
npm run build

# 启动服务器
npm start

这将读取 dist/mcp_hub_config.json，启动托管服务器，加载中心工具，启动 WebSocket 侦听器，监视配置文件，并保持运行直到手动停止 (Ctrl+C)。

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

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

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

{
  "mcpServers": {
    // 删除单个服务器（如 thought-server、file-operations 等）的配置。
    "gateway-client": {
      "command": "node",
      "args": [
        // 使用已编译的客户端脚本的完整绝对路径
        "d:/Projects/mcp-server-hub-server/dist/client/client.js"
      ],
      "options": {
        // CWD 应该是项目根目录
        "cwd": "d:/Projects/mcp-server-hub-server"
      },
      "env": {
        // 可选：配置客户端轮询间隔（默认为 5 分钟）
        // "CLIENT_TOOL_REFRESH_INTERVAL_MS": "60000" // 例如，60 秒
      },
      "disabled": false,
      "autoApprove": []
    }
    // 此处只需要 gateway-client 条目
  }
}

当 LLM 客户端连接到 gateway-client 时，它将自动启动客户端进程 (node dist/client/client.js)，然后该进程通过 WebSocket 连接到已在运行的网关服务器。

6. 使用工具

一旦网关服务器正在运行并且您的 LLM 客户端已连接到 gateway-client：

• 在您的 LLM 客户端中列出工具。 您应该看到命名空间的工具名称：
  • 托管服务器工具：serverId__toolName（例如，thought-server__integratedThinking）
  • 中心原生工具：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 并手动重启以进行配置/客户端更改。
• Linting/格式化： npm run lint、npm run format（也通过 pre-commit hook 运行）。
• 测试： npm test（目前有限，请参阅 tests/）。