gdb-multiarch-mcp

Ein MCP-Server (Model Context Protocol), der KI-Assistenten wie Claude direkten Zugriff auf gdb-multiarch für das Debuggen von Nintendo Switch-Executables ermöglicht, die auf Yuzu oder einer echten Konsole mit GDB-Stub laufen.

Aufbauend auf Ipiano/gdb-mcp fügt dieser Fork Switch-spezifische Debugging-Tools für offset-basierte Breakpoints, Instruction-Patching (NOP/Stub/Replace), Frame-Pointer-Backtraces und Adresslokalisierung hinzu – alles relativ zur Basisadresse des Spiels ($main).

Funktionsweise

Wenn Claude (oder ein beliebiger MCP-Client) switch_start_session aufruft, führt der Server folgende Schritte aus:

1. Startet gdb-multiarch innerhalb von WSL

2. Lädt die Switch-Debugging-Befehle (.gdbinit.switch)

3. Verbindet sich über target extended-remote mit dem GDB-Stub

4. Wartet auf den Start der Anwendung und hängt sich an diese an

5. Setzt automatisch $main auf die Basisadresse von cross2_Release.nss

Von dort aus sind alle Standard-GDB-Operationen und Switch-spezifischen Tools über MCP-Tool-Aufrufe verfügbar.

Voraussetzungen

• Windows mit WSL — gdb-multiarch läuft innerhalb von WSL (getestet mit Debian)

• gdb-multiarch in WSL installiert (sudo apt install gdb-multiarch)

• Python 3.10+ in WSL

• Ein GDB-Stub — entweder der integrierte GDB-Stub von Yuzu oder eine Switch mit sys-gdbstub

• Claude Code (oder ein beliebiger MCP-kompatibler Client)

Installation

1. Installieren Sie gdb-multiarch in WSL

wsl -d Debian
sudo apt install gdb-multiarch

2. Installieren Sie den MCP-Server

Führen Sie unter Windows folgenden Befehl aus:

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'

Oder innerhalb von WSL:

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

3. Zu Claude Code hinzufügen

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"

Oder manuell zu Ihrer .claude.json hinzufügen:

{
  "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. Überprüfung

claude mcp list

Sie sollten gdb-multiarch: ... - Connected sehen.

Konfiguration

Setzen Sie diese Umgebungsvariablen in WSL, um die Verbindung anzupassen:

Um diese zu setzen, fügen Sie env zu Ihrer MCP-Konfiguration hinzu:

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

Verfügbare Tools

Sitzungsverwaltung

Switch-Debugging-Tools

Standard-GDB-Tools

Alle Standard-gdb-mcp-Tools sind ebenfalls verfügbar:

Fehlerbehebung

"No route to host" bei der Verbindung

WSL-Netzwerke können kompliziert sein. Versuchen Sie Folgendes:

1. Bestätigen Sie, dass SSH in WSL läuft: sudo service ssh start

2. Konnektivität testen: nc -vz <switch_ip> 22225

3. Route hinzufügen, falls erforderlich: sudo ip route add 192.168.1.0/24 via <gateway_ip>

4. Port-Proxy von Windows PowerShell:

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

GDB-Stub antwortet nicht

• Stellen Sie sicher, dass das Spiel auf Yuzu/Switch läuft, bevor Sie switch_start_session aufrufen

• Überprüfen Sie, ob der GDB-Stub von Yuzu unter Emulation > Configure > Debug > Enable GDB Stub aktiviert ist

Sitzung läuft bereits

Rufen Sie zuerst switch_stop_session auf und dann erneut switch_start_session.

Credits

• Ipiano/gdb-mcp von Andrew Stelter — der Upstream-MCP-Server für GDB, auf dem dieses Projekt basiert

• Coolsonickirby/smash-ultimate-research-setup — die modifizierte .gdbinit.switch und attach.py (Auto-Attach-Skript), die in diesem Projekt verwendet werden

• blujay — die ursprünglichen .gdbinit.switch-Befehle

• GradualSyrup — print_addr_setup.py (Adress-zu-Offset-Auflösung)

• Gdbinit von mammon_, elaine, pusillus, mong, zhang le, l0kit, truthix, fG!, gln — die erweiterte .gdbinit-Konfiguration

Lizenz

MIT — siehe LICENSE.