mGBA MCP Server

Instructions

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)