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. Proactive Schema Injections

   • Automatically populates the system prompt with a detailed manifest of all cached tools, descriptions, and strict properties schemas, ensuring the model knows exactly how to invoke your servers.

4. Schema Bypassing (JSON Object Passthrough)

   • Declares execution parameters as JSON Any, allowing advanced LLMs to pass raw structured argument payloads directly without string-escaping issues, while remaining backwards compatible with legacy stringified payloads.

5. Fuzzy Routing & Auto-Correction

   • Auto-corrects tool calls using string distance similarity metrics if the model misspells a tool name or misses a server prefix (similarity $\ge 85%$).

---

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

Supports both installation methods:

• Via NPM (Recommended):

  pi install npm:pi-mcp-connector
  

• Via GitHub:

  pi install https://github.com/huanghui-dev/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