# pi-mcp-kit

[English](README.md)

为 [Pi](https://pi.dev) 打造的轻量级模型上下文协议 (MCP) 网关扩展。通过统一代理工具对已配置的本地与远程 MCP 服务进行路由、连接池化管理和按需延迟加载。

## 功能

- **多传输协议支持**：支持 MCP 的 Stdio、SSE 和 Streamable HTTP 传输方式。
- **延迟加载与连接池**：启动时读取缓存的工具元数据，不会立即打开所有服务器连接。
- **紧凑型能力探索**：允许 Agent 按需搜索缓存的 MCP 能力，并调用搜索结果中的精确工具名。
- **结构化 JSON 参数**：接受对象参数，并将其转发给选定的 MCP 服务端进行校验和执行。
- **显式路由防误触发**：要求工具名称精确匹配；重名工具必须通过 `{ server, tool }` 明确路由。
- **传输与输出体积限制**：强制执行 10 MiB 传输消息限制，超大输出会保存到本地临时文件。

## 环境要求

- Node.js 20.0.0 或更高版本
- `@earendil-works/pi-coding-agent`、`@earendil-works/pi-tui` 以及 `typebox`
- 已配置的本地或远程 MCP 服务器

## 安装

```sh
pi install npm:pi-mcp-kit
```

## 配置

MCP 服务器配置会从以下位置加载：

| 路径 | 描述 |
| --- | --- |
| `~/.pi/agent/mcp.json` | 首选的全局 MCP 配置文件。 |
| `~/.config/mcp/mcp.json` | 当首选文件不存在时使用的全局配置文件。 |
| `.pi/mcp.json` 或 `.mcp.json` | 仅在启用本地配置且工作区受信任时读取的项目配置。 |
| `~/.cursor/mcp.json`、`~/.claude/mcp.json` 或 Claude Desktop 配置 | 自动发现的第三方配置，会经过命令、环境变量和请求头检查。 |

`/mcp` 命令用于管理连接和刷新工具缓存。请在对应的配置文件中新增或编辑服务器定义。

## 使用

在 Pi 终端交互界面中：

- `/mcp`：打开交互式 MCP 连接控制面板。
- `/mcp <serverName>`：切换指定服务器的连接状态。

Agent 可以通过代理 `mcp` 工具探索和调用 MCP 工具。

## 安全

Pi 扩展以当前用户的系统权限运行。安装前请审查源代码，并且只配置你信任的服务。

本扩展可以通过 Stdio 启动本地子进程，也可以通过 SSE 或 Streamable HTTP 连接远程端点。请只配置可信的命令和端点。环境变量或请求头中的凭据会直接透传至配置的目标服务器。

## 开发

```sh
git clone https://codeberg.org/huanghui/pi-mcp-kit.git
cd pi-mcp-kit
npm ci
npm run check
npm test
npm pack --dry-run --json
```

## 参与贡献

欢迎通过 [Codeberg](https://codeberg.org/huanghui/pi-mcp-kit) 提交 issue 和范围明确的拉取请求。提交前请运行 `npm run check` 和 `npm test`。

## 许可证

[MIT](LICENSE)