$ cat ~/map/pi-mcp.md

pi-mcp

一个托管 pi agent 的 MCP 服务端：RPC 驱动、沙盒隔离、热恢复与 agent 链式调用。

tools✓ 11月2日

先 uv sync --extra dev，再在设置 PI_MCP_DB、PI_MCP_AGENTS_DIR 与 PI_MCP_ACCESS_TOKEN 后启动：uv run pi-mcp（默认 stdio 传输；HTTP 加 --transport streamable-http --host 0.0.0.0 --port 8000）。run 工具要求宿主机装有 pi 与 bubblewrap。

## 速览

一个用 Python 写的 MCP 服务端，经 pi 的 RPC 模式运行并托管 pi 编码 agent：bubblewrap 隔离的 pi 进程在回合之间保持存活，MCP 客户端用 run、send_message、resurrect 等工具启动、驱动、rip 并复活 agent，链式 agent 经划定的子挂载与每 agent 令牌回调。

## 要点

• $让 pi --mode rpc 进程在回合之间保持存活（热恢复）；显式 resurrect 按保存的 provider、model、context_size、挂载规则、令牌组与回调目标，从会话文件冷恢复已 rip 或已退出的 agent，这些属性均不可覆盖。
• $agent 是 bubblewrap 隔离的 pi 进程：SQLite 存储状态、规范化挂载、空闲保活，外加 rips、retries、self_exits 三个生命周期计数。
• $十二个 MCP 工具覆盖完整生命周期：list、get_info、run、rip、resurrect、send_message、remove、grep、list_tmp、grep_tmp、read_tmp，以及读取 stdout 或 errors 日志的 read。
• $每个 agent 一个公开状态：active（回合运行中）、idle（存活且已落定）、ripped（显式停止，会话可恢复）、exited（自行退出，会话可恢复）；后台刷新线程按可配置间隔巡检存活 agent。
• $每 agent 上下文预算：run(context_size=...) 最低 20,000 token，写入私有 pi-agent/models.json，其窗口为 context_size 加预留量，使 pi 的自动压缩在预计上下文溢出前触发。
• $链式 agent 收到 AGENT_ID，可用 callback_agent_id 启动子 agent，并得到生成的 /tmp/pi-agent/mcp.json，指向带每 agent bearer 令牌的回环端点；子挂载收窄到父级授权范围内，校验可传递，无需逐级回溯。
• $工件存于 PI_MCP_AGENTS_DIR 之下：stdout.log、errors.log、agent_session.jsonl，以及绑定到容器内 /tmp 的 tmp/ 目录；读取与列举路径都限定在该 tmp/ 内，目录穿越或符号链接逃逸一律拒绝。
• $主传输的按请求 HTTP 鉴权尚未实现——传输进程绑定一个 PI_MCP_ACCESS_TOKEN；为子 agent 铸造的令牌权限为 0600，不经任何工具返回、不写入 SQLite，并在 agent 退出、rip 或移除时吊销。

## 常见问题

## 参考链接

• README（设计、工具参考、链式调用、上下文预算） ↗
• 设计文档（MCP 面、RPC 生命周期、持久化、安全） ↗

最后更新: 2026年11月1日