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

Por qué usarlo

Características clave

Servidor MCP integrado — un único binario que funciona como emulador + depurador + MCP
Transportes stdio y HTTP (--mcp-stdio o --mcp-http --mcp-http-port N)
Puede ejecutarse sin interfaz gráfica (headless) a través de MCP para sesiones automatizadas o dirigidas por agentes
Puntos de ruptura de CPU, puntos de ruptura de acceso a memoria, ejecución paso a paso, desensamblade
Inspección de VRAM y paleta para depuración de gráficos

Demo en vivo

Cómo se ve en la práctica

gearsystem.replay ▶ listo

0/0

Instalar

Elige tu 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
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

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

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

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

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

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

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

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

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

Añádelo a context_servers. Zed recarga en caliente al guardar.

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

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: Gearsystem

Depura un ROM homebrew de Master System que se bloquea en la pantalla de título

👤 Desarrolladores de homebrew retro ⏱ ~30 min advanced

Cuándo usarlo: Tu compilación de WLA-DX funciona bien en teoría pero Gearsystem se congela en la pantalla de título.

Requisitos previos

Gearsystem compilado con MCP habilitado — Clona drhelius/Gearsystem y compila según MCP_README.md
El ROM y su archivo de símbolos .sym — Salida de tu ensamblador (WLA-DX, asm6, etc.)

Flujo

Inicia sin interfaz gráfica (headless) y establece un punto de ruptura en el punto de bloqueo

Inicia Gearsystem MCP con mi ROM. Establece un punto de ruptura de CPU en la etiqueta init_vdp y ejecuta.✓ Copiado

→ La ejecución se detiene en el punto de ruptura
Inspecciona el estado de CPU y VRAM

Muéstrame los registros Z80 y los primeros 32 bytes de VRAM. ¿Hay algo que parezca mal en este punto de init?✓ Copiado

→ Volcado de registros + observaciones sobre lo esperado vs lo actual
Ejecuta paso a paso y observa una región de memoria específica

Añade un punto de ruptura de acceso a memoria en $C000 y ejecuta paso a paso hasta que algo escriba allí.✓ Copiado

→ Se detiene en la instrucción problemática

Resultado: Una causa raíz (ej. registro VDP escrito antes de que VRAM sea seguro) con la dirección exacta de la instrucción.

Errores comunes

Símbolos no cargados — las direcciones son opacas — Asegúrate de que .sym coincida con la compilación exacta del ROM; recompila para alinear si es necesario
El error de temporización solo se reproduce en hardware real, no en el emulador — El emulador tiene limitaciones; para casos extremos de temporización de bus, prueba en un SMS real

Combinar con: filesystem

Realiza ingeniería inversa de un ROM que posees para documentar su mapa de memoria

👤 Preservacionistas y desarrolladores que documentan sus propios ROMs o ROMs de dominio público ⏱ ~60 min advanced

Cuándo usarlo: Estás escribiendo un artículo de análisis técnico o desensamblade y necesitas un mapa de memoria.

Flujo

Ejecuta el ROM e inspecciona en momentos clave

Inicia el ROM, detente en VBlank, vuelca WRAM en $C000-$DFFF. Luego ejecuta un fotograma y vuelca nuevamente.✓ Copiado

→ Dos instantáneas de WRAM para comparar
Identifica variables probables mediante comparación

Compara las dos instantáneas. ¿Qué direcciones cambiaron? ¿Qué es probable que sean (contadores, punteros, posiciones de sprites)?✓ Copiado

→ Mapa de variables hipotéticas con justificación

Resultado: Un primer mapa de memoria que puedes refinar manualmente.

Errores comunes

La ingeniería inversa de ROMs comerciales protegidos por derechos de autor que no posees está en un área legal gris — Solo utiliza esto en ROMs que poseas o que estén en el dominio público. No publiques mapas de RAM de ROMs comerciales sin considerar las normas de uso justo en tu jurisdicción

