@geohar/pi-mcp-combiner

中文文档
0.23.1发布于 2026/11/10MITTypeScriptES Module构建来源已验证近 30 天下载 4601

Pi扩展:通过共享服务器运行mcp-combiner MCP聚合器并注入其工具发现指令. 配有pi-mcp-adapter的配对,这使得组合器的工具可以从Pi得到.

中文使用文档
文档目录14 节
  1. 如何融为一体
  2. 运行它
  3. 所需资源
  4. 配置——三层
  5. 1. Pi 设置文件 - $PI_CODING_AGENT_DIR/extensions/mcp-combiner.j…
  6. 2. 共享 MCP 配置阶梯——只读
  7. 3. 环境 - PI_MCP_COMBINER_*
  8. UX号
  9. 聊天身份
  10. 权限
  11. 承认
  12. 主机拥有模式
  13. 发展
  14. 许可证

@geohar/pi-mcp-combiner (英语)

A 类 Pi 扩展名 + 共享 MCP 聚合器: 一次重计 联合工艺前沿 全部 您的 MCP 服务器, 以及您使用的每个客户端 那个过程.

它重用Pi的MCP堆栈而不是取而代之. 运输是 @earendil-works/pi-mcp ——皮自有的MCP客户端库(载: ^1.2.0; 主机提供 作为真正的对等点被问到上游——在那之前,pi的加载器只分享pi-ai/agent-core/tui/typebox,所以 物理复制是受制裁的路线,并且是安全的:没有 pi-mcp 对象交叉为 pi 的复制. 一个 查看的翻转条件 : 如果pi曾经提供pi-mcp,则放弃 dependencies 在同一条目中 释放 ——所携带的拷贝会给主机的模块映射阴影(反模版) docs/packages.md 你应当用它来警告众人 和皮的内置 MCP支持 保持它的作用(/mcp,代码, tool_search) (中文(简体) ). 这个 扩展名是 添加剂加上皮的内置不能做:

  • 语法 ——上游服务器可以询问 你们: 同意梯子,部署 确认,结构化表格。 皮的内置MCP不能转发这些;这个 扩展连接到 Pi 的对话框, 以及您的对接应用程序 无双。 。 。 .
  • 交互式资源( mcp- app 部件) - 皮丝 read_mcp_resource 跳过 ui:// 全部资源; 我们登记 read_* 工具,主机部件,按住 在您交互时打电话,然后将您的动作折叠到结果中.
  • 发现路由器 —— 说 mcp({search}) 编号 : ({describe}) 编号 : ({tool, args})数字 : 在工具名下, 将整个集合表面的发现排序 mcp 呼叫门已经认出来了.

共享是重点. 一个联合工艺,由 sharedserver整个Pi共享, Claude Code, OpenCode, 和 Neovim —— 上游连接、会话和 OAuth 直播 一次,不是每个客户一次。 一个 servers.json 许可政策(拒绝/引出/) 允许,每个服务器)执行 在联合体 对每一个客户都一样,按键 在重启后幸存的每个聊天符:同意赠款、停放的会议和过滤器 以交接方式重新启动组合器,并 combiner__status 报告什么 靴子恢复.

这是Pi的对应方 克劳德代码 财务报告和审定财务报表 打开代码 插件,并共享相同的组合器和相同的组合器 sharedserver 举个例子.

如何融为一体

三分之一,都在这个包里:

  1. 进程 - 开始 session_start 它驱动

    sharedserver use <name> --pid <pi-pid> --grace-period <g> \
        -- <combiner> --mcp --config <servers.json> --port <port>
    

    sharedserver 由 PID 重算, 并带有宽限期, 因此组合器是共享的 超越任何单一的客户。 重计释放量 session_shutdown 仅在 reason === "quit" ——再装入/再装入/叉保持不变 Pi 进程和新鲜 session_start 复次附会.

  2. 客户端 ——自有连接上的pi-mcp运输(每Pi会场保管) 标语,招生能力广告并通向Pi的UI),注册 介质表面:每个组合工具头等号,名称为赤色 (单位:千美元)github_search_code与 pi-1.0 接触/命名空间/注释 mcp() 在同一连接上发现路由器, read_* 资源工具(互动) ui:// 包括部件、快速斜线命令、状态页脚和 交互式小组讨论.

  3. 说明 - 开始 before_agent_start 它附着组合器 <server>_-prefix / "在假设前发现"指令给系统提示 .

