Gearboy MCP — Сценарии использования, Установка & Живое демо

Зачем использовать

Ключевые функции

Embedded MCP server with stdio and HTTP transport for AI-assisted debugging
Advanced debugger: JIT disassembler, CPU/memory breakpoints, trace logging
VRAM viewer with tile, sprite, and palette inspection
Supports MBC1-7, HuC-1/3, MMM01, Pocket Camera, TAMA5 cartridge types
LCD ghosting and dot matrix visual effects mimicking original hardware

Живое демо

Как выглядит на практике

gearboy-2.replay ▶ готово

0/0

Установка

Выберите клиент

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

Откройте Claude Desktop → Settings → Developer → Edit Config. Перезапустите после сохранения.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

Cursor использует ту же схему mcpServers, что и Claude Desktop. Конфиг проекта приоритетнее глобального.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

Щёлкните значок MCP Servers на боковой панели Cline, затем "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

Тот же формат, что и Claude Desktop. Перезапустите Windsurf для применения.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "gearboy-2",
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  ]
}

Continue использует массив объектов серверов, а не map.

~/.config/zed/settings.json

{
  "context_servers": {
    "gearboy-2": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/drhelius/Gearboy"
        ]
      }
    }
  }
}

Добавьте в context_servers. Zed перезагружается автоматически.

claude mcp add gearboy-2 -- TODO 'See README: https://github.com/drhelius/Gearboy'

Однострочная команда. Проверить: claude mcp list. Удалить: claude mcp remove.

Сценарии использования

Реальные сценарии: Gearboy

How to debug a Game Boy ROM with AI assistance using Gearboy

👤 Homebrew Game Boy developers and ROM hackers ⏱ ~30 min intermediate

Когда использовать: You're developing a Game Boy homebrew ROM and need to debug runtime issues.

Предварительные требования

Gearboy built with MCP support — Build from source following the GitHub README
A Game Boy ROM file (.gb or .gbc) — Your own homebrew ROM or a ROM you legally own

Поток

Load ROM and connect

Connect to the Gearboy MCP server and load my ROM. Show me the current CPU state and disassembly at the program counter.✓ Скопировано

→ CPU registers, flags, and disassembled instructions at PC
Set a breakpoint and investigate

Set a breakpoint at address 0x0150 (after the header). Step through execution and explain what each instruction does.✓ Скопировано

→ Step-by-step execution with instruction explanations
Inspect memory

Show me the contents of WRAM from 0xC000 to 0xC0FF. Are there any recognizable data structures?✓ Скопировано

→ Memory dump with analysis of data patterns

Итог: A clear understanding of how the ROM executes, with bugs identified and explained.

Подводные камни

Breakpoints on frequently-hit addresses slow execution dramatically — Use conditional breakpoints or set them only when you're close to the bug

Сочетать с: filesystem

Learn Game Boy architecture interactively with AI and Gearboy

👤 Students learning retro console hardware and assembly ⏱ ~45 min intermediate

Когда использовать: You want to understand how the Game Boy CPU, memory, and graphics work hands-on.

Предварительные требования

Gearboy with MCP server — Build from source
A simple test ROM — Use a homebrew test ROM or Blargg's test ROMs

Поток

Explore the memory map

Show me the Game Boy memory map. Read the ROM header at 0x0100-0x014F and explain each field.✓ Скопировано

→ Annotated header with title, cartridge type, ROM/RAM sizes
Watch VRAM in action

Step through the VBlank interrupt handler and explain how tiles are loaded into VRAM.✓ Скопировано

→ Step-by-step explanation of tile loading with VRAM state

Итог: Hands-on understanding of Game Boy hardware through interactive exploration.

Подводные камни

Assembly can be overwhelming for beginners — Start with simple test ROMs that exercise one hardware feature at a time

Комбинации

Сочетайте с другими MCP — эффект x10

gearboy-2 + filesystem

Export memory dumps and debug logs for offline analysis

Dump the entire VRAM contents to a file and annotate the tile data layout.✓ Скопировано

Инструменты

Что предоставляет этот MCP

Инструмент	Входные данные	Когда вызывать
pause/resume/step	none / step_count?	Control emulator execution
read_memory	address: int, size: int	Read emulator memory at any address
write_memory	address: int, data: bytes	Write to emulator memory
set_breakpoint	address: int, type?: str	Set a CPU or memory breakpoint
disassemble	address: int, count: int	Disassemble instructions at an address
get_cpu_state	none	Get current CPU registers and flags

Стоимость и лимиты

Во что обходится

Квота API: N/A — fully local
Токенов на вызов: 100–500 tokens per debug command
Деньги: Free and open source (MIT license)
Совет: Use targeted memory reads instead of full dumps to keep token usage low.

Безопасность

Права, секреты, радиус поражения

Хранение учётных данных: N/A

Исходящий трафик: Fully local — no network calls

Устранение неполадок

Частые ошибки и исправления

MCP server not responding

Ensure Gearboy was built with MCP support enabled. Check that the server port (default 7777) is not in use.

Проверить: curl http://localhost:7777/health

ROM fails to load

Verify the ROM file is a valid .gb or .gbc file. Check the file isn't corrupted.

Проверить: Check the ROM header with a hex editor

Breakpoint never hits

Verify the address is in the execution path. Use the disassembler to check if code actually runs at that address.

Проверить: Disassemble around the target address

Альтернативы

Gearboy в сравнении

Альтернатива	Когда использовать	Компромисс
Geargrafx	You want to debug PC Engine / TurboGrafx-16 ROMs instead of Game Boy	Different console, same MCP-enabled emulator approach by the same developer

Ещё

Ресурсы

📖 Читать официальный README на GitHub

🐙 Открытые задачи

🔍 Все 400+ MCP-серверов и Skills