embedded-debugger-mcp

# Embedded Debugger MCP Server [](https://rust-lang.org) [](https://github.com/modelcontextprotocol/rust-sdk) [](LICENSE) Embedded Debugger MCP is a Rust server for embedded debugging through either probe-rs (native) or OpenOCD (via the GDB Remote Serial Protocol). It exposes a single MCP tool set for AI assistants — probe discovery, target control, memory, breakpoints, flash, RTT, and AI-facing crash diagnosis — plus a small CLI and bundled skill for a command-driven workflow without setting up an MCP client first. Language versions: [English](README.md) | [中文](README_zh.md) ## What It Provides - One MCP tool set over two interchangeable backends (probe-rs native, or OpenOCD via GDB RSP), chosen at connect. Validated on real ESP32-S3. - MCP tools for probe discovery, target connection, core control, memory access, breakpoints, flash programming, RTT communication, and crash diagnosis (`diagnose_fault`, `unwind_exception`). - CLI commands for environment checks, configuration inspection, probe listing, MCP serving, and skill prompt handoff. - A Codex/Claude Code compatible skill at `skills/embedded-debugger`. - Release checks covering rustfmt, clippy, tests, docs, packaging, and the STM32 demo build. ## Architecture ```text MCP client or CLI | v embedded-debugger-mcp (one MCP tool set) | v DebugBackend: probe-rs (native) | OpenOCD (GDB RSP) | v debug probe / openocd -> target MCU ``` ## Requirements - Rust stable toolchain. - A probe-rs compatible debug probe such as ST-Link, J-Link, DAPLink, Black Magic Probe, or a supported FTDI-based probe. Alternatively, a running `openocd` exposing its GDB port (e.g. openocd-esp32 for ESP32) to use the `openocd` backend. - A supported target chip and working SWD/JTAG wiring for hardware operations. - Nightly Rust plus `rust-src` for the bundled STM32 demo firmware check. ## Build ```bash git clone https://github.com/adancurusul/embedded-debugger-mcp.git cd embedded-debugger-mcp cargo build --release ``` The binary is `target/release/embedded-debugger-mcp`. ## MCP Mode Run the server explicitly: ```bash embedded-debugger-mcp serve ``` For compatibility, running `embedded-debugger-mcp` without a subcommand also serves MCP over stdio. Example MCP client configuration: ```json { "mcpServers": { "embedded-debugger": { "command": "/path/to/embedded-debugger-mcp/target/release/embedded-debugger-mcp", "args": ["serve"], "env": { "RUST_LOG": "info" } } } } ``` On Windows, use the `.exe` path and Windows path separators. ## CLI And Skill Mode CLI mode is useful for setup checks, automation, and agent workflows before an MCP client is configured. ```bash embedded-debugger-mcp doctor embedded-debugger-mcp doctor --json embedded-debugger-mcp probes list embedded-debugger-mcp probes list --json embedded-debugger-mcp config generate embedded-debugger-mcp config validate embedded-debugger-mcp config show embedded-debugger-mcp skill print-prompt embedded-debugger-mcp skill install --target both ``` The bundled skill lives in: ```text skills/embedded-debugger/ ``` It is written as a plain Codex skill and is also packaged for Claude Code with `.claude-plugin/plugin.json`. The skill starts with CLI checks and uses MCP tools only when an MCP client is available. Install the skill for Codex and Claude Code: ```bash embedded-debugger-mcp skill install --target both ``` Preview or automate the install with JSON: ```bash embedded-debugger-mcp skill install --target both --dry-run --json embedded-debugger-mcp skill install --target both --force --json ``` `--target` accepts `codex`, `claude`, or `both`. The command installs the Codex skill under `~/.codex/skills/embedded-debugger`, the Claude Code skill under `~/.claude/skills/embedded-debugger`, and a local Claude plugin-dir package under `~/.claude/plugins/local/embedded-debugger-mcp`. Existing directories are not replaced unless `--force` is passed. Trigger the Codex skill with a prompt such as: ```text Use $embedded-debugger to inspect my embedded target setup. ``` Load the installed Claude Code plugin package: ```bash claude --plugin-dir ~/.claude/plugins/local/embedded-debugger-mcp --print '/embedded-debugger inspect my embedded target setup' ``` For skill-only environments, the same `skills/embedded-debugger` directory can also be copied to a local skills directory. Validate the skill package: ```bash python3 .github/scripts/validate_skill.py skills/embedded-debugger python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/embedded-debugger claude plugin validate . embedded-debugger-mcp skill install --target both --home /tmp/embedded-debugger-skill-home --force --json ``` The first command validates the repository skill metadata, the second validates the standard `SKILL.md` layout when the Codex skill creator validator is installed, and the third validates the Claude Code plugin manifest. ## Backends The tools run over one of two interchangeable engines, selected at `connect`: - `backend: "probe-rs"` (default) — native probe-rs; full flash and RTT support. - `backend: "openocd"` (experimental) — connects to an already-running `openocd` over its GDB port (`openocd_address`, default `127.0.0.1:3333`) using the GDB Remote Serial Protocol. Intended for targets probe-rs does not cover (e.g. Xtensa ESP32 via openocd-esp32). Memory access and halt/run/step/reset are validated on real ESP32-S3; flash and RTT are probe-rs only. Register reads currently use ARM gdb register numbers, so PC/SP are wrong on Xtensa (known limitation); `diagnose_fault` and `unwind_exception` are Cortex-M specific. Start openocd with `gdb_memory_map disable`, otherwise it probes flash on the GDB connect, fails, and rejects the connection — e.g. `openocd -f board/esp32s3-builtin.cfg -c "gdb_memory_map disable"`. The AI sees the same tool set for both; only `connect` arguments change. ## MCP Tool Set Probe management: | Tool | Purpose | |------|---------| | `list_probes` | Discover connected debug probes. | | `connect` | Open a probe session for a target chip. | | `probe_info` | Show active session information. | Target control: | Tool | Purpose | |------|---------| | `halt` | Halt core execution. | | `run` | Resume execution. | | `reset` | Reset the core. Only the implemented hardware-style reset path is accepted. | | `step` | Single-step one instruction. | | `get_status` | Read core/session status. | | `disconnect` | Drop the session and clean up resources. | Memory and breakpoints: | Tool | Purpose | |------|---------| | `read_memory` | Read target memory with configured size/range limits. | | `write_memory` | Write target memory when enabled by configuration. | | `set_breakpoint` | Set a hardware breakpoint. | | `clear_breakpoint` | Clear a hardware breakpoint. | Diagnostics: | Tool | Purpose | |------|---------| | `diagnose_fault` | Read the Cortex-M SCB fault registers (CFSR/HFSR/MMFAR/BFAR/SHCSR/CPUID) plus PC/SP/LR in one call and return a compact structured evidence bundle with the set fault bits. Reports raw evidence; it does not assert a root cause. Halt the target first. | | `unwind_exception` | Unwind the stack after a crash and map each frame to a source line. On the probe-rs backend, returns a full DWARF backtrace (function + file:line per frame) via probe-rs's own unwinder; on the OpenOCD backend, reads the Cortex-M exception stack frame and maps the faulting PC / caller LR to source lines. Needs `elf_path` to firmware built with debug info (`.debug_line`). | Flash: | Tool | Purpose | |------|---------| | `flash_erase` | Erase flash when erase permissions are enabled. | | `flash_program` | Program ELF, HEX, or BIN files through probe-rs flash algorithms. | | `flash_verify` | Compare raw expected data with target flash contents. | | `run_firmware` | Erase, program, reset/run, and optionally attach RTT. | RTT: | Tool | Purpose | |------|---------| | `rtt_attach` | Attach to a SEGGER RTT control block. | | `rtt_detach` | Detach RTT. | | `rtt_channels` | List discovered RTT channels. | | `rtt_read` | Read from an up channel with max byte and timeout limits. | | `rtt_write` | Write to a down channel. | ## Crash Diagnosis After a crash, halt the core and let the model reason over the evidence: 1. `halt`, then `diagnose_fault` — reads the Cortex-M SCB fault registers (CFSR/HFSR/MMFAR/BFAR/SHCSR/CPUID) plus PC/SP/LR in one call and returns a compact structured bundle with the set fault bits. It reports evidence; it does not assert a root cause. 2. `unwind_exception` with `elf_path` — maps the crash to source lines. On the probe-rs backend this is a full DWARF backtrace (function + `file:line` per frame); on the OpenOCD backend it reads the exception stack frame and maps the faulting PC / caller LR. Both are Cortex-M specific (SCB registers, ARM exception frame) and do not apply to Xtensa (ESP32) targets. The firmware must be built with debug info (`.debug_line`) for source mapping. ## Safety Notes - Flash erase is disabled unless `security.allow_flash_erase` or `flash.allow_erase` is enabled. - Memory writes are controlled by `security.allow_memory_write`. - Optional memory range restriction uses target memory regions in the configuration. - Firmware file paths are canonicalized, checked against `security.allowed_file_paths` when configured, and checked against size limits. - Sector erase by arbitrary address is rejected until target-specific sector mapping is implemented. - `flash_verify` supports raw data comparison. Use raw BIN files or hex data for file-based verification. Generate a starting configuration: ```bash embedded-debugger-mcp config generate > embedded-debugger.toml embedded-debugger-mcp --config embedded-debugger.toml config validate ``` ## STM32 Demo The STM32 RTT demo is in `examples/STM32_demo`. ```bash cd examples/STM32_demo CARGO_TARGET_DIR=/tmp/embedded-debugger-mcp-stm32-target cargo +nightly check --locked ``` The demo firmware shows multi-channel RTT communication and is intended as a hardware validation aid. See [examples/STM32_demo/README.md](examples/STM32_demo/README.md). ## Release Checks Run these before cutting a release: ```bash cargo fmt --all -- --check cargo clippy --locked --all-targets --all-features -- -D warnings cargo test --locked --all-targets --all-features RUSTDOCFLAGS="-D warnings" cargo doc --locked --all-features --no-deps cargo package --locked python3 .github/scripts/validate_skill.py skills/embedded-debugger claude plugin validate . embedded-debugger-mcp skill install --target both --home /tmp/embedded-debugger-skill-home --force --json (cd examples/STM32_demo && CARGO_TARGET_DIR=/tmp/embedded-debugger-mcp-stm32-target cargo +nightly check --locked) ``` ## Acknowledgments - [probe-rs](https://probe.rs/) for embedded debug probe support. - [rmcp](https://github.com/modelcontextprotocol/rust-sdk) for the Rust MCP SDK. - [tokio](https://tokio.rs/) for the async runtime. ## License This project is licensed under the MIT License. See [LICENSE](LICENSE).