MCP Hub

一个用于模型上下文协议 (MCP) 服务器的集中式管理器，提供：

• 动态 MCP 服务器管理和监控
• 用于工具执行和资源访问的 REST API
• MCP 服务器市场（使用 Cline marketplace）
• 实时服务器状态跟踪
• 客户端连接管理
• 进程生命周期处理

概述

Hub 服务器 vs MCP 服务器

• Hub 服务器 (MCP Hub)

  • 连接和管理多个 MCP 服务器的中央管理服务器
  • 提供统一的 API 端点，供客户端访问 MCP 服务器功能
  • 处理服务器生命周期、健康监控和客户端连接
  • 在客户端和适当的 MCP 服务器之间路由请求

• MCP 服务器

  • 提供特定工具和资源的独立服务器
  • 每个服务器都有自己的功能（工具、资源、模板）
  • 连接到 Hub 服务器并由其管理
  • 通过 Hub 处理来自客户端的请求

安装

npm install -g mcp-hub

基本用法

启动 hub 服务器：

mcp-hub --port 3000 --config path/to/config.json

CLI 选项

Options:
  --port            Port to run the server on (default: 3000)
  --config          Path to config file (required)
  --watch           Watch config file for changes (default: false)
  --shutdown-delay  Delay in milliseconds before shutting down when no clients are connected (default: 0)
  -h, --help       Show help information

服务器在启动和状态更改时输出 JSON 格式的状态消息：

{
  "status": "ready",
  "server_id": "mcp-hub",
  "version": "1.0.0",
  "port": 3000,
  "pid": 12345,
  "servers": [],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

Nix

Nixpkgs 安装

即将推出...

Flake 安装

只需将其添加到您的 NixOS flake.nix 或 home-manager：

inputs = {
  mcp-hub.url = "github:ravitemer/mcp-hub";
  ...
}

要将 mcp-hub 集成到您的 NixOS/Home Manager 配置中，请将以下内容添加到您的 environment.systemPackages 或 home.packages 中：

inputs.mcp-hub.packages."${system}".default

无需安装即可使用

如果您想使用 mcphub.nvim 而 PATH 中没有 mcp-hub 服务器，您可以通过在插件配置中的 cmd 命令中添加 mcp-hub nix 存储路径来在底层链接服务器，例如

Nixvim 示例：

{ mcphub-nvim, mcp-hub, ... }:
{
  extraPlugins = [mcphub-nvim];
  extraConfigLua = ''
    require("mcphub").setup({
        port = 3000,
        config = vim.fn.expand("~/mcp-hub/mcp-servers.json"),
        cmd = "${mcp-hub}/bin/mcp-hub"
    })
  '';
}

# where
{
  # For nixpkgs (not available yet)
  mcp-hub = pkgs.mcp-hub;

  # For flakes
  mcp-hub = inputs.mcp-hub.packages."${system}".default;
}

配置

MCP Hub 使用 JSON 配置文件来定义托管服务器：

{
  "mcpServers": {
    "stdio-server": {
      "command": "npx",
      "args": ["example-server"],
      "env": {
        "API_KEY": "", // Will use process.env.API_KEY
        "DEBUG": "true", // Will use this value
        "SECRET_TOKEN": null // Will use process.env.SECRET_TOKEN
      },
      "disabled": false
    },
    "sse-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer token",
        "Content-Type": "application/json"
      },
      "disabled": false
    }
  }
}

配置选项

MCP Hub 支持两种类型的服务器：STDIO（本地）和 SSE（远程）。服务器类型根据提供的配置字段自动确定。

STDIO 服务器选项

• command: 启动本地 MCP 服务器的命令
• args: 命令行参数数组
• env: 服务器的环境变量。如果使用 falsy 值（空字符串、null、undefined）指定变量，它将回退到使用相应的系统环境变量（如果可用）。
• disabled: 是否禁用服务器（默认值：false）

SSE 服务器选项

