@geohar/pi-mcp-combiner

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

Pi extension: run the mcp-combiner MCP aggregator via sharedserver and inject its tool-discovery directive. Pairs with pi-mcp-adapter, which makes the combiner's tools reachable from Pi.

原始使用文档
文档目录14 节
  1. How it fits together
  2. Running it
  3. Requirements
  4. Configuration — three layers
  5. 1. Pi settings file — $PI_CODING_AGENT_DIR/extensions/mcp-c…
  6. 2. Shared MCP config ladder — read-only
  7. 3. Environment — PI_MCP_COMBINER_*
  8. The UX
  9. Chat identity
  10. Permissions
  11. Acknowledgments
  12. Host-owned mode
  13. Development
  14. License

@geohar/pi-mcp-combiner

A Pi extension + one shared MCP aggregator: a single refcounted combiner process fronts all your MCP servers, and every client you use talks to that one process.

It reuses Pi's MCP stack rather than replacing it. The transport is @earendil-works/pi-mcp — Pi's own MCP client library (carried at ^1.2.0; host-providing it as a true peer is asked upstream — until then pi's loader shares only pi-ai/agent-core/tui/typebox, so the physical copy is the sanctioned route and is safe: no pi-mcp object crosses into pi's copies). One flip-condition to watch: if pi ever host-provides pi-mcp, drop the dependencies entry in the same release — the carried copy would then shadow the host's module mapping (the antipattern docs/packages.md warns about), so the manifest must move with it: and Pi's built-in MCP support keeps its role (/mcp, codemode, tool_search). The extension is additive; it adds the pieces Pi's built-in can't do:

  • Elicitation — upstream servers can ask you: consent ladders, deploy confirmations, structured forms. Pi's built-in MCP can't forward those; this extension bridges them to Pi's dialogs — and to your paired app over un-bien.
  • Interactive resources (mcp-app widgets) — Pi's read_mcp_resource skips ui:// resources entirely; we register read_* tools, host the widget, hold the call while you interact, and fold your actions back into the result.
  • A discovery router — mcp({search}) / ({describe}) / ({tool, args}): ranked discovery over the whole aggregated surface, under the tool name mcp that tool_call gates already recognize.

The sharing is the point. One combiner process, supervised by sharedserver, is shared across Pi, Claude Code, OpenCode, and Neovim — upstream connections, sessions, and OAuth live once, not once per client. One servers.json permission policy (deny / elicit / allow, per server) is enforced at the combiner for every client alike, keyed by per-chat tokens that survive restarts: consent grants, parked sessions, and filters carry across combiner restarts by handover, and combiner__status reports what a boot restored.

It is the Pi counterpart of the Claude Code and OpenCode plugins, and shares the same combiner and the same sharedserver instance.

How it fits together

