内容
# McuBuddy — AI赋能的MCU和嵌入式固件调试MCP服务器
<!-- mcp-name: io.github.cunjun/mcubuddy -->
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
**语言：** [English](README.md) | [中文](README_zh.md)
**让AI不仅仅分析固件代码：连接真实的MCU，操作调试工具，收集板级证据。**
`McuBuddy`是一个[模型上下文协议（MCP）](https://modelcontextprotocol.io/)服务器，用于MCU板级调试。它将调试探针、Keil MDK项目、ELF/DWARF符号、CPU和内存状态、SVD外设寄存器、UART/RTT日志、FreeRTOS状态、Flash操作和GDB服务器作为结构化工具暴露给AI助手。
它旨在用于固件开发、板级启动、故障隔离、调试自动化和AI辅助验证。
> [!IMPORTANT]
> 该项目仍处于Alpha阶段。人类仍然负责目标、接线和风险决策；AI调用工具，组织证据，推动调试过程。在重置、执行控制、内存写入或Flash操作之前，请确认目标、影响和恢复计划。
**文档：** [快速入门](docs/quickstart.md) ·
[工具参考](docs/tool-reference.md) ·
[支持矩阵](docs/support-matrix.md) ·
[架构](docs/architecture.md)
## ✨ 主要功能
- **真实硬件调试**：发现和连接ST-Link、J-Link、CMSIS-DAP等探针；控制目标执行；检查寄存器、内存、断点和观察点。
- **Keil项目工作流**：发现`.uvprojx` / `.uvproj`文件，选择目标，调用UV4构建或下载，并将生成的AXF/ELF馈入调试工作流。
- **源级故障诊断**：使用ELF/DWARF数据将地址解析为函数、源代码行、局部变量和调用栈，适用于HardFault、启动失败、堆栈溢出和内存损坏的调查。
- **外设和RTOS检查**：通过CMSIS-SVD解码外设寄存器，并检查FreeRTOS任务、任务上下文和堆栈使用情况。
- **日志和运行时可观察性**：读取UART、RTT和选定的J-Link SWO日志，并管理pyOCD/J-Link GDB服务器生命周期。
- **安全边界**：将工具分类为只读、执行更改、运行时写入或持久破坏，并对高风险操作进行显式确认。
- **基于证据的结果**：返回结构化的目标、状态和验证证据，以便AI可以继续调查，而不是仅根据症状猜测代码更改。
## 🏗️ 工作原理
```mermaid
flowchart LR
AI["AI客户端<br/>Codex / Claude Code"] --> MCP["McuBuddy<br/>MCP服务器"]
MCP --> EB["执行边界<br/>序列化会话"]
EB --> TOOLS["调试工具<br/>诊断 / 符号 / SVD / RTOS / 日志"]
TOOLS --> KEIL["Keil UV4<br/>构建 / 可选下载"]
TOOLS --> PROBE["探针后端<br/>pyOCD / J-Link / probe-rs"]
KEIL --> IMAGE["AXF / ELF / HEX / BIN"]
IMAGE --> TOOLS
PROBE --> BOARD["真实MCU板"]
```
| 组件 | 责任 |
| --- | --- |
| AI客户端（如Codex和Claude Code） | 理解问题，选择工具，解释结果，并提出下一步检查 |
| MCP | AI客户端和`McuBuddy`之间的标准工具调用协议 |
| `McuBuddy` | 管理调试会话，调用后端，强制执行安全检查，并返回结构化结果 |
| Keil MDK / UV4 | 构建和链接Keil项目，可选配置固件下载 |
| pyOCD、J-Link和实验性probe-rs | 连接到探针并访问目标寄存器、内存、断点和Flash |
| ELF/AXF、DWARF和SVD | 提供符号、源代码位置、变量、调用栈和外设寄存器语义 |
MCP不是用于调用Keil的协议。AI通过MCP调用`McuBuddy`；`McuBuddy`然后根据任务需要使用Keil UV4、pyOCD、J-Link或其他内部后端。
## 🚀 快速入门
### 1. 先决条件
基本要求：
- Python 3.10或更高版本；
- 一个带电源的MCU开发板；
- 一个正确连接的ST-Link、J-Link或CMSIS-DAP探针；
- 目标芯片名称；
- 优选地，包含调试信息的ELF/AXF镜像。
仅在Keil构建或下载功能需要时，才需要Windows和已安装的Keil MDK / UV4。
### 2. 安装
```bash
pip install McuBuddy
```
安装J-Link Python后端时，安装可选依赖：
```bash
pip install "McuBuddy[jlink]"
```
从源代码进行开发：
```bash
git clone https://github.com/cunjun/McuBuddy.git
cd McuBuddy
pip install -e ".[dev]"
```
### 3. 配置MCP客户端
```json
{
"mcpServers": {
"McuBuddy": {
"command": "python",
"args": ["-m", "McuBuddy"]
}
}
}
```
对于Windows源代码checkout，请显式配置虚拟环境Python可执行文件和工作目录。参见[Windows MCP配置示例](docs/windows-mcp-config-example.md)，然后重启AI客户端。
### 4. 运行第一个只读检查
连接探针并给板供电后，告诉AI：
```text
使用McuBuddy检查当前的调试环境，发现连接的探针，并对板进行第一个只读检查，无需写入Flash。
在开始之前，请告诉我还缺少哪些信息。
```
推荐的顺序是先检查环境和目标，然后配置探针并读取最小目标状态：
```text
doctor()
list_connected_probes()
match_chip_name("py32f030x8")
configure_probe(target="py32f030x8", backend="pyocd")
board_smoke_test(disconnect_after=True)
```
`board_smoke_test`不会写入Flash，但它可能会默认停止目标以捕获稳定上下文，因此它仍然会更改执行状态。如果设备必须不停止，请指示AI仅执行非侵入性的探针和环境检查。
## 💬 AI助手示例
可以将以下提示直接提供给连接到`McuBuddy`的AI助手。
### 检查探针和板
```text
列出连接的调试探针，确认目标芯片匹配，并对板进行只读检查。不要重置目标，写入内存，或擦除或编程Flash。
如果您识别出风险，请先停止并解释它。
```
### 硬Fault诊断
```text
停止目标并读取PC、LR、SP和故障寄存器。使用当前的AXF/ELF解析调用栈，确定HardFault最可能的源代码位置，并列出支持结论的证据。
```
### 构建Keil项目并继续调试
```text
在项目目录下查找Keil项目和目标。首先告诉我使用哪个项目、目标和UV4.exe。在确认后，构建项目并加载生成的AXF而不下载固件，然后使用探针运行到main。
```
### 检查外设配置
```text
加载与目标芯片匹配的SVD，并检查RCC、GPIOA和UART外设状态。检查时钟、引脚复用和中断配置是否一致，并解释任何异常字段。
```
### 调查FreeRTOS僵局
```text
读取FreeRTOS任务列表、当前任务上下文和堆栈使用情况。识别阻塞任务、异常状态或堆栈风险，而不修改目标状态。
```
更多基于证据的提示和决策序列，请参见[AI手册](docs/ai-playbook.md)和[AI示例](docs/ai-examples.md)。
## 🧰 功能和后端支持
### 功能类别
| 类别 | 主要功能 |
| --- | --- |
| 探针和目标 | 探针发现、目标匹配、连接/断开、停止/恢复、重置和步进 |
| CPU和内存 | 核心/FPU/故障寄存器、内存访问、停止上下文、Flash比较和验证 |
| 断点和执行 | 硬件/软件断点、观察点、运行到函数/源代码和步进/出 |
| 符号和源代码 | ELF/AXF、DWARF、反汇编、函数、变量、源代码映射和调用栈 |
| 外设和RTOS | CMSIS-SVD、外设字段、FreeRTOS任务、任务上下文和堆栈检查 |
| 日志和服务 | UART、RTT、选定的SWO和pyOCD/J-Link GDB服务器 |
| 项目和诊断 | Keil项目发现、构建/下载、HardFault、启动、时钟、中断和外设诊断 |
有关完整工具名称、参数和返回值，请参见[工具参考](docs/tool-reference.md)。
### 后端支持状态
| 路径 | 当前角色 | 主要功能 |
| --- | --- | --- |
| pyOCD + ST-Link/CMSIS-DAP | 主要后端 | 控制、内存、Flash、源代码调试、RTT、RTOS和GDB服务器 |
| J-Link | 主要后端 | 控制、内存、Flash、源代码调试、原生RTT、DWT和GDB服务器 |
| probe-rs sidecar | 实验性 | 发现、连接、核心控制、寄存器、内存和硬件断点 |
| Keil UV4 (Windows) | 构建/下载后端 | 项目发现、目标配置、构建、日志和可选下载 |
主要验证覆盖范围包括：
- STM32L496VETx + ST-Link / pyOCD；
- STM32F103C8 + J-Link；
- 内置目标预飞行配置文件，适用于STM32F103ZE和PY32F030X8。
“已在代码中实现”并不意味着“已在每个板子上验证”。请使用[支持矩阵](docs/support-matrix.md)和`list_validation_records()`作为事实来源。
## 🔄 Keil MDK / UV4工作流
Keil提供项目构建、链接和可选的固件下载。`McuBuddy`不会替换Keil编译器或解析和重写项目构建规则。它发现项目，选择目标，调用UV4，读取日志和输出文件，并将结果馈入自动化调试。
```text
发现Keil项目
→ 配置UV4、目标和日志
→ 调用Keil构建
→ 加载生成的AXF/ELF
→ 通过pyOCD/J-Link连接并诊断板
→ 在用户确认后通过Keil下载
→ 重新连接并验证Flash
```
### 1. 发现和配置项目
```text
discover_keil_projects(root=r"E:\work_code\app")
configure_keil_project(
project_path=r"E:\work_code\app\MDK-ARM\Project.uvprojx",
uv4_path=r"C:\Keil_v5\UV4\UV4.exe",
target_name="Debug",
)
```
用户或AI应审查自动发现结果。当目录中包含多个项目、目标或输出文件时，请显式指定`project_path`、`target_name`和`elf_path`。
### 2. 构建和加载AXF
```text
build_project(timeout_seconds=120)
configure_elf(elf_path=r"E:\work_code\app\MDK-ARM\Objects\Project.axf")
elf_load(path=r"E:\work_code\app\MDK-ARM\Objects\Project.axf")
```
一旦加载AXF，AI就可以可靠地解析PC、LR和内存地址到函数、源代码行、局部变量和调用栈。
### 3. 连接探针并继续调试
```text
configure_probe(target="py32f030x8", backend="pyocd")
probe_connect(target="py32f030x8")
probe_halt()
read_stopped_context()
run_to_function("main")
```
如果Keil、J-Link Commander、GDB服务器或另一个调试器已经占用探针，请先关闭该会话；否则pyOCD或J-Link可能会连接失败。
### 4. 下载和验证
`flash_firmware`调用配置的Keil UV4下载流程并修改目标Flash，因此需要显式确认：
```text
flash_firmware(timeout_seconds=120, confirm=True)
compare_elf_to_flash()
```
在下载之前，请确认项目、目标、固件输出、芯片型号和恢复计划。有关完整的新项目工作流程，请参见[通用板工作流程](docs/generic-board-workflow.md)。
## 🔍 常见调试工作流程
### 板不启动或进入HardFault
```text
probe_halt()
read_stopped_context(include_fault_registers=True)
diagnose_hardfault()
backtrace()
```
### 外设无输出
```text
svd_load(svd_path=r"C:\path\Device.svd")
svd_read_peripheral(peripheral="RCC")
svd_read_peripheral(peripheral="GPIOA")
diagnose_peripheral_stuck(peripheral="UART")
```
### FreeRTOS僵局
```text
list_rtos_tasks()
rtos_task_context(task_name="WorkerTask")
read_stack_usage()
```
### 运行到源代码位置
```text
run_to_function("main")
run_to_source(file="main.c", line=120)
source_step()
step_over()
```
## 🛡️ 安全模型
`McuBuddy`通过`list_tool_safety()`提供机器可读的安全分类。
| 类别 | 示例 | 默认要求 |
| --- | --- | --- |
| 只读 | 目标匹配、寄存器/内存读取、符号解析、日志、诊断 | 无需确认 |
| 执行更改 | 停止、恢复、重置、继续、步进 | 不写入Flash，但更改执行状态 |
| 运行时状态写入 | 内存/寄存器写入、断点、观察点、SVD字段写入 | 显式确认 |
| 持久破坏操作 | Flash擦除/编程、Keil固件下载 | 显式确认 |
| 主机进程 | Keil构建、GDB服务器启动/停止 | 启动或停止本地进程 |
安全原则：
1. 对于未知目标，首先匹配芯片和探针；不要猜测地址。
2. 读取证据后再停止、重置或写入。
3. 在Flash操作之前，确认目标、范围、镜像和恢复方法。
4. 对于电机、继电器、电源开关和其他执行器，优先使用断点和低能耗测试。
## 🔒 会话和并发
- 共享探针、Keil、ELF/SVD、日志和运行时配置的操作在同一个`Session`内序列化。
- 不同的会话可以在它们控制无关的板时并发运行。
- 无状态查询（如目标匹配和工具安全信息）可以在会话操作期间运行。
- 取消不能强制终止已进入同步SDK的调用。服务器在释放会话锁之前等待工作线程完成。
这可以防止一个请求切换后端、断开探针或更改共享状态，而另一个探针操作仍在运行。
## 📦 mcubug技能
存储库包含`skills/mcubug`，它引导Codex和Claude Code使用这些工具按照“证据优先，判断第二”的顺序，而不是将MCP工具视为无序的命令列表。
为Codex安装：
```powershell
python .\skills\mcubug\scripts\install_skill.py --target codex --overwrite
```
为Claude Code安装：
```powershell
python .\skills\mcubug\scripts\install_skill.py --target cc --overwrite
```
安装后，请重启客户端或打开新会话。有关详细信息，请参见[mcubug技能适用于Codex和Claude Code](docs/mcubug-skill.md)。
## ⚠️ 当前限制
- Keil构建和下载目前针对Windows + Keil UV4。
- probe-rs sidecar仍然是实验性的，尚未涵盖Flash、RTT、SWO或官方二进制发布。
- RTOS检查依赖于FreeRTOS符号和与目标固件匹配的ELF/AXF。
- SVD文件不会自动为每个芯片捆绑，通常来自CMSIS-Pack或芯片供应商。
- SWO文本捕获依赖于芯片配置、探针功能、引脚复用和板接线。
- 设备补丁和连接策略仍然是轻量级机制，而不是完整的板插件系统。
## 📚 文档
- 首次设置： [快速入门](docs/quickstart.md)
- 任意板和Keil项目： [通用板工作流程](docs/generic-board-workflow.md)
- MCP会话演练： [MCP用法示例](docs/mcp-usage-example.md)
- AI调试决策顺序： [AI手册](docs/ai-playbook.md)
- 常见场景： [AI示例](docs/ai-examples.md)
- 完整工具索引： [工具参考](docs/tool-reference.md)
- 后端和硬件验证： [支持矩阵](docs/support-matrix.md)
- 项目设计： [架构](docs/architecture.md)
- 技能安装和维护： [mcubug技能](docs/mcubug-skill.md)
- 计划工作： [v0.6路线图](docs/v0.6-roadmap.md)
## 🧪 本地开发
```bash
pip install -e ".[dev]"
pytest
ruff check src tests
```
参见[文档索引](docs/README.md)以获取存储库布局和文档所有权。
## 📄 许可证
该项目在MIT许可证下获得许可。有关详细信息，请参见[LICENSE](LICENSE)。
---
如果`McuBuddy`有助于您的MCU调试工作流程，请考虑给项目加Star。
