@bytetrue/pi-mcp

Minimal MCP (Model Context Protocol) adapter for the pi coding agent. One proxy tool instead of hundreds of tool definitions; tool metadata is cached to disk so discovery works without live server connections; servers connect lazily and disconnect when idle.

Context management over feature breadth: the core design (proxy tool, metadata cache, lazy lifecycle, output guard) is ported from pi-mcp-adapter (MIT — see NOTICE), which itself depends only on registry-published @modelcontextprotocol/client/core 2.0.0. What's deliberately absent: OAuth flows, MCP UI, elicitation/sampling, scripting tools, plugin loaders, setup panels.

Install

pi install npm:@bytetrue/pi-mcp

Configuration

Same layered layout as pi-mcp-adapter / Claude Code / Cursor — an existing setup migrates by doing nothing:

| File | Purpose | |------|---------| | ~/.config/mcp/mcp.json | User-global shared MCP config | | ~/.agents/mcp.json | User-global tool-agnostic MCP config | | ~/.agents/mcp/mcp.json | User-global tool-agnostic MCP config (nested) | | ~/.pi/agent/mcp.json | Pi global override ($PI_CODING_AGENT_DIR/mcp.json) | | .mcp.json | Project-local shared MCP config | | .pi/mcp.json | Pi project override |

Same-name servers in higher layers override lower ones; disabled: true in a higher layer disables an inherited server.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "directTools": ["search_repositories", "get_file_contents"],
      "searchKeywords": { "*": ["gh"] }
    },
    "docs": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  },
  "settings": {
    "idleTimeout": 10,
    "outputGuard": { "maxBytes": 51200, "maxLines": 2000, "detailsMaxBytes": 16384 }
  }
}

Server fields: command/args/env/cwd (stdio, npx commands are resolved to direct binaries — cached, with fallback to plain npx), url + headers (HTTP; Streamable HTTP with automatic SSE fallback on 404/405/406/415), type, disabled, lifecycle (lazy default | eager), idleTimeout (minutes; default 10, 0 disables — eager servers never idle-disconnect), directTools (true | ["tool_a"]), includeTools/excludeTools (glob-capable), searchKeywords, toolPrefix.

Usage

The extension registers one mcp tool (~200 tokens of schema):

| Operation | Call | |-----------|------| | Status | mcp({}) | | List server tools | mcp({ server: "name" }) | | Search tools | mcp({ search: "words", limit?: 12, offset?: 0 }) | | Regex search | mcp({ search: "pattern", regex: true }) | | Describe a tool | mcp({ describe: "server_tool" }) | | Call a tool | mcp({ tool: "server_tool", args: { ... } }) | | Server instructions | mcp({ instructions: "name" }) | | Connect/reconnect | mcp({ connect: "name" }) |

mcp({}) reports five honest states per server — ✓ connected / ✗ failed (Ns ago, reason) / ○ cached; not connected / ○ not connected / ⊘ disabled — instead of one blurred "offline" line.

Managing servers

/mcp command (Tab-completion for subcommands and server names):

| Command | Effect | |---------|--------| | /mcp (or /mcp status) | Five-state server listing | | /mcp reconnect [server] | Reconnect one server or all enabled servers | | /mcp tools | All tools across enabled servers (cache-backed) | | /mcp prompts | All discovered prompts, grouped by server | | /mcp disable <server> | Persist a disabled: true project override (.pi/mcp.json), then /reload | | /mcp enable <server> | Remove the marker (or write disabled: false when a lower layer disables), then /reload |

Interactive menu: /mcp with no arguments in the TUI opens a native Pi dialog menu (select, editor, input, notify) — browse servers with live status and direct tool counts, toggle direct tools per server with [●]/[○], enable/disable servers, reconnect individual or all servers, search tools, and browse prompts. Zero fragile custom terminal overlay diffing. All changes persist to .pi/mcp.json overrides.

Footer status bar: the TUI footer shows a live mcp slot, e.g. 2 servers enabled (1 connected) (1 disabled); "compact" renders mcp:1/2. Configure with settings.mcpFooterStatus: "full" (default) | "compact" | "off". Disabled servers stay visible in status instead of vanishing from config, and are skipped by connect/search/direct-tools.

Protocol tracing (opt-in): set settings.trace: { enabled, file?, maxBytes?, maxEvents? } (or trace: true per server) to record metadata-only JSONL protocol traces — direction, method, bytes, duration, secrets redacted — under .pi/mcp-traces/ by default. Writers self-disable on any failure so tracing never changes MCP behavior.

Tool names match fuzzily across -/_; a miss returns ranked suggestions. Search ranks across name, server, description, and configured keywords, paginated via offset/nextOffset.

Direct tools: configure directTools per server (or "directTools": true in settings) to register chosen tools as real Pi tools with real schemas, skipping the search→describe hop. Each costs ~150–300 tokens in the system prompt, so it fits targeted sets of 5–20 tools; use include/exclude filters to trim noisy servers. Direct tools register statically from the disk metadata cache at load; on the first session after adding them, connect the server once (mcp({ connect: "name" })) to populate the cache, then /reload.

Prompts: servers advertising prompt templates become slash commands — /mcp__<server>__<prompt> — with positional and key=value arguments (bash-style quoting supported). Command definitions come from the metadata cache and refresh on reconnect.

How it works

• One proxy tool in context instead of hundreds of definitions — the agent discovers tools on demand.
• Disk metadata cache (~/.pi/agent/mcp-cache.json, keyed by a config hash): search/list/describe work offline; a changed server config invalidates only that server's entry.
• Lazy connections: servers spawn on first tool call, disconnect after the idle timeout, and reconnect automatically on next use.
• Output guard (port of upstream's): text results capped at 50 KiB / 2,000 lines; oversize output spills to a private 0600 temp file whose path is returned for read/grep. Image blocks pass through untouched. details.mcpResult keeps raw JSON up to 16 KiB, then summarizes and spills. Disable with "outputGuard": false or MCP_OUTPUT_GUARD=0.
• Failure backoff: a server that just failed a connection is excluded from search for 60s instead of polluting results.

Limitations (by design)

• No OAuth: HTTP servers authenticate with static headers only.
• No elicitation, sampling, MCP UI, or resource subscriptions — servers requiring them degrade gracefully.
• Direct tools don't hot-load; a /reload applies config or catalog changes.
• No config-writing UI: manage mcp.json files directly (or via your dotfiles).

Development

npm --workspace @bytetrue/pi-mcp test       # vitest (includes real-stdio regression via npx)
npm --workspace @bytetrue/pi-mcp run typecheck

MIT. See NOTICE for upstream attribution.