sharedserver 如果未安装, 将自动获取( 绑定释放通过 / 退货 / a 被绑定的 PyPI 发布器——与兄弟会插件相同的解析器.

运行它

只安装此扩展名 。 - 客户端一半连接到 合并并登记所有文件:

pi install /path/to/mcp-combiner/plugins/pi     # local checkout
# or the published package under settings.json "packages"

启动时您会得到: 每个组合工具头等舱, 使用它的名称( 您的) directTools 已声明的匹配 direct,其余在代码码 mcp 发现 路由器, read_<resource> 工具, /<server>__<prompt> 斜线命令,页脚行 (单位:千美元)14 servers enabled (13 ready) · 671 tools),以及 /mcp-combiner panel。 。 。 .

*Via 另一种机制——pi-mcp-adapter. 目标是Pi的本地MCP支持 (第1.0页) 如果你已经运行 pi-mcp-adapter 用于其他服务器,此 扩展可以将其客户端的半个 : "adapter": false (或默认) "auto",可以自动检测适配器并生成) + 给我们和MCP给适配器的指示. /mcp-combiner install-config 还写着分享..mcp.json 将适配器读取.

所需资源

  • mcp-combiner 作为命令可用( e)uv tool install mcp-combiner),或者仅仅 uv 在PATH上, 要求数 联合器 ^ 0.8.0(版本自动).
  • 组合器 servers.json (以下自动检测地点).
  • pi- mcp- 适应器 没有 所需经费.
  • Pi 1.0 与捆绑 @earendil-works/pi-mcp (在树上溶解 ^1.2.0)——运输是皮自有的MCP客户端库.

配置——三层

1. Pi 设置文件 - $PI_CODING_AGENT_DIR/extensions/mcp-combiner.json

