Driving the game with an AI agent (MCP)

Marchwind 64 has a built-in debug interface. Turn it on in the options and the game opens a port on your computer. The MCP server in the source repository connects to that port and offers the game as a set of tools to any client that speaks the Model Context Protocol, such as Claude Code, Codex or Cursor.

Once connected, an agent can:

• see what the game is doing: the title, dialogue, intermission screens, the pre-battle screen, the settings window;
• take screenshots and record MP4 clips;
• press keys like a player, or use the buttons and text fields of the native screens directly;
• change the language, image mode, rules and interface size;
• read and write game memory, for debugging.

This is how we test the game ourselves: agents play through scenes, reproduce bugs and check translated layouts. You can use it the same way, to script runs, record footage or have an agent look into a problem you hit.

What you need

• The game for Windows, macOS, Linux or Steam Deck.

• Python 3. The one that comes with your system is fine. No extra packages are needed. On Windows, install it from python.org; the command is python.

• The MCP server script. It lives in the source repository. Cloning is enough; nothing needs to be built:

  git clone https://github.com/dyzz/srw64-recomp.git

  The files used are tools/recomp/debug/mcp_server.py and session.py next to it.

• An AI client with MCP support.

1. Turn on the debug interface in the game

Open Options → About and set AI Debug Interface (MCP) to On. It takes effect at once, no restart needed. The setting is saved, and every time the game starts a notice at the top of the screen reminds you it’s still on. Turn it off in the same place when you’re done; any open connection ends immediately.

While it’s on, the row shows the address the game listens on and the folder of this run, with a Copy Run Folder button that copies the full path.

The game opens a port on this computer only (127.0.0.1) and writes debug.json to the run folder, with the port number and a random token. A client has to present the token before anything else, and only your user account can read the file. The file is deleted when the game exits or the switch is turned off.

The run folder on each system:

2. Add the MCP server to your client

The MCP server is a Python script that talks over standard input and output.

Claude Code:

claude mcp add srw64 -- python3 /path/to/srw64-recomp/tools/recomp/debug/mcp_server.py

Other clients mostly take JSON like this; check your client’s docs for where the file lives and the exact top-level key:

{
  "mcpServers": {
    "srw64": {
      "command": "python3",
      "args": ["/path/to/srw64-recomp/tools/recomp/debug/mcp_server.py"]
    }
  }
}

On Windows, use python instead of python3, and a path such as C:\\path\\to\\srw64-recomp\\tools\\recomp\\debug\\mcp_server.py (backslashes are doubled in JSON).

Your client should now list a set of tools whose names start with srw64_.

3. Connect and start working

Just ask the agent to connect. It doesn’t need a path:

Use srw64_attach to connect to the game, then take a screenshot and tell me which screen it's on.

Without arguments, srw64_attach looks in your user folder for games with the debug interface on and connects to the newest one that answers. If several games are running, or you want a particular one, pass the path from Copy Run Folder as its run argument.

After that, give it tasks in plain language:

• “Wait for the main menu, start a new game and fast-forward to the first choice.”
• “Switch the language to English and compare a screenshot with the Chinese version of the same screen. Is any text overflowing?”
• “Record 10 seconds. I want to see where this battle animation stutters.”
• “The dialogue is stuck. Read the status and the recent event log and tell me which script command it stopped on.”

Agents usually read srw64_status and a screenshot to work out where they are, then use srw64_wait to wait for a condition instead of guessing at delays.

Tools

When a tool fails it returns an error result; the MCP server keeps running.

Things to keep in mind

• This is your real game and your real saves. The agent connects to the game you play, with your usual saves and settings, so an agent that saves or changes settings really changes them. To experiment safely, back up saves/ in your user folder first, or point --user-dir at a separate folder and copy in the saves you need.
• srw64_memory_write can break the game. It changes memory behind the game’s back. Use it only when you know what you’re doing.
• The interface is local only. The game listens on 127.0.0.1, so other devices on your network can’t reach it, and other programs on your computer also need the token in debug.json. Don’t share that file. Remote use goes through ssh forwarding (see below).
• srw64_quit closes the game. To disconnect and keep playing, turn the switch off in Options → About instead.
• Turn the switch off when you’re done. It stays saved, which is what the notice at startup is for.

Connecting to a Steam Deck

You need ssh access from your computer to the Deck (for example a host named Deck in ~/.ssh/config), and the debug interface on in the Deck game’s Options → About (or the game started with --debug as above). In the repository on your computer, run:

python3 tools/release/linux/attach.py --host Deck

It finds the running game on the Deck, forwards its port to your computer with ssh -L and makes it the current session. The agent can then call srw64_attach with no arguments. Screenshots, recordings and event logs are files the game writes on the Deck; they come back over the same connection automatically.

attach.py --start starts the game over ssh with --debug. Add --data-dir '~/srw64-debug' to give it a separate data folder: the ROM and HD pack are linked, the saves and settings are copied, so your own saves stay untouched.

Android

On Android, turn it on in Options → About too. The phone reaches your computer through adb: enable USB debugging (or wireless debugging) in the phone’s developer options, connect it with adb, then run this in the repository:

python3 tools/release/android/attach.py --no-start

It forwards the game’s interface to your computer with adb forward and makes it the current session; then call srw64_attach as usual. Screenshots, recordings and event logs come back over the same connection. Android uses no token; your computer reaches the interface through the adb forward.

For developers: starting from source

With a full local build setup (see the build docs in the repository), srw64_launch builds as needed and starts a separate debug session. Its run folder sits under build/recomp/debug/ in the repository and never touches your play saves. It can also set the language, image mode, rules, a save or a mini stage on launch. The session ends when the MCP server exits.

docs/guide/debug-interface.md in the repository covers the rest: the srw64ctl.py command line, the Python scripting interface and what the interface can reach.