Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Pi

Why this agent

Pi(作者 Mario Zechner; pi.dev)是一个极简的、激进可扩展的终端编程框架, 支持树状会话和自定义 provider。Oh My Pi 就是从 Pi 派生出去的。

Pi 对 MCP 的态度是有明确立场的:Mario 主动选择不把 MCP 放进 Pi 核心。上游 packages/coding-agent/README.md 原文写着:

No MCP. Build CLI tools with READMEs (see Skills), or build an extension that adds MCP support. Why?

(中文意译:不做 MCP。 要么用 README 写命令行工具(见 Skills), 要么写个扩展加 MCP 支持。)

espctl 仍然能驱动 Pi —— 只是不走本手册其他客户端用的 install:// MCP 路径。

Prerequisites

  • 已安装 Pi(npx -y @earendil-works/pi-coding-agent@latest,或按 https://pi.dev 的官方安装文档)。
  • 下面四条 alternative 路径之一(espctl skill、MCP 扩展、或 human-in-the-loop 委托)。

Install snippet (or alternative)

Pi 在 本套 MCP 覆盖中是 documented-stub,而且是 上游设计 使然 —— 不是“还没核实“。Pi 没有 server 配置文件入口,因为它的 设计哲学就明确拒绝把 MCP 当成核心抽象(Mario 的那篇博文解释了 “如果你不需要 MCP 怎么办“的论点)。

Pi 风格的、接入 espctl 的路径:

  1. 走 Skill —— 在 ~/.pi/agent/skills/espctl/ 下写一个 espctl skill(一个文件夹 + SKILL.md + 辅助脚本),直接 shell 出去调 espctl build、espctl flash 等。这是 Pi 原生模式;见 Pi 的 Skills 文档。

  2. 写 MCP-bridge 扩展 —— 在 ~/.pi/agent/extensions/mcp-bridge/ 下写一个 TypeScript 扩展,注册一个连 本套 MCP 的 MCP 客户端。 上游 README 明确把 “MCP server integration” 列为合法的扩展用例 (第 368 行)。Pi 目前没有自带这种扩展;你写的会是第一个。

  3. 走浏览器侧 HTTP MCP 端点 —— 用 Pi 内置的 bash 工具 + curl 直接调 https://esphome.cloud/mcp/esp-idf。糙是糙了点,但不需要任何 扩展或 skill。

  4. Human-in-the-loop 委托 —— 用 Pi 做编辑/重构,把具体的固件 操作委托给已经接通 本套 MCP(通过 install://claude-code 或 同类)的 Claude Code / Cursor / Codex CLI / Crush 会话。

对大多数用户,路径 4 最简单。路径 1 是 Pi 原生的“正解“, 适合你想长期接好 espctl 又不愿意为此引入 MCP。

First-run verification

走路径 1–3 时,验证 alternative 端点可达:

curl -fsSL https://esphome.cloud/mcp/esp-idf | head -1

预期:200 OK JSON 响应。

走路径 4 时,验证走你委托过去的编程 agent 会话(见 Claude Code 等)。

Troubleshooting

  • mcp/esp-idf 返回 404 / 5xx —— 看 esphome.cloud 状态。
  • 想要验证过的 install 片段? Pi 的“no MCP“立场是上游的设计 选择。Pi 里接 espctl 的办法是写一个 skill 或扩展 —— 本套 MCP 这边今天都不提供。如果 pi-mono 项目以后改变了对 MCP 的立场, 这一页就会翻面。跟踪 badlogic/pi-mono。
  • 和 Oh My Pi 的关系 —— Oh My Pi(Pi 的 fork)加上了 .claude/... 配置继承来支持 MCP。如果你想要在 Pi 派生的 shell 里开箱即用的 espctl 支持,用 Oh My Pi。

Tested as-of 2026-05-19

Pi 特有注意事项

  • Pi 文档区分三种扩展点:Skills(命令行工具风格;只要写一个 文件夹 + SKILL.md)、Extensions(TypeScript 代码,能用完整 的 Pi API)、Pi Packages(npm / git 分发包装层)。
  • “给 Pi 写第一个 MCP 扩展“会是一个有意义的社区贡献,如果 Pi 生态后来对 MCP 有了兴趣。这不在 本套 MCP 的路线图上。