STM32 J-Link MCP

AI-native hardware debugging and firmware-engineering interface for STM32H7S3 using SEGGER J-Link.

This project is deliberately more than a thin wrapper around JLinkExe. It provides a stateful semantic layer for AI agents such as Claude Code, Codex, and Hermes while keeping SEGGER's J-Link tools as the low-level hardware backend.

Design goals

• Stateful debug session: J-Link and GDB ownership are coordinated instead of being independent subprocesses.

• Semantic tools: expose target, memory, flash, GDB, Cortex-M fault, SVD, XSPI, and workflow operations.

• AI-friendly output: return compact structured evidence and stable error codes instead of terminal transcripts where possible.

• STM32H7S3 specialization: encode verified memory-map facts and Cortex-M diagnostics without pretending that a board-specific external NOR configuration is universal.

• Safety: read-only mode, bounded writes, explicit confirmation for destructive operations, and raw-command escape hatch disabled by default.

• Extensibility: J-Link, GDB, target profiles, SVD, and diagnostics are separate layers so additional STM32 families or probe backends can be added later.

Related MCP server: dbgprobe-mcp-server

Current hardware profile

The checked-in example configuration is tailored to the current custom target:

• MCU: STM32H7S3I8T6, LQFP176

• SEGGER J-Link device name: STM32H7S3I8

• External memory: XSPI1

• NOR: assumed Macronix MX25UW51245GXDI00, 512 Mbit / 64 MiB

• Memory-mapped base: 0x90000000

• Expected RDID: C2 81 3A

This is a board profile, not a claim that the external NOR is currently initialized. See docs/BOARD_STM32H7S3I8T6_XSPI1.md before enabling any programming workflow.

Architecture

AI Agent (Claude / Codex / Hermes)
              |
              | MCP / stdio
              v
      +---------------------+
      | Semantic MCP tools  |
      +----------+----------+
                 |
                 v
      +---------------------+
      | DebugSessionManager |
      | state / ownership   |
      | safety / locking    |
      +----+-----------+----+
           |           |
           v           v
    +-----------+   +-----------+
    | J-Link    |   | GDB       |
    | backend   |   | session   |
    +-----+-----+   +-----+-----+
          |               |
          v               v
     JLinkExe        JLinkGDBServer
          |               |
          +-------+-------+
                  |
                J-Link
                  |
                 SWD
                  |
             STM32H7S3
          /       |        \
       Flash     SRAM      XSPI
                            |
                       External NOR

Important ownership rule

Do not concurrently use JLinkExe and GDB to control the same target. The session manager treats GDB as an owner of the live debug connection while a GDB session is active. Low-level one-shot J-Link operations should be used before/after the GDB session, or only when the session explicitly permits them.

STM32H7S3 memory-map facts

The STM32H7Rx/7Sx reference manual places the following windows in the Cortex-M7 address space:

• User flash: 0x08000000 upward.

• System flash: 0x1FF00000 to 0x1FF1FFFF.

• DTCM RAM: 0x20000000 to 0x2002FFFF.

• AXI SRAM starts at 0x24000000.

• SRAM1/SRAM2 are in the 0x30000000 region.

• XSPI1 window: 0x90000000 to 0x9FFFFFFF.

• XSPI2 window: 0x70000000 to 0x7FFFFFFF.

The address window does not prove that an external memory is fitted, initialized, or memory-mapped on your board. The board schematic and firmware configuration must determine the actual external NOR connection.

External NOR policy

External NOR is intentionally not treated as a generic internal-flash equivalent.

There are three different operations:

1. Read a memory-mapped NOR — requires the MCU's XSPI controller and pins to already be configured.

2. Program/erase NOR — requires a valid J-Link flash loader or a target-side programming mechanism for the exact flash/controller/board.

3. Probe/identify NOR — may require executing controller-specific commands or firmware; a CPU memory read alone is not sufficient.

external_flash_program and external_flash_erase are disabled unless explicitly enabled in configuration. Do not enable them merely because the CPU window is 0x70000000 or 0x90000000.

SEGGER documents an important distinction: VerifyBin performs a memory read/compare and does not initialize an external QSPI/XSPI interface; LoadFile can use a flash download/loader mechanism. Therefore this project does not claim that verifybin can independently access an uninitialized external NOR.

Hardware-profile sources

