ESP Pilot MCP

ESP Pilot MCP 简介

ESP Pilot MCP 是面向 AI 助手的只读 MCP 服务，服务标识为 esp-pilot-mcp，当前版本为 0.5.0。它把 ESP Board Manager 的设备、外设、开发板和 YAML 模板，以及 ADF/GMF 的能力、组件和例程，整理成可查询的目录，供 Cursor、Codex、Claude Code 等客户端在写板级配置或挑选多媒体组件时调用。

地址：

与其它乐鑫 MCP 的分工

ESP Pilot MCP 与其他乐鑫 MCP 搭配使用时，可按下面的职责区分：

ESP Pilot MCP：选 BMGR 设备/外设/开发板，取 YAML 模板，选 ADF/GMF 组件和例程，按需加载 Skills。
Espressif Documentation MCP：检索 ESP-IDF、ESP-ADF、ESP Board Manager 等官方文档。
ESP Component Registry MCP：查找并了解组件仓库中的第三方或官方组件。

多媒体板级适配的常见组合是：ESP Pilot MCP 负责“选什么、YAML 怎么写”，Documentation MCP 负责“API 和文档怎么查”，本地 idf.py bmgr / idf.py build 负责验证。

功能特性

ESP-ADF / ESP-GMF 相关

面向 ESP 多媒体应用开发，提供 ADF/GMF 能力与样例的结构化查询：

能力与组件：按功能和层级浏览 ADF/GMF 能力，获取组件简介、组件注册表、GitHub 和文档链接；部分组件提供独立的 API 文档入口。
应用样例：查询 ADF 多媒体例程，获取例程简介、分类及源码地址，帮助 AI 快速选择合适的参考实现。

ESP Board Manager 相关

面向 ESP Board Manager 的板级硬件配置，帮助 AI 根据硬件信息生成和完善板级 YAML：

设备与外设：查询可用设备、外设及其配置方式。
板级配置：查询板卡签名、SoC 与硬件资源等信息。
配置文档：按章节获取 Board Manager 配置文档，提供可直接参考、用于填写 YAML 的字段说明和模板。

动态加载 Skill

可通过 catalog_get_skill 按需加载 board-manager-create-board、board-manager-use 和 esp-hardware-app-platform-workflow 以及后续其他 ADF/GMF 组件相关的 Skills。

它不替代官方文档检索。README、API 和例程源码仍走 Espressif Documentation MCP，或按返回的 github_url / api_docs_url 阅读。

接入方式

Cursor ~/.cursor/mcp.json：

{
    "mcpServers": {
        "esp-pilot-mcp": {
            "url": "https://mcp.esp-pilot.espressif.com/mcp"
        }
    }
}

Codex：

codex mcp add esp-pilot-mcp --url "https://mcp.esp-pilot.espressif.com/mcp"

Claude Code：

claude mcp add --transport http "esp-pilot-mcp" "https://mcp.esp-pilot.espressif.com/mcp"

工具

BMGR 工具：

catalog_list_bmgr_devices：列设备，可按 type、接口、芯片、IDF 版本过滤。
catalog_list_bmgr_peripherals：列外设，可按 type、role、format、芯片、IDF 版本过滤。
catalog_list_bmgr_boards：列开发板签名。
catalog_list_socs：列 SoC 与可用 IDF profile。
catalog_get_bmgr_doc：按章节取 RST。先 section=overview，选定模式后再取 min_config 或 full_fields；调试/代码/板级参考/API 等剩余小节用 section=heading。

ADF/GMF 工具：

catalog_list_adf_gmf_capabilities：列能力，返回 name / layer / category / 首段 summary。
catalog_get_adf_gmf_capability：取功能清单或剩余介绍，以及 registry / github_url / docs_url / 可选 api_docs_url。
catalog_list_adf_gmf_scenarios：列 ADF 多媒体例程（名称、分类、简介、GitHub URL）。没有对应的 get 工具，源码直接打开 github_url。

其它：

catalog_list_skills / catalog_get_skill：列或读取三个 vendored skill。catalog_get_skill 不传 resources 时返回 SKILL.md 和子文件清单；传入 resources 再取对应原文。
server_info：当前加载产物的来源元数据，可用来核对 catalog 生成时间。

在开发流程中解决的问题

ESP Pilot MCP 不负责生成代码或执行构建，但能在开发前和开发过程中为 AI 助手提供可核对的目录、模板和工作流。以多媒体应用为例，可按下面的方式使用：

配置开发板：先按芯片、设备类型和接口查询可用的设备、外设及现有开发板；再通过 catalog_get_bmgr_doc 获取对应模式的最小 YAML 配置或完整字段说明。AI 助手据此填写 board_devices.yaml 和 board_peripherals.yaml，而不是凭记忆猜字段名、枚举值或接口组合。IO、地址和时序仍须以原理图和器件资料为准。
开始编写工程前查找可复用实现：按播放、录音、显示等需求查询 ADF/GMF 的能力、组件和例程，取得其分类、简介以及仓库和文档链接。这样可以先确认已有组件或示例是否覆盖需求，再决定复用、组合还是自行实现，避免重复实现已有能力。
按阶段推进开发工作：需要从硬件适配推进到应用开发时，可按需加载 esp-hardware-app-platform-workflow。该 skill 把需求确认、硬件信息核对、板级 YAML、ADF/GMF 应用设计与编写、构建验证和评审串成分阶段流程，明确每一步应查询什么、修改什么和如何验证。
定位配置问题：Board Manager 生成或构建失败时，可回查 catalog 中的字段说明、约束和对应 skill，确认 YAML 的模式、外设依赖和配置项；实际生成和构建仍由本地 idf.py bmgr 与 idf.py build 完成。

因此，ESP Pilot MCP 主要解决的是开发决策前的信息不完整和信息不准确问题：

设备、外设、YAML 字段、组件和例程信息来自当前 catalog，可按芯片过滤。
板级配置有与设备模式对应的模板和字段说明，组件与例程有仓库、文档入口可供继续核对。
建板、接入工程，以及从硬件到应用的衔接可以按 task 选择相应 skill，减少遗漏关键确认和验证步骤的情况。

Skills

三个 skill 随 catalog 发布，由 catalog_get_skill 按需加载，不要整包预读：

board-manager-create-board：从原理图 / BOM / 引脚表，或从已有 BSP 源码编写 BMGR 板定义。验证用 idf.py bmgr -b，不走 -n 脚手架。
board-manager-use：在已有工程里接入已存在的 BMGR 板：加依赖、选板、生成、取句柄、小改动用 amend、按阶段排查。不负责从零建板。
esp-hardware-app-platform-workflow：从需求确认、硬件取证、板级 YAML，到 ADF/GMF 应用设计、编写、validation 和评审的端到端入口。

注意事项

公网 catalog 随部署更新，可能略落后于 ESP Board Manager、ESP-GMF、ESP-ADF 文档源。可用 server_info 查看 generated_at。
catalog_get_bmgr_doc 返回的是配方和字段说明，不是完整驱动实现。stock 设备的 init 仍由 BMGR 生成，不要在 setup_device.c 里重写。
同一逻辑 audio_codec 设备不可同时启用 adc_enabled 与 dac_enabled。全双工要拆成两个单向设备。这类约束写在 overview 里，需要先取文档切块再写 YAML。