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

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

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

Embedded MCP server — one binary is emulator + debugger + MCP
stdio and HTTP transports (--mcp-stdio or --mcp-http --mcp-http-port N)
Can run headless via MCP for automated/agent-driven sessions
CPU breakpoints, memory-access breakpoints, step, disassembly
VRAM and palette inspection for graphics debugging

Живое демо

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

gearsystem.replay ▶ готово

0/0

Установка

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

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

{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

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

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

{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

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

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "gearsystem",
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ]
    }
  ]
}

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

~/.config/zed/settings.json

{
  "context_servers": {
    "gearsystem": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/drhelius/Gearsystem"
        ]
      }
    }
  }
}

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

claude mcp add gearsystem -- TODO 'See README: https://github.com/drhelius/Gearsystem'

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

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

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

Debug a homebrew Master System ROM that crashes on title screen

👤 Retro homebrew developers ⏱ ~30 min advanced

Когда использовать: Your WLA-DX build runs fine in your head but Gearsystem freezes on the title screen.

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

Gearsystem built with MCP enabled — Clone drhelius/Gearsystem and build per MCP_README.md
The ROM and its .sym symbol file — Output of your assembler (WLA-DX, asm6 etc.)

Поток

Launch headless and set a breakpoint at the crash point

Launch Gearsystem MCP with my ROM. Set a CPU breakpoint at the label init_vdp and run.✓ Скопировано

→ Execution halts at the breakpoint
Inspect CPU and VRAM state

Show me the Z80 registers and the first 32 bytes of VRAM. Anything look wrong for this point in init?✓ Скопировано

→ Register dump + observations about expected vs actual
Step through and watch a specific memory region

Add a memory-access breakpoint on $C000 and step until something writes there.✓ Скопировано

→ Stops at the offending instruction

Итог: A root cause (e.g. VDP register written before VRAM is safe) with the exact instruction address.

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

Symbols not loaded — addresses are opaque — Make sure .sym matches the exact ROM build; rebuild to align if needed
Timing bug only repros on real hardware, not emulator — Emulator has limits; for bus timing edge cases, test on a real SMS

Сочетать с: filesystem

Reverse-engineer a ROM you own to document its memory map

👤 Preservationists and devs documenting their own or public-domain ROMs ⏱ ~60 min advanced

Когда использовать: You're writing a tech analysis article or disassembly and need a memory map.

Поток

Run the ROM and inspect at key moments

Boot the ROM, break at VBlank, dump WRAM at $C000-$DFFF. Then run one frame and dump again.✓ Скопировано

→ Two WRAM snapshots for diffing
Identify likely variables by diffing

Compare the two snapshots. Which addresses changed? What are they likely to be (counters, pointers, sprite positions)?✓ Скопировано

→ Hypothesized variable map with justification

Итог: A first-pass memory map you can refine by hand.

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

Reverse-engineering commercial copyrighted ROMs you don't own is a legal gray area — Only use this on ROMs you own or that are in the public domain. Don't publish RAM maps for commercial ROMs without considering fair-use rules in your jurisdiction

Automate a smoke test for your ROM on every commit

👤 Homebrew devs with a CI pipeline ⏱ ~25 min intermediate

Когда использовать: You want 'boots to title screen without crashing' as a CI gate.

Поток

Script the MCP session

Write a script that launches Gearsystem MCP headless, runs my ROM for 600 frames, and returns non-zero if the CPU halted on an invalid opcode.✓ Скопировано

→ Shell script with clear exit codes
Wire into CI

Wrap that in a GitHub Actions workflow that runs on every push to main.✓ Скопировано

→ Working CI step

Итог: A smoke test that catches regressions before you manually load the ROM.

Сочетать с: github

Комбинации

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

gearsystem + github

Debug and commit a fix in one flow

Reproduce issue #12 in my ROM, find the faulting address, open a PR with a one-liner fix in src/vdp.asm.✓ Скопировано

gearsystem + filesystem

Read the .sym file alongside the debugger to translate addresses to labels

Load ./build/game.sym and tell me the label at address $03A7.✓ Скопировано

Инструменты

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

Инструмент	Входные данные	Когда вызывать	Стоимость
run	(none)	Resume execution after a break	free (local)
pause	(none)	Halt to inspect	free
step	n?: int	Single-step instructions	free
set_breakpoint	address: hex, kind: cpu\|read\|write	Watch for a PC hit or memory access	free
read_memory	address: hex, length: int	Inspect WRAM / VRAM / cart regions	free
disassemble	address: hex, instructions: int	Read code around a PC	free
get_registers	(none)	Any inspection moment	free
dump_vram	start?: hex, length?: int	Graphics debugging	free

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

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

Квота API: None — fully local process
Токенов на вызов: Memory dumps can be large; narrow ranges keep responses small
Деньги: Free, GPL-3.0 licensed
Совет: Ask for small memory windows (16-64 bytes) unless you actually need a full page.

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

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

Хранение учётных данных: None needed

Исходящий трафик: Runs locally; MCP server binds to stdio or chosen HTTP port

If you expose --mcp-http, bind only to 127.0.0.1 — nothing authenticates the endpoint.
Loaded ROMs can be arbitrary untrusted data; emulator is sandboxed but don't grant the process extra privileges.

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

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

MCP flags not recognized

Your build was compiled without MCP support. Rebuild with the flag enabled per MCP_README.md.

Проверить: gearsystem --help | grep mcp

Breakpoint never hits

Symbol resolution likely off; try using a raw address instead of a label. Confirm ROM is actually loaded.

Проверить: Use get_registers to confirm PC is moving

HTTP transport refused connection

Check the port isn't in use and the emulator started with --mcp-http --mcp-http-port 7777.

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

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

Gearsystem в сравнении

Альтернатива	Когда использовать	Компромисс
Emulicious	You want a full GUI debugger for Game Boy/SMS/etc.	No MCP; human-driven only
BizHawk	Multi-system TAS/debugging	Lua-scripted rather than MCP

Ещё

Ресурсы

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

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

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