Mesen For Ai

mesen-for-ai is an MCP server that lets AI agents drive Mesen headlessly for console reverse engineering and game conversion work.

It does not port or vendor Mesen. It launches an existing Mesen/MesenCE binary, runs bridge.lua inside the emulator, and exposes the debugger-facing Lua API over MCP JSON-RPC on stdio.

If you are an LLM, read this first: AGENTS.md.

Supported Systems

Use this project for Mesen systems where the required debugger surface is available:

• SNES / Super Nintendo
• NES / Famicom
• PC Engine / TurboGrafx-16, including CD-ROM² cue sheets
• Game Boy Advance

The Code/Data Logger is available for SNES PRG ROM, NES PRG/CHR ROM, PC Engine PRG ROM, and GBA PRG ROM. Mesen emulates more systems, but this project does not promise CDL coverage for Master System, Game Boy, or WonderSwan because Mesen does not register those CDL loggers.

Requirements

• Python 3.11 or newer.
• xvfb-run on Linux for headless Mesen execution.
• A Mesen or MesenCE build with --testrunner support and Lua socket support.
• Set MESEN_BIN to the Mesen executable you want to use.

Example:

export MESEN_BIN=/path/to/Mesen

The local wrapper has a development default for MESEN_BIN, but public use should set the variable explicitly.

PC Engine CD sessions also require a user-supplied System Card 3 image. The runner copies it into the isolated session home and Mesen verifies its hash:

export MESEN_PCECD_FIRMWARE=/path/to/syscard3.pce

Run the MCP Daemon

From a checkout:

PYTHONPATH=src python3 -m mesen_mcp.daemon

The daemon speaks MCP-style JSON-RPC 2.0 over its own stdio. Mesen stdout and stderr are not part of the MCP protocol; Mesen talks to the daemon through a per-session TCP socket opened by bridge.lua.

Headless Runner

You can run a Lua testrunner script directly:

MESEN_BIN=/path/to/Mesen ./scripts/run_headless.sh <rom> <script.lua>

The runner creates an isolated Mesen home and writes deterministic settings:

• Lua IO/OS access enabled.
• Lua network access enabled for the socket bridge.
• deterministic RAM power-on state for SNES, NES, PC Engine, GBA, and Game Boy.
• a standard two-button controller on PC Engine port 1.
• NES mapper and CPU/PPU alignment randomization disabled.

Set MESEN_PCE_TURBOTAP=1 when a PC Engine verification needs two players. The isolated session then uses a TurboTap with standard two-button controllers on subports 0 and 1; input.set addresses them with port=0, subport=0/1. MesenCE 2.2.1 also needs patches/mesence-lua-input-subport.patch: its LuaApi::SetInput first requires three parameters and then grows the Lua stack to four, shifting the values read by LuaCallHelper. Removing that second stack adjustment makes the requested TurboTap subport reach the input manager.

For a deterministic RAM smoke test:

MESEN_BIN=/path/to/Mesen MESEN_MCP_FRAMES=60 MESEN_MCP_DUMP_PATH=/tmp/ram-a.bin \
  ./scripts/run_headless.sh /path/to/game.sfc scripts/dump_ram.lua
MESEN_BIN=/path/to/Mesen MESEN_MCP_FRAMES=60 MESEN_MCP_DUMP_PATH=/tmp/ram-b.bin \
  ./scripts/run_headless.sh /path/to/game.sfc scripts/dump_ram.lua
cmp /tmp/ram-a.bin /tmp/ram-b.bin

MCP Tools

Implemented tools:

• session.load_rom, session.info, session.reset, session.shutdown
• run.step_frames, run.status
• input.set, input.get
• video.export_frame
• cpu.registers, cpu.read_memory, cpu.write_memory
• console.state for the held machine's complete serialized scalar state, including NES PPU VideoRamAddr, TmpVideoRamAddr, ScrollX, and WriteToggle
• watch.create, watch.list, watch.delete
• breakpoint.create, breakpoint.list, breakpoint.delete
• cdl.start, cdl.stop, cdl.get, cdl.export
• trace.start, trace.stop, trace.list

session.load_rom accepts normal ROM files and ZIP archives. For ZIPs, the daemon extracts the single supported ROM member into the session temporary directory, launches Mesen against that extracted file, and removes it on session.shutdown.

