mgba_read_range
Read a contiguous range of memory addresses from Game Boy, GBC, or GBA ROMs using the mGBA emulator for automated testing and game analysis.
Instructions
Read a contiguous range of memory addresses
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rom_path | Yes | Path to the ROM file | |
| start_address | Yes | Starting memory address | |
| length | Yes | Number of bytes to read | |
| savestate_path | No | Optional savestate to load | |
| frames | No | Frames to run before reading (default: 60) |
Implementation Reference
- src/mgba_mcp/server.py:255-281 (handler)Handler for mgba_read_range tool in the MCP call_tool dispatcher. Parses arguments, calls emulator.read_memory_range, formats the hex dump output, and adds screenshot if available.elif name == "mgba_read_range": result = emu.read_memory_range( rom_path=arguments["rom_path"], start_addr=arguments["start_address"], length=arguments["length"], savestate_path=arguments.get("savestate_path"), frames_before_read=arguments.get("frames", 60), ) if result.success and result.data: data = result.data["data"] start = result.data["start"] # Format as hex dump with 16 bytes per line lines = [f"Memory range 0x{start:04X} - 0x{start + len(data) - 1:04X}:"] for i in range(0, len(data), 16): addr = start + i hex_bytes = " ".join(f"{b:02X}" for b in data[i:i+16]) lines.append(f" {addr:04X}: {hex_bytes}") result_content.append(TextContent(type="text", text="\n".join(lines))) if result.screenshot: result_content.append(ImageContent( type="image", data=base64.b64encode(result.screenshot).decode(), mimeType="image/png", )) else: result_content.append(TextContent(type="text", text=f"Error: {result.error}"))
- src/mgba_mcp/server.py:85-115 (schema)Schema definition for mgba_read_range tool, including input parameters and validation in the list_tools registration.Tool( name="mgba_read_range", description="Read a contiguous range of memory addresses", inputSchema={ "type": "object", "properties": { "rom_path": { "type": "string", "description": "Path to the ROM file", }, "start_address": { "type": "integer", "description": "Starting memory address", }, "length": { "type": "integer", "description": "Number of bytes to read", }, "savestate_path": { "type": "string", "description": "Optional savestate to load", }, "frames": { "type": "integer", "description": "Frames to run before reading (default: 60)", "default": 60, }, }, "required": ["rom_path", "start_address", "length"], }, ),
- src/mgba_mcp/emulator.py:316-348 (helper)Core helper method that generates Lua script to read memory range using mGBA's emu:read8 API after specified frames, writes JSON output, takes screenshot, and uses _run_with_lua to execute.def read_memory_range( self, rom_path: str, start_addr: int, length: int, savestate_path: Optional[str] = None, frames_before_read: int = 60, ) -> EmulatorResult: """Read a range of memory addresses.""" lua_script = f""" local frame = 0 callbacks:add("frame", function() frame = frame + 1 if frame >= {frames_before_read} then local f = io.open("output.json", "w") if f then f:write('{{"start": {start_addr}, "length": {length}, "data": [') for i = 0, {length - 1} do if i > 0 then f:write(',') end f:write(tostring(emu:read8({start_addr} + i))) end f:write(']}}') f:close() end emu:screenshot("screenshot.png") -- Write DONE marker local done = io.open("DONE", "w") if done then done:write("OK"); done:close() end end end) """ return self._run_with_lua(rom_path, lua_script, savestate_path)