McuBuddy

McuBuddy — AI 驱动的 MCU 和嵌入式固件调试 MCP 服务

语言： English | 中文

将 AI 从固件分析扩展到真实 MCU，在经过验证的环境中打通诊断、代码修改、构建、烧录和验证的闭环。

McuBuddy 是一款用于 MCU 板级调试的 Model Context Protocol (MCP) 服务。 它将调试探针、Keil MDK 项目、ELF/DWARF 符号、 CPU 和内存状态、SVD 外设寄存器、UART/RTT 日志、FreeRTOS 状态、Flash 操作 以及 GDB 服务端封装为结构化工具，供 AI 助手调用。

它专为固件开发、开发板初次启动、故障隔离、调试自动化 和 AI 辅助验证而设计。

McuBuddy 在 default 工具集内提供 19 个稳定工具。使用 MCUBUDDY_TOOLSETS=probe,diagnose 仅添加工作流所需的领域 （可用领域：probe、diagnose、 build_flash、rtos、logs 和 experimental）。core 是唯一的配置档； 启动时的工具集选择明确且不可变。

重要

自动化不能替代工程责任。目标和验收标准、接线与供电安全、高风险操作审批、代码审查以及新环境验证仍由人类负责。电机、继电器及其他安全相关设备还需要恢复计划和独立保护措施。

快速链接： 快速入门 · 项目指南 · 工具参考 · 支持矩阵

✨ 主要功能

• 真实硬件调试：发现并连接 ST-Link、J-Link、CMSIS-DAP 和其他 调试探针；控制目标执行；检查寄存器、内存、断点和观察点。
• Keil 项目工作流：发现 .uvprojx / .uvproj 文件，选择目标，通过 UV4.exe 调用 Keil MDK 进行构建或下载，并将生成的 AXF/ELF 用于调试。
• 源代码级故障诊断：调查 HardFault、启动失败、栈溢出和内存损坏时，利用 ELF/DWARF 数据将地址解析为函数、源代码 行、本地变量和调用栈。
• 外设与 RTOS 检查：通过 CMSIS-SVD 解码外设寄存器，并检查 FreeRTOS 任务、任务上下文和栈使用情况。
• 日志与运行时可观测性：读取 UART、RTT 和选定的 J-Link SWO 日志，并管理 pyOCD/J-Link GDB 服务端的生命周期。
• 基于证据的结果：返回结构化的目标、状态和验证证据，让 AI 能继续调查，而非仅凭症状猜测代码修改。
• 可执行的硬件边界：区分 MCU 限制、不适用于固件的工具、配置问题、工具故障和证据不足，并说明影响和下一步安全检查，避免将不受支持的路径误判为固件缺陷。

🏗️ 工作原理

flowchart LR
    AI["AI Client<br/>Codex / Claude Code"] --> MCP["McuBuddy<br/>MCP Server"]
    MCP --> EB["Execution Boundary<br/>Serialized Session"]
    EB --> TOOLS["Debugging Tools<br/>Diagnostics / Symbols / SVD / RTOS / Logs"]
    TOOLS --> KEIL["Keil MDK / UV4.exe<br/>Build / Optional Download"]
    TOOLS --> PROBE["Probe Backends<br/>pyOCD / J-Link / probe-rs"]
    KEIL --> IMAGE["AXF / ELF / HEX / BIN"]
    IMAGE --> TOOLS
    PROBE --> BOARD["Real MCU Board"]

MCP 并不是调用 Keil 的协议。AI 通过 MCP 调用 McuBuddy；随后，McuBuddy 会根据需要，通过 UV4.exe、pyOCD、J-Link 或其他内部后端使用 Keil MDK。

🚀 快速入门

1. 前置条件

基本要求：

• Python 3.10 或更高版本；
• 已供电的 MCU 开发板；
• 已正确连接的 ST-Link、J-Link 或 CMSIS-DAP 调试探针；
• 目标芯片名称；
• 最好准备包含调试信息的 ELF/AXF 映像。

