Pi Agent MCP

Pi Agent MCP 是一个本机 MCP Server，让 Claude Code、Codex 等 Agent 可以调用用户已经安装并认证的 Pi Coding Agent，并持续管理多个 Pi 会话。

它解决什么问题

直接使用 Pi 时，用户通常需要自己打开终端、输入任务、等待完成，再把结果复制回当前 Agent。当你希望“让一个 Agent 调用另一个 Agent”时，还会遇到：

• Claude/Codex 不知道如何启动和控制本机 Pi。

• 长任务缺少稳定的后台 task_id，容易阻塞主对话。

• 继续任务时容易新开会话，丢失 Pi 已有上下文。

• 多个 Host 可能同时操作同一个 Pi 会话，导致结果串线。

• Host 重启后，已有 Pi 会话难以查询和恢复。

• Pi 或 Host 异常退出后，任务状态难以准确协调。

本项目把这些能力封装为五个 MCP 工具：

Related MCP server: pi-subagent

典型场景

• Claude Code 负责主流程，把代码审查、错误调查或测试编写交给 Pi。

• 主 Agent 继续处理其他工作，稍后等待 Pi 的最终结果。

• 使用 pi_send 在同一个 Pi 上下文中继续追问。

• Claude Code 与 Codex 共享本机会话状态，同时避免并发写坏同一会话。

• MCP Host 重启后继续查询和恢复已有任务。

工作原理

用户
  ↓
Claude Code / Codex 等 MCP Host
  ↓ MCP
pi-agent-mcp
  ↓ 本机 JSON RPC
Pi Coding Agent：pi --mode rpc
  ↓
模型、文件系统、Shell 和 Pi 工具

pi-agent-mcp 不是新的 AI，也不替代 Pi。它是 MCP 与 Pi RPC 之间的协议适配器，同时负责进程启动、持久会话、后台任务、本地状态、恢复和跨进程并发控制。

完整的安装、配置、Skill 和安全说明见 npm/README.md。

仓库分区

这个仓库明确分为两个区域：

npm/           对外发布的 npm 包工程
development/   本地开发、测试与项目说明

npm/：发布产品

npm/ 可以独立构建和打包，包含：

• MCP Server 源码：npm/src/

• 可选 Agent Skill：npm/skills/pi-agent/SKILL.md

• npm 配置：npm/package.json

• MCP Registry 元数据：npm/server.json

• npm 页面使用的中文 README：npm/README.md

• 许可证：npm/LICENSE

发布包名：

@pathli/pi-agent-mcp

development/：开发环境与项目信息

development/ 不进入 npm 发布包，包含：

• 单元、集成和端到端测试

• fake Pi 等测试夹具

• 本地开发与发布说明

• 项目架构和模块说明

• 开发专用 TypeScript 配置

入口：

• development/README.md

• development/ARCHITECTURE.md

开发命令

首次安装两个独立区域的依赖：

npm ci --prefix npm
npm ci --prefix development

类型检查和测试：

npm run typecheck --prefix npm
npm run typecheck --prefix development
npm test --prefix development

单独构建发布包：

npm run build --prefix npm

生成 npm tarball：

cd npm
npm pack

本地备份

本地迁移备份位于：

.local-backups/

该目录被 Git 忽略，不会提交到 GitHub，也不会进入 npm 包。