Hub Server

MCP服务器集线器/网关

目的： 该项目提供了一个中央网关，用于管理多个MCP（模型上下文协议）服务器并公开集线器本机工具，从而避免为每个LLM客户端（如Cline、Cursor等）配置和运行重复的服务器进程。支持 动态配置重新加载，允许在不重新启动主网关服务器的情况下更新托管服务器和集线器工具/服务。将您的LLM客户端连接到单一 gateway-client 此项目提供的端点，用于通过一个接口访问所有托管MCP服务器和集线器本身的工具。

建筑

该系统由该存储库中的两个主要组件组成：

1. 网关服务器(src/server.ts):

- 持续运行的核心中心流程。 - 读取初始配置文件(mcp_hub_config.json)在启动期间。 至关重要的是，构建过程会将此文件复制到 dist/ 目录，正在运行的服务器会监视 dist/mcp_hub_config.json 文件进行更改。 - 动态管理 中定义的底层MCP服务器的生命周期（启动、停止、监视、重新启动） mcpServers 配置部分。 - 动态加载/卸载/更新 中定义的中心本机工具 hubTools 配置部分。 - 支持 可配置的内部服务 （比如 exampleService)对配置更改做出反应。 - 侦听来自网关客户端的WebSocket连接（默认端口8081）。 - 从托管服务器中发现工具，并使用 serverId__toolName 命名空间。 - 使用 hub__toolName 命名空间。 - 将从网关客户端收到的工具调用路由到相应的托管服务器或内部集线器工具处理程序。

1. 网关客户端(src/client/client.ts):

- 充当LLM客户端通过STDIO连接到的代理服务器。 - 通过WebSocket连接到正在运行的网关服务器（具有自动重新连接功能）。 - 转发MCP请求（如 mcp_listTools, mcp_callTool)从LLM客户端到网关服务器。 - 将网关服务器的响应返回给LLM客户端。 - 定期民意调查 网关服务器用于更新工具列表以处理动态更改（可通过以下方式配置 CLIENT_TOOL_REFRESH_INTERVAL_MS env-var，默认为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 文件在 项目根目录The 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：定义由集线器管理的外部MCP服务器。

- 关键词：独一无二 serverId （用于工具名称间距。， thought-server). - command, args, env, workingDir, autoRestart, maxRestarts：标准工艺配置。

• hubTools：定义直接在此中心项目中实现的工具（in src/tools/).

- Key：工具的基本名称（例如。， example). - description：工具说明。 - modulePath：编译的JS文件的路径（相对于 dist/tools/). - handlerExport （可选）：包含工具处理程序函数的命名导出（默认为 default).该模块还应导出 inputSchema （Zod模式）。 - enabled （可选）： true 或 false （默认值： true).

• exampleService：特定于的配置 ExampleConfigurableService。在此处添加其他可配置中心服务的部分。
• settings：常规网关设置。

- wsPort：WebSocket接口的端口 gateway-client. - 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，启动托管服务器，加载集线器工具，启动WebSocket侦听器，监视配置文件，并保持运行，直到手动停止（Ctrl+C）。

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

您的法学硕士客户只需要 一 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 客户端进程的env-var）。服务器端更改和客户端意识到更改之间可能会有短暂的延迟。请参阅 docs/client-dynamic-tools-guide.md 了解详情。

故障排除

• 启动 ENOENT 错误 gateway-client 在LLM客户端中： 确保 command (node), args （绝对路径 dist/client/client.js)，以及 options.cwd LLM客户端MCP设置中的（项目根的绝对路径）对于您的系统是正确的。
• 工具名称验证错误(String should match pattern...): 确保您的 serverId 钥匙和 hubTools 钥匙在 mcp_hub_config.json 仅包含 a-zA-Z0-9_-.
• 网关客户端无法连接到服务器： 验证网关服务器(npm start)正在运行。检查 wsPort 在……里面 dist/mcp_hub_config.json 匹配客户端使用的URL（默认 ws://localhost:8081).检查防火墙。
• 初始 listTools LLM客户端失败/超时： 如果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 并手动重新启动以进行配置/客户端更改。
• 装订/格式化： npm run lint, npm run format （也可以通过预提交钩子运行）。
• 测试： npm test （目前有限，请参阅 tests/).