/geargrafx-debugging

name: geargrafx-debugging
description: >-
  Debug and trace TurboGrafx-16 / PC Engine / SuperGrafx games using the
  Geargrafx emulator MCP server. Provides workflows for HuC6280 CPU debugging,
  breakpoint management, hardware inspection, disassembly analysis, and
  execution tracing. Use when the user wants to debug a PC Engine game, trace
  code execution, inspect CPU registers or hardware state, set breakpoints,
  analyze interrupts, step through HuC6280 instructions, reverse engineer game
  code, examine VDC/VCE/PSG registers, view the call stack, or diagnose
  rendering, audio, or timing issues. Also use when the user mentions PC Engine
  development, TurboGrafx-16 homebrew testing, SuperGrafx debugging, CD-ROM
  game debugging, or HuC6280 debugging with 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 Game Debugging with Geargrafx

Overview

Debug TurboGrafx-16, PC Engine, and SuperGrafx games using the Geargrafx emulator as an MCP server. Control execution (pause, step, breakpoints), inspect the HuC6280 CPU and hardware (HuC6270 VDC, HuC6260 VCE, HuC6202 VPC, PSG), read/write memory, disassemble code, trace instructions, 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 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 investigating specific hardware.

| Reference | File | Load when... | |---|---|---| | HuC6280 CPU | [references/huc6280_cpu.md](references/huc6280_cpu.md) | CPU registers, MPR mapping, timer, interrupts, I/O, speed modes | | 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, volume, DDA | | HuC6270 VDC | [references/huc6270_vdc.md](references/huc6270_vdc.md) | Video Display Controller: BAT, sprites, scroll, DMA, interrupts | | HuC6260 VCE | [references/huc6260_vce.md](references/huc6260_vce.md) | Video Color Encoder: 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 |

---

Debugging Workflow

1. Load and Orient

load_media → get_media_info → get_huc6280_status → get_screenshot

Start every session by loading the ROM, confirming it loaded correctly, then checking CPU state and taking a screenshot to understand the current game state. If a `.sym`, `.lbl`, or `.noi` file exists alongside the ROM, symbols are loaded automatically.

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_huc6280_status` — registers A, X, Y, S, P (flags), PC, MPR mapping, timer, interrupts, I/O port, speed mode
• **Disassembly**: `get_disassembly` with a start/end address range — only shows executed code paths
• **Call stack**: `get_call_stack` — current subroutine hierarchy
• **Memory**: `read_memory` with a memory area tab ID (use `list_memory_areas` to discover available areas and their IDs)

3. Set Breakpoints

Use breakpoints to stop execution at points of interest:

| Breakpoint Type | Tool | Use Case | |---|---|---| | Execution | `set_breakpoint` (type: exec) | Stop when PC reaches address | | Read | `set_breakpoint` (type: read) | Stop when memory address is read | | Write | `set_breakpoint` (type: write) | Stop when memory address is written | | Range | `set_breakpoint_range` | Cover an address range (exec/read/write) |

Breakpoints support 5 memory areas: `rom_ram` (default), `vram`, `palette`, `huc6270_reg`, `huc6260_reg`.

**Important**: Re