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

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 = "[email protected]"
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

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

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

Environment Variables

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

Available Tools (47)

Connection & Configuration

Execution Control

Breakpoints

Advanced Breakpoints

Memory

Registers

Variables

Symbols

Commands & Scripting

Debug Views

Multicore

On-chip Trace (MCDS)

System Configuration

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

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}