/gearsystem-debugging

name: gearsystem-debugging
description: >-
  Debug and trace Sega Master System, Game Gear, and SG-1000 games using the
  Gearsystem emulator MCP server. Provides workflows for Z80 CPU debugging,
  breakpoint management, VDP/PSG/YM2413 hardware inspection, disassembly
  analysis, execution tracing, and rewind/time-travel debugging. Use when the
  user wants to debug an SMS/GG/SG-1000 game, trace code execution, inspect Z80
  CPU registers or hardware state, set breakpoints, analyze interrupts, step
  through Z80 instructions, reverse engineer game code, examine VDP registers,
  view sprites, inspect PSG or YM2413 FM audio, view the call stack, rewind to
  earlier execution points, or diagnose rendering, audio, or timing issues.
  Also use when the user mentions Master System development, Game Gear homebrew
  testing, or Z80 debugging with Gearsystem.
compatibility: >-
  Requires the Gearsystem 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"

Sega Master System / Game Gear / SG-1000 Debugging with Gearsystem

Overview

Debug Sega Master System, Game Gear, and SG-1000 games using the Gearsystem emulator as an MCP server. Control execution (pause, step, breakpoints), inspect the Z80 CPU and hardware (VDP, PSG, YM2413), read/write memory across multiple areas (ROM+RAM, VRAM, CRAM), disassemble code, trace instructions, rewind to earlier states, view sprites, and capture screenshots — all through MCP tool calls. Hardware documentation is available in the [references/](references/) directory and also at [SMS Power! Development Documents](https://www.smspower.org/Development/Documents).

MCP Server Prerequisite

**IMPORTANT — Check before installing:** Before attempting any installation or configuration, you MUST first verify if the Gearsystem MCP server is already connected in your current session. In the default mode, call `debug_get_status` directly. If Gearsystem 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 Gearsystem MCP server:

Installing Gearsystem

Run the bundled install script (macOS/Linux):

bash scripts/install.sh

This installs Gearsystem 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/Gearsystem/releases/latest) or install with `brew install --cask drhelius/geardome/gearsystem` on macOS.

Connecting as MCP Server

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

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

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

Hardware Documentation (References)

SMS/GG/SG-1000 hardware documentation is available in the [references/](references/) directory. Load them into your context when investigating specific hardware. Additional community documentation is available at [SMS Power! Development Documents](https://www.smspower.org/Development/Documents).

| Reference | File | Quality | Load when... | |---|---|---|---| | SMS VDP (MacDonald) | [references/msvdp.md](references/msvdp.md) | **PRIMARY** — hardware-tested, definitive | VDP registers, display modes, Mode 4, CRAM, sprites, scrolling, display timing, interrupts, GG/Genesis VDP | | SMS/GG Hardware (MacDonald) | [references/smstech.md](references/smstech.md) | **PRIMARY** — hardware-tested, definitive | I/O ports, memory map, memory control, nationalization, interrupts (IM 0/1/2), BIOS, GG stereo, YM2413 detection | | SMS Technical Info (Talbot-Watkins) | [references/richard.md](references/richard.md) | HIGH — comprehensive, best YM2413 detail | YM2413 FM registers, SN76489 PSG, paging registers, line interrupt examples, VDP overview | | TMS9918A VDP (Sean Young) | [references/tms9918a.md](references/tms9918a.md) | HIGH — detailed TMS9918 reference | SG-1000 video modes, TMS9918 legacy modes on SMS, Graphic I/II, Text, Multicolor, undocumented modes | | SG-1000 Specs (Cornut) | [references/sg1000.md](references/sg1000.md) | MEDIUM — concise SG-1000 quick ref | SG-1000 memory map, TMS9918 palette, basic VDP/PSG, SG-1000 specifics | | SMS/GG Technical (Jon) | [references/jon.md](references/jon.md) | MEDIUM — unique GG serial link info | Game Gear Gear-to-Gear cable protocol, GG Start button, GG serial communication |

---

Debugging Workflow

1. Load and Orient

load_media → get_media_info → get_z80_status → get_screenshot

Start every session by loading the ROM, confirming it loaded correctly (file path, type, size, mapper, zone, system), then checking Z80 CPU state and taking a screenshot to understand the current game state. If a `.sym` file exists alongside the ROM, symbols are loaded automatically. Gearsystem supports sjasmplus/Pasmo (EQU), SDCC/NoICE (.noi), wla-dx, and vasm/generic symbol formats.

Load additional symbols with `load_symbols` or add individual labels with `add_symbol`.

2. Pause and Inspect

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

• **CPU state**: `get_z80_status` — registers AF, BC, DE, HL, AF', BC', DE', HL', IX, IY, SP, PC, WZ, I, R