mcjtag

What mcjtag does

Probe and Scan

Detect debug probes, enumerate JTAG chains, and identify connected chips by IDCODE. Supports DAP-Link, ST-Link, J-Link, and FTDI-based adapters through OpenOCD.

Memory and Registers

Read and write memory with hexdump formatting, access all CPU registers, and search memory for byte patterns. Alignment and range validation built in.

SVD Peripheral Decoding

Load CMSIS SVD files to decode peripheral registers down to individual bitfields. See exactly what GPIOA, USART1, or RCC are doing without consulting the datasheet.

Flash Programming

Program firmware images (.bin, .hex, .elf) with erase and verify steps, progress reporting, and file validation. Safe by default.

Quick start

# Install and run
uvx mcjtag

# Or with auto-spawned OpenOCD
OPENOCD_CONFIG=openocd-daplink-swd.cfg uvx mcjtag

A typical first session looks like this:

probe_diagnostics()             # verify everything works (9-point health check)
jtag_scan()                     # see what's on the chain
target_state()                  # check if halted or running
read_memory("0x08000000", 4)    # read the vector table
read_registers()                # see CPU state

The LLM sees structured responses for each call — addresses, hex values, decoded bitfields, formatted hexdumps — and can reason about the hardware state from there.

17 tools across 9 categories

Category	Tools	Purpose
Connection	connect, start_openocd, disconnect	Connect to or spawn OpenOCD, tear down sessions
Diagnostics	probe_diagnostics	9-point health check of probe, target, and capabilities
Target	target_state, target_control	Halt, resume, step, reset, query execution state
Memory	read_memory, write_memory, search_memory	Read with hexdump, write (SRAM-safe), byte pattern search
Registers	read_registers, write_register	Read all or specific CPU registers, write individual registers
Flash	flash_info, flash_program	Bank topology, program firmware with erase/verify
JTAG	jtag_scan, jtag_shift	Chain enumeration, raw IR/DR scan operations
SVD	svd_inspect	Load SVD files, list peripherals, decode register bitfields
Raw	raw_command	Direct OpenOCD TCL command escape hatch

Plus 7 resources for polling live state without tool calls (jtag://target/state, jtag://registers/all, jtag://flash/banks, and more) and 5 prompts that guide the LLM through common workflows like crash debugging and chip identification.

Safety by default

mcjtag is built for use alongside safety-critical firmware. It ships with conservative defaults that prevent accidental damage to your target:

• Memory writes restricted to SRAM by default (0x20000000-0x20100000). Flash, peripherals, and system registers are protected unless you explicitly widen the range.
• Destructive OpenOCD commands blocked in raw_command mode. Flash writes, memory writes, resets, and TCL metaprogramming are caught by a deny-list.
• Flash programming validates files before writing — checks existence, extension, and size. Progress is reported through erase, write, and verify phases.
• All safety rails are configurable via environment variables. See the Safety Configuration guide for details.

---

Hero image: Arshon Technology