Pyromaniac

Introduction

The Pyromaniac MCP server lets an MCP client (Claude Code, Claude Desktop, the API's MCP connector, ...) drive a RISC OS Pyromaniac instance directly: run commands, read/write files, take screenshots, and inject keyboard/mouse input.

It builds on two mechanisms Pyromaniac already provides:

• The command server (pyro-server/pyro-client) - a persistent RISC OS environment you can send * command lines to and get streamed output and a return code back.
• The sysrq server - a line-based protocol for discrete, out-of-band operations (filesystem, input, config, reset/terminate, ...) independent of running a command.

Unlike those tools, the MCP server owns the Pyromaniac process itself: it launches pyro_server.py as a subprocess with both sockets enabled, and can stop and relaunch that process entirely, not just reset the RISC OS environment running inside it.

Requirements

Install the MCP Python SDK and PyYAML:

$ pip install -r scripts/pyro-mcp/requirements.txt

If you're working from a built/installed Pyromaniac archive (the one crosscompile/Makefile's cross_install produces, alongside pyro, pyro-server and pyro-client) rather than a source checkout, use the pyro-mcp command it ships instead: it builds and caches its own Python 3 virtualenv from pyromaniac-resources/pyro-mcp/requirements.txt (separate from the Python 2.7 environment pyro/pyro-server/pyro-client use, since the MCP SDK and PyYAML are Python 3 only), also ensures that Python 2.7 environment exists and is on PATH (needed because pyro_mcp.py launches pyro_server.py as a subprocess via its shebang line), then runs pyro_mcp.py. PYROMCP_ENVDIR overrides where that Python 3 environment lives, the same way PYROMANIAC_ENVDIR does for the Python 2.7 one. In that case, substitute pyro-mcp for python3 scripts/pyro-mcp/pyro_mcp.py everywhere below.

Configuration (environment variables)

Wiring into MCP clients

