# @geohar/pi-mcp-combiner 中文文档

规范地址：https://npmcn.com/package/%40geohar/pi-mcp-combiner/

版本：0\.23\.1
npm 元数据更新时间：2026-11-09T20:36:19.095Z
中文译文更新时间：2026-11-16T04:34:01.203Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40geohar/pi-mcp-combiner
原文对照：https://npmcn.com/package/%40geohar/pi-mcp-combiner/?lang=original
项目主页：https://github.com/georgeharker/mcp-combiner/tree/main/plugins/pi#readme
源码仓库：https://github.com/georgeharker/mcp-combiner

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：864 kB，127 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：1 个
- peer 依赖：@earendil-works/pi-mcp ^1\.2\.0，@earendil-works/pi-tui ^0\.85\.1
- 首次发布：2026-08-17T21:07:46.158Z
- 最新版本发布：2026-11-09T20:36:18.716Z
- 近 30 天下载量：4601（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 42 个）

## 中文简介

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

## 安装

```sh
npm install @geohar/pi-mcp-combiner
```

也可以使用：`pnpm add @geohar/pi-mcp-combiner`、`yarn add @geohar/pi-mcp-combiner`、`bun add @geohar/pi-mcp-combiner`

## README

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

A 类 [Pi](https://pi.dev/) 扩展名 + 共享 **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 的对话框, 以及您的对接应用程序 [无双](https://github.com/georgeharker/un-bien)。 。 。 .
-   **交互式资源( mcp- app 部件)** - 皮丝 `read_mcp_resource` 跳过 `ui://` 全部资源; 我们登记 `read_*` 工具,主机部件,按住 在您交互时打电话,然后将您的动作折叠到结果中.
-   **发现路由器** —— 说 `mcp({search})` 编号 : `({describe})` 编号 : `({tool, args})`数字 : 在工具名下, 将整个集合表面的发现排序 `mcp` 呼叫门已经认出来了.

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

这是Pi的对应方 [克劳德代码](https://github.com/georgeharker/mcp-combiner/tree/main/plugins/claude) 财务报告和审定财务报表 [打开代码](https://github.com/georgeharker/mcp-combiner/tree/main/plugins/opencode) 插件,并共享相同的组合器和相同的组合器 `sharedserver` 举个例子.

## 如何融为一体

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

1.  **进程** - 开始 `session_start` 它驱动
    
    ```sh
    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 发布器——与兄弟会插件相同的解析器.

## 运行它

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

```sh
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`](https://pi.dev/packages/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`](https://npmcn.com/package/%40geohar/pi-mcp-combiner/settings.example.json):

| 密钥 | 默认 | 效果 |
| --- | --- | --- |
| `toolName` | `"mcp"` | 代理工具的名称 。 重命名( 例如 ). `"combiner"`与 pi-mcp- 适应者自己的共存 `mcp`。 。 。 . |
| `adapter` | `"auto"` | 客户半门-见上文. |
| `lazy` | `"lazy"` | `"eager"` 在会话开始时连接; `"lazy"` 开始使用。 提示/资源/直接工具意味着渴望. |
| `exposeResources` | `true` | 登记册 `read_<resource>` 工具. |
| `prompts` | `true` | 注册快速斜线命令 . |
| `uiAutoOpen` | `true` | 浏览器中自动打开交互式部件URL(Stage 2 holds + reading). |
| `warnLargeDirectExposure` | `true` | 当 > 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赢了. |
| `notify` | `true` | 通过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` 条目带有连接+每个项目接触:

```jsonc
{
  "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_PORT` | `9741` | HTTP 连接器服务端口 . |
| `PI_MCP_COMBINER_HOST` | `127.0.0.1` | HTTP主机集成器绑定. |
| `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_NAME` | `mcp-combiner` | `sharedserver` 实例名称. |
| `PI_MCP_COMBINER_GRACE` | `30m` | `sharedserver` 宽限期. |
| `PI_MCP_COMBINER_LOG` 编号 : `_PYLOG` 编号 : `_LOG_LEVEL` | _(状态 dir)_ | 联合伐木; `"none"` 禁用 . |
| `PI_MCP_COMBINER_MANAGE` | `true` | `false` ——不要发射(combiner运行在别处). |
| `PI_MCP_COMBINER_INSTRUCTIONS` | `true` | `false` ~ 跳过系统即时指令. |
| `PI_MCP_COMBINER_NOTIFY` | `true` | `false` 不要通过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`——一个工具而不是数百个:

```ts
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`](https://npmcn.com/package/%40geohar/pi-mcp-combiner/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`](https://github.com/gotgenes/pi-packages),保留 `toolName: "mcp"` 联合国 `mcp`\- 表面规则(工具 - glob 模式,如 `github_*` 匹配从 说到盒子里.

## 承认

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

## 主机拥有模式

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

## 发展

```sh
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`](https://npmcn.com/package/%40geohar/pi-mcp-combiner/docs/adapter-design.md)编辑 `src/sharedserver-resolve.ts` 文件为 **供应商字节相同** 从 [`georgeharker/sharedserver`](https://github.com/georgeharker/sharedserver) (通过) `scripts/sync-vendored.sh`) (中文(简体) ). 上游编辑;在此重新同步 .

## 许可证

麻省理工学院 乔治·哈克

## 常见问题

### @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 和提交记录判断。

