MCP Hub

MCP Hub

MCP Hub 是 MCP 服务和客户端的中央协调器，提供两个关键接口：

1. 管理接口（/api/*）：通过统一的 REST API 和 Web UI 管理多个 MCP 服务
2. MCP 服务接口（/mcp）：让任何 MCP 客户端都能通过单一端点访问所有服务功能

通过这种双接口方式，你可以通过 Hub 的 UI 管理服务，而 MCP 客户端（Claude Desktop、Cline 等）只需连接一个端点（localhost:37373/mcp），即可访问所有功能。实现了 MCP 2025-03-26 规范。

功能支持

类别	功能	支持	备注
传输
	streamable-http	✅	远程服务的主要传输协议
	SSE	✅	远程服务的备用传输协议
	STDIO	✅	用于运行本地服务
身份验证
	OAuth 2.0	✅	使用 PKCE 流程
	Headers	✅	用于 API 密钥／令牌
功能
	Tools	✅	列出工具
	🔔 Tool List Changed	✅	实时更新
	Resources	✅	完整支持
	🔔 Resource List Changed	✅	实时更新
	Resource Templates	✅	URI 模板
	Prompts	✅	完整支持
	🔔 Prompts List Changed	✅	实时更新
	Roots	❌	不支持
	Sampling	❌	不支持
	Completion	❌	不支持
市场
	服务发现	✅	浏览可用服务
	安装	✅	自动配置
实时
	状态更新	✅	服务和连接状态
	功能更新	✅	自动刷新
	向客户端传输事件	✅	基于 SSE
	自动重新连接	✅	带退避机制
开发
	热重载	✅	在 dev 模式下，文件变更时自动重启 MCP 服务
配置
	${} 语法	✅	在所有字段中使用环境变量和执行命令
	VS Code 兼容性	✅	支持 servers 键、${env:}、${input:} 和预定义变量
	JSON5 支持	✅	配置文件中的注释和尾随逗号

简化客户端配置

只需一个端点即可配置所有 MCP 客户端：

{
    "mcpServers" : {
        "Hub": {
            "url" : "http://localhost:37373/mcp"  
        }
    }
}

Hub 会自动：

• 对功能进行命名空间隔离，避免冲突（例如，filesystem__search 与 database__search）
• 将请求路由到相应的服务
• 在添加／移除服务时实时更新功能
• 处理身份验证和连接管理

主要功能

• 统一的 MCP 服务端点（/mcp）：

  • 所有 MCP 客户端均可连接到同一个端点
  • 通过一个连接访问所有托管服务的功能
  • 自动设置命名空间，避免服务之间发生冲突
  • 服务变更时实时更新功能
  • 简化客户端配置，只需配置一个端点，无需配置多个

• 动态服务管理：

  • 按需启动、停止、启用或禁用服务
  • 实时更新配置，并自动重新连接服务
  • 支持本地（STDIO）和远程（streamable-http/SSE）MCP 服务
  • 健康监控和自动恢复
  • 使用 PKCE 流程进行 OAuth 身份验证
  • 基于标头的令牌身份验证

• 统一的 REST API：

  • 执行任意已连接服务提供的工具
  • 访问资源和资源模板
  • 通过 Server-Sent Events（SSE）实时更新状态
  • 提供完整的服务器管理 CRUD 操作

• 实时事件与监控：

  • 实时更新服务状态和功能
  • 跟踪客户端连接
  • 工具和资源列表变更通知
  • 结构化 JSON 日志，支持输出到文件

• 客户端连接管理：

  • 通过 /api/events 建立简单的基于 SSE 的客户端连接
  • 断开连接时自动清理连接
  • 可选：无客户端连接时自动关闭
  • 实时监控连接状态

• 进程生命周期管理：

  • 妥善处理启动和关闭
  • 正确清理服务连接
  • 错误恢复和重新连接

• 工作区管理：

  • 跟踪不同工作目录中的活动 MCP Hub 实例
  • 在符合 XDG 规范的状态目录中缓存全局工作区信息
  • 通过 SSE 事件实时更新工作区信息
  • 提供用于列出和监控活动工作区的 API 端点

组件

Hub 服务端

主要的管理服务，负责：

• 维护与多个 MCP 服务的连接
• 提供对服务功能的统一 API 访问
• 处理服务生命周期和健康监控
• 管理 SSE 客户端连接和事件
• 处理配置更新并重新连接服务

MCP 服务

已连接的服务，负责：

• 提供工具、资源、模板和提示词
• 支持两种连接模式：
  • 用于本地操作的基于脚本的 STDIO 服务
  • 支持 OAuth 的远程服务（streamable-http/SSE）
• 实现实时功能更新
• 支持自动状态恢复
• 在不同传输类型之间保持一致的接口

安装

npm install -g mcp-hub

基本用法

启动 hub 服务：

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

# Or with multiple config files (merged in order)
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json

CLI 选项

Options:
  --port            Port to run the server on (required)
  --config          Path to config file(s). Can be specified multiple times. Merged in order. (required)
  --watch           Watch config file for changes, only updates affected servers (default: false)
  --auto-shutdown   Whether to automatically shutdown when no clients are connected (default: false)
  --shutdown-delay  Delay in milliseconds before shutting down when auto-shutdown is enabled (default: 0)
  -h, --help       Show help information

配置

MCP Hub 使用 JSON 配置文件定义托管服务，并为环境变量和命令执行提供通用的 ${} 占位符语法。

VS Code 配置兼容性

MCP Hub 与 VS Code 的 .vscode/mcp.json 配置格式无缝兼容，你可以在 VS Code 和 MCP Hub 中使用相同的配置文件。

支持的功能

服务配置键

支持 mcpServers 和 servers 两种键：

{
  "servers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "perplexity": {
      "command": "npx", 
      "args": ["-y", "server-perplexity-ask"],
      "env": {
        "API_KEY": "${env:PERPLEXITY_API_KEY}"
      }
    }
  }
}

变量替换

MCP Hub 支持 VS Code 风格的变量替换：

• 环境变量：${env:VARIABLE_NAME} 或 ${VARIABLE_NAME}
• 工作区变量：${workspaceFolder}、${userHome}、${pathSeparator}
• 命令执行：${cmd: command args}

支持的预定义变量：

• ${workspaceFolder} - mcp-hub 运行所在的目录
• ${userHome} - 用户主目录
• ${pathSeparator} - 操作系统路径分隔符（/ 或 \）
• ${workspaceFolderBasename} - 仅文件夹名称
• ${cwd} - workspaceFolder 的别名
• ${/} - VS Code 中 pathSeparator 的简写

VS Code 输入变量

对于 VS Code 配置中使用的 ${input:} 变量，请使用 MCP_HUB_ENV 环境变量：

# Set input variables globally
export MCP_HUB_ENV='{"input:api-key":"your-secret-key","input:database-url":"postgresql://..."}'

# Then use in config
{
  "servers": {
    "myserver": {
      "env": {
        "API_KEY": "${input:api-key}"
      }
    }
  }
}

从 VS Code 迁移

现有的 .vscode/mcp.json 文件可直接与 MCP Hub 配合使用。只需将 MCP Hub 指向你的 VS Code 配置：

mcp-hub --config .vscode/mcp.json --port 3000

多个配置文件

MCP Hub 支持按顺序加载并合并多个配置文件，从而实现灵活的配置管理：

• 全局配置：系统级设置（例如，~/.config/mcphub/global.json）
• 项目配置：项目专属设置（例如，./.mcphub/project.json）
• 环境配置：特定环境的覆盖设置

指定多个配置文件时，后面的文件会覆盖前面的文件：

# Global config is loaded first, then project config overrides
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json

合并行为：

• 合并 mcpServers 部分（后续文件中的服务定义会覆盖前面的定义）
• 后续文件会完全替换其他顶层属性
• 会静默跳过缺失的配置文件

通用占位符语法

• ${ENV_VAR} 或 ${env:ENV_VAR} - 解析环境变量
• ${cmd: command args} - 执行命令并使用其输出
• ${workspaceFolder} - mcp-hub 的运行目录
• ${userHome} - 用户的主目录
• ${pathSeparator} - 操作系统路径分隔符
• ${input:variable-id} - 从 MCP_HUB_ENV 解析（兼容 VS Code）
• null 或 "" - 回退到 process.env

配置示例

本地 STDIO 服务

{
  "mcpServers": {
    "local-server": {
      "command": "${MCP_BINARY_PATH}/server",
      "args": [
        "--token", "${API_TOKEN}",
        "--database", "${DB_URL}",
        "--secret", "${cmd: op read op://vault/secret}"
      ],
      "env": {
        "API_TOKEN": "${cmd: aws ssm get-parameter --name /app/token --query Parameter.Value --output text}",
        "DB_URL": "postgresql://user:${DB_PASSWORD}@localhost/myapp",
        "DB_PASSWORD": "${cmd: op read op://vault/db/password}",
        "FALLBACK_VAR": null
      },
      "dev": {
        "enabled": true,
        "watch": ["src/**/*.js", "**/*.json"],
        "cwd": "/absolute/path/to/server/directory"
      }
    }
  }
}

远程服务

{
  "mcpServers": {
    "remote-server": {
      "url": "https://${PRIVATE_DOMAIN}/mcp",
      "headers": {
        "Authorization": "Bearer ${cmd: op read op://vault/api/token}",
        "X-Custom-Header": "${CUSTOM_VALUE}"
      }
    }
  }
}

配置选项

MCP Hub 同时支持 STDIO 服务和远程服务（streamable-http/SSE）。服务类型会根据配置自动检测。所有字段都支持通用 ${} 占位符语法。

STDIO 服务选项

用于在本地运行基于脚本的 MCP 服务：

• command：启动 MCP 服务可执行文件的命令（支持 ${VARIABLE} 和 ${cmd: command}）
• args：命令行参数数组（支持 ${VARIABLE} 和 ${cmd: command} 占位符）
• env：环境变量，支持占位符解析和系统级回退
• cwd：用于启动 MCP 服务进程的 cwd
• dev：开发模式配置（可选）
  • enabled：启用/禁用开发模式（默认值：true）
  • watch：用于监视变更的 glob 模式数组（默认值：["/*.js", "/.ts", "**/.json"]）
  • cwd：文件监视所需的服务工作目录绝对路径

