ude-mcp

English | 中文

Drive the PLS UDE® (Universal Debug Engine) debugger from an AI agent or from your shell. One core, two frontends: an MCP server and a plain CLI — the CLI is handy when no MCP client is around (or the other way).

Works against real hardware over DAS/JTAG, not just the simulator.

Verified on hardware

The test bench: Infineon AURIX TC364 TriBoard (SAK-TC364DP-64F300F), UDE Starterkit 2021 (build 8417), DAS over JTAG, Windows 11. This tool has been the daily flash-and-debug loop of a real TriCore firmware project for weeks of bring-up and regression. Every claim below traces to bench runs — the counts are bridge.call sites in the bench scripts that ran against the board.

Feature	TC364 hardware	Notes
Session start (launch UDE + inject bridge agent)	✅ verified	every bench session
Connect via DAS, with retry	✅ verified	40+ connects incl. flaky-DAS recovery
Flash (LoadAndFlash, retried)	✅ verified	7+ flash+verify runs; this ritual is what flash runs
Reset + post-flash reset×N cycles	✅ verified	TC3xx comes up broken without them
Go / halt	✅ verified	~80 / ~10 uses
Status snapshot (cores, run state)	✅ verified
mem_read 32-bit — halted and while running	✅ verified	SFRs (port OUT), CAN node regs (CCCR/PSR/ECR/IR/TXBRP/TXBTO), CAN message RAM
mem_write 32-bit (RAM)	✅ verified	runtime variable patching
reg_read (PC)	✅ verified
var_read (UDE expression evaluator)	✅ verified	sampled a FreeRTOS task counter on the live target
Symbol read via linker map (read g_var)	✅ verified	8225-symbol HighTec map, width derived from symbol size
CLI one-liners (read on live board)	✅ verified	2026-09-22

TSIM simulator only (prototype e2e): wait_halt, struct-member var_read.

Implemented but not yet exercised on real hardware — use with care, PRs with bench evidence welcome:

step · breakpoints (bp_*) · callstack · eval · var_write · load_program · disconnect · 8/16-bit memory widths

How it works

UDE Starterkit cannot be automated from outside its process (the COM launcher is not shipped/registered in the free toolchain), so ude-mcp injects a JScript bridge agent into UDE as a startup macro (UDE.exe -s<agent.js>). The agent binds to the live UDE object model and talks back over localhost HTTP long-polling:

AI client ⇄ (MCP/stdio or CLI) ⇄ ude-mcp (Python) ⇄ (localhost HTTP) ⇄ bridge.js (in UDE) ⇄ UDE object model ⇄ target

Everything uses officially supported UDE mechanisms (startup macros + the COM object model) — no patching, no unsupported hacks. See docs/api-selection.md.

The reliability rituals (why it works on a real bench)

These live in core.py, shared by CLI and MCP, instead of rotting in ad-hoc scripts:

1. Leaked UDE instances hold the DAP. flash kills leftovers first.
2. DAS connect is flaky. Connect is retried with backoff (default 3×).
3. LoadAndFlash often fails on the first attempt after a fresh connect. Retried with a halt between attempts (default 4×).
4. TC3xx comes up with weird bugs unless reset several times after flashing. Every flash ends with reset+go cycles (default 3).

Setup

Prerequisites: Windows, UDE Starterkit installed, uv.

uv sync

One-time config — ~/.ude-mcp.conf (or ./ude-mcp.conf), flat key = value:

wsx = C:\path\to\workspace.wsx            # UDE workspace
cfg = C:\path\to\TriBoard_TC36xA.cfg      # or a target config to create one
elf = C:\path\to\project.elf              # default for flash
map = C:\path\to\project.map              # linker map for symbol reads
resets = 3

Missing ude_exe is resolved from UDE_MCP_UDE_EXE, then known install paths. Every key can be overridden per-invocation (--wsx/--cfg/--elf/--map/--ude-exe/...), before or after the subcommand.

CLI

uv run ude-mcp-cli flash                  # connect -> halt -> flash -> reset x3 -> run
uv run ude-mcp-cli flash other.elf --resets 5
uv run ude-mcp-cli read g_app_status 0xD0000000    # target keeps running
uv run ude-mcp-cli watch g_app_speed --interval 0.5
uv run ude-mcp-cli write g_some_var 0
uv run ude-mcp-cli runctl go|halt|reset
uv run ude-mcp-cli status
uv run ude-mcp-cli symbols '^g_app'       # offline map search, no UDE started

Notes:

• read/watch never halt the target — DAP reads work while it runs.
• Symbol width (8/16/32) comes from the map's size column; force with --width.
• flash kills leaked UDE instances first; --no-kill keeps your GUI session.
• watch --json emits machine-readable lines for scripts.

MCP server

{
  "mcpServers": {
    "ude": {
      "command": "uv",
      "args": ["--directory", "path/to/ude-mcp", "run", "ude-mcp"]
    }
  }
}

Same core, same rituals. Tools: ude_session_start (kill_existing, connect), ude_flash (retries + reset cycles built in), ude_read_symbol (map-based, width-aware), ude_symbols, run control (ude_go/halt/reset/ reset_and_run/step/wait_halt), ude_bp_*, ude_var_read/var_write, ude_reg_read/write, ude_mem_read/write, ude_callstack, ude_eval, ude_status. Failures surface as tagged errors — [connect], [flash], [mem], [symbol] — instead of silent Nones.

Layout

src/ude_mcp/
  bridge_server.py  localhost HTTP broker <-> in-UDE JScript agent
  session.py        UDE process + bridge agent lifecycle
  core.py           high-level API: the bench rituals (connect/flash/read)
  symbols.py        GCC/HighTec .map parser — symbol -> address/width, offline
  config.py         conf-file/env discovery
  cli.py            command-line interface
  server.py         MCP server (thin wrappers over core)
tests/test_offline.py  no-UDE self-checks (CI runs this)
scratch/              bench history: the scripts that produced the evidence

License

MIT