@geohar/pi-mcp-combiner

A Pi extension that gives Pi the mcp-combiner MCP aggregator — end to end. It starts the combiner (supervised by sharedserver), speaks MCP to it directly (a built-in client half — no second package required), and surfaces every server, tool, resource, and prompt as first-class Pi UX.

Use it standalone (recommended) or alongside pi-mcp-adapter — see Two ways to run it.

It is the Pi counterpart of the Claude Code and OpenCode plugins, and shares the same combiner and the same sharedserver instance — so Pi, Claude Code, OpenCode, and Neovim can all talk to one refcounted combiner process.

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 — a thin, combiner-specific MCP client (streamable HTTP, per-Pi-session identity, an elicitation bridge) that registers the agent-facing surface: the mcp() proxy tool, a scripting tool, read_* resource tools, prompt slash commands, a status footer, and an interactive panel. Everything the hundreds of tool definitions would cost in context is replaced by two or three tool definitions and on-demand discovery.

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.

Two ways to run it

A. Standalone (recommended)

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

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

On startup you get: the mcp tool (search → describe → call), mcpScript, read_<resource> tools, /<server>__<prompt> slash commands, a footer line (14 servers enabled (13 ready) · 671 tools), and /mcp-combiner panel.

B. Alongside pi-mcp-adapter

Already running pi-mcp-adapter (for other servers, or while evaluating)? The client half is gated by a tri-state:

Setting	Behaviour
"adapter": "auto" (default)	client off when pi-mcp-adapter is detected installed, on otherwise — existing adapter setups upgrade with zero behaviour change
"adapter": true	client on, adapter stays for other servers. Rename ours ("toolName": "combiner") so both tools coexist, and remove the combiner entry from the shared mcp.json so the adapter doesn't double-connect
"adapter": false	legacy mode — process + instructions only; the adapter owns all MCP

Env override: PI_MCP_COMBINER_ADAPTER=off|on|auto. /mcp-combiner status reports which mode is active and why.

The legacy /mcp-combiner install-config verb (writes the combiner entry into the shared mcp.json for the adapter to read) still exists for mode B.

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.

Configuration — three layers

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

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

Key	Default	Effect
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.
exposeResources	true	Register read_<resource> tools.
prompts	true	Register prompt slash commands.
scriptMode	true	Register the <toolName>Script batching tool.
uiAutoOpen	true	Auto-open interactive widget URLs in the browser (Stage 2 holds + resource reads).
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.
notify	true	Surface 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 — promote named tools (globs) to first-class Pi tools at session start, or "search" to promote tools the first time mcp({search}) matches them. A >50-entry allowlist warns; true is deliberately not offered (context cost).
• 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_*

Variable	Default	Effect
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_PORT	9741	HTTP port the combiner serves on.
PI_MCP_COMBINER_HOST	127.0.0.1	HTTP 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_NAME	mcp-combiner	sharedserver instance name.
PI_MCP_COMBINER_GRACE	30m	sharedserver grace period.
PI_MCP_COMBINER_LOG / _PYLOG / _LOG_LEVEL	(state dir)	Combiner logging; "none" disables.
PI_MCP_COMBINER_MANAGE	true	false → don't launch (combiner runs elsewhere).
PI_MCP_COMBINER_INSTRUCTIONS	true	false → skip the system-prompt directive.
PI_MCP_COMBINER_NOTIFY	true	false → 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

In "directTools": "search" mode, search matches are promoted to first-class tools and announced in the result.

mcpScript — batch calls with trusted JavaScript: {code: "const r = await tools.search('q'); emit(r); return await tools.call('t', {})"}.

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:

Verb	Effect
(none) / status	Connection state, per-server glyph table, session view
panel	Interactive panel (below)
enable / disable / restart-server <srv>	Drive the combiner's meta-tools
system-prompt	Show 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.

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). 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