adancurusul / embedded-debugger

Embedded Debugger

Use the local embedded-debugger-mcp binary as the source of truth. Prefer CLI
checks first, then MCP tools when an MCP client is available.

Entry Decision

1. If the user has an MCP client configured, start or verify the server:
   embedded-debugger-mcp serve

2. If the user wants no MCP install, use CLI-first mode:
   embedded-debugger-mcp doctor, embedded-debugger-mcp probes list, and
   embedded-debugger-mcp skill print-prompt.

3. If hardware access is required, confirm the probe and target are connected
   before destructive actions such as flash erase or program.

CLI Workflow

Run these in order and report the exact outcome:

embedded-debugger-mcp doctor
embedded-debugger-mcp probes list
embedded-debugger-mcp config show

Use JSON for automation:

embedded-debugger-mcp doctor --json
embedded-debugger-mcp probes list --json

Backends

One tool set runs over two interchangeable engines, chosen at connect:

• backend: "probe-rs" (default) — native probe-rs; supports flash and RTT.

• backend: "openocd" (experimental) — talks to an already-running openocd
  over its GDB port via openocd_address (default 127.0.0.1:3333). Use for
  chips probe-rs does not cover well (e.g. Xtensa ESP32 via openocd-esp32).
  Memory access and halt/run/step/reset are validated on real ESP32-S3; flash
  and RTT are not available on this backend. 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 and do not
  apply to Xtensa targets.

  • Start openocd with gdb_memory_map disable, otherwise it probes flash on
    the GDB connect, fails, and REJECTS the connection. Example:
    openocd -f board/esp32s3-builtin.cfg -c "gdb_memory_map disable".

The AI uses the same tools regardless of backend; only connect differs.

MCP Workflow

Use MCP tools for session-based operations:

1. list_probes
2. connect (add backend: "openocd" and openocd_address to use OpenOCD)
3. Read-only checks such as probe_info, get_status, and read_memory

4. On a crash or halt, call diagnose_fault: it reads the Cortex-M SCB fault
   registers (CFSR/HFSR/MMFAR/BFAR/SHCSR/CPUID) plus PC/SP/LR and returns a
   compact structured evidence bundle in one call. Halt the target first for
   meaningful values; reason over the set fault bits yourself. Then call
   unwind_exception with elf_path to map the crash to a source line
   (full DWARF backtrace on probe-rs; faulting PC/LR on OpenOCD).

5. Mutating operations only after the user confirms target, file path, and risk:
   write_memory, flash_erase, flash_program, run_firmware (probe-rs)

6. RTT operations after firmware is running: rtt_attach, rtt_channels,
   rtt_read, rtt_write, rtt_detach (probe-rs)

7. disconnect

Fetch authoritative info yourself

You are a capable model: prefer fetching ground truth over relying on memorized
or hardcoded chip data. This skill points you to sources; it does not embed
register tables. In order of authority:

1. The target itself (runtime, most authoritative for this exact chip):
   registers are self-described by the GDB target description; memory is read
   with read_memory; core identity from CPUID / the connected target.

2. The firmware ELF (what is actually running): symbols and source lines come
   from DWARF — use unwind_exception (pass elf_path) to map addresses to
   file:line.

3. The chip datasheet / reference manual (external, per-chip): for a peripheral
   or fault register, find the peripheral's base in the memory-map chapter, add
   the register offset, then read_memory. Search the vendor document for the
   exact value; do not guess addresses from memory. CMSIS-SVD files are a
   machine-readable source for register maps.

4. ARM Cortex-M architecture registers (SCB fault regs, CPUID) are fixed by the
   ARM architecture and identical across vendors — diagnose_fault reads them.
   They do not exist on non-Cortex-M targets (e.g. Xtensa ESP32).

Do not hardcode or invent register/peripheral addresses. If a value is not
recoverable from the target, the ELF, or a cited datasheet, say so.

Know your versions

Behavior and target support depend on tool versions — check them before
concluding something is unsupported or broken:

• probe-rs version determines which chips and architectures are supported
  (e.g. Xtensa support is comparatively new). Check embedded-debugger-mcp doctor.

• OpenOCD version and fork matter: the Espressif fork (openocd-esp32) is needed
  for Xtensa ESP32, and some targets need flags like gdb_memory_map disable.
  Check openocd --version.

• Probe firmware (ST-Link / J-Link) can affect connectivity; probes list
  reports the connected probe.

Safety Rules

• Treat flash erase, flash program, memory write, reset, run, and RTT write as
  mutating hardware operations.

• Prefer read-only discovery before mutation.

• Respect project configuration limits for file paths, file sizes, memory
  ranges, and flash erase permissions.

• Do not claim hardware success from command text alone; cite the command or MCP
  tool result that produced the evidence.

Prompt Reference

For a reusable CLI+Skill prompt, read
references/default-prompt.md.