mGBA MCP Server

Instructions

Implementation Reference

• src/mgba_mcp/emulator.py:350-389 (handler)

  Core implementation of mgba_dump_oam: generates Lua script to dump 40 OAM sprites (position, tile, flags, palette, visibility) from GBA memory (0xFE00-0xFE9F) after specified frames, outputs JSON, takes screenshot.

      def dump_oam(
          self,
          rom_path: str,
          savestate_path: Optional[str] = None,
          frames_before_dump: int = 60,
      ) -> EmulatorResult:
          """Dump OAM (sprite) data."""
          lua_script = f"""
  local frame = 0
  
  callbacks:add("frame", function()
      frame = frame + 1
      if frame >= {frames_before_dump} then
          local f = io.open("output.json", "w")
          if f then
              f:write('{{"oam": [')
              for slot = 0, 39 do
                  local addr = 0xFE00 + slot * 4
                  local y = emu:read8(addr)
                  local x = emu:read8(addr + 1)
                  local tile = emu:read8(addr + 2)
                  local flags = emu:read8(addr + 3)
                  if slot > 0 then f:write(',') end
                  f:write(string.format(
                      '{{"slot":%d,"y":%d,"x":%d,"tile":%d,"flags":%d,"palette":%d,"visible":%s}}',
                      slot, y, x, tile, flags, flags % 8,
                      (y > 0 and y < 160) and "true" or "false"
                  ))
              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)

• src/mgba_mcp/server.py:119-137 (schema)

  Input schema defining parameters for mgba_dump_oam tool: required rom_path, optional savestate_path and frames.

  inputSchema={
      "type": "object",
      "properties": {
          "rom_path": {
              "type": "string",
              "description": "Path to the ROM file",
          },
          "savestate_path": {
              "type": "string",
              "description": "Optional savestate to load",
          },
          "frames": {
              "type": "integer",
              "description": "Frames to run before dumping (default: 60)",
              "default": 60,
          },
      },
      "required": ["rom_path"],
  },

• src/mgba_mcp/server.py:116-138 (registration)

  Registers the mgba_dump_oam tool in the MCP server's list_tools() function.

  Tool(
      name="mgba_dump_oam",
      description="Dump OAM (Object Attribute Memory) sprite data - shows all 40 sprites with position, tile, flags, and palette",
      inputSchema={
          "type": "object",
          "properties": {
              "rom_path": {
                  "type": "string",
                  "description": "Path to the ROM file",
              },
              "savestate_path": {
                  "type": "string",
                  "description": "Optional savestate to load",
              },
              "frames": {
                  "type": "integer",
                  "description": "Frames to run before dumping (default: 60)",
                  "default": 60,
              },
          },
          "required": ["rom_path"],
      },
  ),

• src/mgba_mcp/server.py:283-309 (handler)

  MCP server handler for mgba_dump_oam: calls emulator.dump_oam, parses OAM JSON into formatted text table of visible sprites, adds screenshot if available.

  elif name == "mgba_dump_oam":
      result = emu.dump_oam(
          rom_path=arguments["rom_path"],
          savestate_path=arguments.get("savestate_path"),
          frames_before_dump=arguments.get("frames", 60),
      )
  
      if result.success and result.data:
          oam = result.data["oam"]
          lines = ["OAM Sprite Data (40 slots):"]
          lines.append("Slot  Y    X   Tile  Flags  Pal  Visible")
          lines.append("-" * 45)
          for sprite in oam:
              if sprite["visible"]:
                  lines.append(
                      f"{sprite['slot']:3d}  {sprite['y']:3d}  {sprite['x']:3d}  "
                      f"0x{sprite['tile']:02X}   0x{sprite['flags']:02X}    {sprite['palette']}    *"
                  )
          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}"))