pi-cli-mcp

MCP 服务器，将编码任务委托给你本地安装的 pi CLI。

它包装了真正的 pi 二进制文件，而不是捆绑自己的代理副本，因此每次调用都会继承 你的 ~/.pi/agent/settings.json —— 提供商、模型、思考级别、扩展、AGENTS.md / CLAUDE.md 发现。这里不会重复你的模型栈的任何内容，并且当你升级 pi 时服务器不会漂移。

当你的主代理（Claude Code、Cursor 或任何 MCP 客户端）应该将工作交给 pi 时使用它：来自不同模型的第二意见、你想保留在主上下文窗口之外的调查，或并行工作。

安装

npx -y pi-cli-mcp            # no install
npm install -g pi-cli-mcp    # or global

需要 Node ≥ 20 和 PATH 上可用的 pi（npm i -g @earendil-works/pi-coding-agent）。

Claude Code

claude mcp add-json pi -s user '{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "pi-cli-mcp"],
  "timeout": 3600000
}'
claude mcp list | grep '^pi:'      # expect: ✔ Connected

慷慨的 timeout 很重要：一个真正的委托任务可能运行数分钟。

任何其他 MCP 客户端

{
  "mcpServers": {
    "pi": { "command": "npx", "args": ["-y", "pi-cli-mcp"] }
  }
}

保持服务器名称简短（pi）：它会成为你的模型看到的工具名称的一部分。

工具

pi

pi({
  prompt: "Map how retries are wired in src/http.rs. Report call sites only.",
  cwd: "/abs/path/to/repo",
  tools: "read,grep,find,ls"
})

pi 没有权限系统。 使用其默认工具时，它会以你的用户身份在 cwd 内编辑文件和运行 shell 命令。只要任务是分析，就传递 tools 或 no_tools。如果你想要沙箱，请使用 PI_MCP_WRAP。

返回内容

仅返回 pi 的最终答案和汇总统计信息 —— 绝不返回转录、工具参数或工具输出：

[session: 0927adc5-a840-4b68-93ca-5ca344c9fafb]

Created note.md containing "hello" and updated target.txt to read "new content".

---
pi: bifrost/minimax/MiniMax-M3 · 5 turns · 4 tool calls: bash, read, write, edit · 11k in / 276 out · 9.8s
pi wrote: note.md, target.txt

• “最终答案”由 stopReason 定义，而不是由位置定义：最后一条已定稿的助手消息 —— 最后一条 stopReason 不是 toolUse 的消息，这是 pi 标记工具调用步骤的方式。即使前言与工具调用共享一条消息，中途的叙述也会被丢弃。如果已定稿的消息没有文本，则报告为运行失败，而不是静默回退到更早的前言。如果根本没有定稿，则返回最后产生的文本，并标注为如此。

• 答案永远不会被截断。 如果你想设置上限，请设置 PI_MCP_MAX_OUTPUT。只有诊断信息有界。

• pi wrote: 仅在 pi 实际写入文件时出现，因此它兼作副作用检查。

• 错误的 stopReason 会使调用失败，采用失败关闭。 stop / length 是成功；error、aborted、缺少 stopReason 以及已知词汇表之外的任何内容都会报告为错误，并附上答案。被验证的 stopReason 属于正在返回的消息，而不是最后到达的事件。pi 可能在未干净定稿的轮次上以退出码 0 退出，因此不能仅信任退出码。

• 原始 stdout 永远不会作为答案返回。 如果事件流不符合预期契约，响应会说明这一点，并描述到达内容的形状（消息数、stopReason 值、工具调用数、字节数）—— 绝不返回转录本身，那会泄露叙述、工具参数和工具结果。

会话

pi 返回一个会话 id；pi_reply 继续它。对话存在于 pi 自己的会话文件中，因此后续操作在此服务器重启后仍然有效 —— 会话 → 目录映射持久化在 ~/.local/state/pi-mcp/sessions.json 中。

对同一会话的并发回复会被串行化：两个 pi 进程写入同一个会话文件会损坏它。如果 id 未知，pi 会开始一个新的对话，答案会带有明确的 [warning: no existing session …]，而不是假装继续。

跨进程注意事项。 会话互斥锁是进程本地的。如果你运行两个 MCP 客户端连接两个服务器进程，并且两者同时回复同一个会话 id，则没有任何东西会串行化它们。状态文件采用重新读取后合并的方式写入，因此一个进程学到的会话不会被另一个进程擦除，但底层的 pi 会话文件没有这种保护。实际上，一个客户端拥有一个会话；如果你需要硬保证，请保持一个服务器进程。

取消

MCP notifications/cancelled 会用 SIGTERM 终止 pi，在宽限期后升级为 SIGKILL。子进程也会随之终止：pi 在自己的进程组中运行，整个树都会被发送信号，因此即使 pi 未能转发信号，被中断的 sleep 120 也不会存活。

取消会在调用排队等待并发槽或会话锁之前注册，因此仍在等待时被取消的调用根本不会启动 pi。

关闭 —— stdin EOF、SIGTERM、SIGINT、SIGHUP 或关闭的 stdout —— 会在退出前收割所有正在运行的 pi 树。分离的子进程没有其他父进程来清理它们。

环境

设计

• 每次调用一个进程。 pi 自己的会话文件是事实来源，这就是后续操作在此服务器重启后仍然有效的原因。

• pi -p --mode json。 json 事件流产生轮次、工具调用、令牌使用量和成本 —— 无需抓取人类可读的输出。

• 无依赖。 直接使用换行分隔的 JSON-RPC 2.0，因此没有需要保持同步的 SDK，除了一个文件外无需审计任何内容。

• 长提示或破折号开头的提示 作为 @file 附件传递，因为 pi 没有 -- 分隔符，并且 argv 有操作系统大小限制。

为什么不用替代方案

pandysp/pi-mcp-server 依赖 @mariozechner/pi-coding-agent@^0.52.9 —— 这是 pi 之前包名下的旧分支 —— 因此它运行的是捆绑的旧得多的代理副本，而不是你的 CLI，并且只知道固定的提供商列表。生态系统中的其他一切（pi-mcp-adapter、pi-mcp-extension 及分支）都运行在相反方向：MCP 服务器进入 pi。pi 本身没有原生的 mcp-server 子命令。

测试

npm test

该套件通过 stdio 驱动真实服务器，并使用假的 pi 二进制文件来覆盖实时模型无法按需产生的路径（错误的 stopReason、过大的答案、取消），因此它不需要 API 访问，也不花费令牌。

许可证

MIT