DebugForge

Bridge Lauterbach TRACE32 to AI Agents via MCP

DebugForge is an MCP server that connects Lauterbach TRACE32 debuggers to AI agents.
It gives Claude Code, Codex, Qwen and other AI agents direct access to your hardware debugger
— enabling them to autonomously read target state, locate software bugs, and drive the fix-debug cycle end-to-end.
Supports both local and remote (WinRM/SSH) TRACE32 environments.

---

Highlights

• 47 MCP Tools — Full TRACE32 access for AI agents: execution control, breakpoints, memory, registers, variables, symbols, and more
• Autonomous Debugging — AI agents can independently connect to your target, reproduce issues, locate root causes, and suggest fixes
• Local + Remote — Debug locally or connect to a remote Windows TRACE32 via WinRM/SSH with full file transfer support
• Project-Aware — Configure once via debugforge.toml, your AI agent automatically knows your ELF paths, flash scripts, and TRACE32 setup
• Real Hardware — Battle-tested on TC397 TriCore via USB. Your AI agent controls actual silicon, not a simulator
• Advanced Breakpoints — Conditional, data watchpoints, hit-count, task-specific, action triggers, and temporary breakpoints
• Deep Inspection — AI agents can read call stacks with locals, expand structs, view disassembly, inspect peripherals
• Any MCP Agent — Works with Claude Code, Codex CLI, Qwen, or any MCP-compatible AI assistant
• Zero Lock-in — MIT licensed, open source, no vendor dependencies beyond TRACE32 itself

Architecture

┌─────────────────┐         MCP (stdio)         ┌──────────────┐       PYRCL/TCP       ┌──────────────┐
│                 │◄───────────────────────────►│              │◄─────────────────────►│              │
│   AI Agent      │   JSON-RPC tool calls        │  DebugForge  │   Remote Control API  │   TRACE32    │
│  (Claude Code,  │   (47 debugging tools)       │  MCP Server  │   (lauterbach-trace32 │  PowerView   │
│   Codex, etc.)  │                              │              │    -rcl)              │              │
│                 │◄───────────────────────────►│              │◄─────────────────────►│              │
└─────────────────┘         Results              └──────────────┘       Hardware         └──────┬───────┘
                                                                                               │
                                                                                        ┌──────▼───────┐
                                                                                        │   Target MCU  │
                                                                                        │  (e.g. TC397) │
                                                                                        └──────────────┘

Remote Mode

┌─────────────────────────────────────────────────────────────┐
│  Local Linux (Agent)                                        │
│  - Source/ELF/CMM files                                     │
│  - AI Agent (DebugForge MCP Server)                         │
└────────────────┬────────────────────────┬───────────────────┘
                 │ SCP/WinRM              │ PYRCL (port 20000)
                 │ File transfer          │ Remote control
                 ▼                        ▼
┌─────────────────────────────────────────────────────────────┐
│  Remote Windows                                             │
│  - TRACE32 PowerView                                        │
│  - Hardware target (TC38x/TC39x)                            │
└─────────────────────────────────────────────────────────────┘

Quick Start

# 1. Install DebugForge
pip install debugforge

# 2. Install TRACE32 Python package (from your TRACE32 installation)
pip install <YOUR_T32_PATH>/demo/api/python/rcl/dist/lauterbach_trace32_rcl-*.whl

# 3. Add to your AI agent's MCP config (e.g. .claude/settings.json)

{
  "mcpServers": {
    "debugforge": {
      "command": "debugforge"
    }
  }
}

# 4. Configure your project
cp debugforge.toml.example debugforge.toml
# Edit debugforge.toml with your paths and connection settings

# 5. Start TRACE32 with API port enabled, then ask your AI agent:
#    "Connect to TRACE32, load the firmware, find why the system crashes at boot"

Installation

Prerequisites

Requirement	Details
Python	3.10 or higher
TRACE32	PowerView running with Remote API enabled
PYRCL	lauterbach-trace32-rcl package from your TRACE32 installation