Keil 构建和下载功能需要安装了 Keil MDK 的 Windows。McuBuddy 通过 UV4.exe 调用 µVision，包括 Keil MDK v5 安装版本。

2. 安装

pip install "McuBuddy @ git+https://github.com/cunjun/McuBuddy.git"

这会为所有本地固件项目安装一次 McuBuddy。请勿将 McuBuddy 仓库克隆或复制到每个目标项目中。McuBuddy 是仅限本地使用的 MCP 后端：客户端会为每个连接启动一个 stdio 进程，McuBuddy 不会公开 HTTP、SSE、WebSocket 或其他 MCP 网络监听器。

目标项目、Keil 安装、ELF/SVD 文件、探针和串口必须能被运行 McuBuddy 的机器直接访问。要更新，请从官方仓库 https://github.com/cunjun/McuBuddy 重新安装；McuBuddy 绝不会自动检查、下载或安装更新。

使用 J-Link Python 后端时，请安装可选依赖：

pip install "McuBuddy[jlink]"

从源代码进行开发：

git clone https://github.com/cunjun/McuBuddy.git
cd McuBuddy
pip install -e ".[dev]"

3. 配置 MCP 客户端

{
  "mcpServers": {
    "McuBuddy": {
      "command": "McuBuddy",
      "args": []
    }
  }
}

对于 Windows 源代码检出，请明确配置虚拟环境中的 Python 可执行文件和 工作目录。请参阅安装和首次连接， 然后重启 AI 客户端。

4. 运行首次只读检查

连接探针并为开发板供电后，告诉 AI：

Use McuBuddy to inspect the current debugging environment, discover connected probes,
and perform a first read-only check of the board without writing Flash.
Before starting, tell me what information is still missing.

建议按以下顺序操作：先检查环境和目标，然后配置探针并读取最少的目标状态：

doctor()
list_connected_probes()
match_chip_name("py32f030x8")
configure_probe(target="py32f030x8", backend="pyocd")
probe_connect(target="py32f030x8")
read_stopped_context()

默认 core 配置中提供 probe_connect 和 read_stopped_context。读取稳定的停止状态上下文可能会暂停目标，因此仍会改变执行状态。如果设备绝不能暂停，请指示 AI 仅执行非侵入式的探针和环境检查。

💬 自动化调试示例

Use McuBuddy to debug <project path>. The MCU is <exact model>, and the probe is
<ST-Link/J-Link/CMSIS-DAP>. First collect board-level evidence and locate the problem. After
authorization, modify the code, build and flash it, then validate the result on the real board.

关于证据优先的决策顺序和常见场景，请参阅 常见调试工作流。

🧰 后端和硬件验证

路径	当前角色	主要功能
pyOCD + ST-Link/CMSIS-DAP	主要后端	控制、内存、Flash、源码调试、RTT、RTOS 和 GDB 服务器
J-Link	主要后端	控制、内存、Flash、源码调试、原生 RTT、DWT 和 GDB 服务器
probe-rs sidecar	扩展预览	ARM/RISC-V/Xtensa 发现、可配置的核心控制、寄存器、内存、硬件断点、Flash 和 RTT
Keil MDK（Windows，通过 UV4.exe）	构建/下载后端	项目发现、目标配置、构建、日志和可选下载；支持 MDK v5 安装

主要验证范围包括：

• STM32L496VETx + ST-Link / pyOCD；
• STM32F103C8 + J-Link；
• 内置的 STM32F103ZE 和 PY32F030X8 目标预检配置。

“代码中已实现”并不意味着“已在每块开发板上验证”。请以 支持矩阵和 list_validation_records() 为准。

🛡️ 安全模型

McuBuddy 通过 list_tool_safety() 提供机器可读的安全分类。

类别	示例	默认要求
只读	目标匹配、寄存器／内存读取、符号解析、日志、诊断	无需确认
执行状态变更	halt、resume、reset、continue、单步执行	不会写入 Flash，但会改变执行状态
运行时状态写入	内存／寄存器写入、断点、观察点、SVD 字段写入	需要明确确认
持久性破坏操作	Flash 擦除／编程、Keil 固件下载	需要明确确认
主机进程	Keil 构建、GDB 服务启动／停止	启动或停止本地进程

