rr-context-mcp

An open-source, local MCP server that gives coding agents a deterministic runtime record they can inspect and replay while diagnosing bugs. This first MVP uses Mozilla's rr engine and the official Python MCP SDK.

Existing-project review

This is a new implementation, not a fork. Both reference projects establish that rr can be made accessible to agents through MCP, so the useful design question is how to make the root-cause path clear and reliable.

Proposed architecture

Coding agent (Claude Code / Cursor / other MCP host)
       │ MCP stdio
       ▼
MCP tool layer (workflow-oriented, typed, small outputs)
       │
       ├── Capture adapter ── argv-only `rr record`
       ├── Trace catalog ──── local rr trace directories
       └── Replay adapter ─── `rr replay -s` + persistent GDB/MI2
                                  │
                                  └── structured evidence: stop, stack, locals, threads

The tool surface is deliberately small for an MVP:

Evidence and error contracts

Evidence contract version: v1. This is the current stable schema for rr_inspect and rr_move.

Successful rr_inspect and rr_move calls, including dry-run mode, return the same fields:

{
  "ok": true,
  "session_id": "rr-...",
  "frame": {
    "level": "0",
    "address": "0x4011a2",
    "function": "parse_packet",
    "file": "src/parser.c",
    "fullname": null,
    "line": "84"
  },
  "backtrace": [],
  "locals": [],
  "threads": [],
  "current_thread_id": "3",
  "stop_reason": {
    "reason": "signal-received",
    "signal_name": "SIGSEGV",
    "signal_meaning": "Segmentation fault",
    "thread_id": "3",
    "stopped_threads": "all",
    "frame": null,
    "details": {}
  },
  "position": {"event": 481, "ticks": 90214},
  "parse_warnings": []
}

Frame objects use fixed fields: level, address, function, file, fullname, and line; unavailable values are null. stop_reason uses fixed fields and retains stop-specific MI fields in details. position always contains numeric-or-null event and ticks. parse_warnings is empty for complete MI records. For incomplete records it contains { "parse_error": "...", "raw": "original MI line" }, while any successfully parsed evidence remains available in its regular field.

backtrace, locals, and threads are always arrays, including when GDB provides no entries. frame may be null when no frame is available. Live and dry-run paths use the same frame and stop-reason field names.

All tool errors use this shape, with code identifying invalid input, unavailable runtime, timeout, a stopped target interrupt request, or an unexpected internal error:

{ "ok": false, "error": { "code": "timeout", "message": "..." } }

Root-cause analysis should move from the observed failure toward the first event that violates an invariant. Agents can inspect at the crash, form a hypothesis, set a watchpoint on a value that should remain stable, and reverse-step or reverse-continue to identify the earlier mutation. Event/tick coordinates make observations easier to compare and cite. A future version can add direct event seeking, process selection, durable trace metadata, and automated evidence summaries without bloating the initial tool list.

MVP limits

• rr is Linux-only in normal use and has CPU/kernel/performance-counter requirements. Some virtual machines work only when performance counters are passed through.

• Recording captures the target process tree's execution. It does not capture arbitrary remote services or all machine state.

• Replay needs the executable that matches the recording. Debug symbols improve the quality of stack and local-variable evidence.

• The server can keep multiple replay sessions open in one MCP process, but process selection within a multi-process trace, checkpoints, and trace deletion are not implemented yet.

• The current execution wait is bounded by configurable forward/reverse timeouts; expired waits return a structured timeout error. rr_interrupt can send an asynchronous interrupt while a movement command is running.

• GDB/MI results are parsed into structured frames, locals, threads, stop reasons, and event/tick coordinates. Variable inspection still depends on symbols and the executable matching the trace.

• Expected tool failures are returned as JSON objects with ok: false and an error code/message. rr_environment reports missing binaries and a best-effort performance-counter check; only a real recording can confirm the host's full rr permissions.

• rr_record accepts an argv array and never runs a shell command. Build steps and shell pipelines must be represented by a wrapper executable/script or run separately before recording.

Related MCP server: cdp-tools-mcp

Requirements

• Linux supported by rr

• Python 3.11+

• rr and gdb on PATH

• rr hardware performance counter access configured for your environment

Check rr independently before connecting the MCP server. Replay opens the interactive debugger, so exit it after the smoke test:

rr record -o /tmp/rr-smoke -- /bin/true && rr replay /tmp/rr-smoke

rr may not work inside containers or VMs without the necessary performance-counter access. Consult the rr installation guide for your CPU and distribution.

Install from this checkout

Install the runtime package with pip:

python -m pip install .
rr-context-mcp

For development, install the optional test dependencies in an editable checkout:

python -m pip install -e '.[dev]'
pytest

Or install the local command into an isolated pipx environment:

pipx install .
rr-context-mcp

After a release is published to PyPI, users can run pipx run rr-context-mcp or uvx rr-context-mcp without installing it into a project environment.

On Windows, the venv activation command is .venv\\Scripts\\activate; the server itself still requires Linux and rr.

Run the mocked unit and MCP protocol tests:

pytest

The real rr smoke test is opt-in and requires Linux, rr, and working performance counters:

RR_INTEGRATION=1 pytest tests/test_rr_integration.py

Launch the stdio server directly:

rr-context-mcp

You can override rr's standard recording directory (~/.local/share/rr) with RR_TRACE_DIR=/path/to/traces.

Exercise the full MCP handshake and a sample crash-analysis workflow without rr/GDB:

rr-context-mcp --dry-run

The demo server does not record or replay an actual program. Its sample workflow starts at a SIGSEGV, returns full evidence, installs a cursor watchpoint, simulates a reverse continue to the earlier write, and produces a watchpoint-specific root-cause hint. Set RR_INTEGRATION=1 when running tests to opt into a real rr record/replay smoke test; the default suite remains fully mocked.

Claude Code configuration

From the repository root, use an absolute checkout path:

claude mcp add --transport stdio rr-context-mcp -- /absolute/path/to/rr-context-mcp/.venv/bin/rr-context-mcp

Or add a project-local .mcp.json:

{
  "mcpServers": {
    "rr-context-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/rr-context-mcp/.venv/bin/rr-context-mcp",
      "env": {
        "RR_TRACE_DIR": "/home/you/.local/share/rr"
      }
    }
  }
}

Cursor configuration

Add a project .cursor/mcp.json (or use Cursor's MCP settings UI):

{
  "mcpServers": {
    "rr-context-mcp": {
      "command": "/absolute/path/to/rr-context-mcp/.venv/bin/rr-context-mcp",
      "env": {
        "RR_TRACE_DIR": "/home/you/.local/share/rr"
      }
    }
  }
}

Restart or reload the MCP connection after changing configuration. For other stdio MCP clients, configure the same executable and environment.

Typical agent workflow

1. Build the program with debug symbols and reproduce the problem once with rr_record, passing the executable and arguments separately.

2. Start replay with the returned trace_path and the matching executable.

3. Inspect the stop, stack, locals, and threads. Set a breakpoint or evaluate the suspect value.

4. Use rr_move with reverse_step or reverse_continue to identify when the incorrect value was created; move forward to confirm the causal path.

5. Report the observed evidence and close the session.

The server includes an rr://guide resource with this workflow.

Development status

This is a runnable MVP. It includes the official MCP SDK, tolerant GDB/MI parsing with partial data and original text for malformed records, fully structured inspect/move evidence, stale-stop-resistant bounded execution waits, asynchronous interrupts, multiple replay sessions, capability diagnostics, watchpoints, symptom-specific investigation hints, and a demo mode. Ten realistic MI fixture lines cover stacks, locals, threads, watchpoints, signals, breakpoints, stream output, and truncated data. Unit and protocol tests run without rr hardware. Real capture/replay remains host-dependent and is covered by an opt-in RR_INTEGRATION=1 smoke test.

License

MIT