Step 1: Install DebugForge

pip install debugforge

Or install from source:

git clone https://github.com/YangPan2020/debugforge.git
cd debugforge
pip install -e .

Step 2: Install TRACE32 Python Library

The PYRCL wheel is bundled with your TRACE32 installation:

pip install <T32_INSTALL_PATH>/demo/api/python/rcl/dist/lauterbach_trace32_rcl-*.whl

Step 3: Enable TRACE32 Remote API

Add these lines to your TRACE32 configuration file (.t32 or config.t32):

RCL=NETTCP
PORT=20000

Then restart TRACE32 PowerView.

Configuration

Project Configuration (debugforge.toml)

Create a debugforge.toml in your project root. A complete template is provided:

cp debugforge.toml.example debugforge.toml

[mode]
mode = "local"  # "local" or "remote"

[connection]
node = "localhost"
port = 20000
protocol = "TCP"
auto_connect = true

[remote]
host = "192.168.1.100"
winrm_port = 5985
winrm_user = "user@domain.local"
winrm_password = "your_password"
ssh_user = "username"
staging_dir = "D:\\T32\\debugforge"

[project]
elf = "output/build/firmware.elf"

[scripts]
flash = "tools/Trace32/flash.cmm"

Note: debugforge.toml contains credentials and is gitignored. Never commit it.

MCP Client Setup

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "debugforge": {
      "command": "debugforge"
    }
  }
}

Claude Code (with auto-connect)

