# Ai Mcu Auto Debug > AI-assisted MCU debug automation framework / AI 辅助 MCU 自动调试框架 - **Type:** MCP server - **Install:** `agentstack add mcp-yukina0079-ai-mcu-auto-debug` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [yukina0079](https://agentstack.voostack.com/s/yukina0079) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [yukina0079](https://github.com/yukina0079) - **Source:** https://github.com/yukina0079/ai-mcu-auto-debug ## Install ```sh agentstack add mcp-yukina0079-ai-mcu-auto-debug ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # AI MCU Auto Debug [](LICENSE) [](pyproject.toml) AI MCU Auto Debug is an open-source automation toolchain for AI agents that need to write, build, flash, debug, observe, and report on MCU firmware. It keeps the core low-coupling: existing build tools, OpenOCD/J-Link/pyOCD/probe-rs style debuggers, CMSIS-SVD/user-provided documents, UART logs, CLI, MCP, and skills are connected through small deterministic adapters. AI MCU Auto Debug 是一个面向 AI agent 的开源 MCU 自动化工具链，用来完成代码编写、构建、烧录、调试、观测和报告闭环。项目保持低耦合：复用现有构建工具、OpenOCD/J-Link/pyOCD/probe-rs 调试后端、CMSIS-SVD/用户提供资料、UART 日志、CLI、MCP 和 skill，而不是把所有东西绑死在一个平台里。 > Images in this repository are AI-generated illustrative assets. They do not represent a specific vendor board, probe, or certification. > > 仓库图片为 AI 生成的说明性素材，不代表某个具体厂商开发板、探针或认证。 ## Quick Start / 快速开始 Give this repository URL to an AI coding agent, then ask it to run the safe bootstrap first. 把仓库地址发给 AI 编程工具后，让它先执行安全部署检查。 ```powershell git clone https://github.com/yukina0079/ai-mcu-auto-debug.git cd ai-mcu-auto-debug python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -e . ai-mcu-debug agent-bootstrap --project . --client generic-json ai-mcu-debug doctor ai-mcu-debug capability-audit --project . ``` Recommended first prompt for Codex, Claude, OpenCode, Trae, Qoder, or another vibe coding agent: 推荐给 Codex、Claude、OpenCode、Trae、Qoder 或其他 vibe coding 工具的第一句话： ```text Use this repository as an AI MCU automation toolchain. Run agent-bootstrap first, then use workflow-plan before hardware actions. Do not flash, repair, force writes, or run parallel hardware debug sessions unless I explicitly approve the current board and operation. ``` ```text 把这个仓库当作 AI MCU 自动化工具链使用。先运行 agent-bootstrap，再用 workflow-plan 判断下一步。除非我明确批准当前板卡和操作，否则不要烧录、修复代码、强制写入，也不要并行运行硬件调试会话。 ``` ## What It Automates / 自动化能力 - Natural-language loop: user goal -> agent plan -> code/build -> hardware debug -> UART observation -> evidence report -> repair iteration. - 自然语言闭环：用户目标 -> agent 规划 -> 写代码/构建 -> 硬件调试 -> UART 观测 -> 证据报告 -> 修复迭代。 - Debug control: reset/halt, breakpoints, single-step, core register reads, guarded peripheral register access, memory reads, debug sequences. - 调试控制：reset/halt、断点、单步、核心寄存器读取、受保护的外设寄存器访问、内存读取和调试序列。 - Knowledge guard and anti-hallucination: build `mcu_context.json` from user-provided SVD, linker/startup files, datasheets, reference manuals, errata, or document repositories. - 知识库防幻觉：从用户提供的 SVD、linker/startup、datasheet、reference manual、errata 或资料仓库生成 `mcu_context.json`。 - Signal observation: `runtime-log` wraps existing UART/RTT/SWO tools, and `serial-log` / MCP `collect_serial_log` can read UART through pyserial. - 信号观测：`runtime-log` 复用已有 UART/RTT/SWO 工具，`serial-log` / MCP `collect_serial_log` 可通过 pyserial 读取串口。 - Visual observation: `camera-scan`, `camera-capture`, and MCP `capture_board_image` collect image evidence, deterministic quality/change metrics, and a standard MCP image block for agent visual inspection. - 视觉观测：`camera-scan`、`camera-capture` 和 MCP `capture_board_image` 可采集图像证据、可重复的画质/变化指标，并通过标准 MCP 图像内容交给 agent 进行视觉分析。 - Agent deployment: `agent-bootstrap`, `skill-bootstrap`, `mcp-config`, and `mcp-smoke` make the repo easy to hand to different AI coding agents. - Agent 部署：`agent-bootstrap`、`skill-bootstrap`、`mcp-config` 和 `mcp-smoke` 让不同 AI 编程工具更容易接入。 Camera access is disabled by default because it captures the surrounding environment. Each scan or capture requires explicit `allow_camera=true` / `--allow-camera`. Visual appearance is supporting evidence only and must be correlated with debug, serial, build, and MCU-document evidence. 摄像头会拍摄周边环境，因此默认禁用。每次扫描或采集都必须显式设置 `allow_camera=true` / `--allow-camera`。外观只能作为辅助证据，必须与调试、串口、构建和 MCU 资料证据交叉判断。 ## Agent Compatibility / Agent 兼容 The project exposes the same capabilities through CLI, Python API, MCP tools, and a bundled skill. The goal is simple: most AI agents should be able to receive the repository URL and bootstrap themselves without private setup knowledge. 项目通过 CLI、Python API、MCP 工具和内置 skill 暴露同一套能力。目标很直接：多数 AI agent 拿到仓库地址后，应能在没有私有背景信息的情况下自行完成部署检查。 ```powershell ai-mcu-debug agent-bootstrap --client codex --project . ai-mcu-debug agent-bootstrap --client claude-desktop --project . ai-mcu-debug agent-bootstrap --client claude-code --project . ai-mcu-debug agent-bootstrap --client opencode --project . ai-mcu-debug agent-bootstrap --client trae --project . ai-mcu-debug agent-bootstrap --client qoder --project . ai-mcu-debug mcp-config --client generic-json --project . ai-mcu-debug mcp-smoke --project . ``` `mcp-config` outputs verified stdio MCP snippets. For clients whose private config format is not public or stable, the tool emits a generic MCP JSON definition and points the agent back to the CLI flow instead of guessing. `mcp-config` 会输出可检查的 stdio MCP 配置片段。对于私有配置格式不公开或不稳定的客户端，工具会输出通用 MCP JSON，并让 agent 回退到 CLI 流程，而不是乱猜配置。 ## Bench, DUT, Instrument, Workflow / 核心概念 - `Bench`: a reproducible setup made of a DUT, instruments, wiring notes, workflow, and safety policy. - `Bench`：由 DUT、仪器、接线说明、workflow 和安全策略组成的可复现实验台配置。 - `DUT`: the device under test, for example an STM32F103 board. - `DUT`：被测设备，例如 STM32F103 开发板。 - `Instrument`: debug probe, UART adapter, runtime-log command, or optional camera/signal tool. - `Instrument`：调试探针、UART 转接器、runtime-log 命令，或可选的摄像头/信号工具。 - `Workflow`: repeatable steps such as doctor -> probe scan -> context check -> build -> serial observation -> read-only debug -> report. - `Workflow`：可复现步骤，例如 doctor -> probe scan -> context check -> build -> serial observation -> read-only debug -> report。 - `Evidence/Report`: JSON/Markdown artifacts that another agent or engineer can replay or audit. - `Evidence/Report`：可供另一个 agent 或工程师回放和审计的 JSON/Markdown 产物。 Start from these examples: 可以从这些示例开始： ```text configs/benches/stm32f103_minimal.yaml configs/boards/stm32f103rct6_daplink.yaml configs/instruments/daplink_cmsis_dap.yaml configs/instruments/uart_serial.yaml configs/instruments/camera_usb_optional.yaml configs/workflows/stm32f103_readonly_debug.yaml configs/benches/esp32c3_supermini.yaml configs/instruments/esp32c3_usb_serial_jtag.yaml configs/workflows/esp32c3_supermini_readonly_debug.yaml ``` ESP32-C3 SuperMini is supported through an optional ESP-IDF backend. `doctor` discovers ESP-IDF installations managed by EIM or the VS Code extension, including Espressif OpenOCD and RISC-V GDB, without requiring them on the global `PATH`. ESP32-C3 SuperMini 通过可选 ESP-IDF backend 接入。`doctor` 可以发现由 EIM 或 VS Code 扩展管理的 ESP-IDF、Espressif OpenOCD 和 RISC-V GDB，不要求把它们加入全局 `PATH`。 ## Verified Hardware / 已验证硬件 | Board / 板卡 | Status / 状态 | Verified path / 已验证路径 | Evidence / 验证内容 | |---|---|---|---| | STM32F103RCT6 generic board | verified / 已验证 | DAPLink/CMSIS-DAP + OpenOCD + GDB | Cortex-M3 and 256 KiB Flash identity, build, flash verification, reset/halt, core-register and RAM reads, source breakpoint, single-step, and resume. NRST was not connected on the verified bench. / 已验证 Cortex-M3 与 256 KiB Flash 识别、构建、烧录校验、复位暂停、核心寄存器与 RAM 读取、源码断点、单步和恢复运行；验证时未连接 NRST。 | | ESP32-C3 SuperMini | verified debug link / 调试链路已验证 | Built-in USB Serial/JTAG + Espressif OpenOCD + RISC-V GDB | Chip and 4 MB Flash identity, registers, memory read, hardware breakpoint, single-step, resume, and serial log. / 已验证芯片与 4 MB Flash 识别、寄存器、内存读取、硬件断点、单步、恢复运行和串口日志。 | ## Hardware Workflow / 硬件流程 ```powershell ai-mcu-debug resolve-chip --project . --chip STM32F103RCT6 ai-mcu-debug doc-intake --project . --chip STM32F103RCT6 ai-mcu-debug prepare-mcu --project . --chip STM32F103RCT6 --svd --linker --startup --doc datasheet= --doc reference_manual= --doc errata= --output examples/mcu_context.json ai-mcu-debug check-context --context examples/mcu_context.json ai-mcu-debug init-workspace --project . --chip STM32F103RCT6 --context examples/mcu_context.json ai-mcu-debug workflow-plan --project . --chip STM32F103RCT6 ai-mcu-debug ai-debug --mode dry-run --workspace-config .embeddedskills/config.json ai-mcu-debug ai-debug --mode read-only --workspace-config .embeddedskills/config.json ``` Optional embedded tools on Windows: Windows 上可选安装的嵌入式工具： ```powershell winget install xpack-dev-tools.openocd winget install Arm.GnuArmEmbeddedToolchain python -m pip install pyocd pyserial ai-mcu-debug doctor --debug-backend openocd-gdb ai-mcu-debug probe-scan ``` UART observation example: 串口观测示例： ```powershell ai-mcu-debug serial-log --port COM3 --baud 115200 --duration-s 5 --output debug_runs/serial/latest.json ai-mcu-debug workflow-run --project . --chip STM32F103RCT6 --no-hardware ``` Camera observation example (install the optional backend first): 摄像头观测示例（先安装可选 backend）： ```powershell python -m pip install -e ".[vision]" ai-mcu-debug camera-scan --allow-camera ai-mcu-debug camera-capture --camera-index 0 --image-output debug_runs/vision/latest.jpg --report-output debug_runs/vision/latest.json --allow-camera ai-mcu-debug vision-analyze --image debug_runs/vision/latest.jpg --baseline debug_runs/vision/baseline.jpg ``` MCP tools `camera_scan`, `capture_board_image`, and `analyze_board_image` expose the same flow. Successful image tools return both a JSON evidence report and a standard MCP image content block, allowing a vision-capable agent to inspect LEDs, displays, wiring, and visible board state without coupling this project to one model provider. MCP 工具 `camera_scan`、`capture_board_image` 和 `analyze_board_image` 提供同一流程。图像工具成功后会同时返回 JSON 证据报告和标准 MCP 图像内容，使具备视觉能力的 agent 能检查 LED、显示屏、接线和可见板卡状态，而不绑定特定模型供应商。 For handoff replay, keep `workflow-run --no-hardware` unless hardware access is explicitly intended; policy records this risk as `replay_workflow_run_may_touch_hardware` when the flag is absent. handoff 回放时，除非明确要触碰硬件，否则保留 `workflow-run --no-hardware`；缺少该参数时策略会记录 `replay_workflow_run_may_touch_hardware` 风险。 ## Golden Suites, Verified Boards, Reports / 公开证据 The public repo separates claims from evidence. A board is only listed as verified when there is a reproducible workflow and report artifact. Candidate boards stay marked as candidates. 公开仓库会区分“能力声明”和“证据”。只有具备可复现 workflow 与报告产物的板卡才列为 verified；候选板卡保持 candidate 标记。 - [Agent Quickstart](docs/AGENT_QUICKSTART.md) - [Golden Suites](docs/GOLDEN_SUITES.md) - [Verified Boards](docs/VERIFIED_BOARDS.md) - [Reports](docs/REPORTS.md) ## Safety Policy / 安全策略 - Hardware debug sessions are exclusive per board. Do not run OpenOCD/GDB/pyOCD/J-Link/probe-rs/debug commands in parallel against the same target. - 同一块板子的硬件调试会话必须独占。不要对同一目标并行运行 OpenOCD/GDB/pyOCD/J-Link/probe-rs/debug 命令。 - Flash, repair, force, memory writes, option bytes, clock/reset-control writes, and standalone hardware replay require explicit approval for the current board. - 烧录、修复代码、强制操作、内存写入、option bytes、时钟/复位控制写入、独立硬件回放，都需要针对当前板卡明确批准。 - The tool asks for MCU documents or a user-provided document repository. It does not guess datasheet URLs by default. - 工具会向用户索要 MCU 资料或用户提供的资料仓库，默认不猜 datasheet URL。 - Unknown addresses and unsafe writes are blocked unless the user intentionally overrides the guard. - 未知地址和不安全写入会被阻止，除非用户明确要覆盖保护。 ## License / 许可证 This project is open source under the [MIT License](LICENSE). 本项目基于 [MIT License](LICENSE) 开源。 ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [yukina0079](https://github.com/yukina0079) - **Source:** [yukina0079/ai-mcu-auto-debug](https://github.com/yukina0079/ai-mcu-auto-debug) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-yukina0079-ai-mcu-auto-debug - Seller: https://agentstack.voostack.com/s/yukina0079 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.