Gearsystem MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

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

Demo ao vivo

Como fica na prática

gearsystem.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/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
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

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

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

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

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

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

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

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

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

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

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

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Gearsystem

Debug a homebrew Master System ROM that crashes on title screen

👤 Retro homebrew developers ⏱ ~30 min advanced

Quando usar: Your WLA-DX build runs fine in your head but Gearsystem freezes on the title screen.

Pré-requisitos

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.)

Fluxo

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.✓ Copiado

→ 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?✓ Copiado

→ 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.✓ Copiado

→ Stops at the offending instruction

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

Armadilhas

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

Combine com: 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

Quando usar: You're writing a tech analysis article or disassembly and need a memory map.

Fluxo

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.✓ Copiado

→ 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)?✓ Copiado

→ Hypothesized variable map with justification

Resultado: A first-pass memory map you can refine by hand.

Armadilhas

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

Quando usar: You want 'boots to title screen without crashing' as a CI gate.

Fluxo

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.✓ Copiado

→ Shell script with clear exit codes
Wire into CI

Wrap that in a GitHub Actions workflow that runs on every push to main.✓ Copiado

→ Working CI step

Resultado: A smoke test that catches regressions before you manually load the ROM.

Combine com: github

Combinações

Combine com outros MCPs para 10× de alavancagem

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.✓ Copiado

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.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
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

Custo e limites

O que custa rodar

Cota de API: None — fully local process
Tokens por chamada: Memory dumps can be large; narrow ranges keep responses small
Monetário: Free, GPL-3.0 licensed
Dica: Ask for small memory windows (16-64 bytes) unless you actually need a full page.

Segurança

Permissões, segredos, alcance

Armazenamento de credenciais: None needed

Saída de dados: 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.

Solução de problemas

Erros comuns e correções

MCP flags not recognized

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

Verificar: 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.

Verificar: 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.

Verificar: curl http://127.0.0.1:7777/

Alternativas

Gearsystem vs. outros

Alternativa	Quando usar	Troca
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

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills