# TRACE32 MCP Server

An [MCP](https://modelcontextprotocol.io) server that wraps Lauterbach **TRACE32**'s
public remote API (RCL) via the official [`lauterbach-trace32-rcl`](https://pypi.org/project/lauterbach-trace32-rcl/)
(PyRCL) package. It lets an AI agent (e.g. **GitHub Copilot** agent mode) drive
TRACE32 PowerView for three MVP use cases:

- **Debugging** — read/write memory, registers and variables; run control (go / break / step); breakpoints
- **Resource inspection** — connection/run state, CPU, memory & register snapshots, PRACTICE function evaluation
- **Script execution & flash** — run PRACTICE `.cmm` scripts, including SW target flash

## Prerequisites

- Python 3.9+
- **TRACE32 PowerView already running** with the remote API (RCL) enabled.
  Add this to your `config.t32` (blank line before/after each block):

  ```
  RCL=NETTCP
  PORT=20000
  ```

  Sanity-check it works before wiring up MCP:

  ```
  t32rem localhost PRINT VERSION.SOFTWARE()
  ```

## Install

```bash
pip install -e .
```

## Configuration (environment variables)

| Variable | Default | Description |
|---|---|---|
| `T32_NODE` | `localhost` | PowerView host |
| `T32_PORT` | `20000` | RCL port |
| `T32_PROTOCOL` | `TCP` | `TCP` (recommended) or `UDP` |
| `T32_PACKLEN` | `1024` | UDP packet length (ignored for TCP) |
| `T32_TIMEOUT` | `10` | Connection/request timeout (s) |
| `T32_ALLOW_WRITE` | `false` | Enables `t32_write_memory`, `t32_write_register`, `t32_run_command`, `t32_run_script` |
| `T32_ALLOW_FLASH` | `false` | Enables `t32_flash` |

### Safety guards

All **read** and **debug-control** tools are always available. **Destructive**
operations are OFF by default and must be explicitly enabled:

- `T32_ALLOW_WRITE=true` → memory/register writes, arbitrary command passthrough, script execution
- `T32_ALLOW_FLASH=true` → flash programming (independent of `T32_ALLOW_WRITE`)

When a guard is closed, the tool returns an error explaining which flag to set —
it never silently touches the target.

## Register with GitHub Copilot (VS Code)

Workspace file [`.vscode/mcp.json`](.vscode/mcp.json) is included. Adjust the `env`
values (host/port, and the guard flags when you intend to write/flash), then start
the server from the MCP view or the `MCP: List Servers` command. You can also run it
standalone:

```bash
python -m trace32_mcp
```

## Tools

| Tool | Guard | Purpose |
|---|---|---|
| `t32_status` | — | Connection, run state, CPU, software build |
| `t32_read_memory` | — | Read N bytes → hex |
| `t32_read_register` / `t32_list_registers` | — | Read register(s) |
| `t32_read_variable` | — | Read an HLL variable/symbol |
| `t32_eval` | — | Evaluate a PRACTICE function expression |
| `t32_go` / `t32_break` / `t32_step` | — | Run control |
| `t32_set_breakpoint` / `t32_clear_breakpoint` / `t32_list_breakpoints` | — | Breakpoints |
| `t32_write_memory` / `t32_write_register` | `ALLOW_WRITE` | Write memory/register |
| `t32_run_command` | `ALLOW_WRITE` | Arbitrary TRACE32 command |
| `t32_run_script` | `ALLOW_WRITE` | Run a PRACTICE `.cmm` (`DO`) |
| `t32_flash` | `ALLOW_FLASH` | Program target flash via a flash `.cmm` |

## Tests

```bash
pytest
```

Unit tests mock PyRCL, so no running TRACE32 is required. For end-to-end checks,
the TRACE32 Instruction Set Simulator can stand in for real hardware.

## Roadmap (post-MVP)

Trace/CTS inspection, symbol/source browsing, multicore selection, call stack,
peripheral register views, structured variable trees, multi-instance routing.