All of these register the same command as a stdio MCP server: python3 scripts/pyro-mcp/pyro_mcp.py. Run it from whatever directory you want the RISC OS native filesystem to see (typically the project you're working on) - pyro_server.py inherits that directory unchanged, and it's what filesystem.native_directory's default ('.') resolves against, so this is how your own files stay reachable rather than hidden behind the Pyromaniac checkout. PYROMCP_PYRO_SERVER doesn't need to be an absolute path for this to work - it's resolved relative to this script's own location, not the launch directory - but set it explicitly if pyro_server.py isn't where the default expects. Run it standalone for a quick smoke test of the server itself (it will just sit waiting for stdio JSON-RPC input):

$ python3 scripts/pyro-mcp/pyro_mcp.py

Claude Code

Register it against your user, not a single project, so it's available in every checkout: from a terminal (or via ! inside an interactive session):

$ claude mcp add pyromaniac -s user -- python3 scripts/pyro-mcp/pyro_mcp.py

This is CLI-only - there is no in-chat/slash-command equivalent. The in-chat /mcp command manages servers already configured this way (status, OAuth, tool listing); it can't register a new one. -s/--scope controls where claude mcp add writes the definition: user (~/.claude.json, just you, all projects - what we want here), local (default when -s is omitted, also ~/.claude.json, but just you and this project), or project (.mcp.json, shared via git - copy scripts/pyro-mcp/mcp.json.example to .mcp.json if you want it checked in for a team instead). Other subcommands: claude mcp list, claude mcp get <name>, claude mcp remove <name>.

Codex CLI

$ codex mcp add pyromaniac -- python3 scripts/pyro-mcp/pyro_mcp.py

codex mcp add writes to ~/.codex/config.toml (user scope) by default - no flag needed, that's what we want here. A project-scoped .codex/config.toml also exists (trusted projects only) and overrides the user one, so don't create one for this unless you deliberately want a per-project override. Either way the section name is mcp_servers with an underscore, not mcp-servers:

[mcp_servers.pyromaniac]
command = "python3"
args = ["scripts/pyro-mcp/pyro_mcp.py"]

OpenCode

There's no add subcommand or scope flag - it's just which config file you edit. Add to ~/.config/opencode/opencode.json (global, tied to you across all projects - what we want here) rather than a per-project opencode.json in a project root (which would take precedence over the global one if both define the same server), under mcp, with command as an array and type: "local":

{
  "mcp": {
    "pyromaniac": {
      "type": "local",
      "command": ["python3", "scripts/pyro-mcp/pyro_mcp.py"],
      "enabled": true
    }
  }
}

Gemini CLI

gemini mcp add defaults to project scope (.gemini/settings.json), so add -s/--scope user explicitly to tie it to you instead, across all projects:

$ gemini mcp add -s user pyromaniac python3 scripts/pyro-mcp/pyro_mcp.py

or edit ~/.gemini/settings.json (user - what we want here) directly:

{
  "mcpServers": {
    "pyromaniac": {
      "command": "python3",
      "args": ["scripts/pyro-mcp/pyro_mcp.py"]
    }
  }
}

Antigravity

In the IDE: open an Agent session, use the ... dropdown in the side panel, choose MCP Servers to open the MCP store, then Manage MCP Servers → View raw config and add the same mcpServers block shown above for Gemini CLI. This edits mcp_config.json, typically under ~/.gemini/config/ (or ~/.gemini/antigravity/ on some installs) - the same file is picked up by both the Antigravity CLI and IDE. Unlike Gemini CLI/Qwen Code, there's no separate project-scoped file here - this config is already tied to you across all projects, so no scope flag or choice of file is needed.

Qwen Code

$ qwen mcp add pyromaniac python3 scripts/pyro-mcp/pyro_mcp.py

qwen mcp add defaults to user scope (~/.qwen/settings.json) - no flag needed, that's what we want here - unlike Gemini CLI, whose default is the other way round. A project-scoped .qwen/settings.json also exists (qwen mcp add -s project ...) if you deliberately want a per-project override; either way it's the same mcpServers structure shown above for Gemini CLI (Qwen Code is a fork of Gemini CLI and shares its config format).

Process lifecycle

The server launches Pyromaniac lazily, on the first tool call, rather than requiring an explicit "start" step. pyro_server.py runs its command socket permanently - it does not depend on a driven -- <command> process to stay alive - and, given sysrqserver.enable=true, the sysrq socket alongside it. Closing its stdin is its designed-in clean shutdown signal (it issues a sysrq system-terminate internally and exits with return code 0), which is what the MCP server uses in preference to a signal wherever it can.

The instance defaults to graphics.implementation=cairo, so riscos_screenshot() works out of the box (the default null implementation can't render anything). This is only a default, not a forced value: since a manual --config always wins over --config-file regardless of order, the MCP server only passes it when the config file doesn't already set graphics.implementation itself - so riscos_config_set('graphics.implementation', ..., persist=True) (or editing the config file directly) does take effect on the next riscos_restart(), overriding the built-in default rather than being silently overridden by it.

pyro_server.py is launched without an explicit cwd=, so it inherits pyro_mcp.py's own working directory unchanged - whatever directory the MCP client actually started it in. This matters because filesystem.native_directory defaults to '.', resolved against that inherited directory: it's what makes the native filesystem land on your own project rather than the Pyromaniac checkout. A user-scoped registration (see "Wiring into MCP clients" above) still gets this right per project, since the MCP client itself launches the server with its own current project directory as the cwd - the user scope only controls where the registration lives, not what directory the server runs in.

Tools

See "Debugging tools" below for response shapes and the semantics behind break-tagged watchpoints/tracepoints/switraps.

Sysrq requests and the idle emulation loop

Sysrq requests (used by the config tools and, in later stages, the filesystem/input tools) are only drained while the RISC OS emulation loop is actively running - normally while a riscos_run() command is executing. Without help, a request sent while the instance sits idle between commands would simply queue up unserviced. pyro_server.py's idle wait loop is patched to drain the sysrq queue itself so these tools work at any time, not just mid-command.

This idle draining is deliberately conservative for the two sysrqs that raise a control-flow exception rather than just replying (system-reboot and system-terminate): outside of an active command's execution context there is no safe way to perform Pyromaniac's normal in-place reboot handling, so if one of those arrives while idle, the process exits cleanly instead (riscos_reset() detects this and relaunches automatically, reporting warm=False). A reset requested while a command is running - including a stuck one - is unaffected by this and still gets a genuine warm reboot, since the emulation loop also drains sysrqs on every instruction while it's busy.

Debugging tools

Pause semantics: boundary-granularity, not instruction-exact

riscos_debug_pause() and a break-tagged watchpoint/tracepoint/switrap both work by setting state that Pyromaniac's emulation loop (RISCOS.emulate()) checks at the top of its own loop - the same boundary every sysrq is already limited to. This means:

• riscos_debug_pause() is asynchronous: it returns immediately, but the actual halt only takes effect the next time the emulation loop reaches its check (typically very soon - a SWI call, exception, timer tick, or a break-tagged hit - but not necessarily the very next instruction). Poll riscos_debug_status() to confirm the CPU has genuinely stopped before trusting that registers/memory reflect a fully paused state.
• A break-tagged watchpoint or address-based tracepoint halts the CPU before it has advanced past the instruction that triggered it - a watchpoint's memory hook fires as the access completes, a tracepoint's code hook fires before the instruction executes. Simply calling riscos_debug_resume() would therefore re-trigger on the exact same access, forever. To avoid this, riscos_debug_resume() removes a watchpoint or address-based tracepoint that caused the pause as part of resuming - call riscos_debug_watchpoint('add', ...) /  riscos_debug_tracepoint('add', ...) again to re-arm it for the next hit. Pattern-based tracepoints (a function-name pattern rather than a literal address) are left alone, since the literal address that fired can't be matched back to the pattern that added it.
• A break-tagged SWI trap is different: it's triggered from plain SWI-dispatch code rather than an in-flight CPU hook, so resuming is genuine forward progress, not a same-instant re-trigger - it is not disarmed automatically, and fires again on every further call to the same SWI. Call riscos_debug_switrap('remove', swi) explicitly to stop that.

Ticker/IRQ suspension whilst halted

Any debug halt - riscos_debug_pause(), a break-tagged watchpoint/ tracepoint/switrap, or a riscos_debug_step() boundary - suspends the system ticker and defers hardware IRQ delivery for as long as the halt lasts, restoring both only on a genuine riscos_debug_resume() (not on taking a further step). A pending IRQ is queued rather than dropped, and delivered once execution actually resumes. Without this, a halt lasting any real length of time (or a single-step session taking many steps) would let ticker/IRQ events queue up and land all at once the moment execution continued.

Single-instruction stepping

riscos_debug_step(mode='into', count=1) steps one or more real ARM instructions, in one of two modes:

• 'into' - every instruction is stepped one at a time, including the first instruction of any real ARM code a SWI ends up invoking (a claimed vector, a callback, ...).
• 'over' - a SWI call runs to completion as a single atomic step, regardless of how much ARM code it invokes internally; only ARM instructions outside of SWI dispatch are stepped one at a time. This needs no return-address breakpoint and no special-casing for  OS_WriteS (which advances the PC past an embedded string, not by a fixed amount) or OS_CallASWI/OS_CallASWIR12 (which resolve their target SWI dynamically from a register) - by the time a SWI's Python handler returns, any real ARM code it invoked has already run to completion via its own recursive execute()/emulate() call, so the PC is already correct.

Like riscos_debug_pause(), this is asynchronous: it returns immediately, and the step(s) only complete the next time the emulation loop reaches a step boundary. Poll riscos_debug_status() - reason will be 'step', with info containing {'kind': 'instruction'|'swi', 'address': ...} - to confirm before trusting registers/memory. A count > 1 request may complete fewer steps than asked if something else interrupts it first (e.g. a break-tagged watchpoint/tracepoint/ switrap firing part way through). Interrupts are never stepped into - see "Ticker/IRQ suspension whilst halted" above.

Backtrace availability

riscos_backtrace() reports {available: bool, lines: [...]}. available: False means the current register state doesn't look like a C-style stack frame (a C module in SVC mode, or user mode) - not that the call stack is genuinely empty, which the underlying frame-pointer walker can't actually distinguish from "unavailable". Treat available: False as "can't tell right now", e.g. because execution paused somewhere that isn't in C code with a conventional frame pointer set up.

Tracing debug options vs. watchpoints/tracepoints/switraps

riscos_debug_option() is a different layer from riscos_debug_watchpoint()/tracepoint()/switrap(): those observe RISC OS execution at specific addresses/patterns/SWIs you name, whereas riscos_debug_option() flips Pyromaniac's own built-in tracing hooks - the same set *PyromaniacDebug and --debug control - which apply globally rather than to a location you pick. traceblock in particular is the one most useful for "where did execution actually go before this failed" style questions, since it remembers where each executed code block was for better exception/error reporting, at a much lower cost (~1.2x slowdown) than full instruction tracing (trace, ~60x). See pyromaniac/trace.py's module docstring for the complete option list and what each one costs.

Enabling an option that isn't registered (a typo, or one gated behind a feature not built into this instance) is accepted without error by the underlying system - it's recorded as requested, but has no effect since there's no hook to call - so riscos_debug_option() reports ok: False and a None state in that case, to make the difference visible rather than silently doing nothing.

Breaking on exceptions and errors

Two debug options are boolean halt switches rather than tracing flags, enabled/disabled the same way as any other riscos_debug_option() entry:

• breakexception halts on a genuinely unclaimed CPU exception - a branch through zero (a call through a NULL pointer), a data abort, a prefetch abort, or an undefined instruction that nothing (not even the FP emulator) claimed. The halt happens at the point Pyromaniac's own fallback handling (RISCOS.exception_dispatch()) is about to raise the exception through to RISC OS's environment handler (DataAbortHandler,  UndefinedHandler, ...) - so registers/memory reflect the exception having just been entered (abort-mode CPSR, LR pointing back at the faulting code, riscos_backtrace() from there), before that handler's own code runs, not instead of it: resuming lets it proceed normally. Deliberately does not fire on the earlier, raw point where an undefined-encoding instruction is first noticed (before the Kernel/FP emulator/any other vector claimant has had a chance to handle it) - breaking there would trip on every ordinary FP instruction, since the FP emulator's own instructions look identical to a genuinely undefined one until it has actually run.
• breakerror halts when any RISC OS error is generated by a genuine SWI call (an actual ARM SWI instruction dispatched through  Kernel.swi_dispatch()), regardless of X-bit hiding - both an X-bit-hidden error (which would otherwise just silently set the V flag and continue) and a propagating non-X error trigger it, since  Trace.swi_leave() (where this is checked) runs either way. Halts before the error is delivered to a non-X caller's ErrorV/error environment handler. Only covers the SWI-dispatch path - a few internal Pyromaniac helpers used by pure-Python *command implementations (e.g.  *Delete's "file not found") construct and raise a RISCOSError directly without going through Kernel.swi_dispatch(), and aren't covered, since there's no X-bit distinction being made there in the first place.

Both report through riscos_debug_status() exactly like any other pause - reason is 'exception' or 'error', with info giving {'label': ..., 'address': ...} (label is the exception name for 'exception', or the SWI name for 'error', which also adds 'errnum'/'errmess'). Neither needs disarming on riscos_debug_resume() the way a watchpoint/tracepoint does - the triggering condition doesn't repeat merely by resuming past it, so plain resume is enough.

Breakpoints are tracepoint sugar

Pyromaniac has no separate breakpoint mechanism. riscos_debug_breakpoint is implemented entirely as sugar over riscos_debug_tracepoint with actions='break' - action='list' just filters tracepoints down to the ones tagged break. Anything documented above about tracepoints (including the resume-disarms-it behaviour) applies equally to breakpoints.

Response shapes

Most debugging tools return small dicts built from the underlying debug-*/watchpoints-*/tracepoints-*/switraps-* sysrq replies (dict-shaped replies parsed via parse_sysrq_dict(); list-shaped replies split on newlines). Notable shapes:

Comparison with RPCEmu Extended's MCP debug tools

Pyromaniac's debugging tools are inspired by (and named to loosely match) the riscos_debug_* tool set in RPCEmu Extended's MCP server (rpcemu-extended/tools/mcp/), but the two aren't wire-compatible - they sit on genuinely different architectures (a sysrq-based control channel here, vs. RPCEmu's dedicated DebugCmd socket) and diverge where that difference matters: