# Gearlynx MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/introduction) server for the Gearlynx emulator, enabling AI-assisted debugging and development of Atari Lynx games.

This server provides tools for game development, rom hacking, reverse engineering, and debugging through standardized MCP protocols compatible with AI agents like Claude Code, Codex and others.

## Downloads

These MCP Bundles (`.mcpb`) package Gearlynx with its MCP server configuration for MCP clients that install bundles, and are the packages published to the [MCP Registry](https://registry.modelcontextprotocol.io/). Claude Code and Codex use a regular Gearlynx build instead, see [Quick Start](#quick-start).

<table>
  <thead>
    <tr>
      <th>Platform</th>
      <th>Architecture</th>
      <th>Download Link</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="2"><strong>Windows</strong></td>
      <td>x64</td>
      <td><a href="https://github.com/drhelius/Gearlynx/releases/download/1.2.36/Gearlynx-1.2.36-mcpb-windows-x64.mcpb">Gearlynx-1.2.36-mcpb-windows-x64.mcpb</a></td>
    </tr>
    <tr>
      <td>ARM64</td>
      <td><a href="https://github.com/drhelius/Gearlynx/releases/download/1.2.36/Gearlynx-1.2.36-mcpb-windows-arm64.mcpb">Gearlynx-1.2.36-mcpb-windows-arm64.mcpb</a></td>
    </tr>
    <tr>
      <td rowspan="2"><strong>macOS</strong></td>
      <td>x64</td>
      <td><a href="https://github.com/drhelius/Gearlynx/releases/download/1.2.36/Gearlynx-1.2.36-mcpb-macos-x64.mcpb">Gearlynx-1.2.36-mcpb-macos-x64.mcpb</a></td>
    </tr>
    <tr>
      <td>ARM64</td>
      <td><a href="https://github.com/drhelius/Gearlynx/releases/download/1.2.36/Gearlynx-1.2.36-mcpb-macos-arm64.mcpb">Gearlynx-1.2.36-mcpb-macos-arm64.mcpb</a></td>
    </tr>
    <tr>
      <td rowspan="2"><strong>Linux</strong></td>
      <td>x64</td>
      <td><a href="https://github.com/drhelius/Gearlynx/releases/download/1.2.36/Gearlynx-1.2.36-mcpb-linux-x64.mcpb">Gearlynx-1.2.36-mcpb-linux-x64.mcpb</a></td>
    </tr>
    <tr>
      <td>ARM64</td>
      <td><a href="https://github.com/drhelius/Gearlynx/releases/download/1.2.36/Gearlynx-1.2.36-mcpb-linux-arm64.mcpb">Gearlynx-1.2.36-mcpb-linux-arm64.mcpb</a></td>
    </tr>
  </tbody>
</table>

## Features

- **Full Debugger Access**: 6502 CPU registers, memory inspection, breakpoints, and execution control
- **Multiple Memory Areas**: Access RAM, Zero Page, Stack, Bank 0/0A/1/1A, BIOS, and EEPROM
- **Disassembly**: View disassembled 6502 code for any address range
- **Hardware Inspection**: 6502 CPU, Mikey (timers, audio, display), Suzy (sprites, math), UART (ComLynx)
- **Frame Buffer Capture**: Capture VIDBAS (Suzy) and DISPADR (Mikey) frame buffers
- **Symbol Support**: Add, remove, load, list, and look up debug symbols
- **Input State**: Inspect effective pressed buttons and pending tap releases
- **Bookmarks**: Memory and disassembler bookmarks for navigation
- **Call Stack**: View function call hierarchy
- **Trace Logger**: CPU instructions, master-clock cycles, absolute pagination, and exact Suzy/Mikey/UART/RedEye/cartridge event filters
- **Profiler**: Per-function call counts, calls per frame, and inclusive/exclusive cycle statistics
- **Screenshot Capture**: Get current frame as PNG image
- **Video Recording**: Record emulated video and audio to AVI files on disk
- **Rewind**: Time-travel debugging — seek to any recorded snapshot to inspect past emulator state
- **Documentation Resources**: Built-in hardware and programming documentation for AI context
- **GUI Integration**: MCP server runs alongside the emulator GUI, sharing the same state

## Transport Modes

The Gearlynx MCP server supports two transport modes:

### STDIO Transport (Recommended)

The default mode uses standard input/output for communication. The emulator is launched by the AI client and communicates through stdin/stdout pipes.

### HTTP Transport

The HTTP transport mode runs the emulator with an embedded web server on `127.0.0.1:7777/mcp` by default. The emulator stays running independently while the AI client connects via HTTP. Each request's `Host` and browser `Origin` must match the address on which its connection reached the server. Loopback mode can run without authentication; wildcard and other non-loopback bind addresses require `GEARLYNX_MCP_HTTP_TOKEN`, and the server refuses to start without it.

### Headless Mode

Add `--headless` to run without a GUI window. This is useful for servers, CLI agents, or any machine without a display. All MCP tools work identically in headless mode. Requires `--mcp-stdio` or `--mcp-http`.

A save state can be loaded at launch too, with `--load-state 1` for slot 1 or `--load-state FILE` for a state file; run `gearlynx --help` for the full list.

### Pause When Inactive

While the MCP server is running, the emulator keeps running when its window loses focus, even with **Pause When Inactive** enabled in the **Emulator** menu. The setting keeps its value and applies again once the server stops.

### Concurrent Clients

The HTTP server accepts repeated valid MCP initialization requests. All connected clients control the same Gearlynx instance. Individual HTTP requests are serialized, but multi-request debugging workflows are not atomic. Concurrent agents can interfere with each other through pauses, resets, breakpoints, memory writes, media loads, and save states.

For independent agent tasks, run one Gearlynx instance per agent on a unique HTTP port. Use `--headless` and give each instance its own portable application directory so its configuration and runtime files are isolated:

```bash
./gearlynx --mcp-http --headless --portable --mcp-http-port 7778
```

The `--portable` option stores configuration and user data beside the application. Alternatively, create an empty `portable.ini` beside the executable in each application directory. On macOS, place it next to each `.app` bundle.

## MCP Tool Router

By default, Gearlynx exposes every MCP tool directly. This avoids nested tool discovery in clients that already defer MCP schemas, including Claude Code.

Add `--mcp-router` to expose a compact set of high-frequency tools directly and route advanced debugger tools through lightweight discovery tools. This reduces MCP context while preserving access to the full debugger surface.

Direct tools in routed mode: `load_media`, `get_media_info`, `debug_pause`, `debug_continue`, `debug_step_into`, `get_6502_status`, `read_memory`, `write_memory`, `get_disassembly`, `set_breakpoint`, `get_screenshot`, and `controller_button`.

Router tools:

- `list_tool_categories` lists routed tool categories with descriptions and tool counts.
- `get_category_tools` lists routed tools in a category with compact descriptions.
- `search_tools` searches direct and routed tools and returns compact category/tool/description matches.
- `get_tool_info` returns one tool's real input schema and metadata.
- `execute_tool` executes a routed tool by name. First use `search_tools` or `get_category_tools` to discover the tool, then call `get_tool_info` to obtain its exact input schema.

Example routed call:

```json
{
  "name": "get_suzy_registers",
  "arguments": {}
}
```

Without `--mcp-router`, call every MCP tool directly.

## Quick Start

Get a desktop build of Gearlynx from the [downloads](README.md#downloads) or [build it from source](README.md#build-instructions). In the examples below, replace `/path/to/gearlynx` with the full path to the executable:

- **macOS:** `/Applications/Gearlynx.app/Contents/MacOS/gearlynx`
- **Linux:** `/path/to/gearlynx`
- **Windows:** `C:/path/to/gearlynx.exe`

### STDIO Mode with Claude Code

1. **Add the Gearlynx MCP server** using the CLI:

   ```bash
   claude mcp add --transport stdio --scope user gearlynx -- /path/to/gearlynx --mcp-stdio
   ```

   Everything after `--` is passed to Gearlynx untouched. `--scope user` makes the server available in all your projects. Use `--scope local` (the default) to add it only to the current project, or `--scope project` to share it through a `.mcp.json` file in the project root:

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

   Claude Code asks for approval the first time it uses a server from `.mcp.json`.

2. **Verify the server was added**:

   ```bash
   claude mcp list
   ```

3. **Start debugging**: Start Claude Code and ask about the game state. Gearlynx launches when the session starts. Run `/mcp` inside Claude Code to check the server status or reconnect it.

### STDIO Mode with Codex

The Codex CLI, IDE extension, and desktop app share the same MCP configuration, so you only need to add the server once.

1. **Add the Gearlynx MCP server** using the CLI:

   ```bash
   codex mcp add gearlynx -- /path/to/gearlynx --mcp-stdio
   ```

   Or add it to `~/.codex/config.toml`:

   ```toml
   [mcp_servers.gearlynx]
   command = "/path/to/gearlynx"
   args = ["--mcp-stdio"]
   ```

   To use the server only in one project, add the same table to `.codex/config.toml` in that project. Codex loads project configuration only for trusted projects. In TOML, write Windows paths with forward slashes or in single quotes.

2. **Verify the server was added**:

   ```bash
   codex mcp list
   ```

3. **Start debugging**: Start Codex and ask about the game state. Gearlynx launches when the session starts. Type `/mcp` in the Codex CLI to see the active servers.

### HTTP Mode

1. **Start the emulator manually** with HTTP transport:

   ```bash
   ./gearlynx --mcp-http
   ```

   The default endpoint is `http://127.0.0.1:7777/mcp`.

   To use a custom port:

   ```bash
   ./gearlynx --mcp-http --mcp-http-port 3000
   ```

   To bind to a custom address, set a bearer token first:

   ```bash
   GEARLYNX_MCP_HTTP_TOKEN="change-this-token" ./gearlynx --mcp-http --mcp-http-address 0.0.0.0 --mcp-http-port 3000
   ```

   Clients must connect using the server's actual interface address, such as `http://192.168.1.50:3000/mcp`, not `0.0.0.0` or a spoofed loopback address.

   You can also start the server using the "MCP" menu in the GUI.

2. **Configure bearer-token authentication**:

   Set `GEARLYNX_MCP_HTTP_TOKEN` before starting HTTP mode. Authentication is optional for loopback binds and required for wildcard or other non-loopback binds.

   macOS and Linux:

   ```bash
   GEARLYNX_MCP_HTTP_TOKEN="change-this-token" ./gearlynx --mcp-http
   ```

   Windows PowerShell:

   ```powershell
   $env:GEARLYNX_MCP_HTTP_TOKEN = "change-this-token"
   .\gearlynx.exe --mcp-http
   ```

   Windows Command Prompt:

   ```cmd
   set GEARLYNX_MCP_HTTP_TOKEN=change-this-token
   gearlynx.exe --mcp-http
   ```

3. **Configure Claude Code**:

   ```bash
   claude mcp add --transport http --scope user gearlynx http://127.0.0.1:7777/mcp
   ```

   If the server uses a bearer token, add the header:

   ```bash
   claude mcp add --transport http --scope user gearlynx http://127.0.0.1:7777/mcp \
     --header "Authorization: Bearer change-this-token"
   ```

   In a shared `.mcp.json`, read the token from the environment instead of committing it:

   ```json
   {
     "mcpServers": {
       "gearlynx": {
         "type": "http",
         "url": "http://127.0.0.1:7777/mcp",
         "headers": {
           "Authorization": "Bearer ${GEARLYNX_MCP_HTTP_TOKEN}"
         }
       }
     }
   }
   ```

4. **Or configure Codex**:

   ```bash
   codex mcp add gearlynx --url http://127.0.0.1:7777/mcp
   ```

   If the server uses a bearer token, Codex reads it from an environment variable, so set `GEARLYNX_MCP_HTTP_TOKEN` in the environment where Codex runs too:

   ```bash
   codex mcp add gearlynx --url http://127.0.0.1:7777/mcp --bearer-token-env-var GEARLYNX_MCP_HTTP_TOKEN
   ```

   The equivalent `~/.codex/config.toml` entry:

   ```toml
   [mcp_servers.gearlynx]
   url = "http://127.0.0.1:7777/mcp"
   bearer_token_env_var = "GEARLYNX_MCP_HTTP_TOKEN"
   ```

5. **Start a new Claude Code or Codex session** and start debugging

> **Note:** The MCP HTTP Server must be running standalone before connecting the AI client.
> **Security:** Without `GEARLYNX_MCP_HTTP_TOKEN`, HTTP mode starts only on a loopback address. Wildcard and other non-loopback binds are refused. `Host` and browser `Origin` values are matched to the connection's actual destination address to prevent DNS rebinding and address spoofing.

## Usage Examples

Once configured, you can ask your AI assistant:

### Basic Commands

- "What game is currently loaded?"
- "Load the ROM at /path/to/game.lnx"
- "Show me the current CPU registers"
- "Read 16 bytes from RAM starting at 0x0000"
- "Set a breakpoint at address 0x8000"
- "Pause execution and show me the Mikey timers"
- "Step through the next 5 instructions"
- "Capture a screenshot of the current frame"
- "Record a video of the next 600 frames to /path/to/clip.avi"
- "Tap the A button on the controller"
- "Show me the Suzy registers"

### Advanced Debugging Workflows

- "Find the VBlank interrupt handler, analyze what it does, and add symbols for all the subroutines it calls"
- "Locate the sprite update routine. Study how this game manages its sprite system, explain the algorithm, and add bookmarks to key sections. Also add watches for any sprite-related variables you find"
- "There's a data decompression routine around address 0xC000. Step through it instruction by instruction, reverse engineer the compression algorithm, and explain how it works with examples"
- "Find where the game stores its level data in ROM. Analyze the data structure format, create a memory map showing each section, and add symbols for the data tables"
- "The game is rendering corrupted graphics. Examine the Suzy registers, check the VIDBAS frame buffer, inspect the Mikey display settings, and diagnose what's causing the corruption. Set up watches on relevant memory addresses"
- "Profile the game for a few seconds, then tell me which functions use the most CPU time per frame and what they do"

## Available MCP Tools

This is the full tool catalog. All tools are exposed directly by default. With `--mcp-router`, discover advanced tools through `search_tools` or `get_category_tools`, inspect their schemas with `get_tool_info`, then invoke them with `execute_tool`.

The server exposes tools organized in the following categories:

### Execution Control
- `debug_pause` - Pause emulation
- `debug_continue` - Resume emulation
- `debug_step_into` - Step into next 6502 instruction (enters subroutines)
- `debug_step_over` - Step over next 6502 instruction (skips subroutines like JSR)
- `debug_step_out` - Step out of current subroutine (continues until RTS/RTI)
- `debug_step_frame` - Step one or more video frames. Optional `frames` is 1-1000 (default 1). Optional `mode` is `async` (default, returns after scheduling) or `sync` (returns after all requested frames complete at VBlank). Use `mode: "sync"` when issuing dependent tool calls.
- `debug_run_to_cursor` - Continue execution until reaching specified address
- `debug_reset` - Reset the Atari Lynx emulated system
- `debug_get_status` - Get debugger status (paused, at_breakpoint, pc address)

### CPU & Registers
- `get_6502_status` - Get 6502 CPU status (registers, flags, interrupts, memory map visibility based on MAPCTL)
- `write_6502_register` - Write to a 6502 CPU register (PC, A, X, Y, S, P)

### Memory Operations
- `list_memory_areas` - List memory editor tabs (RAM, Zero Page, Stack, Bank 0/0A/1/1A, BIOS, EEPROM) with CPU address ranges
- `read_memory` - Read from specific memory area
- `write_memory` - Write to specific memory area
- `get_memory_selection` - Get current memory selection range
- `select_memory_range` - Select a range of memory addresses
- `set_memory_selection_value` - Set all bytes in selection to specified value
- `add_memory_bookmark` - Add bookmark in memory area
- `remove_memory_bookmark` - Remove memory bookmark
- `list_memory_bookmarks` - List all bookmarks in memory area
- `add_memory_watch` - Add watch (tracked memory location)
- `remove_memory_watch` - Remove memory watch
- `list_memory_watches` - List all watches in memory area
- `memory_search_capture` - Capture memory snapshot for search comparison
- `memory_search` - Search memory with operators (<, >, ==, !=, <=, >=), compare types (previous, value, address), and data types (hex, signed, unsigned)
- `memory_find` - Find hex byte sequences (`hex_bytes`) or text (`text`, optional `case_sensitive`) in memory

### Disassembly & Debugging
- `get_disassembly` - Get disassembled 6502 code for specified address range (only executed code is available)
- `add_symbol` - Add symbol (label) at specified address
- `remove_symbol` - Remove symbol
- `list_symbols` - List all defined symbols
- `lookup_symbol_by_name` - Find all exact-name symbol matches
- `lookup_symbol_at_address` - Find symbol at address
- `load_symbols` - Load debug symbols from file (.sym ADDRESS LABEL, llvm-nm text, llvm-mos ELF, and other supported label formats)
- `add_disassembler_bookmark` - Add bookmark in disassembler
- `remove_disassembler_bookmark` - Remove disassembler bookmark
- `list_disassembler_bookmarks` - List all disassembler bookmarks
- `get_call_stack` - View function call hierarchy
- `get_trace_log` - Read trace entries by absolute sequence. Omit `start` for the latest 100 retained entries, or use a negative value to start that many entries from the retained tail. Results contain `total_entries`, monotonic `total_logged`, `oldest_sequence`, actual `start`, `next_sequence`, `count`, `overrun`, and formatted `lines`. An expired non-negative start is advanced to `oldest_sequence` with `overrun=true`.
- `set_trace_log` - Start or stop tracing. `enabled` is required. Optional storage settings are `output` (`memory` or `disk`), `memory_size` (`100K`, `500K`, `1M`, `2M`, `5M`), `disk_size` (`10MB`, `50MB`, `100MB`, `250MB`, `500MB`, `1GB`, `unbounded`), and `output_path` (directory). `filters` is a non-empty unique array of exact names; omission selects `cpu.instructions` and `cpu.irqs`. Optional `debug_output` controls $FDC0-$FDC4 and preserves its current state when omitted. Filter-only changes preserve retained memory and active disk files.

Exact trace filters:

- CPU: `cpu.instructions`, `cpu.irqs`
- Suzy math/input: `suzy.math.operations`, `suzy.math.completions`, `suzy.input.reads`
- Suzy sprites: `suzy.sprites.engine`, `suzy.sprites.scbs`, `suzy.sprites.skips`, `suzy.sprites.collisions`, `suzy.sprites.rows`, `suzy.bus`
- Mikey timers/display: `mikey.timers.registers`, `mikey.timers.underflows`, `mikey.timers.irqs`, `mikey.timers.links`, `mikey.interrupts`, `mikey.display.registers`, `mikey.display.palette`, `mikey.display.dma`, `mikey.display.timing`, `mikey.display.missed_vblank`
- Mikey audio/UART: `mikey.audio.channels`, `mikey.audio.mixer`, `mikey.audio.clocks`, `mikey.uart.registers`, `mikey.uart.transfers`, `mikey.uart.irqs`, `mikey.uart.problems`, `mikey.uart.breaks`, `mikey.uart.comlynx`
- RedEye/cartridge/debug: `redeye.packets`, `redeye.problems`, `cartridge.address`, `cartridge.accesses`, `cartridge.eeprom`, `cartridge.audin`, `cartridge.storage`, `debug.messages`

`mikey.display.missed_vblank` logs each frame where the CPU access set with `vblank_watch_address` (hex) and `vblank_watch_operation` (`read`, `write`, or `read_write`) did not happen before the Timer 2 underflow that raises the VBL interrupt, with the number of consecutive misses; the first VBlank after starting, changing the watch, resetting, or loading a state only arms the check. Both parameters persist and keep their current values when omitted.

CPU entries are captured before opcode fetch. Hardware events emitted while Suzy and Mikey process a completed CPU/bus batch use that committed batch's `GearlynxCore::m_total_cycles` position. A backwards clock after reset is formatted as `RESET`; sequence identities remain monotonic across clears and resets.

### Profiler
- `set_profiler` - Start, stop, or reset the function profiler with `action` (`start`, `stop`, `reset`). `start` opens the Profiler debugger window and `stop` closes it. Statistics are only collected while the window is visible (in headless mode, while started), starting on the next frame
- `get_profiler_data` - Read profiler results: `collecting`, `window_open`, `total_cycles`, `frame_cycles`, `frames`, `function_count`, and per-function `name`, `symbol`, `address`, `type`, `calls`, `calls_per_frame`, `inclusive_cycles`, `inclusive_percent`, `exclusive_cycles`, `exclusive_percent`, `average_cycles`, `min_cycles`, and `max_cycles`. Optional `sort` (`inclusive`, `exclusive`, `calls`, `average`, `max`; highest first), `count` (default 50, max 1000), and `filter` (name or hex address substring)

### Breakpoints
- `set_breakpoint` - Set execution, read, or write breakpoint at address. Read/write breakpoints stop with PC at instruction after memory access
- `set_breakpoint_range` - Set breakpoint for an address range (exec, read, or write)
- `remove_breakpoint` - Remove breakpoint (single address or range)
- `list_breakpoints` - List all breakpoints
- `set_breakpoint_on_irq` - Set breakpoint on specific IRQ (Timer0-7)
- `clear_breakpoint_on_irq` - Clear IRQ breakpoint
- `list_breakpoints_on_irq` - List which IRQs have breakpoints set

### Hardware Status
- `get_mikey_registers` - Get all Mikey registers ($FD00-$FDFF) or filter by specific address
- `write_mikey_register` - Write to a Mikey register
- `get_mikey_timers` - Get timer status (Timer 0-7: HBLANK, VBLANK, UART, etc.)
- `get_mikey_audio` - Get audio channel status (Channel 0-3)
- `get_suzy_registers` - Get all Suzy registers ($FC00-$FCFF) or filter by specific address
- `write_suzy_register` - Write to a Suzy register
- `get_uart_status` - Get UART (ComLynx) status
- `get_cart_status` - Get cartridge status (address generation, bank 0/1 info, AUDIN)
- `get_eeprom_status` - Get EEPROM status (type, size, mode, state, IO pins)
- `get_lcd_status` - Get LCD status. Pixel and DMA info only on visible lines

### Screen Capture
- `get_screenshot` - Capture current screen frame as base64 PNG
- `start_video_recording` - Start recording video and audio to an AVI file (MJPEG, uncompressed or PNG compressed video, 16-bit PCM audio). Only the resulting `file_path` is returned; the video stays on disk. Optional `file_path` (absolute; if omitted, an automatic name in the configured video recordings directory), `scale` (1-20), `aspect_ratio` (`screen`, `square`, `4:3`, `16:9`, `16:10`), and `quality` (`low`, `medium`, `high`, `lossless`, `lossless_compressed`). `lossless` is uncompressed; `lossless_compressed` stores PNG frames, much smaller but playable only with FFmpeg based players. Given options update the recording settings, same as the GUI menu. `screen` follows the display aspect ratio, which uses square pixels while debugging. When a shader preset is active outside debug mode, the shader output is recorded at the output window size and `scale` and `aspect_ratio` are ignored. Frames are recorded only while the emulator runs, so continue or step execution before stopping
- `stop_video_recording` - Stop the active recording and finalize the AVI file. Returns `file_path` and the number of recorded `frames`
- `get_frame_buffer` - Capture debug frame buffer as base64 PNG (VIDBAS from Suzy or DISPADR from Mikey)
- `get_sprite` - Render SCB sprite image or return sprite metadata

### Media & State Management
- `get_media_info` - Get loaded ROM info (file path, type, size, CRC, rotation, EEPROM, BIOS status)
- `list_recent_media` - List the 10 most recent ROM files opened by Gearlynx
- `load_media` - Load ROM file (.lnx, .lyx, .o, .zip). Automatically loads symbol file if present (.sym, .elf, .lbl, .noi)
- `load_bios` - Load BIOS file (must be exactly 512 bytes).
- `list_save_state_slots` - List all 5 save state slots with information (rom name, timestamp, screenshot availability)
- `select_save_state_slot` - Select active save state slot (1-5) for save/load operations
- `save_state` - Save emulator state to currently selected slot
- `load_state` - Load emulator state from currently selected slot
- `save_state_file` - Save emulator state to an explicit file path
- `load_state_file` - Load emulator state from an explicit file path
- `set_fast_forward_speed` - Set fast forward speed multiplier (0: 1.5x, 1: 2x, 2: 2.5x, 3: 3x, 4: Unlimited)
- `toggle_fast_forward` - Toggle fast forward mode on/off
- `get_rewind_status` - Get rewind buffer status (snapshot count, capacity, buffered seconds, configuration)
- `rewind_seek` - Seek to a specific rewind snapshot by number (1 = oldest, snapshot_count = newest). Non-destructive — can seek repeatedly

### Cheats
- `list_cheats` - List cheats with index, code, description, enabled, valid and active state
- `add_cheat` - Add an enabled cheat: `AAAA:VV` or `AAAA?CC:VV` at a 16-bit RAM address (e.g. `0050:05`), join codes with `+`
- `remove_cheat` - Remove a cheat by index

### Controller Input
- `controller_button` - Control a button on the Lynx controller. Use action 'press' to hold, 'release' to let go, or 'press_and_release' for a quick tap. Buttons: up, down, left, right, a, b, option1, option2, pause
- `controller_macro` - Run an ordered input macro. Supported commands are `tap`, `press`, `release`, and `wait`; timing is explicit through `wait` frame counts
- `get_input_state` - Get effective pressed buttons and pending tap releases

## Available MCP Resources

In addition to tools, the MCP server provides documentation resources that AI assistants can access to better understand the Atari Lynx hardware and programming.

In Claude Code, type `@` in your prompt to pick a resource, or reference one directly, for example `@gearlynx:gearlynx://hardware/lynx1_general_overview`. Codex reads resources through its built-in MCP resource tools, so ask it to read the ones that are relevant.

### Hardware Documentation Resources

Complete technical reference documentation for Atari Lynx hardware components:

- **Chapter 1: General Overview** (`gearlynx://hardware/lynx1_general_overview`) - Marketing Feature Set and External Specification
- **Chapter 2: Hardware Overview** (`gearlynx://hardware/lynx2_hardware_overview`) - System components overview including CPU, Mikey, and Suzy
- **Chapter 3: Software Related Hardware Perniciousness** (`gearlynx://hardware/lynx3_software_hardware_perniciousness`) - Important notes about hardware quirks and issues
- **Chapter 4-5: CPU/ROM** (`gearlynx://hardware/lynx4_cpu_rom`) - CPU cycle timing, ROM, and CPU Sleep documentation
- **Chapter 6: Display** (`gearlynx://hardware/lynx5_display`) - Frame Rate, Pen Numbers/Color Palette, Display Buffers
- **Chapter 7: Sprite/Collision** (`gearlynx://hardware/lynx6_sprite_collision`) - Sprite features, data structure, and engine documentation
- **Chapter 8-10: Audio, Magnetic Tape, ROM Cart** (`gearlynx://hardware/lynx7_audio_tape_romcart`) - Audio system, magnetic tape interface, and ROM cartridge
- **Chapter 11: Timers/Interrupts** (`gearlynx://hardware/lynx8_timers_interrupts`) - Timer system and interrupt handling
- **Chapter 11a: UART** (`gearlynx://hardware/lynx8a_uart`) - UART connector signals, baud rate, and data format
- **Chapter 12-13: Other Hardware Features** (`gearlynx://hardware/lynx9_other_hardware`) - Multiply/Divide hardware, Parallel Port, Expansion Connector
- **Chapter 14-19: System Reset and Related Topics** (`gearlynx://hardware/lynx10_system_reset`) - System Reset/Power Up, Definitions, Variances, Exemptions, Common Errors, Savegame
- **Appendix 1: System Bus Interplay** (`gearlynx://hardware/lynx11_system_bus_interplay`) - System bus architecture and interactions
- **Appendix 2: Interrupts and CPU Sleep** (`gearlynx://hardware/irq_interrupts_cpu_sleep`) - Handy interrupts, CPU sleep mode, and debugging
- **Appendix 3: Hardware Addresses** (`gearlynx://hardware/hardware_addresses`) - Complete memory map and register documentation for Mikey and Suzy
- **Appendix 4: Sprite Engine** (`gearlynx://hardware/sprite_engine`) - Display creation, double-buffering, and sprite positioning

## How MCP Works in Gearlynx

- The MCP server runs **alongside** the GUI in a background thread
- The emulator GUI remains fully functional (you can play/debug normally while using MCP)
- Commands from the AI are queued and executed on the GUI thread
- Both GUI and MCP share the same emulator state
- Changes made through MCP are instantly reflected in the GUI and vice versa

## Architecture

### STDIO Transport
```
┌─────────────────┐                    ┌──────────────────┐
│  Claude Code /  │       stdio        │     Gearlynx     │
│      Codex      │◄──────────────────►│    MCP Server    │
│   (AI Client)   │       pipes        │   (background)   │
└─────────────────┘                    └──────────────────┘
        │                                       │
        └───► Launches ►────────────────────────┘
                                                │
                                                │ Shared State
                                                ▼
                                       ┌──────────────────┐
                                       │   Emulator Core  │
                                       │   + GUI Window   │
                                       └──────────────────┘
```

### HTTP Transport
```
┌─────────────────┐                    ┌──────────────────┐
│  Claude Code /  │  HTTP (port 7777)  │     Gearlynx     │
│      Codex      │◄──────────────────►│ MCP HTTP Server  │
│   (AI Client)   │                    │    (listener)    │
└─────────────────┘                    └──────────────────┘
                                                │
                                                │ Shared State
                                                ▼
                                       ┌──────────────────┐
                                       │   Emulator Core  │
                                       │   + GUI Window   │
                                       └──────────────────┘
```