全局环境变量（MCP_HUB_ENV）

MCP Hub 会在自身进程环境中查找环境变量 MCP_HUB_ENV（一个 JSON 字符串）。如果已设置，此变量中的所有键值对都会注入到每个受管理 MCP 服务（包括 stdio 和远程服务）的环境中。这样无需在每个服务配置中重复设置，即可向所有服务传递密钥、令牌或其他共享配置。

• 服务专属的 env 字段始终会覆盖 MCP_HUB_ENV 中的值。
• 使用示例：

  MCP_HUB_ENV='{"DBUS_SESSION_BUS_ADDRESS":"/run/user/1000/bus","MY_TOKEN":"abc"}' mcp-hub --port 3000 --config path/to/config.json
  

远程服务选项

用于连接远程 MCP 服务：

• url：服务端点 URL（支持 ${VARIABLE} 和 ${cmd: command} 占位符）
• headers：身份验证标头（支持 ${VARIABLE} 和 ${cmd: command} 占位符）

服务类型检测

服务类型根据以下规则确定：

• STDIO 服务 → 包含 command 字段
• 远程服务 → 包含 url 字段

注意：服务配置不能混用 STDIO 和远程服务字段。

占位符解析顺序

1. 先执行命令：首先执行 ${cmd: command args}
2. 环境变量：先从 env 对象解析 ${VAR}，再从 process.env 解析
3. 回退：null 或 "" 值回退到 process.env
4. 多轮解析：自动解析变量之间的依赖关系

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，但不希望 mcp-hub 服务位于 PATH 中，可以在插件配置中将 mcp-hub 的 nix store 路径添加到 cmd 命令中，从而在底层链接该服务，例如：

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;
}