• url: 远程 SSE 服务器端点的 URL
• headers: SSE 连接的可选 HTTP 标头（例如，用于身份验证）
• disabled: 是否禁用服务器（默认值：false）

服务器类型检测

服务器类型（STDIO 或 SSE）根据特定字段的存在自动确定：

• 如果存在 command → STDIO 服务器
• 如果存在 url → SSE 服务器

注意：服务器配置不能混合 STDIO 和 SSE 字段 - 它必须是一种类型或另一种类型。

示例集成

Neovim 集成

ravitemer/mcphub.nvim 插件提供与 Neovim 的无缝集成，允许直接从您的编辑器与 MCP Hub 交互：

• 直接从 Neovim 执行 MCP 工具
• 在您的编辑工作流程中访问 MCP 资源
• Neovim 中的实时状态更新
• 使用市场添加自动安装 mcp 服务器

日志记录

MCP Hub 对所有事件使用结构化的 JSON 日志记录：

{
  "type": "error",
  "code": "TOOL_ERROR",
  "message": "Failed to execute tool",
  "data": {
    "server": "example-server",
    "tool": "example-tool",
    "error": "Invalid parameters"
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

日志级别包括：

• info: 正常操作消息
• warn: 警告条件
• debug: 详细的调试信息
• error: 错误条件（包括错误代码和详细信息）

REST API

健康和状态

健康检查

GET /api/health

响应：

{
  "status": "ok",
  "server_id": "mcp-hub",
  "version": "1.0.0",
  "activeClients": 2,
  "timestamp": "2024-02-20T05:55:00.000Z",
  "servers": []
}

列出 MCP 服务器

GET /api/servers

获取服务器信息

POST /api/servers/info
Content-Type: application/json

{
  "server_name": "example-server"
}

刷新服务器功能

POST /api/servers/refresh
Content-Type: application/json

{
  "server_name": "example-server"
}

响应：

{
  "status": "ok",
  "server": {
    "name": "example-server",
    "capabilities": {
      "tools": ["tool1", "tool2"],
      "resources": ["resource1", "resource2"],
      "resourceTemplates": []
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

刷新所有服务器

POST /api/refresh

响应：

{
  "status": "ok",
  "servers": [
    {
      "name": "example-server",
      "capabilities": {
        "tools": ["tool1", "tool2"],
        "resources": ["resource1", "resource2"],
        "resourceTemplates": []
      }
    }
  ],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

启动服务器

POST /api/servers/start
Content-Type: application/json

{
  "server_name": "example-server"
}

响应：

{
  "status": "ok",
  "server": {
    "name": "example-server",
    "status": "connected",
    "uptime": 123
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

停止服务器

POST /api/servers/stop?disable=true|false
Content-Type: application/json

{
  "server_name": "example-server"
}

可选的 disable 查询参数可以设置为 true 以禁用配置中的服务器。

响应：

{
  "status": "ok",
  "server": {
    "name": "example-server",
    "status": "disconnected",
    "uptime": 0
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

客户端管理

注册客户端

POST /api/client/register
{
  "clientId": "unique_client_id"
}

注销客户端

POST /api/client/unregister
{
  "clientId": "unique_client_id"
}

市场集成

列出可用服务器

GET /api/marketplace

查询参数：

• search: 按名称、描述或标签过滤
• category: 按类别过滤
• tags: 按逗号分隔的标签过滤
• sort: 按“最新”、“星标”或“名称”排序

响应：

{
  "items": [
    {
      "mcpId": "github.com/user/repo/server",
      "name": "Example Server",
      "description": "Description here",
      "category": "search",
      "tags": ["search", "ai"],
      "githubStars": 100,
      "isRecommended": true,
      "createdAt": "2024-02-20T05:55:00.000Z"
    }
  ],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

获取服务器详细信息

POST /api/marketplace/details
Content-Type: application/json

{
  "mcpId": "github.com/user/repo/server"
}

响应：

{
  "server": {
    "mcpId": "github.com/user/repo/server",
    "name": "Example Server",
    "description": "Description here",
    "githubUrl": "https://github.com/user/repo",
    "readmeContent": "# Server Documentation...",
    "llmsInstallationContent": "Installation guide..."
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

MCP 服务器操作

执行工具

POST /api/servers/tools
Content-Type: application/json

{
  "server_name": "example-server",
  "tool": "tool_name",
  "arguments": {}
}

访问资源

POST /api/servers/resources
Content-Type: application/json

{
  "server_name": "example-server",
  "uri": "resource://uri"
}

获取提示

POST /api/servers/prompts
Content-Type: application/json

{
  "server_name": "example-server",
  "prompt": "prompt_name",
  "arguments": {}
}

响应：

{
  "result": {
    "messages": [
      {
        "role": "assistant",
        "content": {
          "type": "text",
          "text": "Text response example"
        }
      },
      {
        "role": "assistant",
        "content": {
          "type": "image",
          "data": "base64_encoded_image_data",
          "mimeType": "image/png"
        }
      }
    ]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

重启 Hub

POST /api/restart

重新加载配置文件并重启所有 MCP 服务器。

响应：

{
  "status": "ok",
  "timestamp": "2024-02-20T05:55:00.000Z"
}

实时更新

Hub 服务器通过服务器发送事件 (SSE) 在 /api/events 提供实时更新。连接到此端点以接收有关服务器状态、客户端连接和功能更改的实时更新。

事件类型

1. server_info - 初始连接信息

{
  "server_id": "mcp-hub",
  "version": "1.0.0",
  "status": "connected",
  "pid": 12345,
  "port": 3000,
  "activeClients": 1,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

2. server_ready - 服务器已启动并准备就绪

{
  "status": "ready",
  "server_id": "mcp-hub",
  "version": "1.0.0",
  "port": 3000,
  "pid": 12345,
  "servers": [],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

3. client_registered/unregistered - 客户端连接事件

{
  "activeClients": 2,
  "clientId": "client_123",
  "timestamp": "2024-02-20T05:55:00.000Z"
}

4. tool_list_changed - 服务器的工具列表已更改

{
  "type": "TOOL",
  "server": "example-server",
  "tools": ["tool1", "tool2"],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

5. resource_list_changed - 服务器的资源列表已更改

{
  "type": "RESOURCE",
  "server": "example-server",
  "resources": ["resource1", "resource2"],
  "resourceTemplates": [],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

6. prompt_list_changed - 服务器的提示列表已更改

{
  "type": "PROMPT",
  "server": "example-server",
  "prompts": ["prompt1", "prompt2"],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

错误处理

MCP Hub 实现了全面的错误处理系统，具有用于不同类型错误的自定义错误类：

错误类

• ConfigError: 与配置相关的错误（无效配置、缺少字段）
• ConnectionError: 服务器连接问题（连接失败、传输错误）
• ServerError: 服务器启动/初始化问题
• ToolError: 工具执行失败
• ResourceError: 资源访问问题
• ValidationError: 请求验证错误

每个错误包括：

• 易于识别的错误代码
• 详细的错误消息
• 详细信息对象中的其他上下文
• 用于调试的堆栈跟踪

示例错误结构：

{
  "code": "CONNECTION_ERROR",
  "message": "Failed to communicate with server",
  "details": {
    "server": "example-server",
    "error": "connection timeout"
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

错误类别

1. 配置错误

   • 无效的配置格式
   • 缺少必需字段
   • 环境变量问题

2. 服务器管理错误

   • 连接失败
   • 连接丢失
   • 功能获取问题
   • 服务器启动问题

3. 请求处理错误

   • 无效的参数
   • 服务器可用性
   • 工具执行失败
   • 资源访问问题

4. 客户端管理错误

   • 注册失败
   • 重复注册
   • 无效的客户端 ID

架构

Hub 服务器生命周期

sequenceDiagram
    participant H as Hub Server
    participant M1 as MCP Server 1
    participant M2 as MCP Server 2
    participant C as Client

    Note over H: Server Start
    activate H
    H->>+M1: Connect
    M1-->>-H: Connected + Capabilities
    H->>+M2: Connect
    M2-->>-H: Connected + Capabilities

    Note over C,H: Client Interactions
    C->>H: Register Client
    H-->>C: Servers List & Capabilities
    
    C->>H: Call Tool (M1)
    H->>M1: Execute Tool
    M1-->>H: Tool Result
    H-->>C: Response

    C->>H: Access Resource (M2)
    H->>M2: Get Resource
    M2-->>H: Resource Data
    H-->>C: Response

    Note over H: Server Management
    H->>H: Monitor Server Health
    H->>H: Track Server Status
    H->>H: Update Capabilities

    Note over H: Shutdown Process
    C->>H: Unregister
    H->>M1: Disconnect
    H->>M2: Disconnect
    deactivate H

Hub 服务器协调客户端和 MCP 服务器之间的通信：

1. 启动并连接到配置的 MCP 服务器
2. 管理客户端注册
3. 路由工具执行和资源请求
4. 处理服务器监控和健康检查
5. 执行所有连接的干净关闭

MCP 服务器管理

flowchart TB
    A[Hub Server Start] --> B{Config Available?}
    B -->|Yes| C[Load Server Configs]
    B -->|No| D[Use Default Settings]
    
    C --> E[Initialize Connections]
    D --> E
    
    E --> F{For Each MCP Server}
    F -->|Enabled| G[Attempt Connection]
    F -->|Disabled| H[Skip Server]
    
    G --> I{Connection Status}
    I -->|Success| J[Fetch Capabilities]
    I -->|Failure| K[Log Error]
    
    J --> L[Store Server Info]
    K --> M[Mark Server Unavailable]
    
    L --> N[Monitor Health]
    M --> N
    
    N --> O{Health Check}
    O -->|Healthy| P[Update Capabilities]
    O -->|Unhealthy| Q[Attempt Reconnect]
    
    Q -->|Success| P
    Q -->|Failure| R[Update Status]
    
    P --> N
    R --> N

Hub 服务器通过以下方式主动管理 MCP 服务器：

1. 基于配置的服务器初始化
2. 连接和功能发现
3. 健康监控和状态跟踪
4. 自动重新连接尝试
5. 服务器状态管理

请求处理

sequenceDiagram
    participant C as Client
    participant H as Hub Server
    participant M as MCP Server
    
    Note over C,H: Tool Execution Flow
    C->>H: POST /api/servers/{name}/tools
    H->>H: Validate Request
    H->>H: Check Server Status
    
    alt Server Not Connected
        H-->>C: Error: Server Unavailable
    else Server Connected
        H->>M: Execute Tool
        
        alt Tool Success
            M-->>H: Tool Result
            H-->>C: Success Response
        else Tool Error
            M-->>H: Error Details
            H-->>C: Error Response
        end
    end
    
    Note over C,H: Resource Access Flow
    C->>H: POST /api/servers/{name}/resources
    H->>H: Validate URI
    H->>H: Check Server Status
    
    alt Valid Resource
        H->>M: Request Resource
        M-->>H: Resource Data
        H-->>C: Resource Content
    else Invalid Resource
        H-->>C: 404 Not Found
    end

所有客户端请求都遵循标准化流程：

1. 请求验证
2. 服务器状态验证
3. 将请求路由到适当的 MCP 服务器
4. 响应处理和错误管理

要求

• Node.js >= 18.0.0

待办事项

• [ ] 实现自定义市场，而不是依赖 mcp-marketplace

致谢

• Cline mcp-marketplace - 用于提供支持 MCP Hub 市场集成的 MCP 服务器市场端点