/gearcoleco-debugging

name: gearcoleco-debugging
description: >-
  Debug and trace ColecoVision and Super Game Module games using the Gearcoleco
  emulator MCP server. Provides workflows for Z80 CPU debugging, breakpoint
  management, TMS9918A VDP/SN76489/AY-3-8910 hardware inspection, disassembly
  analysis, execution tracing, and rewind/time-travel debugging. Use when the
  user wants to debug a ColecoVision or SGM 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 SN76489 or AY-3-8910 audio, view the call
  stack, rewind to earlier execution points, or diagnose rendering, audio,
  controller, SGM RAM, or timing issues. Also use when the user mentions
  ColecoVision development, Super Game Module homebrew testing, or Z80
  debugging with 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 Debugging with Gearcoleco

Overview

Debug ColecoVision and Super Game Module games using the Gearcoleco emulator as an MCP server. Control execution (pause, step, breakpoints), inspect the Z80 CPU and hardware (TMS9918A VDP, SN76489 PSG, AY-3-8910 SGM PSG), read/write memory across multiple areas (BIOS, RAM, SGM RAM, VRAM, ROM banks), 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.

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 or BIOS 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 |

---

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), 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. Gearcoleco accepts `.sym` entries using `BANK:ADDRESS LABEL` format.

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, flags (S, Z, H, P/V, N, C), interrupt state, halt status, interrupt mode (0/1/2)
• **Disassembly**: `get_disassembly` with a start/end address range. Disassembled records exist for code that has executed during emulation
• **Call stack**: `get_call_stack` - current subroutine hierarchy
• **Memory**: `read_memory` with a memory editor area ID and offset. Use `list_memory_areas` first to see available areas and physical offsets
• **Sprites**: `list_sprites` - all 32 TMS9918A spri