集成示例

Neovim 集成

ravitemer/mcphub.nvim 插件可与 Neovim 无缝集成，让你能够直接在编辑器中与 MCP Hub 交互：

• 直接在 Neovim 中执行 MCP 工具
• 在编辑工作流中访问 MCP 资源
• 在 Neovim 中实时查看状态更新
• 添加市场后自动安装 MCP 服务

REST API

健康状态与运行状态

健康检查

GET /api/health

健康检查端点提供全面的状态信息，包括：

• 当前 Hub 状态（starting、ready、restarting、restarted、stopping、stopped、error）
• 已连接服务的状态和能力
• 活跃的 SSE 连接详情
• 详细的连接指标
• 适用时的错误状态详情

响应：

{
  "status": "ok",
  "state": "ready",
  "server_id": "mcp-hub",
  "version": "4.1.1",
  "activeClients": 2,
  "timestamp": "2024-02-20T05:55:00.000Z",
  "servers": [],
  "connections": {
    "totalConnections": 2,
    "connections": [
      {
        "id": "client-uuid",
        "state": "connected",
        "connectedAt": "2024-02-20T05:50:00.000Z",
        "lastEventAt": "2024-02-20T05:55:00.000Z"
      }
    ]
  },
  "workspaces": {
    "current": "40123",
    "allActive": {
      "40123": {
        "cwd": "/path/to/project-a",
        "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
        "pid": 12345,
        "port": 40123,
        "startTime": "2025-01-17T10:00:00.000Z",
        "state": "active",
        "activeConnections": 2,
        "shutdownStartedAt": null,
        "shutdownDelay": null
      }
    }
  }
}