{
  "mcpServers": {
    "debugforge": {
      "command": "debugforge",
      "env": {
        "T32_AUTO_CONNECT": "true",
        "T32_PORT": "20000"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client can use DebugForge. Configure the command as debugforge with stdio transport.

Environment Variables

Environment variables override debugforge.toml values (highest priority):

Variable	Default	Description
T32_INSTALL_PATH	—	TRACE32 installation directory
T32_NODE	localhost	TRACE32 host address
T32_PORT	20000	TRACE32 API port
T32_PROTOCOL	TCP	Communication protocol (TCP/UDP)
T32_AUTO_CONNECT	false	Auto-connect on server start
DEBUGFORGE_CONFIG	./debugforge.toml	Path to config file

Available Tools (47)

Connection & Configuration

Tool	Description
connect	Connect to a TRACE32 PowerView instance
disconnect	Disconnect from TRACE32
status	Get connection status, TRACE32 version, and system state
get_project_config	Get the loaded project configuration (paths, scripts, settings)

Execution Control

Tool	Description
go	Start/continue program execution
step	Single-step execution (into, over, or out)
halt	Stop program execution
reset	Reset the target CPU
get_state	Get current CPU execution state
get_source_location	Get current source file and line
get_current_function	Get name of currently executing function
get_run_stats	Combined run/halt statistics

Breakpoints

Tool	Description
set_breakpoint	Set a program/read/write/readwrite breakpoint
list_breakpoints	List all active breakpoints
delete_breakpoint	Delete a breakpoint
clear_all_breakpoints	Delete all breakpoints at once
toggle_breakpoint	Enable/disable a breakpoint without deleting

Advanced Breakpoints

Tool	Description
set_conditional_breakpoint	Breakpoint with HLL condition (e.g., i > 100)
set_data_breakpoint	Trigger on memory access with optional value match
set_count_breakpoint	Stop after N-th hit (loop debugging)
set_task_breakpoint	Trigger only for a specific OS task/thread
set_action_breakpoint	Execute a TRACE32 command on hit
set_temporary_breakpoint	Auto-deletes after first hit

Memory

Tool	Description
read_memory	Read target memory (hex dump format)
write_memory	Write data to target memory
read_memory_cached	Read through CPU data cache
read_memory_physical	Read bypassing cache

Registers

Tool	Description
read_register	Read a single CPU register
read_registers	Read multiple registers at once
write_register	Write a value to a CPU register

Variables

Tool	Description
read_variable	Read a C/C++ variable by symbol name
write_variable	Write a value to a C/C++ variable
var_view	View a variable/struct/array with full expansion

Symbols

Tool	Description
symbol_by_name	Look up symbol address by name
symbol_by_address	Look up symbol name by address

Commands & Scripting

Tool	Description
execute_command	Execute any TRACE32 PRACTICE command
run_practice	Run a PRACTICE (.cmm) script with timeout
evaluate	Evaluate a TRACE32 expression or function

Debug Views

Tool	Description
get_callstack	Get call stack with function names
get_locals	Get call stack with all local variables per frame
get_data_dump	Formatted memory dump (hex + ASCII)
get_register_view	Full register view with all flags
get_window	Get text content of any TRACE32 window command

Multicore

Tool	Description
select_core	Switch debugger focus to a specific core
get_chip_info	Get chip stepping and configuration
get_all_cores_state	Get execution state of all cores
sync_cores	Synchronized Go/Break/Step across cores

On-chip Trace (MCDS)

Tool	Description
trace_start	Configure and start trace recording
trace_stop	Stop trace recording
trace_list	Display trace buffer contents
trace_clear	Clear trace buffer
trace_set_trigger	Set trace start/stop triggers

System Configuration

Tool	Description
set_reset_behavior	Configure reset handling
set_cache_read	Enable/disable cache-aware reads
set_peripheral_suspend	Suspend peripherals on halt
load_symbol_file	Load ELF debug symbols
get_system_options	Get all system option settings

Usage Examples

Basic Debug Session

You: "Connect to TRACE32 and help me find why the system crashes after boot"

AI Agent workflow:
  1. get_project_config()           → learns your ELF path and scripts
  2. connect()                      → connects to TRACE32
  3. run_practice("flash.cmm")      → flashes firmware
  4. set_breakpoint("main")
  5. go()                           → runs to main
  6. step("over")                   → steps through code
  7. get_callstack()                → analyzes the call stack
  8. read_variable("error_code")    → checks variables
  → "Found it: error_code = -1 because init_hardware() fails at line 84"

Remote Debug Session

You: "Connect to the remote TRACE32 on Windows and debug the TC397 board"

AI Agent workflow:
  1. get_project_config()           → detects remote mode, gets WinRM credentials
  2. connect(node="192.168.1.100")  → connects via PYRCL over network
  3. run_practice("tc39x_flash.cmm") → flashes via remote TRACE32
  4. go() → halt() → get_callstack()
  → Debugging the remote target as if it were local

Supported AI Agents

Agent	Status	Configuration
Claude Code	✅ Tested	.claude/settings.json
Codex CLI	✅ Compatible	MCP stdio transport
Qwen Agent	✅ Compatible	MCP stdio transport
Any MCP Client	✅ Compatible	Standard MCP protocol

File Structure

debugforge/
├── src/debugforge/          # MCP Server core
│   ├── server.py            # FastMCP server entry
│   ├── config.py            # Configuration (local + remote)
│   ├── state.py             # Connection state management
│   └── tools/               # Tool implementations (47 tools)
├── examples/                # Example scripts
│   ├── remote_debug.py      # Remote debug via WinRM + PYRCL
│   ├── remote_debug_tc38x.py
│   ├── test_all_tools.py    # Full tool verification
│   └── debug_tc397_live.py  # TC397 complete workflow
├── debugforge.toml.example  # Configuration template
├── WINDOWS_SSH_SETUP.md     # Remote Windows setup guide
└── README.md

Development

Setup

git clone https://github.com/YangPan2020/debugforge.git
cd debugforge
pip install -e ".[dev]"

Run Tests

pytest tests/ -v

Code Style

ruff check src/ tests/
ruff format src/ tests/

License

MIT — free for personal and commercial use.

---

_{Built with ❤️ for the embedded debugging community}