/gearcoleco-romhacking

name: gearcoleco-romhacking
description: >-
  Hack, modify, and translate ColecoVision and Super Game Module ROMs using the
  Gearcoleco 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 a ColecoVision 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, inspect
  SGM RAM, or reverse engineer data structures in ColecoVision or Super Game
  Module games. Also use for any ROM hacking, memory poking, or game
  modification task involving Gearcoleco.
compatibility: >-
  Requires the Gearcoleco 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"

ColecoVision / Super Game Module ROM Hacking with Gearcoleco

Overview

Hack, modify, and translate ColecoVision and Super Game Module ROMs using the Gearcoleco emulator as an MCP server. Search memory for game variables, create cheats, find text strings for translation, locate sprite and tile data, inspect VRAM, patch RAM or ROM bytes in the emulator's in-memory copy, 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. Hardware documentation is available in the [references/](references/) directory.

MCP Server Prerequisite

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

Installing Gearcoleco

Run the bundled install script (macOS/Linux):

bash scripts/install.sh

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

Connecting as MCP Server

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

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

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

Hardware Documentation (References)

ColecoVision and Super Game Module hardware documentation is available in the [references/](references/) directory. Load them into your context when investigating specific hardware, BIOS, memory-map, graphics, sound, or SGM behavior.

| Reference | File | Quality | Load when... | |---|---|---|---| | ColecoVision Technical Notes | [references/colecovision.md](references/colecovision.md) | **PRIMARY** - system quick reference | Cartridge headers, title-screen behavior, controller modes, keypad codes, memory map, I/O map, basic SN76489 and VDP context | | TMS9918A VDP (Sean Young) | [references/tms9918a.md](references/tms9918a.md) | **PRIMARY** - detailed VDP reference | VDP registers, status flags, VRAM access, display modes, interrupts, sprites, fifth-sprite flag, collisions, undocumented modes | | SN76489A PSG | [references/sn76489.md](references/sn76489.md) | **PRIMARY** - ColecoVision PSG quick reference | SN76489 latch/data writes, tone periods, attenuation, noise control, frequency formula, PSG debugging | | Super Game Module Notes | [references/super_game_module.md](references/super_game_module.md) | **PRIMARY** - SGM memory reference | SGM RAM mapping, port $53, port $7F, ADAM compatibility, SGM initialization, SGM AY summary |

---

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. list_memory_areas          -> identify WRAM, SGM RAM, or another area ID
2. memory_search_capture      -> snapshot current memory state
3. (change the value in-game using controller_button, fast forward, etc.)
4. memory_search              -> compare against snapshot to find changed addresses
5. Repeat 2-4 until only a few candidates remain
6. 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. list_memory_areas                                  -> find WRAM area ID
2. memory_search_capture                              -> snapshot with 3 lives
3. Lose a life in-game (play or use controlle