列出 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"
}

工作区管理

列出活跃工作区

GET /api/workspaces

响应：

{
  "workspaces": {
    "40123": {
      "cwd": "/path/to/project-a",
      "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
      "pid": 12345,
      "port": 40123,
      "startTime": "2025-01-17T10:00:00.000Z",
      "state": "active",
      "activeConnections": 2,
      "shutdownStartedAt": null,
      "shutdownDelay": null
    },
    "40567": {
      "cwd": "/path/to/project-b",
      "config_files": ["/home/user/.config/mcphub/global.json"],
      "pid": 54321,
      "port": 40567,
      "startTime": "2025-01-17T10:05:00.000Z",
      "state": "shutting_down",
      "activeConnections": 0,
      "shutdownStartedAt": "2025-01-17T10:15:00.000Z",
      "shutdownDelay": 600000
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

市场集成

列出可用服务

GET /api/marketplace

查询参数：

• search：按名称、描述或标签筛选
• category：按类别筛选
• tags：按逗号分隔的标签筛选
• sort：按 "newest"、"stars" 或 "name" 排序

响应：

{
  "servers": [
    {
      "id": "example-server",
      "name": "Example Server",
      "description": "Description here",
      "author": "example-author",
      "url": "https://github.com/user/repo",
      "category": "search",
      "tags": ["search", "ai"],
      "stars": 100,
      "featured": true,
      "verified": true,
      "lastCommit": 1751257963,
      "updatedAt": 1751265038
    }
  ],
  "timestamp": "2024-02-20T05:55:00.000Z"
}

获取服务详情

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

{
  "mcpId": "example-server"
}

响应：

{
  "server": {
    "id": "example-server",
    "name": "Example Server",
    "description": "Description here",
    "author": "example-author",
    "url": "https://github.com/user/repo",
    "category": "search",
    "tags": ["search", "ai"],
    "installations": [],
    "stars": 100,
    "featured": true,
    "verified": true,
    "lastCommit": 1751257963,
    "updatedAt": 1751265038
  },
  "readmeContent": "# Server Documentation...",
  "timestamp": "2024-02-20T05:55:00.000Z"
}

MCP 服务操作

执行工具

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

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

访问资源

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

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

获取提示词

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

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

响应：

{
  "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"
}

实时事件系统

MCP Hub 使用 /api/events 上的服务器发送事件（SSE），实现了全面的实时事件系统。此端点提供有关服务状态、配置变更、能力更新等内容的实时更新。

Hub 状态

Hub 服务在其生命周期中会经历多个状态：

状态	描述
starting	初始启动，正在加载配置
ready	服务正在运行并已准备好处理请求
restarting	正在重新加载配置／重新连接服务
restarted	配置重新加载完成
stopping	正在进行正常关闭
stopped	服务已完全停止
error	错误状态（包含错误详情）

你可以通过 /health 端点或 SSE 事件监控这些状态。

事件类型

MCP Hub 会发出多种类型的事件：

核心事件

1. heartbeat - 定期连接健康检查

{
  "connections": 2,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

2. hub_state - Hub 服务状态变更

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

3. log - 服务日志消息

{
  "type": "info",
  "message": "Server started",
  "data": {},
  "timestamp": "2024-02-20T05:55:00.000Z"
}

订阅事件

1. config_changed - 检测到配置文件变更

{
  "type": "config_changed",
  "newConfig": {},
  "isSignificant": true,
  "timestamp": "2024-02-20T05:55:00.000Z"
}

2. servers_updating - 正在更新服务

{
  "type": "servers_updating",
  "changes": {
    "added": ["server1"],
    "removed": [],
    "modified": ["server2"],
    "unchanged": ["server3"]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

3. servers_updated - 服务更新完成

{
  "type": "servers_updated",
  "changes": {
    "added": ["server1"],
    "removed": [],
    "modified": ["server2"],
    "unchanged": ["server3"]
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

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

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

5. resource_list_changed - 服务的资源／模板已更新

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

6. prompt_list_changed - 服务的提示词列表已更新

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

7. workspaces_updated - 活跃工作区已变更

{
  "type": "workspaces_updated",
  "workspaces": {
    "40123": {
      "cwd": "/path/to/project-a",
      "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
      "pid": 12345,
      "port": 40123,
      "startTime": "2025-01-17T10:00:00.000Z",
      "state": "active",
      "activeConnections": 2,
      "shutdownStartedAt": null,
      "shutdownDelay": null
    }
  },
  "timestamp": "2024-02-20T05:55:00.000Z"
}

连接管理

• 每个 SSE 连接都会分配一个唯一 ID
• 客户端断开连接时，会自动清理该连接
• 可通过 /health 端点查看连接统计信息
• 可选择在没有客户端连接时自动关闭

日志记录

MCP Hub 使用结构化 JSON 日志记录所有事件。日志遵循 XDG 基本目录规范，同时写入控制台和文件：

• 符合 XDG 规范：$XDG_STATE_HOME/mcp-hub/logs/mcp-hub.log（通常为 ~/.local/state/mcp-hub/logs/mcp-hub.log）
• 旧版回退路径：~/.mcp-hub/logs/mcp-hub.log（用于向后兼容）

日志条目示例：

{
  "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：错误情况（包括错误代码和堆栈跟踪）

日志每天轮换，默认保留 30 天。

工作区缓存

MCP Hub 维护全局工作区缓存，以跟踪不同工作目录中的活动实例，并实时管理其生命周期：

• 缓存位置：$XDG_STATE_HOME/mcp-hub/workspaces.json（通常为 ~/.local/state/mcp-hub/workspaces.json）
• 用途：防止端口冲突、支持工作区发现，并实时跟踪生命周期
• 内容：将端口号（作为键）映射到包含详细生命周期状态的 hub 进程信息
• 清理：进程不再运行时自动移除过期条目

缓存结构

{
  "40123": {
    "cwd": "/path/to/project-a",
    "config_files": ["/home/user/.config/mcphub/global.json", "/path/to/project-a/.mcphub/project.json"],
    "pid": 12345,
    "port": 40123,
    "startTime": "2025-01-17T10:00:00.000Z",
    "state": "active",
    "activeConnections": 2,
    "shutdownStartedAt": null,
    "shutdownDelay": null
  },
  "40567": {
    "cwd": "/path/to/project-b", 
    "config_files": ["/home/user/.config/mcphub/global.json"],
    "pid": 54321,
    "port": 40567,
    "startTime": "2025-01-17T10:05:00.000Z",
    "state": "shutting_down",
    "activeConnections": 0,
    "shutdownStartedAt": "2025-01-17T10:15:00.000Z",
    "shutdownDelay": 600000
  }
}

错误处理

MCP Hub 通过针对不同错误类型的自定义错误类，实现了全面的错误处理系统：

错误类

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

每个错误都包含：

• 便于识别的错误代码
• 详细的错误消息
• details 对象中的附加上下文
• 用于调试的堆栈跟踪

错误结构示例：

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

架构

Hub 服务生命周期

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

    Note over H: Server Start (state: starting)
    activate H
    
    Note over H: Config Loading
    H->>H: Load & Validate Config
    H->>H: Watch Config File
    H->>H: Initialize SSE Manager
    
    Note over H: Server Connections (state: ready)
    H->>+M1: Connect
    M1-->>-H: Connected + Capabilities
    H->>+M2: Connect
    M2-->>-H: Connected + Capabilities
    H-->>C: hub_state (ready)

    Note over C,H: Client Setup
    C->>H: Connect to /api/events (SSE)
    H-->>C: connection_opened
    
    Note over C,H: Client Operations
    C->>H: Execute Tool (HTTP)
    H->>M1: Execute Tool
    M1-->>H: Tool Result
    H-->>C: HTTP Response
    
    Note over H,C: Real-time Updates
    H->>H: Detect Config Change
    H-->>C: servers_updating (SSE)
    H->>M1: Reconnect with New Config
    M1-->>H: Updated Capabilities
    H-->>C: servers_updated (SSE)

    Note over H,C: Server Events
    M2->>H: Tool List Changed
    H-->>C: tool_list_changed (SSE)
    
    Note over H: Shutdown Process
    Note over C,H: Client Disconnects
    H-->>C: hub_state (stopping) (SSE)
    H->>M1: Disconnect
    H->>M2: Disconnect
    H-->>C: hub_state (stopped) (SSE)
    deactivate H

Hub 服务负责协调客户端与 MCP 服务之间的通信：

1. 启动并连接已配置的 MCP 服务
2. 处理 SSE 客户端连接和事件
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
    C->>H: POST /api/servers/tools (HTTP)
    H->>H: Validate Request & Server
    
    alt Server Not Connected
        H-->>C: 503 Server Unavailable (HTTP)
    else Server Connected
        H->>M: Execute Tool
        
        alt Success
            M-->>H: Tool Result
            H-->>C: Result Response (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end
    
    Note over C,H: Resource Access
    C->>H: POST /api/servers/resources (HTTP)
    H->>H: Validate URI & Template
    
    alt Invalid Resource
        H-->>C: 404 Not Found (HTTP)
    else Server Not Connected
        H-->>C: 503 Unavailable (HTTP)
    else Valid Request
        H->>M: Request Resource
        
        alt Success
            M-->>H: Resource Data
            H-->>C: Resource Content (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end
    
    Note over C,H: Prompt Execution
    C->>H: POST /api/servers/prompts (HTTP)
    H->>H: Validate Prompt & Args
    
    alt Invalid Prompt
        H-->>C: 404 Not Found (HTTP)
    else Server Not Connected
        H-->>C: 503 Unavailable (HTTP)
    else Valid Request
        H->>M: Execute Prompt
        
        alt Success
            M-->>H: Messages Array
            H-->>C: Messages Response (HTTP)
        else Error
            M-->>H: Error Details
            H-->>C: Error Response (HTTP)
            H-->>C: log (SSE Event)
        end
    end

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

1. 验证请求
2. 检查服务状态
3. 将请求路由到相应的 MCP 服务
4. 处理响应和错误

要求

• Node.js >= 18.0.0

MCP Registry

MCP Hub 现在使用 MCP Registry 系统提供市场功能。该系统提供：

• 去中心化服务发现：Registry 托管在 GitHub Pages 上，可靠性更高
• 直接集成 GitHub：直接从代码仓库获取 README 文档
• 增强的元数据：提供全面的服务信息，包括星标数、类别和安装说明
• 更好的缓存：改进缓存系统，TTL 为 1 小时，便于频繁更新
• 回退支持：fetch 失败时自动回退到 curl（适用于代理/VPN 环境）

Registry 会定期更新，添加新服务并改进现有条目。

待办事项

• 实现自定义市场，而非依赖 mcp-marketplace
• 类似 mcphub.nvim 的 TUI
• 用于管理服务端的 Web UI

致谢

• ravitemer/mcp-registry - 提供 MCP 服务市场端点，为 MCP Hub 的市场集成功能提供支持