nicobailon/pi-mcp-adapter

Pi MCP Adapter – 它是什么

用途 – 此适配器让 Pi 编码助手（一个由 LLM 驱动的 AI 代理）能与 MCP 服务器通信，而无需将每个服务器的工具定义加载到模型上下文。它只在模型实际调用某个工具时启动服务器，在短暂闲置后停止，并缓存工具元数据。结果是减少“膨胀”所花费的 token、降低内存使用量，并加快会话速度。

运作方式

• Pi 看到一个名为 mcp 的单一代理工具（约 200 个 token）。当模型运行 mcp({search:…}) 或 mcp({tool:…}) 时，适配器会将请求转发到适当的 MCP 服务器。
• 服务器是惰性的：它们在首次使用时启动，并在 10 分钟不活动后关闭（可配置）。
• 工具列表会缓存在磁盘上，因此模型可以在服务器未运行时搜索或描述工具。
• OAuth token 默认存储在 OS 钥匙串中，而非纯文本 JSON 文件。
• 可选的脚本模式让您可以在一个请求中批量处理多个调用，比照 Pi 内置的 codemode 行为。

相较于 Pi 内置 MCP 支持的主要优势

功能	Pi 内置 MCP	pi-mcp-adapter
会话开始时启动的服务器	所有启用的服务器（高内存）	仅实际使用的服务器（内存低得多）
单次查询的 token 成本	较高（完整 codemode 脚本）	减少 10-33%
语义工具搜索	仅文字	文字或正则表达式；使用 System One 密钥可按意义排名
OAuth token 存储	纯文本 JSON 文件	OS 钥匙串
UI 支持	无	原生窗口或浏览器 UI
从其他 IDE 导入配置	手动转换	引导式导入（/mcp-adapter setup）

典型工作流程

1. 安装适配器：pi install npm:pi-mcp-adapter 并重启 Pi。
2. 将服务器（例如 Chrome DevTools）添加到 .mcp.json 文件，或运行 /mcp-adapter setup 导入现有配置。
3. 在 Pi 聊天中调用：

   mcp({ search: "screenshot" })
   

   适配器会返回匹配的工具描述。
4. 执行工具：

   mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })
   

   服务器启动、运行命令，然后闲置并在 10 分钟后关闭。

主要命令（在 Pi 会话内运行）

• /mcp-adapter – 打开交互式设置/入门面板。
• /mcp-adapter setup – 引导式导入 Cursor/Claude/VS Code 配置，添加预设服务器（Figma、GitHub 等）。
• /mcp-auth <server> – 服务器的 OAuth 登录。
• /mcp-adapter edit [project|global] – 编辑 .mcp.json 或全局配置。
• /mcp-adapter tools – 列出所有发现的工具。
• /mcp-adapter reconnect … – 手动重新连接服务器。

限制

• 每个 Pi 会话会生成自己的服务器进程（可通过 rmcp-mux 共享）。
• 内嵌图片仍依赖 Pi 的显示设置。
• MCP 采样仅支持文本；音频/图像负载会被拒绝。

文档 – 完整参考位于 docs/ 文件夹（配置、服务器选项、认证、脚本、UI、扩展 API 等）。