Automatiza una prueba de humo para tu ROM en cada commit

👤 Desarrolladores de homebrew con un pipeline de CI ⏱ ~25 min intermediate

Cuándo usarlo: Deseas que 'inicia hasta la pantalla de título sin bloquearse' sea una puerta de CI.

Flujo

Crea un script para la sesión de MCP

Escribe un script que inicie Gearsystem MCP sin interfaz gráfica, ejecute mi ROM durante 600 fotogramas y devuelva un código no cero si la CPU se detiene en un opcode inválido.✓ Copiado

→ Script de shell con códigos de salida claros
Integra en CI

Envuelve eso en un flujo de trabajo de GitHub Actions que se ejecute en cada push a main.✓ Copiado

→ Paso de CI funcional

Resultado: Una prueba de humo que detecte regresiones antes de que cargues manualmente el ROM.

Combinar con: github

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

gearsystem + github

Depura y confirma una solución en un flujo

Reproduce el problema #12 en mi ROM, encuentra la dirección fautla, abre un PR con una solución de una línea en src/vdp.asm.✓ Copiado

gearsystem + filesystem

Lee el archivo .sym junto con el depurador para traducir direcciones a etiquetas

Carga ./build/game.sym e indícame la etiqueta en la dirección $03A7.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
run	(ninguno)	Reanuda la ejecución después de una pausa	gratuito (local)
pause	(ninguno)	Detén para inspeccionar	gratuito
step	n?: int	Ejecuta instrucciones paso a paso	gratuito
set_breakpoint	address: hex, kind: cpu\|read\|write	Observa un salto de PC o acceso a memoria	gratuito
read_memory	address: hex, length: int	Inspecciona regiones de WRAM / VRAM / cartucho	gratuito
disassemble	address: hex, instructions: int	Lee código alrededor de un PC	gratuito
get_registers	(ninguno)	Cualquier momento de inspección	gratuito
dump_vram	start?: hex, length?: int	Depuración de gráficos	gratuito

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Ninguno — proceso completamente local
Tokens por llamada: Los volcados de memoria pueden ser grandes; los rangos estrechos mantienen las respuestas pequeñas
Monetario: Gratuito, licencia GPL-3.0
Consejo: Solicita ventanas de memoria pequeñas (16-64 bytes) a menos que realmente necesites una página completa.

Seguridad

Permisos, secretos, alcance

Almacenamiento de credenciales: Ninguno necesario

Salida de datos: Se ejecuta localmente; el servidor MCP se vincula a stdio o al puerto HTTP elegido

Si expones --mcp-http, vincula solo a 127.0.0.1 — nada autentica el endpoint.
Los ROMs cargados pueden ser datos no confiables arbitrarios; el emulador está en un sandbox pero no otorgues al proceso privilegios adicionales.

Resolución de problemas

Errores comunes y soluciones

Banderas de MCP no reconocidas

Tu compilación se compiló sin soporte de MCP. Recompila con la bandera habilitada según MCP_README.md.

Verificar: gearsystem --help | grep mcp

El punto de ruptura nunca se alcanza

La resolución de símbolos es probable que esté desactivada; intenta usar una dirección sin procesar en lugar de una etiqueta. Confirma que el ROM está realmente cargado.

Verificar: Usa get_registers para confirmar que PC se está moviendo

El transporte HTTP rechazó la conexión

Verifica que el puerto no esté en uso y que el emulador se haya iniciado con --mcp-http --mcp-http-port 7777.

Verificar: curl http://127.0.0.1:7777/

Alternativas

Gearsystem vs otros

Alternativa	Cuándo usarla	Contrapartida
Emulicious	Deseas un depurador GUI completo para Game Boy/SMS/etc.	Sin MCP; solo dirigido por humanos
BizHawk	Depuración y TAS multisistema	Con scripts Lua en lugar de MCP

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills