Gearsystem MCP — Cas d'usage, Installer & Démo en direct

Pourquoi l'utiliser

Fonctionnalités clés

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

Démo en direct

Aperçu en pratique

gearsystem.replay ▶ prêt

0/0

Installer

Choisissez votre client

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

Ouvrez Claude Desktop → Settings → Developer → Edit Config. Redémarrez après avoir enregistré.

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

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

Cursor utilise le même schéma mcpServers que Claude Desktop. La config projet l'emporte sur la globale.

VS Code → Cline → MCP Servers → Edit

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

Cliquez sur l'icône MCP Servers dans la barre latérale Cline, puis "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Même format que Claude Desktop. Redémarrez Windsurf pour appliquer.

~/.continue/config.json

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

Continue utilise un tableau d'objets serveur plutôt qu'une map.

~/.config/zed/settings.json

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

Ajoutez dans context_servers. Zed recharge à chaud à la sauvegarde.

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

Une seule ligne. Vérifiez avec claude mcp list. Supprimez avec claude mcp remove.

Cas d'usage

Usages concrets : Gearsystem

Debug a homebrew Master System ROM that crashes on title screen

👤 Retro homebrew developers ⏱ ~30 min advanced

Quand l'utiliser : Your WLA-DX build runs fine in your head but Gearsystem freezes on the title screen.

Prérequis

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

Déroulement

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.✓ Copié

→ 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?✓ Copié

→ 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.✓ Copié

→ Stops at the offending instruction

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

Pièges

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

Combiner avec : 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

Quand l'utiliser : You're writing a tech analysis article or disassembly and need a memory map.

Déroulement

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.✓ Copié

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

→ Hypothesized variable map with justification

Résultat : A first-pass memory map you can refine by hand.

Pièges

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

Quand l'utiliser : You want 'boots to title screen without crashing' as a CI gate.

Déroulement

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.✓ Copié

→ Shell script with clear exit codes
Wire into CI

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

→ Working CI step

Résultat : A smoke test that catches regressions before you manually load the ROM.

Combiner avec : github

Combinaisons

Associez-le à d'autres MCPs pour un effet 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.✓ Copié

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.✓ Copié

Outils

Ce que ce MCP expose

Outil	Entrées	Quand appeler	Coût
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

Coût et limites

Coût d'exécution

Quota d'API: None — fully local process
Tokens par appel: Memory dumps can be large; narrow ranges keep responses small
Monétaire: Free, GPL-3.0 licensed
Astuce: Ask for small memory windows (16-64 bytes) unless you actually need a full page.

Sécurité

Permissions, secrets, portée

Stockage des identifiants : None needed

Sortie de données : 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.

Dépannage

Erreurs courantes et correctifs

MCP flags not recognized

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

Vérifier : 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.

Vérifier : 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.

Vérifier : curl http://127.0.0.1:7777/

Alternatives

Gearsystem vs autres

Alternative	Quand l'utiliser	Compromis
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

Plus

Ressources

📖 Lire le README officiel sur GitHub

🐙 Voir les issues ouvertes

🔍 Parcourir les 400+ serveurs MCP et Skills