/gearsystem-romhacking

name: gearsystem-romhacking
description: >-
  Hack, modify, and translate Sega Master System, Game Gear, and SG-1000 ROMs
  using the Gearsystem emulator MCP server. Provides workflows for memory
  searching, value discovery, cheat creation, data modification, sprite/text
  finding, translation patching, and rewind-assisted experimentation. Use when
  the user wants to create cheats, find game values in memory, modify ROM data,
  translate an SMS/GG game, patch game behavior, create ROM hacks, discover
  hidden content, change sprites or graphics, find text strings, apply Game
  Genie or Pro Action Replay codes, do infinite lives or health hacks, search
  for score or item counters, or reverse engineer data structures in Sega
  Master System, Game Gear, or SG-1000 games. Also use for any ROM hacking,
  memory poking, or game modification task involving 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 ROM Hacking with Gearsystem

Overview

Hack, modify, and translate Sega Master System, Game Gear, and SG-1000 ROMs using the Gearsystem emulator as an MCP server. Search memory for game variables, create cheats, find text strings for translation, locate sprite data, inspect VRAM/CRAM, and reverse engineer data structures — all through MCP tool calls. Use save states or rewind as checkpoints and fast forward to reach specific game states. The emulator also supports Game Genie and Pro Action Replay codes natively. 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 |

---

Core Technique: Memory Search

Memory search is the primary tool for ROM hacking. It uses a capture → change → compare cycle to isolate memory addresses holding game values.

The Search Loop

1. memory_search_capture    → snapshot current memory state
2. (change the value in-game using controller_button, fast forward, etc.)
3. memory_search            → compare against snapshot to find changed addresses
4. Repeat 2-3 until only a few candidates remain
5. read_memory / write_memory → verify and modify the found addresses

Search Operators and Types

`memory_search` supports these **operators**: `<`, `>`, `==`, `!=`, `<=`, `>=`

**Compare types**:

• `previous` — compare