/gearboy-debugging

name: gearboy-debugging
description: >-
  Debug and trace Game Boy / Game Boy Color / Super Game Boy games using the Gearboy emulator MCP
  server. Provides workflows for SM83 CPU debugging, breakpoint management,
  hardware inspection, disassembly analysis, and execution tracing. Use when the
  user wants to debug a Game Boy game, trace code execution, inspect CPU
  registers or hardware state, set breakpoints, analyze interrupts, step through
  SM83 instructions, reverse engineer game code, examine LCD, APU, or SGB registers,
  view the call stack, or diagnose rendering, audio, or timing issues. Also use
  when the user mentions Game Boy development, GB/GBC/SGB homebrew testing, or SM83
  debugging with Gearboy.
compatibility: >-
  Requires the Gearboy MCP server. Direct tool mode is the default. Before
  installing or configuring, call debug_get_status to check if the server is
  already connected. If --mcp-router is enabled, use get_tool_info and
  execute_tool for routed tools.
metadata:
  author: drhelius
  version: "1.0"

Game Boy / Game Boy Color Debugging with Gearboy

Overview

Debug Game Boy, Game Boy Color, and Super Game Boy games using the Gearboy emulator as an MCP server. Control execution (pause, step, breakpoints), inspect the SM83 CPU and hardware (LCD, APU, SGB, sprites), read/write memory, disassemble code, trace instructions, and capture screenshots — all through MCP tool calls.

MCP Server Prerequisite

**IMPORTANT — Check before installing:** Before attempting any installation or configuration, you MUST first verify if the Gearboy MCP server is already connected in your current session. In the default mode, call `debug_get_status` directly. If Gearboy was intentionally started with `--mcp-router`, call `get_tool_info` with `{"name":"debug_get_status"}`, then call `execute_tool` with `{"name":"debug_get_status","arguments":{}}`. A valid response from either workflow means the server is active and ready.

Only if neither workflow is available or the call fails, you need to help install and configure the Gearboy MCP server:

Installing Gearboy

Run the bundled install script (macOS/Linux):

bash scripts/install.sh

This installs Gearboy via Homebrew on macOS or downloads the latest release on Linux. It prints the binary path on completion. You can also set `INSTALL_DIR` to control where the binary goes (default: `~/.local/bin`).

Alternatively, download from [GitHub Releases](https://github.com/drhelius/Gearboy/releases/latest) or install with `brew install --cask drhelius/geardome/gearboy` on macOS.

Connecting as MCP Server

Configure your AI client to run Gearboy as an MCP server via STDIO transport. Example for Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

{
  "mcpServers": {
    "gearboy": {
      "command": "/path/to/gearboy",
      "args": ["--mcp-stdio"]
    }
  }
}

Replace `/path/to/gearboy` with the actual binary path from the install script. Add `--headless` before `--mcp-stdio` on headless machines.

---

Debugging Workflow

1. Load and Orient

load_media → get_media_info → get_cpu_status → get_screenshot

Start every session by loading the ROM, confirming it loaded correctly (MBC type, ROM/RAM size, CGB/SGB flags), then checking CPU state and taking a screenshot to understand the current game state. If a `.sym` or `.noi` file exists alongside the ROM, symbols are loaded automatically.

Load additional symbols with `load_symbols` or add individual labels with `add_symbol`. Gearboy supports RGBDS, GBDK-2020, WLA-DX, no$gmb, SDCC/NoICE (.noi), EQU, and generic symbol formats.

2. Pause and Inspect

Always call `debug_pause` before inspecting state. While paused:

• **CPU state**: `get_cpu_status` — registers A, F, B, C, D, E, H, L, SP, PC, flags Z/N/H/C, IME, halt state, CGB double speed
• **Disassembly**: `get_disassembly` with a start/end address range
• **Call stack**: `get_call_stack` — current subroutine hierarchy
• **Memory**: `read_memory` with area name (ROM0, ROM1, VRAM, RAM, WRAM0, WRAM1, WRAM, OAM, IO, HIRAM) and address/length

3. Set Breakpoints

Use breakpoints to stop execution at points of interest:

| Breakpoint Type | Tool | Use Case | |---|---|---| | Execution | `set_breakpoint` (type: exec) | Stop when PC reaches address | | Read | `set_breakpoint` (type: read) | Stop when memory address is read | | Write | `set_breakpoint` (type: write) | Stop when memory address is written | | Range | `set_breakpoint_range` | Cover an address range (exec/read/write) | | IRQ | `toggle_irq_breakpoints` | Break on VBlank, LCD STAT, Timer, Serial, or Joypad interrupts |

Breakpoints support 3 memory area types: `rom_ram`, `vram`, and `io`.

**Important**: Read/write breakpoints stop with PC at the instruction *after* the memory access.

Manage breakpoints with `list_breakpoints` and `remove_breakpoint`.

4. Step Through Code

After hitting a breakpoint or pausing:

| Action | Tool | Behavior | |---|---|---| | Step Into | `debug_step_into` | Execute one SM83 instruction, enter subroutines | | Step Over | `debug_step_over` | Execute one instruction, skip CALL instructions | | Step Out | `debug_step_out` | Run until RET/RETI returns from current subroutine | | Step Frame | `debug_step_frame` | Execute until next VBlank; use `mode: "sync"` before dependent calls | | Run To | `debug_run_to_cursor` | Continue until PC reaches target address | | Continue | `debug_continue` | Resume normal execution |

After each step, call `get_cpu_status` and `get_disassembly` to see where you are.

5. Trace Execution

The trace logger records CPU instructions interleaved with hardware events (LCD, APU, I/O, bank switching). Start the trace logger from the emulator's debugger window, then:

1. `set_trace_log` with `enabled: true` to start recording (optionally filter event types) 2. Let the game run or step through code 3. `set_trace_log` with `enabled: false` to