Skip to main content
Glama

McpHub

一个 MCP 桥接器:对上只占 Agent 的一份 MCP 配置,对下动态管理按项目绑定的子 MCP。

解决的核心问题:Agent 只有一份全局 MCP 配置、不支持项目级 MCP,导致 sqlite、aoci 这类需要绑定项目/文件的 MCP 一切换项目就指向旧路径或直接失效。McpHub 把项目差异从"配置文件里的固定值"变成"调用时的动态参数",切项目不需要改全局配置,也不需要重启 Agent。

设计细节见 docs/方案设计.md。

工作原理

Agent ──一份配置──> McpHub ──按 project 渲染参数──> 子 MCP 实例池
                     (元工具)                 filesystem@projA / filesystem@projB
  • 每个子 MCP 声明 bindings.strategy:global(全项目共享一个实例)、per_project(每项目独立进程)、per_file(按文件隔离)。

  • args/env/cwd 支持 ${PROJECT_ROOT} ${CWD} 等模板,调用时用 project 渲染。

  • 实例 Key 为 mcp:project_root,命中复用、未命中惰性启动,空闲回收、LRU 淘汰、崩溃后重建。

Related MCP server: lsp-mcp

快速开始

1. 安装依赖

python -m venv .venv
.venv/Scripts/python.exe -m pip install mcp

2. 写 hub 配置

默认读取 ~/.mcp-hub/hub.json,可用环境变量 MCPHUB_CONFIG 指向别处。最小示例见 config/hub.example.json:

{
  "version": 1,
  "defaults": { "default_project": null },
  "mcps": {
    "filesystem": {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${PROJECT_ROOT}"],
      "bindings": {
        "strategy": "per_project",
        "required": ["PROJECT_ROOT"]
      }
    }
  }
}

${PROJECT_ROOT} 会渲染成调用时传入的项目目录,因此同一个 filesystem MCP 在不同项目下是独立实例,各自只能访问自己的目录。

3. Agent 侧只加一条

{
  "mcpServers": {
    "mcp-hub": {
      "command": "D:/Projects/Python/McpHub/.venv/Scripts/python.exe",
      "args": ["-m", "mcp_hub"],
      "cwd": "D:/Projects/Python/McpHub",
      "env": { "MCPHUB_CONFIG": "C:/Users/Admin/.mcp-hub/hub.json" }
    }
  }
}

cwd 指向本项目根,保证 -m mcp_hub 能找到包。

从普通 MCP 配置迁移

普通 MCP 配置是一条扁平的 mcpServers 条目,路径通常写死。转成 Hub 的子 MCP 就三步:把 command/args/env 搬过来 → 硬编码的项目路径换成模板变量 → 选绑定策略。下面拿快速开始里的 filesystem 走一遍。

之前(普通配置,目录写死):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/projects/myapp"
      ]
    }
  }
}

之后(Hub 配置,目录跟着项目走):

{
  "mcps": {
    "filesystem": {
      "name": "filesystem",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${PROJECT_ROOT}"
      ],
      "bindings": {
        "strategy": "per_project",
        "required": ["PROJECT_ROOT"]
      }
    }
  }
}

字段对照:

普通配置

Hub 配置

说明

mcpServers.<name>

mcps.<name>

名字即 mcp_call 的 mcp 参数

command

command

原样

args

args

硬编码路径换成模板变量

env

env

值同样支持模板

—

bindings.strategy

新增,决定实例隔离方式

—

bindings.required

必需变量,缺失时直接报错而不是静默回退

—

enabled / description

可选

策略怎么选:

这个 MCP 的特征

strategy

参数含项目路径、要按项目隔离(filesystem、aoci)

per_project

按具体库/文件隔离(sqlite)

per_file

与项目无关、全项目共用一个实例(time、fetch)

global

与项目无关的 MCP 直接原样搬,只加一个 global:

{
  "mcps": {
    "time": {
      "name": "time",
      "command": "uvx",
      "args": ["mcp-server-time"],
      "bindings": { "strategy": "global" }
    }
  }
}

也可以不手写 JSON,用元工具装:

mcp_install(
  name="filesystem",
  command="npx",
  args=["-y", "@modelcontextprotocol/server-filesystem", "${PROJECT_ROOT}"],
  strategy="per_project",
  required=["PROJECT_ROOT"]
)

迁移时最容易踩的两个点:

  1. 绝对路径要全部换成模板。只要留一处硬编码,切项目后就会指向旧目录 —— 这正是 Hub 要解决的问题。

  2. env 里的路径同样要换,例如 aoci 的 {"AOCI_PROJECT": "${PROJECT_ROOT}"}。

元工具

工具

说明

mcp_list

列出子 MCP、策略、运行实例

mcp_get

查看单个子 MCP 配置

mcp_install

注册子 MCP

mcp_update

修改配置(自动重启现有实例)

mcp_remove

卸载并关闭实例

mcp_restart

重启指定/全部子 MCP

mcp_set_context

设置默认项目

mcp_tools

发现子 MCP 的工具

mcp_call

代理执行:mcp + tool + args + project

典型调用:

{ "mcp": "filesystem", "tool": "list_directory", "args": { "path": "src" }, "project": "D:/work/proj-a" }

