McpHub
Supports managing SQLite MCP instances bound to specific database files or projects, isolating databases per file/project and resolving database paths for proxied SQLite operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@McpHub list files in src for project D:/work/proj-a using filesystem"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 mcp2. 写 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 配置 | 说明 |
|
| 名字即 |
|
| 原样 |
|
| 硬编码路径换成模板变量 |
|
| 值同样支持模板 |
— |
| 新增,决定实例隔离方式 |
— |
| 必需变量,缺失时直接报错而不是静默回退 |
— |
| 可选 |
策略怎么选:
这个 MCP 的特征 | strategy |
参数含项目路径、要按项目隔离(filesystem、aoci) |
|
按具体库/文件隔离(sqlite) |
|
与项目无关、全项目共用一个实例(time、fetch) |
|
与项目无关的 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"]
)迁移时最容易踩的两个点:
绝对路径要全部换成模板。只要留一处硬编码,切项目后就会指向旧目录 —— 这正是 Hub 要解决的问题。
env里的路径同样要换,例如 aoci 的{"AOCI_PROJECT": "${PROJECT_ROOT}"}。
元工具
工具 | 说明 |
| 列出子 MCP、策略、运行实例 |
| 查看单个子 MCP 配置 |
| 注册子 MCP |
| 修改配置(自动重启现有实例) |
| 卸载并关闭实例 |
| 重启指定/全部子 MCP |
| 设置默认项目 |
| 发现子 MCP 的工具 |
| 代理执行: |
典型调用:
{ "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 自动加载并深度合并到全局配置之上,全局配置不用动。
模板变量
变量 | 含义 |
| 项目根目录绝对路径 |
| 项目目录名 |
| 项目路径短 hash |
| 调用方 cwd(默认等于项目根) |
| 用户主目录 |
| 由 |
| 读取环境变量 |
模板需要项目但调用未传 project、也没有默认项目时,直接返回 PROJECT_REQUIRED —— 不会静默回退到旧路径。
测试
.venv/Scripts/python.exe -m unittest discover -s tests -vtest_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 toolsmcp_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Hosted MCP runtime where your agent publishes its own tools by tool call and keeps working.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP-first control plane for ProAgentStore agents and private instances.
Toolstile is a managed MCP gateway that connects remote MCP servers behind one endpoint, with per-agent permissions, shared accounts and activity logs. Connect at https://mcp.toolstile.com/mcp over Streamable HTTP with OAuth; sign in at https://toolstile.com, select a workspace and connect your upstream servers. Available tools, resources and prompts depend on that workspace and the agent's granted access.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to run declarative agents and DAG workflows as plain tools, with parallel nodes, review loops, and per-run least-privilege sandboxing.5 npmMIT
- AlicenseNot gradedqualityCmaintenanceProvides 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 npmMIT
- AlicenseNot gradedqualityCmaintenancePresents 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
- AlicenseNot gradedqualityBmaintenanceEnables 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 npmMIT