STM32 GDB Debugger

Reports stack used/free bytes and a clear overflow verdict for the halted core. stack_top defaults to the initial MSP (first word of the vector table at vector_table_addr). Give stack_size or stack_limit for the overflow check (else only usage is reported). The key tool for diagnosing stack overflows.

Runs several tool calls in ONE round trip and returns ALL their full results — the fastest way to do a sequence of operations (e.g. read registers + backtrace + several variables) without per-call latency. ok is false if ANY step failed; data.succeeded/data.failed count the outcomes (count/total only count steps run vs requested). Pass session to run every step against a named debug session.

Breakpoint / watchpoint management. action=set(location[,condition,temporary,ignore_count]) | delete(breakpoint_id) | list | watch(location,access_type). access_type=r|w|a.

Builds firmware with Keil uVision (UV4), CMake, make, or a custom command, so the AI can rebuild after a fix. Keil emits a .axf (ELF/DWARF) that the debug tools load like any .elf. Returns the exit code, success flag, and build log tail.

Invoke ANY stm32-gdb-mcp tool by name — including one that is NOT in your current tool list (clients with tool-count limits may hide some). Use this to reach e.g. start_debug_session when it isn't directly listed: call(tool='start_debug_session', args={...}). Returns that tool's result.

Like call, but restricted to tools that only READ state — so it needs no approval prompt where call, which can reach anything, does. Prefer it for hidden read-only tools: call_read(tool='read_core_registers', args={}). The gate is per-ACTION, not per-tool: a family's reading action goes through even though the family also writes, so call_read(tool='debug_profile', args={'action':'get'}) works while action='set' does not. A refusal names the actions it would accept. Refuses anything that writes; use call for those.

One-call 'where am I': decoded core registers + a PC/LR/SP summary, the decoded backtrace, and the innermost-frame locals. The fastest way to get full halted context.

Closes a named debug session, tearing down its GDB client and server.

Resumes execution of the target device until the next breakpoint. Safe to call when the target is already running (reports already_running instead of erroring), so 'make sure it is running' is expressible.

Active debug profile (mcu/elf/svd/probe). action=get | set([mcu,elf_path,svd_path,board,probe,server_type,server_args,project_root,hub,notes,merge]). set merges at the TOP LEVEL ONLY: omitted fields keep their value, but a nested block you pass REPLACES the stored one whole — hub={map:{3:{label:TC}}} drops the rest of hub, including what hub(action=discover) wrote. merge=true deep-merges nested blocks instead; leave it off to DROP a stale entry, since replace is the only way to remove one. Returns the full resulting profile, which is in-memory only: empty again after the MCP server restarts.

One-call repro step: set an optional conditional/temporary breakpoint at a location, run, and return the stop event PLUS the decoded backtrace and innermost-frame locals. Collapses set_breakpoint + run + read frame/vars into a single round-trip.

Lists physical ST-Link, J-Link, and CMSIS-DAP probes currently connected over USB. Preserves serial numbers so multiple identical probes are never silently collapsed.

One-call bring-up: flash an ELF (loads symbols), reset-halt, set a temporary breakpoint at an entry point (default 'main'), run to it, and return the decoded stop context. With hub_channel (or usb_location) and no session running, it starts one pinned to that probe first -- so 'flash the firmware on channel 4' is this single call, on a bench with several probes, without disconnecting any of the others.

Flashes a compiled firmware binary to the target. Accepts GCC .elf or Keil .axf. By default it then resets and RUNS the firmware (Keil-style 'Load + Run'). Pass reset_run=false to flash only (e.g. to set breakpoints before the firmware starts). Refuses (elf_layout_unsupported) an image GDB would flash incompletely, such as a Keil ARMCC5 AXF whose RW initializer lies outside its segment; flash its fromelf BIN instead.

Returns this session's record by view: 'journal' (every tool call with args/ok/summary/duration; supports limit), 'timeline' (compact human-readable replay), or 'metrics' (per-tool call counts, success/failure, durations).

Interrupts/halts the target device execution.

Programmable USB hub: per-port power, USB2 data lines, cold boot, and V/I sampling. action=describe | power(state[,channel,confirm]) | data(state[,channel,exclusive,confirm]) | cycle([channel,off_ms,settle_ms,confirm]) | measure([channel,duration_sec,interval_sec,all_channels]) | discover([apply,force,settle_sec]) | dashboard([state,port,interval_sec,open_browser]). dashboard serves a read-only live web page on 127.0.0.1 and returns its URL. state=on|off; channel is 1-based and defaults to the session's mapped hub channel. Removing port power cold-boots that board and un-enumerates its probe.

