MCP Hub Python

MCP集线器

](https://www.npmjs.com/package/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 规范。

功能支持

简化的客户端配置

仅使用一个端点配置所有MCP客户端：

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

Hub会自动执行以下操作：

• 命名空间防止冲突的能力（例如。， filesystem__search 兽医 database__search)
• 将请求路由到相应的服务器
• 添加/删除服务器时实时更新功能
• 处理身份验证和连接管理

主要特点

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

- 所有MCP客户端连接到的单一端点 - 通过一个连接从所有托管服务器访问功能 - 自动命名空间可防止服务器之间的冲突 - 服务器更改时实时更新功能 - 简化的客户端配置-只需一个端点，而不是多个端点

• 动态服务器管理:

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

• 统一REST API:

- 从任何连接的服务器执行工具 - 访问资源和资源模板 - 通过服务器发送事件（SSE）实时更新状态 - 用于服务器管理的完整CRUD操作

• 实时事件和监控:

- 实时服务器状态和功能更新 - 客户端连接跟踪 - 工具和资源列表更改通知 - 带文件输出的结构化JSON日志记录

• 客户端连接管理:

- 通过/api/events实现简单的基于SSE的客户端连接 - 断开连接时自动清理连接 - 未连接客户端时可选择自动关闭 - 实时连接状态监控

• 流程生命周期管理:

- 优雅的启动和关闭处理 - 正确清理服务器连接 - 错误恢复和重新连接

组件

集线器服务器

主管理服务器：

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

MCP服务器

互联服务：

• 提供工具、资源、模板和提示
• 支持两种连接模式：

- 用于本地操作的基于脚本的STDIO服务器 - 支持OAuth的远程服务器（可流式传输的http/SE）

• 实施实时能力更新
• 支持自动状态恢复
• 跨传输类型保持一致的接口

安装

npm install -g mcp-hub

基本用法

启动集线器服务器：

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

CLI选项

Options:
  --port            Port to run the server on (required)
  --config          Path to config file (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配置文件定义托管服务器 通用的 ${} 占位符语法 用于环境变量和命令执行。

通用占位符语法

• ${ENV_VAR} -解析环境变量
• ${cmd: command args} -执行命令并使用输出
• 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服务器和远程服务器（可流式传输的http/SE）。服务器类型将从配置中自动检测。 所有领域都支持通用 ${} 占位符语法。

STDIO服务器选项

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

• 命令：启动MCP服务器可执行文件的命令（支持 ${VARIABLE} 和 ${cmd: command})
• 参数：命令行参数数组（支持 ${VARIABLE} 和 ${cmd: command} 占位符）
• 环境：具有占位符解析和系统回退的环境变量
• 开发：开发模式配置（可选）

- 启用：启用/禁用开发模式（默认值：true） - 观看：观察变化的glob模式数组（默认值：\[“**/\*.js“，”**/*.ts“，”\*\*/*.json“\]） - 当前工作目录: 必需 用于文件监视的服务器工作目录的绝对路径

远程服务器选项

要连接到远程MCP服务器：

• 网址：服务器终结点URL（支持 ${VARIABLE} 和 ${cmd: command} 占位符）
• 标头：身份验证标头（支持 ${VARIABLE} 和 ${cmd: command} 占位符）

服务器类型检测

服务器类型由以下因素决定：

• STDIO服务器→ Has command 领域
• 远程服务器→ Has url 领域

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

占位符决议顺序

1. 命令优先: ${cmd: command args} 先执行
2. 环境变量: ${VAR} 已解决 env 对象，然后 process.env
3. 后备方案: null 或 "" 值回落到 process.env
4. 多通道：变量之间的依赖关系会自动解析

无

Nixpkgs安装

来了。..

薄片安装

只需将其添加到您的NixOS flake.nix或家庭经理中：

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

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

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

无需安装即可使用

如果你想在PATH中没有mcp-hub服务器的情况下使用mcphub.nvim，你可以在引擎盖下链接服务器，添加 mcp集线器nix存储路径 cmd 插件配置中的命令，如

尼希米 例子：

{ 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集成

这 拉维特梅尔/麦克弗布恩维姆 插件提供与Neovim的无缝集成，允许从编辑器直接与MCP Hub交互：

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

REST API

健康和状态

健康检查

GET /api/health

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

• 当前集线器状态（启动、就绪、重启、重新启动、停止、停止、错误）
• 连接的服务器状态和功能
• 活动SSE连接详细信息
• 详细的连接指标
• 错误状态详细信息（如适用）

答复：

{
  "status": "ok",
  "state": "ready",
  "server_id": "mcp-hub",
  "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"
      }
    ]
  }
}

列出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/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": {},
  "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"
}

重新启动集线器

POST /api/restart

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

答复：

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

实时事件系统

MCP Hub使用服务器发送事件（SSE）在 /api/events此端点提供有关服务器状态、配置更改、功能更新等的实时更新。

枢纽州

集线器服务器在其生命周期中会经历几个状态：

您可以通过以下方式监视这些状态 /health 端点或SSE事件。

事件类型

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

核心活动

1. 心跳 -定期连接健康检查

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

1. hub_state -集线器服务器状态更改

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

1. 日志 -服务器日志消息

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

订阅活动

1. 配置已更改 -检测到配置文件更改

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

1. 服务器_更新 -服务器更新正在进行中

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

1. 服务器_已更新 -服务器更新已完成

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

1. 工具列表已更改 -服务器的工具列表已更新

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

1. 资源列表已更改 -服务器的资源/模板已更新

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

1. prompt_list_已更改 -服务器的提示列表已更新

{
  "type": "prompt_list_changed",
  "server": "example-server",
  "prompts": ["prompt1", "prompt2"],
  "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实现了一个全面的错误处理系统，为不同类型的错误提供了自定义错误类：

错误类别

• 配置错误：配置相关错误（配置无效，缺少字段）
• 连接错误：服务器连接问题（连接失败、传输错误）
• 服务器错误：服务器启动/初始化问题
• 工具误差：工具执行失败
• 资源错误：资源获取问题
• 验证错误：请求验证错误

每个错误包括：

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

错误结构示例：

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

建筑

集线器服务器生命周期

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

集线器服务器协调客户端和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

集线器服务器通过以下方式主动管理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市场

致谢

• Cline mcp市场 -提供MCP服务器市场端点，为MCP Hub的市场集成提供动力