双侧旋钮(参见 settings.example.json:

密钥默认效果
toolName"mcp"代理工具的名称 。 重命名( 例如 ). "combiner"与 pi-mcp- 适应者自己的共存 mcp。 。 。 .
adapter"auto"客户半门-见上文.
lazy"lazy""eager" 在会话开始时连接; "lazy" 开始使用。 提示/资源/直接工具意味着渴望.
exposeResourcestrue登记册 read_<resource> 工具.
promptstrue注册快速斜线命令 .
uiAutoOpentrue浏览器中自动打开交互式部件URL(Stage 2 holds + reading).
warnLargeDirectExposuretrue当 > 50 工具结束时警告 direct- 暴露(每个请求中每个计划都搭车) false 安静 本地模式 .
mcpFooterStatus"full"页脚文本 : "full" =: N servers enabled (M ready) · T tools, (中文(简体) ), "compact" =: MCP M/N, (中文(简体) ), "off" = 无.
mcpFooterKey"mcp"这个 ctx.ui.setStatus 键入页脚下公布(插槽 oh-my-posh- system footers聚合).
url—— 说明确组合器 URL. Env赢了.
notifytrue通过Pi UI的地表生命周期信息.

2. 共享 MCP 配置阶梯——只读

延期 读取 标准 MCP 文件(梯度和优先级相同于 pi-mcp-适应器,后取胜: ~/.config/mcp/mcp.json → ~/.agents/mcp.json → ~/.agents/mcp/mcp.json → <agent dir>/mcp.json → .mcp.json → .pi/mcp.json (项目). 这个 从不写。 。 。 .

公认的 mcp-combiner 条目带有连接+每个项目接触:

{
  "mcpServers": {
    "mcp-combiner": {
      "url": "http://127.0.0.1:9741/mcp",
      "auth": "bearer",
      "bearerTokenEnv": "MCP_COMBINER_AUTH_TOKEN",
      "combiner": {
        // extension-specific, ignored by other readers
        "servers": { "allow": ["github", "svg-mcp"] }, // or "deny": [...]
        "exposeResources": true,
        "prompts": true,
        "directTools": ["combiner__status", "github_search_*"], // or "search"
      },
    },
  },
}
  • servers.allow/deny ——每个项目暴露,强制 在联合体 这个 聊天符(也通过脚本查询)并镜像客户端.
  • directTools - 用于申报的工具的许可列表(组) direct (乡村, 在每项请求中)而不是 codemode (可从脚本和皮氏取出) tool_search) (中文(简体) ). "search" 降解为全码模式——pi自己的发现取而代之 旧的搜索推广。 > 50-允许入境者警告; true 故意没有 提供(文字成本:每一次请求中每个直接计划都搭乘).
  • 代码激活( pi 1. 1. 0. x quirk) —— pi 不自动激活代码代号 用于扩展注册工具的工具(只用于自身连接的MCP服务器),因此 codemode- 暴露的组合工具在添加前无法从脚本中获取 "defaultTools": ["+codemode"] 给您的 pi 设置。 json。 该设定适用于 新会话 创建(续会保留其记录的工具集)。 狦 不要使用代码, 联合工具外面 directTools 可以通过 mcp 发现/路由工具.
  • 项目层对照 会话 cwd 工作树亚剂和 项目开关有自己的 .pi/mcp.json提交 combiner 区域 想要工作树的经纪人尊重它.
  • URL优先级 : MCP_COMPANION_COMBINER_URL (主机拥有) • PI_MCP_COMBINER_URL → 设置 url • 梯入 url → host:port/mcp。 。 。 .

3. 环境 - PI_MCP_COMBINER_*

变量默认效果
PI_MCP_COMBINER_ADAPTER(设置)off 编号 : on 编号 : auto ——客户半门.
PI_MCP_COMBINER_TOOL_NAME(设置)代理工具名覆盖 .
PI_MCP_COMBINER_URL—— 说明确组合器 URL.
PI_MCP_COMBINER_PORT9741HTTP 连接器服务端口 .
PI_MCP_COMBINER_HOST127.0.0.1HTTP主机集成器绑定.
PI_MCP_COMBINER_CONFIG(自动复制)连接器的路径 servers.json。 。 。 .
PI_MCP_COMBINER_COMMAND 编号 : _ARGS(自动解决)超越联合体的引用.
PI_MCP_COMBINER_CHECKOUT—— 说报到 uv run --project <checkout> python -m mcp_combiner。 。 。 .
PI_MCP_COMBINER_NAMEmcp-combinersharedserver 实例名称.
PI_MCP_COMBINER_GRACE30msharedserver 宽限期.
PI_MCP_COMBINER_LOG 编号 : _PYLOG 编号 : _LOG_LEVEL(状态 dir)联合伐木; "none" 禁用 .
PI_MCP_COMBINER_MANAGEtruefalse ——不要发射(combiner运行在别处).
PI_MCP_COMBINER_INSTRUCTIONStruefalse ~ 跳过系统即时指令.
PI_MCP_COMBINER_NOTIFYtruefalse 不要通过Pi UI显示消息.
SHAREDSERVER_BIN 编号 : SHAREDSERVER_LOCKDIR(自动)sharedserver 二进制/ 锁定目录 .

servers.json 自动探测 : $PI_MCP_COMBINER_CONFIG → ~/.cache/secrets/<user>.mcpservers.json → ~/.config/mcp-combiner/servers.json → ~/.config/mcp/servers.json。 。 。 .

UX号

代理工具 (单位:千美元)mcp时,或您的 toolName——一个工具而不是数百个:

mcp({search: "github search code"})     → ranked hits + describe-next hint
mcp({describe: "github_search_code"})   → full schema (TS-shaped) + description
mcp({tool: "github_search_code", args: {...}})  → the call
mcp({})                                 → status

每个工具的注册 - 联合体的工具也宣布为头等舱 个人姓名(github_search_code: directTools 逐字匹配, 其余部分 可从代码脚本和 pi 中达到 tool_search ——同时 mcp 上方路由器 继续在同一连接上注册(匹配 mcp 工具 名称继续工作)。 见 docs/call-chain.md 全文 呼叫的层图.

read_<resource> 工具 – 每MCP资源一个零参数工具;交互式 mcp-app 资源及其 read_* 结果附加合并器 UI- host URL(/ui/<token>/?resource=…),在浏览器中自动打开——交互式部件运行集成器-侧.

交互式部件( mcp- app) ——当一个装有部件的工具结果到达时(例如. todoist_find-tasks-by-date,即联合体 在飞机上待命页:1 扩展自动打开浏览器中的部件,工具的数据流 超过SSE,而你交互 当呼叫等待。 点击 完成 部件和 电话以你所作所为的摘要解决。 每个部件动作运行 通过组合器的许可管道, 和完整的交互保留 可获取: 请求 combiner__ui_messages 之后(持有预算为50) 默认情况下—— MCP_COMBINER_UI_HOLD_TIMEOUT 合并侧; 部件 URL 保留 在超时后有效, 您只是失去了折叠结果 对于那个电话. 自摸的部件(svg-mcp的预览)同样有效.

提示斜线命令 —— 说 mcp__<server>__<name> (例如:. mcp__todoist__productivity_analysis, (中文(简体) ), 职位+ name=value 并引用了这些话.

页脚 —— 说 14 servers enabled (13 ready) · 671 tools 下划线 mcp 状态密钥; 通过连接/变化和每30次更新;无法到达时诚实地退化.

/mcp-combiner 命令数字 :

动词效果
(无) 编号 : status连接状态, 每个服务器的 glyph 表, 会话视图
panel互动面板( 下方)
enable 编号 : disable 编号 : restart-server <srv>驱动组合器的元工具
system-prompt显示注入指令
install-config [path]遗产:写下共享的..mcp.json pi- mcp- 适应器条目

小组 —— 说 /mcp-combiner panel: 连接+端口+会话符号,曝光 过滤器,模糊搜索(/),每个服务器行有州格字母(● ○ ⊘ ✗ ◌)和 工具/资源/瞬间计数三重奏,可扩展的工具列表,并附有符号估计, [session off] 项目过滤服务器的标签, 组合器自己的 ⬢ 元工具 组合。 密钥 : ↑↓/jk 移动 enter 扩展/复制 e 可用/残废 c 副本 · / 过滤器 r 刷新 q 关闭.

聊天身份

每一次Pi会话都会铸造自己的组合符号(pi-<sessionId>) 输入合并器 URL 路径,所以每个聊天隔离(isolate: true 服务器),停放上游会话 重新启动聊天中的所有密钥交接——子代理自动获得自己的令牌 (每届儿童会议都有新鲜内容)。 恢复聊天继续其身份; 叉 故意开始新鲜。 在配置的 URL 中, 明确符号总是获胜 .

由于身份住在客户端,一个联合体重启会优雅地降解: 核准重新启动的移交携带同意书,每箱过滤器并停放 会话到后继启动, 每个连接方法都会重复一次 stale会话 (单位:千美元)withStaleRetry),以及 combiner__status 编号 : /health 报告此靴子恢复的内容 (单位:千美元)_handover) ——重启后重新定向收受.

权限

实施工具调用政策 在联合体 (单位:千美元)permissions 内 servers.json数字 : 拒绝/ 合法/ 允许每个服务器, 交互诱导连接到 Pi 的 UI 子剂默认安全下降)。 "Allow for session"的赠款由 聊天符牌,并携带到受制裁的组合器重启中. 在本地模式下 组合器工具说明( 读取 Only/ 破坏性提示) 骑 Pi 的注册 分类认识门。 如果您也运行 pi-permission-system,保留 toolName: "mcp" 联合国 mcp- 表面规则(工具 - glob 模式,如 github_* 匹配从 说到盒子里.

承认

服务对象的一半开始于大幅度减少 pi- mcp- 适应器 (麻省理工学院,尼科·拜伦) - 代理工具呼叫会议,搜索语义,结果守护行为,即时 命令格式、资源命名、 计划签名渲染器和 HTML/JS 部件合同来源于该合同,符合合同情形 test/ 从 它的套间。 一切OAuth,多服务器, 和交通相关的都是故意的 没有 在这里,联合体拥有它。 这个套装更糟糕 没有尼科的设计工作,去明星.

主机拥有模式

若为 $MCP_COMPANION_COMBINER_URL 设置,一个编辑器/主机(例如Neovim)已经拥有 并重新计算联合体——这个扩展从未发射过(客户端仍然) 页:1 等值为 PI_MCP_COMBINER_MANAGE=false 过程的一半.

发展

npm install
npm run typecheck
npm run build      # emits dist/ (not committed; built on publish)
npm run smoke      # live suite against the running combiner on :9741

设计注释 : docs/adapter-design.md编辑 src/sharedserver-resolve.ts 文件为 供应商字节相同 从 georgeharker/sharedserver (通过) scripts/sync-vendored.sh) (中文(简体) ). 上游编辑;在此重新同步 .

许可证

麻省理工学院 乔治·哈克

版本与发布记录

@geohar/pi-mcp-combiner 共发布 42 个版本,首次发布于 2026/08/18;过去 12 个月发布了 42 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.23.1latest2026/11/106 天前
0.23.02026/11/106 天前
0.22.02026/11/097 天前
0.21.42026/11/0610 天前
0.21.32026/11/0511 天前
0.21.22026/11/0412 天前

其他发布通道:dev → 0.21.2-dev.1。

关于 @geohar/pi-mcp-combiner 的常见问题

@geohar/pi-mcp-combiner 是什么?

Pi扩展:通过共享服务器运行mcp-combiner MCP聚合器并注入其工具发现指令. 配有pi-mcp-adapter的配对,这使得组合器的工具可以从Pi得到.

如何安装 @geohar/pi-mcp-combiner?

在项目目录运行 npm install @geohar/pi-mcp-combiner,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@earendil-works/pi-tui(^0.85.1)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@geohar/pi-mcp-combiner 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geohar/pi-mcp-combiner 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@geohar/pi-mcp-combiner 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@geohar/pi-mcp-combiner 可以商用吗?

@geohar/pi-mcp-combiner 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geohar/pi-mcp-combiner 的下载量有多少?

根据 npm 官方下载统计,@geohar/pi-mcp-combiner 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,601 次,日均约 153 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geohar/pi-mcp-combiner 还在维护吗?

最新版本 0.23.1 发布于 2026/11/10(6 天前);至今共发布 42 个版本,其中过去 12 个月发布了 42 个;首次发布于 2026/08/18。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。