安全原则：

1. 对于未知目标，应先匹配芯片和探针；不要猜测地址。
2. 在暂停、复位或写入之前，先读取证据。
3. 执行 Flash 操作前，确认目标、范围、映像和恢复方法。
4. 对于电机、继电器、电源开关和其他执行器，优先使用断点和低能量测试。
5. 使用 uart_send_with_cleanup 发送执行器命令，然后在给出最终结论前调用 finish_debug_session。作为后备措施，服务关闭时会重复执行相同的幂等清理操作。

🔒 会话与并发

• 共享探针、Keil、ELF／SVD、日志和运行时配置的操作，会在同一 Session 内串行执行。
• 控制互不相关的开发板时，不同会话可以并行运行。
• 目标匹配和工具安全信息等无状态查询，可以与会话操作并行执行。
• 取消操作无法强制终止已进入同步 SDK 的调用。服务会等待工作线程完成后，才释放会话锁。

这样可以防止一个请求在另一个探针操作仍在运行时切换后端、断开探针或更改共享状态。

📦 mcubuddy Skill

仓库包含 skills/mcubuddy，可引导 Codex 和 Claude Code 按照“先取证，再判断”的顺序使用这些工具，而不是将 MCP 工具当作无序的命令列表。

Skill 是可选的工作流增强功能，并非硬件调试的前提条件。正确安装并配置的本地 McuBuddy MCP 服务，即使没有 Skill 也可以正常使用。

已安装的发行版会包含 Skill。无需克隆仓库，即可注册持久化的 Codex 集成：

uv tool install McuBuddy
McuBuddy setup codex --confirm --json

为 Codex 安装：

python .\skills\mcubuddy\scripts\install_skill.py --target codex --overwrite

为 Claude Code 安装：

python .\skills\mcubuddy\scripts\install_skill.py --target cc --overwrite

安装后，请重启客户端或开启新会话。有关源码检出恢复、安装注册和使用边界的详情，请参阅 《McuBuddy、MCP 与 Skill 之间的边界》。

⚠️ 当前限制

• Keil 构建和下载目前需要安装 Keil MDK 的 Windows 系统，并通过 UV4.exe 调用 µVision，包括 MDK v5 安装。
• probe-rs 辅助程序支持 Flash 和 RTT，但仍需针对具体目标在真实开发板上进行验证，且目前尚无官方二进制发行版。
• RTOS 检查依赖 FreeRTOS 符号，以及与目标固件匹配的 ELF／AXF。
• 并非每种芯片都会自动附带 SVD 文件，通常需要从 CMSIS-Pack 或芯片供应商处获取。
• SWO 文本捕获取决于芯片配置、探针功能、引脚复用和开发板接线。
• 设备补丁和连接策略仍是轻量级机制，而非完整的开发板插件系统。

📚 文档

• 完整的项目概览和工作流：项目指南
• 中文项目概览：项目指南
• 完整的工具索引：工具参考
• 中文工具用法：MCP 工具中文参考
• 后端和硬件验证：支持矩阵
• 项目设计：架构
• 发布历史：更新日志

🧪 本地开发

pip install -e ".[dev]"
pytest
ruff check src tests

有关仓库布局和文档维护责任，请参阅项目指南。

🙏 上游项目与致谢

McuBuddy 基于 SolarWang233/mcudbg， 在其 MIT 许可作品的基础上，进一步扩展了架构、安全边界、证据工作流、后端支持和文档。原始版权声明保留在 LICENSE 中，来源详情见 NOTICE。

📄 许可证

本项目基于 MIT 许可证授权。详情请参阅 LICENSE。

---

如果 McuBuddy 对你的 MCU 调试工作流有所帮助，欢迎为项目点亮 Star。 如有建议，请提交 Issue 或发送邮件至 [email protected]。