gdb-multiarch-mcp

Un servidor MCP (Model Context Protocol) que brinda a asistentes de IA como Claude acceso directo a gdb-multiarch para depurar ejecutables de Nintendo Switch que se ejecutan en Yuzu o en una consola real con un stub de GDB.

Construido sobre Ipiano/gdb-mcp, este fork añade herramientas de depuración específicas para Switch para puntos de interrupción basados en desplazamiento, parcheo de instrucciones (NOP/stub/reemplazo), seguimientos de pila de puntero de marco y localización de direcciones, todo relativo a la dirección base del juego ($main).

Qué hace

Cuando Claude (o cualquier cliente MCP) llama a switch_start_session, el servidor:

1. Inicia gdb-multiarch dentro de WSL

2. Carga los comandos de depuración de Switch (.gdbinit.switch)

3. Se conecta al stub de GDB mediante target extended-remote

4. Espera a que la aplicación se inicie y se adjunta a ella

5. Establece automáticamente $main en la dirección base de cross2_Release.nss

A partir de ahí, todas las operaciones estándar de GDB y las herramientas específicas de Switch están disponibles a través de llamadas a herramientas MCP.

Requisitos previos

• Windows con WSL — gdb-multiarch se ejecuta dentro de WSL (probado con Debian)

• gdb-multiarch instalado en WSL (sudo apt install gdb-multiarch)

• Python 3.10+ en WSL

• Un stub de GDB — ya sea el stub de GDB integrado de Yuzu o una Switch con sys-gdbstub

• Claude Code (o cualquier cliente compatible con MCP)

Instalación

1. Instalar gdb-multiarch en WSL

wsl -d Debian
sudo apt install gdb-multiarch

2. Instalar el servidor MCP

Desde Windows, ejecuta:

wsl.exe -d Debian -e bash -c 'export PATH=$HOME/.local/bin:$PATH && pip install --break-system-packages -e /mnt/c/path/to/gdb-multiarch-mcp'

O desde dentro de WSL:

pip install -e /mnt/c/path/to/gdb-multiarch-mcp

3. Añadir a Claude Code

claude mcp add gdb-multiarch -s user -- wsl.exe -d Debian -e bash -c "export PATH=\$HOME/.local/bin:\$PATH && python3 -m gdb_multiarch_mcp"

O añádelo manualmente a tu .claude.json:

{
  "mcpServers": {
    "gdb-multiarch": {
      "type": "stdio",
      "command": "wsl.exe",
      "args": [
        "-d", "Debian", "-e", "bash", "-c",
        "export PATH=$HOME/.local/bin:$PATH && python3 -m gdb_multiarch_mcp"
      ]
    }
  }
}

4. Verificar

claude mcp list

Deberías ver gdb-multiarch: ... - Connected.

Configuración

Establece estas variables de entorno en WSL para personalizar la conexión:

Para configurarlas, añade env a tu configuración de MCP:

{
  "mcpServers": {
    "gdb-multiarch": {
      "type": "stdio",
      "command": "wsl.exe",
      "args": ["..."],
      "env": {
        "SWITCH_IP": "192.168.1.100",
        "SWITCH_PORT": "22225"
      }
    }
  }
}

Herramientas disponibles

Gestión de sesiones

Herramientas de depuración de Switch

Herramientas estándar de GDB

Todas las herramientas estándar de gdb-mcp también están disponibles:

Solución de problemas

"No route to host" al conectar

La red de WSL puede ser complicada. Intenta:

1. Confirmar que SSH se está ejecutando en WSL: sudo service ssh start

2. Probar conectividad: nc -vz <switch_ip> 22225

3. Añadir una ruta si es necesario: sudo ip route add 192.168.1.0/24 via <gateway_ip>

4. Proxy de puerto desde Windows PowerShell:

netsh interface portproxy add v4tov4 listenport=22225 listenaddress=127.0.0.1 connectport=22225 connectaddress=<switch_ip>

El stub de GDB no responde

• Asegúrate de que el juego se esté ejecutando en Yuzu/Switch antes de llamar a switch_start_session

• Verifica que el stub de GDB de Yuzu esté habilitado en Emulation > Configure > Debug > Enable GDB Stub

Sesión ya en ejecución

Llama primero a switch_stop_session y luego a switch_start_session de nuevo.

Créditos

• Ipiano/gdb-mcp por Andrew Stelter — el servidor MCP ascendente para GDB sobre el que se construye este proyecto

• Coolsonickirby/smash-ultimate-research-setup — el .gdbinit.switch modificado y attach.py (script de auto-adjuntar) utilizados en este proyecto

• blujay — los comandos originales de .gdbinit.switch

• GradualSyrup — print_addr_setup.py (resolución de dirección a desplazamiento)

• Gdbinit por mammon_, elaine, pusillus, mong, zhang le, l0kit, truthix, fG!, gln — la configuración extendida de .gdbinit

Licencia

MIT — ver LICENSE.