Mame

mame_mcp is a Model Context Protocol bridge for MAME-focused reverse engineering. It is aimed at arcade-to-SNES porting work: memory access traces, input injection, ROM audit checks, IO-port discovery, and reproducible headless harnesses.

Stock-MAME compatible — no custom MAME binary required. Two modes, both on stock MAME: the stateless tools drive MAME with generated -autoboot_script Lua sidecars (spawn, run, exit); the live session suite keeps a persistent MAME alive behind a bridge and exposes debugger-style live memory read/write, register access, run/pause, save/load state, and input injection across calls. A deeper MAME source fork is still only needed for the harder stuff (low-overhead instruction-trace ring buffers; device introspection Lua can't reach) — see Fork Roadmap.

Quick Start

python -m pip install -e .

$env:MAME_EXE = "/path/to/mame"      # or leave unset if mame is on PATH

mame-mcp-tools --names
mame-mcp-tools --category trace

Wire it into Codex or another MCP client:

{
  "mcpServers": {
    "mame": {
      "command": "mame-mcp-bridge",
      "env": {
        "MAME_EXE": "/path/to/mame"
      }
    }
  }
}

Restart the MCP client after editing its config.

This repo includes a generic .mcp.json that only starts the bridge. Pass system and rompath in each tool call, or set MAME_SYSTEM and MAME_ROMPATH in your local MCP config for the project you are inspecting.

Tools

Two families: stateless one-shot tools (each spawns MAME, does its job, exits) and a live session suite (one persistent MAME kept alive across calls — read/write/run/inject like a debugger). 25 tools total.

Stateless (one-shot)

Tool	Purpose
ping	Echo back an optional payload; verify the MCP bridge is alive.
config_check	Resolve MAME env/config paths and report which required pieces exist.
audit_romset	Run mame -verifyroms <system> and return the audit tail.
get_ioports	Boot a machine briefly and list MAME Lua IO-port fields (for input injection).
trace_memory_access	Install Lua read/write taps over CPU address ranges; log deduped accesses.
trace_cchip_superman	Superman helper: trace $900000-$900FFF C-Chip accesses + the $900803 status verdict.
run_lua_script	Run a caller-supplied MAME Lua autoboot script (by path), headlessly.
run_lua_inline	Run caller-supplied MAME Lua source (string, not a path); optional artifact read-back.
capture_leaf_io	Golden-vector capture for a pure leaf that transforms one word/byte in place — inject inputs via taps, record output+regs+CCR. Independent oracle for a transpiler differential harness.

Live session (persistent MAME, debugger-style)

Call mame_launch first (keeps MAME running across calls); the rest operate on that session.

Tool	Purpose
mame_launch	Launch a PERSISTENT live MAME (headless + bridge). Required before any other mame_* tool.
mame_session_status	Live session status (system, frame, paused).
mame_session_stop	Terminate the live session.
mame_pause / mame_resume	Pause / resume the machine (state stays readable while paused).
mame_run_frames	Run N frames then pause; returns the frame number.
mame_read_memory / mame_write_memory	Read / write a hex block in a device's program space.
mame_get_regs / mame_set_reg	Read all CPU registers (D0-D7/A0-A7/PC/SR/USP/…) / set one.
mame_save_state / mame_load_state	Save / load a MAME save state by name (needs stateDirectory).
mame_send_input	Set an ioport field value (e.g. Coin 1, P1 Right).
mame_exec_lua_live	Run Lua on the live machine (M/machine = manager.machine); returns its value.
mame_capture_game_tick	Run to the Nth GAME_TICK and snapshot regs + a memory region at the prologue read (lockstep primitive).
mame_drive_to_gameplay	Boot-aware drive to a running game: wait for idle, inject clean coin/start edges, confirm GAME_TICK (replay-robust where a fixed .inp desyncs).

The MCP responses return JSON text with command lines, log paths, return codes, stderr/stdout tails, and parsed trace summaries where applicable.

Environment

Env var	Default	Purpose
MAME_EXE	mame	MAME executable or command on PATH.
MAME_SYSTEM	none	Default machine short name, e.g. driver_short_name.
MAME_ROMPATH	none	ROM search path.
MAME_CWD	current directory	Working directory for generated scripts/logs and MAME state.
MAME_WORKDIR	<MAME_CWD>/.mame_mcp	Generated Lua, logs, nvram, cfg, etc.

Generic Trace Example

{
  "system": "driver_short_name",
  "rompath": "/path/to/roms",
  "frames": 1800,
  "ranges": [
    { "name": "device_window", "start": 9437184, "end": 9441279 }
  ],
  "trackReads": [
    { "name": "status", "address": 9439234 }
  ],
  "injectPreset": "none",
  "dryRun": true
}

trace_memory_access installs read/write taps over each range, dedupes by (R/W, PC, address, range), optionally counts values read from selected addresses, and writes a human-readable log plus a parsed JSON summary.

Use "dryRun": true to generate the Lua harness without launching MAME.

Superman C-Chip Helper

trace_cchip_superman is a convenience wrapper for the known Superman C-Chip window. It still requires the caller or environment to provide the ROM path.

{
  "rompath": "/path/to/roms",
  "frames": 1800,
  "injectPreset": "none"
}

It expands to a trace_memory_access call over $900000-$900FFF, tracking reads from $900802/$900803 and reporting whether status $01 and $05 were seen.

Fork Roadmap

The stock-MAME Lua layer can cover a lot:

• address read/write taps,
• frame callbacks,
• input-field injection,
• ROM audit and machine metadata,
• screenshots via MAME command-line/video options,
• reproducible generated scripts and logs.

Already delivered without a fork, via the live-session bridge (stock MAME + a persistent process): a long-lived session, debugger-grade live memory reads/writes, register get/set, run/pause, and save/load state (the mame_* tools above).

A true MAME source fork becomes worthwhile only for what Lua/the bridge can't do well:

• instruction trace ring buffers with low overhead,
• tile/sprite/sound device introspection not exposed through Lua,
• screenshot APIs as one-shot MCP calls.

The MCP tool names and response shapes here are intentionally similar to the Mesen MCP bridge so agents can learn one mental model and apply it to both console and arcade sources.