# Pi MCP Connector

[English](README.md)

为 [Pi](https://pi.dev) 打造的轻量级 Model Context Protocol (MCP) 连接器扩展。通过单一网关工具 `mcp` 统一路由、自动纠错并按需并发调用本地/远程配置的 MCP 服务器。

---

## 核心特性

1. **多协议传输通道支持 (Multi-transport Support)**
   - 完整兼容 MCP 规范定义的三类核心传输通道：
     - **Stdio 传输**：基于本地子进程，通过标准输入输出（stdin/stdout）执行双向 JSON-RPC 通信。
     - **SSE 传输**：支持远程长连接，通过 Server-Sent Events（事件推送流）进行数据通信。
     - **Streamable HTTP 传输**：支持基于 Chunked 流式 HTTP 通道的高并发数据交换。

2. **自动延迟加载与连接池管理 (Lazy Connection & Pooling)**
   - 启动会话时仅拉取缓存元数据，在大模型初次调用具体工具时才真正建立底层通信信道，极速缩短会话冷启动时间，并在会话关闭时自动回收释放资源。

3. **声明式工具 Manifest 自动注入**
   - 启动会话时自动生成精确的工具模式描述注入大模型的上下文，即使服务端处于离线或延迟状态，模型也能如同调用内置工具般精准填参。

4. **双向兼容的大模型传参适配 (Schema Bypassing)**
   - 彻底优化底层 execute schema，支持大模型在参数传输中免转义直接传递 JSON 对象，同时向下兼容传 JSON 字符串，显著提升调用成功率。

5. **高级自愈与相似度容错路由**
   - 如果大模型拼写错误或携带错误的服务器前缀，系统将执行 Levenshtein 模糊匹配算法进行相似度分析，置信度 $\ge 85\%$ 时自动对齐自愈路由，并给大模型以友好提示。

---

## 项目结构

```
pi-mcp-connector/
├── index.ts                  # 扩展入口（重导出 src/index.ts）
├── src/
│   ├── index.ts               # Gateway `mcp` 注册与 TUI 面板
│   ├── config.ts              # 加载本地/全局 MCP 配置文件 (~/.pi/pi-mcp-connector/config.json)
│   ├── client.ts              # SimpleMcpClient 客户端（含 stdio, sse, streamable http 协议支持）
│   ├── proxy.ts               # MCP 请求与资源代理服务
│   ├── cache.ts               # 本地已连接工具的 Metadata 缓存系统
│   ├── logger.ts              # 本地调试日志
│   ├── mutex.ts               # 互斥排队锁（用于非只读工具按需排队）
│   ├── types.ts               # TS 类型定义
│   └── dispatch-classifier.ts # 只读与并发请求智能分类器
├── test.ts                   # 单元与集成测试
└── biome.json
```

---

## 安装

```bash
pi install npm:pi-mcp-connector
```

---

## 配置与使用

在 Pi 终端中：

- `/mcp` — 打开交互式 TUI 控制面板进行多服务器管理。
- `/mcp <serverName>` — 切换指定配置服务器的连接与断开状态。

---

## 执行测试

运行内置的 TypeScript 单元测试（基于 Node.js 原生测试运行器）：
```bash
npm run test
```

---

## 开发与规范

已严格对齐 `pi-main` 核心工程的质量与安全规范：
1. **格式化与语法检查**：使用 Biome 对项目代码进行统一格式化。缩进风格配置为 `tab`，缩进宽度为 `3`。
2. **常用指令**：
   - 运行风格与语法检测：`npm run check`（自动执行 `biome check --write .`）
   - 运行单元测试：`npm test`

---

## 许可证书

MIT