返回:

{ "ok": true, "mcp": "filesystem", "instance": "filesystem:d:/work/proj-a", "is_error": false, "content": [{ "type": "text", "text": "[DIR] components; [FILE] main.ts" }] }

项目级覆盖

在项目根放 .mcp-hub.json,只写差异:

{
  "mcps": {
    "filesystem": {
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${PROJECT_ROOT}", "${PROJECT_ROOT}/../shared"]
    }
  }
}

这个项目额外允许访问同级的 shared 目录。切换项目时 McpHub 自动加载并深度合并到全局配置之上,全局配置不用动。

模板变量

变量

含义

${PROJECT_ROOT}

项目根目录绝对路径

${PROJECT_NAME}

项目目录名

${PROJECT_ID}

项目路径短 hash

${CWD}

调用方 cwd(默认等于项目根)

${HOME}

用户主目录

${DB_PATH}

由 bindings.db_file 解析出的数据库绝对路径(数据库类 MCP 用,见文末附注)

${ENV:NAME}

读取环境变量

模板需要项目但调用未传 project、也没有默认项目时,直接返回 PROJECT_REQUIRED —— 不会静默回退到旧路径。

测试

.venv/Scripts/python.exe -m unittest discover -s tests -v
  • test_bindings.py:模板渲染、实例 Key、项目隔离、overlay 合并(9 个用例)。

  • test_e2e_sqlite.py:MCP 协议层连通性 + 真实启动子 MCP 验证两个项目命中不同数据库(用 sqlite 覆盖 per_project 隔离)。

目录

mcp_hub/
  server.py     # 对上 MCP Server(MCPServer + 9 个元工具)
  hub.py        # 配置/绑定/代理编排
  manager.py    # 实例池:惰性创建、复用、重启、LRU、空闲回收
  client.py     # stdio 子 MCP 客户端(专用 worker task 持有 session)
  bindings.py   # 模板渲染与实例 Key
  config.py     # pydantic 配置模型与项目级合并
  errors.py     # 结构化错误
config/hub.example.json
docs/方案设计.md
tests/

Available Tools

9 tools
mcp_callB

代理执行子 MCP 的工具。project 决定绑定到哪个项目(sqlite 会指向该项目的库文件)。

Inputs: mcp (required), tool (required), args, project. Returns: object

mcp_getA

查看某个子 MCP 的完整配置与实例 Key。

Inputs: name (required). Returns: object

mcp_installB

安装(注册)一个子 MCP。strategy 可选 global / per_project / per_file;args/env/cwd 支持 ${PROJECT_ROOT} ${DB_PATH} 等模板。

Inputs: name (required), command (required), cwd, env, +5 more. Returns: object

mcp_listA

列出已安装的子 MCP、绑定策略与当前运行实例。

Inputs: no named parameters. Returns: object

mcp_removeB

卸载子 MCP 并关闭它的全部实例。

Inputs: name (required). Returns: object

mcp_restartA

重启指定子 MCP(不传 name 则重启全部),下次调用时按最新配置惰性重建。

Inputs: name. Returns: object

mcp_set_contextA

设置默认项目上下文;后续 mcp_call 未显式传 project 时使用它。传空值则清除。

Inputs: project. Returns: object

mcp_toolsC

发现某个子 MCP 暴露的工具。会按需启动该项目的实例。

Inputs: name (required), project. Returns: object

mcp_updateB

修改子 MCP 配置;改动会自动重启该 MCP 的现有实例。

Inputs: name (required), cwd, env, args, +6 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct operation: lifecycle CRUD, restart, context setting, tool discovery, and proxied invocation. list/get and tools/call are clearly separated by scope, so misselection is unlikely.

    Naming Consistency4/5

    All tools use the mcp_ prefix and snake_case, and most follow a verb_noun or verb pattern. mcp_tools is noun-based while mcp_set_context is a longer verb phrase, which is a minor inconsistency.

    Tool Count5/5

    Nine tools are well scoped for a sub-MCP manager: lifecycle operations, context, discovery, and invocation are all covered without filler. The count matches the server's purpose.

    Completeness4/5

    The surface covers CRUD lifecycle management plus restart, context, tool discovery, and proxied calls. Minor gaps exist around diagnostics/logs or explicit enable/disable controls, but core workflows are complete.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to run declarative agents and DAG workflows as plain tools, with parallel nodes, review loops, and per-run least-privilege sandboxing.
      5 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides any MCP-capable coding agent with shared, warm language-server intelligence and project-local configuration, so diagnostics, definitions, references, hover, symbols, code actions, formatting, rename, and sync behave consistently across harnesses and sessions. This lets users switch agent tools without reconfiguring LSP integrations or falling back to CLI verification.
      4 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Presents multiple stdio backend tool servers to an MCP client as one aggregated server, sharing those backend processes across concurrent agent sessions through a background broker while namespacing and routing each tool call to the right backend. Servers can be run shared, per-session, or lazily, with automatic restart and request ID remapping so many sessions coexist without collisions.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to list and call tools from multiple configured servers while each backend starts only on first use, is shared across sessions, and stops when idle. This reduces memory and process overhead without changing tool names or permissions.
      15 npm
      MIT