Mesen accepts PC Engine CD media as a .cue plus its referenced track files. For those sessions, pceCdromRam exposes the CD unit RAM and pceCardRam exposes the 192 KiB Super CD-ROM² RAM supplied by System Card 3, in addition to the usual pceMemory, pceWorkRam, and pcePrgRom aliases. pceArcadeCardRam separately exposes the 2 MiB Arcade Card expansion RAM when that hardware is active. pceAdpcmRam, pceVideoRam, pceSpriteRam, and pcePaletteRam expose the remaining asset-bearing memories needed to verify audio and graphics extraction. Disc images and System Card firmware remain private inputs and are never copied into this repository.

Start deterministic PC Engine CD evidence from a new session and advance with reset=false. In the source-built MesenCE version validated here, calling emu.reset() from the bridge after a cue sheet has started closes the testrunner instead of returning a frame response. A fresh isolated session supplies the cold-boot boundary without that reset call.

PC Engine CD READ(6) compatibility patch

MesenCE commit 20ba206cef5ba207c21203176d02cb9f43dda9fb treats a zero READ(6) transfer-length byte as an empty request. SCSI READ(6) defines that byte as 256 sectors, and commercial PC Engine CD software can depend on it. Apply patches/mesence-pce-read6-zero-length.patch to that revision before building:

git apply /path/to/mesen-for-ai/patches/mesence-pce-read6-zero-length.patch
git apply /path/to/mesen-for-ai/patches/mesence-lua-input-subport.patch
make core -j4
make ui

The patch widens the saved sector counter to 16 bits and maps command byte zero to 0x100. It was validated with the Japanese PC Engine CD release of World Heroes 2: command 08 00 22 78 00 00 transfers sectors 8824 through 9079 and allows the original post-versus loader to reach CPU $C15B. No game bytes or firmware are included here.

For deterministic evidence runs, call run.step_frames with reset=true. That makes reset plus N frames one bridge operation and avoids variable frames between separate MCP calls. A newly loaded ROM is held before its first frame starts until that explicit run request, so watches and CDL can be armed without recording an uncontrolled pre-reset interval.

input.set latches named controller buttons and applies them from Mesen's inputPolled callback, which is the only safe point for scripted input. Change the latch while held at a frame boundary, then advance the intended number of frames. video.export_frame writes the held rendered frame as binary P6 RGB.

Code/Data Logger Semantics

Mesen's Lua API exposes getCdlData; it does not expose a logger on/off switch. cdl.start and cdl.stop are MCP-side window markers only. Collection is continuous inside Mesen.

The Lua getCdlData table is zero-indexed even though ordinary Lua arrays are usually one-indexed. The bridge preserves physical ROM offset zero as JSON element zero; do not add an index adjustment in callers.

cdl.export returns coveredBytes and memorySize. Equality means the exported map has one decoded record for every byte in that ROM region. It does not mean the run executed or read the whole ROM.

The evidence that CDL is live is growth in codeBytes, dataBytes, and summaryRanges when a deterministic run is driven for longer or through more gameplay.

NES CHR is the platform-specific exception to the generic flag names. Mesen's source defines bit 0x01 as NesChrDrawn for CHR ROM, not CPU Code. Inline/exported CHR records therefore expose drawn, summaries classify those ranges as drawn, and export counts report drawnBytes; codeBytes and dataBytes remain zero for CHR.

Skills

The repo ships Codex/Codex-compatible skills in skills/:

• skills/mesen-emulator - load ROMs, manage session handles, step frames, read/write memory, and inspect CPU registers.
• skills/mesen-debug - answer debugging questions with watches, breakpoints, traces, registers, and memory inspection.
• skills/mesen-codedata - export and interpret Mesen Code/Data Logger maps.

Install them by symlinking or copying the skill directories into your agent's skill directory. If the skills are installed outside this checkout, set MESEN_FOR_AI_REPO to the checkout root so scripts/mesen_client.py can find the daemon.

Validation

Unit and static smoke tests:

python3 -m py_compile src/mesen_mcp/*.py scripts/test_mcpd.py
PYTHONPATH=src python3 -m unittest discover -s tests -v

Real emulator validation requires a private test ROM supplied by the user:

MESEN_BIN=/path/to/Mesen PYTHONPATH=src scripts/test_mcpd.py --rom /path/to/test-rom.zip --frames 60

Do not commit, upload, or redistribute ROM, BIOS, firmware, disc-image, or other copyrighted game material.

License

mesen-for-ai is licensed under GPL-3.0-only. See LICENSE.

Mesen itself is an upstream GPL-3.0 emulator and is not vendored in this repository. The wrapper code in this repository is original, but bridge.lua runs inside the Mesen process and calls Mesen's Lua API directly. The conservative licensing position is therefore to publish the wrapper under GPL-3.0-only as well.