STM32 GDB MCP Server

An MCP server that lets an AI agent debug STM32 firmware on real hardware — drive GDB + OpenOCD/ST-Link/J-Link to flash, breakpoint, inspect memory/registers/RTOS, triage HardFaults, and profile — and get back decoded, structured evidence instead of raw GDB text.

让 AI 智能体在真实硬件上调试 STM32:通过 GDB + OpenOCD/ST-Link/J-Link 烧录、打断点、查 内存/寄存器/RTOS、定位 HardFault、做性能采样,返回已解码的结构化证据而非原始 GDB 文本。

What you get / 能力一览

Two cross-cutting goals: low comprehension cost (decoded outputs, suggested_next_actions) and minimal repro steps (composites like flash_and_run / debug_until collapse 5–15 calls into one). Lean surface: ~31 tools in compact mode (full ~60); reach any tool via call(tool, args).

Install / 安装

deploy.py installs the server, writes the IDE's MCP config, and drops a project-aware rules file into your firmware project. Per-client config snippets + the rules template are in docs/install-ides.md. Compact mode is on by default.

Requirements — on PATH: arm-none-eabi-gdb, plus one server (openocd / JLinkGDBServerCL / st-util). Check with python setup_env.py.

30-second quickstart / 快速上手

suggest_server_args(mcu="STM32L431", probe="stlink")   # → the -f interface/target cfgs
start_debug_session(server_type="openocd", server_args=[...])
self_check()                                           # ALWAYS first: byte order, core, family
debug_profile(action=set, mcu="STM32L431", elf_path="build/app.elf", svd_path="STM32L4.svd")
flash_and_run(file_path="build/app.elf", run_to="main")
breakpoint(action=set, location="my_func", condition="state == BAD")
run_and_wait()                                         # structured stop event + next actions
run_for_duration(duration_sec=30, capture={"expressions": ["rx_count"]})
run_for_duration(duration_sec=60, sample={"interval_ms": 500, "expressions": ["rx_count", "state"]})
reconstruct_fault_context()                            # on a crash: faulting PC → file:line

The full tool reference (lean families with action=/what=) is skills/stm32-debug/reference/tool-map.md. The server also ships always-on instructions, so any MCP client gets the debug loop without setup.

Key rules (the target must cooperate) / 关键规则

• Reads need a HALTED core. If a read says target_unresponsive, halt_execution first.
• run_for_duration(sample=...) is best-effort low-rate debugger polling. It does not halt the target itself, but running-target expression reads may fail on some probes/MCUs; use SWO/ring-buffer firmware telemetry for higher-rate or guaranteed capture.
• A breakpoint TIMEOUT means the path was NOT reached — don't just retry. Halt, capture_state, breakpoint(action=list) (hit_count=0 confirms), read the gating flag, set an earlier breakpoint or drive the precondition.
• Writes are guarded (option bytes/IWDG/WWDG blocked) — write_guard(action=policy) to allow.
• Never hard-kill OpenOCD (wedges the ST-Link USB) — use recover_session. SWD is exclusive.

Response shape / 响应结构

Every tool returns a stable JSON envelope inside the MCP TextContent transport:

{ "ok": true, "data": {}, "error": null, "raw_response": null, "suggested_next_actions": [] }

Human-readable text lives in data.message / error.message; raw GDB output stays in raw_response when it aids diagnosis. Errors carry a code (e.g. target_unresponsive).

Agent guidance — three layers / 三层引导

1. Inline — most results carry suggested_next_actions (the next loop step).
2. Always-on — the server's instructions (debug loop + key rules) inject automatically.
3. On-demand — skills: stm32-debug (bring-up, HardFault, hang, minimal repro, replayable scenarios) and stm32-instrument (write-time SWO/ITM trace). In other IDEs the same guidance travels as a rules file (AGENTS.md).

Repeatable config / 可复现配置

Load a YAML debug profile so sessions reproduce across clients: debug_config(action=load, path="mcp/board.yaml").

mcu: STM32L431CCUx
probe: stlink
server_type: openocd
server_args: ["-f", "interface/stlink.cfg", "-f", "target/stm32l4x.cfg"]
elf_path: build/app.elf
svd_path: STM32L4.svd

See examples/configs/ for J-Link and OpenOCD samples.

Develop / 开发

pip install -e ".[dev]"
python -m ruff check . && python -m pytest && python -m compileall src tests

• docs/install-ides.md — per-IDE install + rules template
• docs/TROUBLESHOOTING.md — common failures + recovery
• docs/hil-validation.md — hardware-in-the-loop validation (STM32_GDB_MCP_HIL=1)
• CONTRIBUTING.md, SECURITY.md, docs/release.md

Hardware validation runs on a self-hosted runner labeled stm32; normal CI is hardware-free (lint, tests, compile, packaging).