Pi MCP Connector

中文版

Lightweight Model Context Protocol (MCP) gateway extension for Pi. Routes, pools, and lazy-loads configured local and remote MCP servers through a single proxy tool.

---

Key Features

1. Multi-transport Protocol Support

   • Fully compatible with the three core transport channels defined by the MCP specification:
     • Stdio: Spawns local subprocesses communicating via standard input/output streams (stdin/stdout) using JSON-RPC.
     • SSE (Server-Sent Events): Interacts with remote servers using push event streams over HTTP.
     • Streamable HTTP: Exchanges high-throughput messages over chunked HTTP streams.

2. Lazy Client Instantiation & Pooling

   • Loads tool schemas instantly from a local cache at startup, and establishes the underlying connection channel only when a tool on that server is first invoked, drastically improving boot times and freeing connections automatically on exit.

3. Compact, Contextual Discovery

   • Keeps startup guidance small. Agents search cached capabilities on demand and receive a bounded list with exact invocation templates instead of paying the token cost of a complete manifest every turn.

4. Validated JSON Arguments

   • Accepts structured JSON objects in the public schema. A compatibility shim upgrades legacy stringified arguments before validation.

5. Fail-loud Routing

   • Requires exact tool names. Similar names are suggestions only and are never executed automatically. Ambiguous qualified names require explicit { server, tool } routing, protecting mutation tools from prefix collisions.

6. Bounded Transport & Agent Output

   • Enforces a 10 MiB limit on HTTP, SSE-event, and STDIO-line input. Oversized text and non-text tool/resource output is omitted from model context, saved to a temporary file, and exposed through an explicit full-output path.

---

Project Structure

pi-mcp-connector/
├── index.ts                  # Pi extension entry point (re-exports src/index.ts)
├── src/
│   ├── index.ts               # Gateway `mcp` registration & TUI dashboard
│   ├── config.ts              # Loads local/global MCP config (~/.pi/pi-mcp-connector/config.json)
│   ├── client.ts              # SimpleMcpClient (stdio, sse, streamable http support)
│   ├── proxy.ts               # MCP requests and resource proxy server
│   ├── cache.ts               # Metadata caching for connected tools
│   ├── logger.ts              # Local debugging log utility
│   ├── mutex.ts               # Mutex lock for non-readonly tool queuing
│   ├── types.ts               # TypeScript type definitions
│   └── dispatch-classifier.ts # Smart classifier for readonly vs concurrent requests
├── test.ts                   # Unit & integration tests
└── biome.json

---

Installation

pi install npm:pi-mcp-connector

---

Configuration & Usage

In the Pi terminal:

• /mcp — Interactive TUI control panel for server management.
• /mcp <serverName> — Toggle connection state for a specific configured server.

---

Testing

Run the native TypeScript unit test suite (Node.js native test runner):

npm run test

---

Development

We align with the code quality and security standards of the primary pi-main workspace:

1. Linter & Formatter: Biome is configured to auto-format and check codebase. We use tab indentation with a width of 3 characters.
2. Commands:
   • Check format and Lint: npm run check
   • Run tests: npm test

---

License

MIT