pi-mcp-kit

English

为 Pi 打造的轻量级模型上下文协议 (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 服务器

安装

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 连接远程端点。请只配置可信的命令和端点。环境变量或请求头中的凭据会直接透传至配置的目标服务器。

开发

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 提交 issue 和范围明确的拉取请求。提交前请运行 npm run check 和 npm test。

许可证

MIT