/geargrafx-romhacking

name: geargrafx-romhacking
description: >-
  Hack, modify, and translate TurboGrafx-16 / PC Engine / SuperGrafx ROMs using
  the Geargrafx emulator MCP server. Provides workflows for memory searching,
  value discovery, cheat creation, data modification, sprite/text finding, and
  translation patching. Use when the user wants to create cheats, find game
  values in memory, modify ROM data, translate a PC Engine game, patch game
  behavior, create ROM hacks, discover hidden content, change sprites or
  graphics, find text strings, do infinite lives or health hacks, search for
  score or item counters, or reverse engineer data structures in TurboGrafx-16
  or PC Engine games. Also use for any ROM hacking, memory poking, or game
  modification task involving Geargrafx.
compatibility: >-
  Requires the Geargrafx 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"

TurboGrafx-16 / PC Engine ROM Hacking with Geargrafx

Overview

Hack, modify, and translate TurboGrafx-16, PC Engine, and SuperGrafx ROMs using the Geargrafx emulator as an MCP server. Search memory for game variables, create cheats, find text strings for translation, locate sprite data, and reverse engineer data structures — all through MCP tool calls. Use save states as checkpoints and fast forward to reach specific game states.

MCP Server Prerequisite

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

Installing Geargrafx

Run the bundled install script (macOS/Linux):

bash scripts/install.sh

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

Connecting as MCP Server

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

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

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

Hardware Documentation (References)

PC Engine hardware documentation is available in the [references/](references/) directory. Load them into your context when you need data formats, memory layout, or hardware details.

| Reference | File | Load when... | |---|---|---| | HuC6280 CPU | [references/huc6280_cpu.md](references/huc6280_cpu.md) | CPU registers, MPR mapping, timer, I/O, opcode reference | | Instruction Set | [references/huc6280_instructions.md](references/huc6280_instructions.md) | Opcode reference, addressing modes, cycle counts | | PSG | [references/huc6280_psg.md](references/huc6280_psg.md) | 6-channel sound: waveform, noise, LFO, DDA | | HuC6270 VDC | [references/huc6270_vdc.md](references/huc6270_vdc.md) | BAT, sprites, scroll, DMA, VRAM layout | | HuC6260 VCE | [references/huc6260_vce.md](references/huc6260_vce.md) | Palette, dot clock, color format | | HuC6202 VPC | [references/huc6202_vpc.md](references/huc6202_vpc.md) | Video Priority Controller (SuperGrafx): window, priority | | Memory Map | [references/memory_map.md](references/memory_map.md) | Full memory map: MPR pages, I/O, WRAM, VRAM, ROM banking |

---

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 current value to last captured snapshot (most common)
• `value` — compare current value to a specific number
• `address` — compare current value to value at another address

**Data types**: `hex`, `signed`, `unsigned`

Example: Finding the Lives Counter

1. memory_search_capture                         → snapshot with 3 lives
2. Lose a life in-game (play or use controller_button)
3. memory_search (operator: <, compare: previous) → values that decreased
4. memory_search_capture                         → snapshot with 2 lives
5. Lose another life
6. memory_search (operator: <, compare: previous) → narrow further
7. Or use: memory_search (operator: ==, compare: value, value: 1)
   → find addresses holding exactly 1
8. write_memory on the candidate address to set lives to 99
9. get_screenshot to verify the change took effect

Example: Finding a Score Counter

Score values are often stored as multi-byte (16-bit little-end