Lists all debug target sessions (the 'default' one plus any named) with their liveness and port. To debug MULTIPLE boards at once, pass a 'session' argument (any string) to any tool — e.g. start_debug_session(session='rackA', ...) — and each gets fully isolated state.

Loads symbols from an ELF/AXF into the current GDB session WITHOUT flashing. Symbols are per-session, so after a fresh connect or recover_session you need this (or flash_firmware) before symbol breakpoints resolve. Falls back to the debug profile's elf_path if elf_path is omitted.

Firmware log capture over a channel. action=start(channel[,port,baudrate,command,args,file,timeout]) | stop(channel) | get(channel[,limit,since_index,clear]) | clear(channel). channel=rtt|swo|uart; uart takes port/baudrate, rtt/swo take command/args or file.

Identifies THIS running stm32-gdb-mcp server: release version, git commit, the package directory the code was imported from (plus the install root the git probe used), whether compact mode is hiding tools, and how many tools this build advertises versus how many exist. Needs NO debug session, NO probe and NO target — call it the moment a tool you expect is missing or behaves like an older build, instead of guessing which checkout the client actually launched.

Reads the call stack as a decoded list of frames {level, func, file, line, addr} plus a one-line summary. Set include_raw=true to also get the raw GDB output.

Reads a block of memory from the target. Returns the raw bytes in memory order, plus value_le -- the same bytes as one little-endian value -- for a 1/2/4/8-byte read. Use value_le for a peripheral register: the raw string arrives least-significant-byte first, so reversing it by hand is where bit positions get misread.

Reads a peripheral register using its name from the loaded SVD.

Reads the value of a C variable currently in scope.

Reconstructs the full crash site after a HardFault: decodes fault registers, unwinds the auto-stacked exception frame from MSP/PSP via EXC_RETURN to recover the true faulting PC, and resolves it to source file:line. Run this when halted in a fault handler.

Recovers a dropped or wedged session: cleanly tears down the GDB client and server, then restarts the server (with retry/backoff for a busy probe) using the last start_debug_session arguments and reconnects. Use after a probe_unavailable or connection_lost error. When a programmable USB hub is configured (debug_profile hub.channel), a retry that cannot fix the probe escalates to toggling its USB data lines and then power-cycling the port -- the only in-band cure for a wedged endpoint. Any hub action taken is reported in recovery_steps.

Files a GitHub issue about an MCP problem from THIS session — auto-bundling the session journal, metrics, and MCP version into a structured report (via the gh CLI). Call this when a tool misbehaves or confuses you. Deduplicated per session so retries don't spam. Defaults to the stm32-gdb-mcp repo.

Resets the target device. Can optionally halt immediately after reset. strategy="cold" removes target power through a configured programmable USB hub before resetting, which is the only strategy that produces a true power-on reset (RCC_CSR POR flag, cleared .noinit, drained RAM); it fails rather than silently doing a warm reset when no hub channel is mapped. It needs no confirm argument -- asking for a cold reset by name IS the confirmation the hub guard wants -- and it stops the GDB session before the cut, then re-establishes it.

Resumes the target and waits, returning a structured stop event (reason, symbolized frame, breakpoint id, signal) or a timeout. Use this instead of continue_execution + polling to close the debug loop.

Runs the target freely for a wall-clock duration, halts it, and returns one structured report with final frame/context and optional expression captures. Useful for counters, telemetry buffers, polling loops, and timing-sensitive bus diagnostics without breakpoint perturbation.

Replays a declarative scenario — a list of {tool, args} steps — deterministically and returns a per-step pass/fail report. Provide inline 'steps' or a 'path' to a JSON scenario file. The minimal-step way to re-run a complex bug repro.

Validates the link right after connecting: reads CPUID and DBGMCU IDCODE and checks byte order, that a real Cortex-M is present, and that the device matches the expected family (from the profile MCU or the 'expected_family' arg). Run this first to catch endianness/config faults before debugging. Halts the core first (identity reads are unreliable while running); pass halt=false to skip.

Starts the specified GDB Server (openocd, stlink, jlink) and connects the GDB Client to it. openocd REQUIRES server_args naming the probe and target, e.g. ['-f','interface/stlink.cfg','-f','target/stm32l4x.cfg'] — without them OpenOCD cannot find a config or adapter. Omitted values come from the active debug profile.

Stops the GDB client/server, variable tracking, and all active RTT/SWO/UART readers.

Returns the correct OpenOCD server_args for an MCU family + probe (e.g. STM32L431 + stlink -> ['-f','interface/stlink.cfg','-f','target/stm32l4x.cfg']) and validates the config files exist in OpenOCD's bundled scripts dir. Call this to get start_debug_session args — do NOT search the disk for .cfg files.

Returns descriptions and complete schemas for full-surface tools, including tools hidden in compact mode.

Writes a value to a specific memory address.