The checked-in STM32H7S3I8T6/XSPI1 values are based on the ST STM32H7S3I8 product/datasheet and RM0477 memory map, SEGGER's supported-device database, ST's NUCLEO-H7S3L8 documentation identifying the 256-Mbit NOR family, and Macronix documentation for the 512-Mbit density equivalent. The exact custom-board BOM and schematic remain the authoritative source for the assembled hardware.

Requirements

• Python 3.10+

• SEGGER J-Link Software and Documentation Pack

• J-Link probe

• ARM GDB (arm-none-eabi-gdb or gdb-multiarch)

• Optional firmware ELF with debug information

• Optional CMSIS-SVD file for peripheral/register semantics

SEGGER supports J-Link Commander and J-Link GDB Server on Linux and macOS.

Install

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -e ".[dev]"
cp config.example.yaml config.yaml

Edit config.yaml, then:

stm32-jlink-mcp

Configuration path can be overridden with:

export STM32_JLINK_MCP_CONFIG=/absolute/path/config.yaml

Direct hardware smoke test

Before involving MCP, validate J-Link itself:

JLinkExe
Device STM32H7S3I8
SI SWD
Speed 4000
Connect
Halt
Regs
Mem8 0x08000000, 0x40

SEGGER recommends specifying the target device explicitly because device-specific handling may be required during connect/reset.

MCP tool groups

Probe / target

• probe_list

• jlink_connect

• jlink_disconnect

• jlink_status

• target_identify

• target_status

• target_reset

• target_halt

• target_run

• target_step

Memory / registers

• memory_read

• memory_write

• registers_read

• register_read

• register_write

Internal flash

• flash_program

• flash_verify

• flash_erase

GDB / source debugging

• debug_start

• debug_stop

• debug_continue

• debug_pause

• debug_step

• debug_breakpoint_set

• debug_breakpoint_clear

• debug_watchpoint_set

• debug_watchpoint_clear

• debug_stop_reason

• debug_backtrace

• read_variable

ELF / SVD

• load_symbols

• resolve_address

• resolve_symbol

• svd_info

• peripheral_info

• register_info

• register_read

STM32 diagnostics

• stm32_fault_info

• stm32_snapshot

• stm32_reset_reason

• boot_diagnose

XSPI / external memory

• external_flash_info

• external_flash_read

• external_flash_test

• external_flash_program

• external_flash_erase

Workflows / expert escape hatches

• flash_and_verify

• diagnose_crash

• jlink_command (disabled by default)

Safety model

Configuration supports:

safety:
  mode: read_only

In read-only mode, target inspection and diagnostics remain available while writes/program/erase are denied.

Destructive or target-modifying operations can require exact confirmation tokens. The MCP server does not interpret a natural-language phrase such as "yes" as authorization.

Testing

Fast tests do not require J-Link hardware:

pytest
ruff check .

Hardware tests are marked separately:

pytest -m hardware

They are intentionally not part of normal CI unless a self-hosted runner with the required hardware is configured.

Project status

This is an engineering-focused v0.2 foundation. The core architecture is intended to be production-oriented, but board-specific external NOR programming still requires validation against the actual schematic, NOR part number, XSPI instance/configuration, and programming method.

Do not use this repository as a substitute for SEGGER documentation, the STM32 reference manual/datasheet, or your board's schematic.

RTT and deployment sequence

J-Link RTT is supported as a first-class diagnostic transport. The preferred board workflow is:

erase -> program -> verify -> RTT connect -> NRST pulse -> capture boot logs

Available MCP tools:

• rtt_connect

• rtt_read

• rtt_write

• rtt_disconnect

• nrst_assert

• nrst_release

• nrst_pulse

• program_verify_rtt_nrst

RTT uses SEGGER's local RTT TELNET transport and channel 0. When no GDB session is already active, the MCP starts a persistent J-Link GDB Server solely to maintain the J-Link connection required by RTT. If GDB is already active, RTT attaches to its configured RTT TELNET port.

See docs/RTT_AND_PROGRAMMING_SEQUENCE.md for ownership, reset, and RTT control-block guidance.

Option bytes

STM32H7S3 option-byte inspection is exposed separately from ordinary memory/register access.

Planned/guarded operations:

• option_bytes_read

• option_bytes_write

• option_bytes_mass_erase

Option-byte writes and mass erase are disabled by default in configuration because they are persistent device configuration changes. The implementation must use the STM32H7S3-specific FLASH option-byte sequence; it must not guess a generic J-Link Commander command or treat option bytes as ordinary RAM/register writes.

See docs/OPTION_BYTES.md.