Three halves, all in this one package:

  1. Process — on session_start it drives

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

    sharedserver refcounts by PID with a grace period, so the combiner is shared across clients and outlives any single one. The refcount releases on session_shutdown only when reason === "quit" — reload/resume/fork keep the same Pi process and a fresh session_start re-attaches.

  2. Client — the pi-mcp transport on an owned connection (per-Pi-session custody token, elicitation capability advertised and bridged to Pi's UI) that registers the agent-facing surface: every combiner tool first-class under its bare name (github_search_code) with pi-1.0 exposure/namespace/annotations, the mcp() discovery router on the same connection, read_* resource tools (interactive ui:// widgets included), prompt slash commands, a status footer, and an interactive panel.

  3. Instructions — on before_agent_start it appends the combiner's <server>_-prefix / "discover before assuming" directive to the system prompt.

sharedserver itself is fetched automatically if not installed (pinned release via the cargo-dist installer), and the combiner is resolved from PATH / a checkout / a pinned PyPI release — same resolvers as the sibling plugins.

Running it

Install only this extension. Nothing else needed — the client half connects to the combiner and registers everything:

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

On startup you get: every combiner tool first-class under its bare name (your directTools matches declared direct, the rest on codemode), the mcp discovery router, read_<resource> tools, /<server>__<prompt> slash commands, a footer line (14 servers enabled (13 ready) · 671 tools), and /mcp-combiner panel.

*Via another mechanism — pi-mcp-adapter. The target is Pi's native MCP support (Pi ≥ 1.0). If you already run pi-mcp-adapter for other servers, this extension can stand down its client half: "adapter": false (or the default "auto", which detects the adapter and yields automatically) leaves the process half + instructions to us and MCP to the adapter. /mcp-combiner install-config still writes the shared-mcp.json entry for the adapter to read.

Requirements

  • mcp-combiner available as a command (uv tool install mcp-combiner), or just uv on PATH — a pinned release is fetched from PyPI on demand. Requires combiner ≥ 0.8.0 (version-gated automatically).
  • A combiner servers.json (auto-probe locations below).
  • pi-mcp-adapter not required.
  • Pi ≥ 1.0 with its bundled @earendil-works/pi-mcp (resolved in-tree at ^1.2.0) — the transport is Pi's own MCP client library.

Configuration — three layers

1. Pi settings file — $PI_CODING_AGENT_DIR/extensions/mcp-combiner.json

Pi-side knobs (see settings.example.json):

KeyDefaultEffect
toolName"mcp"Name of the proxy tool. Rename (e.g. "combiner") to coexist with pi-mcp-adapter's own mcp.
adapter"auto"Client-half gate — see above.
lazy"lazy""eager" connects at session start; "lazy" on first use. Prompts/resources/directTools imply eager.
exposeResourcestrueRegister read_<resource> tools.
promptstrueRegister prompt slash commands.
uiAutoOpentrueAuto-open interactive widget URLs in the browser (Stage 2 holds + resource reads).
warnLargeDirectExposuretrueWarn when >50 tools end up direct-exposed (every schema rides in every request); set false to silence. Native mode.
mcpFooterStatus"full"Footer text: "full" = N servers enabled (M ready) · T tools, "compact" = MCP M/N, "off" = none.
mcpFooterKey"mcp"The ctx.ui.setStatus key the footer publishes under (the slot oh-my-posh-style footers aggregate).
url—Explicit combiner URL. Env wins.
notifytrueSurface lifecycle messages via the Pi UI.

2. Shared MCP config ladder — read-only

The extension reads the standard MCP files (same ladder and precedence as pi-mcp-adapter, later wins): ~/.config/mcp/mcp.json → ~/.agents/mcp.json → ~/.agents/mcp/mcp.json → <agent dir>/mcp.json → .mcp.json → .pi/mcp.json (project). It never writes them.

The recognized mcp-combiner entry carries connection + per-project exposure:

{
  "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 — per-project exposure, enforced at the combiner for this chat's token (sees through scripting too) and mirrored client-side.
  • directTools — an allowlist (globs) of tools to declare direct (verbatim, in every request) instead of codemode (reachable from scripts and pi's tool_search). "search" degrades to all-codemode — pi's own discovery replaces the old search-promote. A >50-entry allowlist warns; true is deliberately not offered (context cost: every direct schema rides in every request).
  • Codemode activation (pi 1.0.x quirk) — pi does NOT auto-activate the codemode tool for extension-registered tools (only for its own connected MCP servers), so codemode-exposed combiner tools are unreachable from scripts until you add "defaultTools": ["+codemode"] to your pi settings.json. That setting applies at a fresh session's creation (resumed sessions keep their recorded tool set). If you don't use codemode, combiner tools outside directTools stay callable via the mcp discovery/router tool.
  • Project layers are read against the session cwd — worktree subagents and project switches get their own .pi/mcp.json. Commit the combiner block if you want worktree agents to honour it.
  • URL precedence: MCP_COMPANION_COMBINER_URL (host-owned) → PI_MCP_COMBINER_URL → settings url → ladder entry url → host:port/mcp.

3. Environment — PI_MCP_COMBINER_*

VariableDefaultEffect
PI_MCP_COMBINER_ADAPTER(settings)off / on / auto — client-half gate.
PI_MCP_COMBINER_TOOL_NAME(settings)Proxy tool name override.
PI_MCP_COMBINER_URL—Explicit combiner URL.
PI_MCP_COMBINER_PORT9741HTTP port the combiner serves on.
PI_MCP_COMBINER_HOST127.0.0.1HTTP host the combiner binds.
PI_MCP_COMBINER_CONFIG(auto-probed)Path to the combiner's servers.json.
PI_MCP_COMBINER_COMMAND / _ARGS(auto-resolved)Override the combiner invocation.
PI_MCP_COMBINER_CHECKOUT—Checkout for uv run --project <checkout> python -m mcp_combiner.
PI_MCP_COMBINER_NAMEmcp-combinersharedserver instance name.
PI_MCP_COMBINER_GRACE30msharedserver grace period.
PI_MCP_COMBINER_LOG / _PYLOG / _LOG_LEVEL(state dir)Combiner logging; "none" disables.
PI_MCP_COMBINER_MANAGEtruefalse → don't launch (combiner runs elsewhere).
PI_MCP_COMBINER_INSTRUCTIONStruefalse → skip the system-prompt directive.
PI_MCP_COMBINER_NOTIFYtruefalse → don't surface messages via the Pi UI.
SHAREDSERVER_BIN / SHAREDSERVER_LOCKDIR(auto)sharedserver binary / lock dir.

servers.json auto-probe: $PI_MCP_COMBINER_CONFIG → ~/.cache/secrets/<user>.mcpservers.json → ~/.config/mcp-combiner/servers.json → ~/.config/mcp/servers.json.

The UX

The proxy tool (mcp, or your toolName) — one tool instead of hundreds:

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

Per-tool registration — the combiner's tools are also declared first-class under their own bare names (github_search_code): directTools matches verbatim, the rest reachable from codemode scripts and pi's tool_search — while the mcp router above keeps registering on the same connection (tool_call gates that match the mcp tool name keep working). See docs/call-chain.md for the full layer map of a call.

read_<resource> tools — one zero-parameter tool per MCP resource; interactive mcp-app resources are flagged and their read_* results append the combiner UI-host URL (/ui/<token>/?resource=…), auto-opened in the browser — the interactive widget runs combiner-side.

Interactive widgets (mcp-app) — when a widget-bound tool result arrives (e.g. todoist_find-tasks-by-date), the combiner holds the call in flight: the extension auto-opens the widget in your browser, the tool's data streams to it over SSE, and you interact while the call waits. Hit Done in the widget and the call resolves with a summary of what you did. Every widget action runs through the combiner's permission pipeline, and the full interaction stays retrievable: ask for combiner__ui_messages afterwards (the hold budget is 50s by default — MCP_COMBINER_UI_HOLD_TIMEOUT combiner-side; the widget URL stays valid after a timeout, you just lose the fold-into-result for that call). Widgets that self-fetch (svg-mcp's preview) work the same way.

Prompt slash commands — mcp__<server>__<name> (e.g. mcp__todoist__productivity_analysis), positional + name=value args with bash quoting.

Footer — 14 servers enabled (13 ready) · 671 tools under the mcp status key; refreshed on connect/changes and every 30s; honest degradation when unreachable.

/mcp-combiner command:

VerbEffect
(none) / statusConnection state, per-server glyph table, session view
panelInteractive panel (below)
enable / disable / restart-server <srv>Drive the combiner's meta-tools
system-promptShow the injected directive
install-config [path]Legacy: write the shared-mcp.json entry for pi-mcp-adapter

The panel — /mcp-combiner panel: connection + port + session token, exposure filter, fuzzy search (/), per-server rows with state glyphs (● ○ ⊘ ✗ ◌) and the tools/resources/prompts counts trio, expandable tool lists with token estimates, [session off] labels for project-filtered servers, the combiner's own ⬢ meta-tools group. Keys: ↑↓/jk move · enter expand/copy · e enable/disable · c copy · / filter · r refresh · q close.

Chat identity

Each Pi session mints its own grouping token (pi-<sessionId>) into the combiner URL path, so per-chat isolation (isolate: true servers), parked upstream sessions, and restart handover all key on the chat — subagents automatically get their own tokens (each child session binds fresh). A resumed chat continues its identity; a fork deliberately starts fresh. An explicit token in the configured URL always wins.

Because identity lives at the client, a combiner restart degrades gracefully: the sanctioned-restart handover carries consent grants, per-token filters and parked sessions to the successor boot, every connection method retries a stale session once (withStaleRetry), and combiner__status / /health report what this boot restored (_handover) — the post-restart re-orientation receipt.

Permissions

Tool-call policy is enforced at the combiner (permissions in servers.json: deny/elicit/allow per server, with interactive elicitation bridged to Pi's UI — subagents decline securely by default). "Allow for session" grants are keyed by the chat token and carried across sanctioned combiner restarts. In native mode the combiner's tool annotations (readOnly/destructive hints) ride pi's registration for classification-aware gates. If you also run pi-permission-system, keep toolName: "mcp" for its mcp-surface rules (tool-glob patterns like github_* match out of the box).

Acknowledgments

The client half began as a substantial reduction of pi-mcp-adapter (MIT, © Nico Bailon) — the proxy-tool calling convention, search semantics, result-guard behavior, prompt command format, resource naming, the schema-signature renderer, and the HTML/JS widget contract derive from it, and the conformance cases in test/ are ported from its suite. Everything OAuth, multi-server, and transport-related is deliberately not here — the combiner owns that. This package would be a much worse tool without Nico's design work; go star it.

Host-owned mode

If $MCP_COMPANION_COMBINER_URL is set, an editor/host (e.g. Neovim) already owns and refcounts the combiner — this extension never launches it (the client still connects). Equivalent to PI_MCP_COMBINER_MANAGE=false for the process half.

Development

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

Design notes: docs/adapter-design.md. The src/sharedserver-resolve.ts file is vendored byte-identical from georgeharker/sharedserver (via scripts/sync-vendored.sh). Edit upstream; re-sync here.

License

MIT © George Harker

版本与发布记录

@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 extension: run the mcp-combiner MCP aggregator via sharedserver and inject its tool-discovery directive. Pairs with pi-mcp-adapter, which makes the combiner's tools reachable from 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 和提交记录判断。