gdb-multiarch-mcp

Claude와 같은 AI 어시스턴트가 Yuzu 또는 GDB 스텁이 있는 실제 콘솔에서 실행 중인 Nintendo Switch 실행 파일을 디버깅하기 위해 gdb-multiarch에 직접 액세스할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.

Ipiano/gdb-mcp를 기반으로 구축된 이 포크는 오프셋 기반 중단점, 명령어 패치(NOP/stub/replace), 프레임 포인터 역추적 및 주소 로컬라이제이션(모두 게임의 기본 주소인 $main 기준)을 위한 Switch 전용 디버깅 도구를 추가합니다.

기능

Claude(또는 모든 MCP 클라이언트)가 switch_start_session을 호출하면 서버는 다음을 수행합니다:

1. WSL 내에서 gdb-multiarch 실행

2. Switch 디버깅 명령어(.gdbinit.switch) 로드

3. target extended-remote를 통해 GDB 스텁에 연결

4. 애플리케이션이 시작될 때까지 기다린 후 연결(attach)

5. 자동으로 $main을 cross2_Release.nss의 기본 주소로 설정

그 이후부터는 모든 표준 GDB 작업과 Switch 전용 도구를 MCP 도구 호출을 통해 사용할 수 있습니다.

사전 요구 사항

• Windows with WSL — gdb-multiarch는 WSL 내에서 실행됩니다(Debian에서 테스트됨)

• gdb-multiarch가 WSL에 설치되어 있어야 함 (sudo apt install gdb-multiarch)

• Python 3.10+ (WSL 내)

• GDB 스텁 — Yuzu의 내장 GDB 스텁 또는 sys-gdbstub이 설치된 Switch

• Claude Code (또는 MCP 호환 클라이언트)

설치

1. WSL에 gdb-multiarch 설치

wsl -d Debian
sudo apt install gdb-multiarch

2. MCP 서버 설치

Windows에서 다음을 실행하세요:

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'

또는 WSL 내부에서 실행:

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

3. 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"

또는 .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. 확인

claude mcp list

gdb-multiarch: ... - Connected 메시지가 표시되어야 합니다.

구성

연결을 사용자 지정하려면 WSL에서 다음 환경 변수를 설정하세요:

설정하려면 MCP 구성에 env를 추가하세요:

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

사용 가능한 도구

세션 관리

Switch 디버깅 도구

표준 GDB 도구

모든 표준 gdb-mcp 도구도 사용할 수 있습니다:

문제 해결

연결 시 "No route to host" 오류

WSL 네트워킹은 까다로울 수 있습니다. 다음을 시도해 보세요:

1. WSL에서 SSH가 실행 중인지 확인: sudo service ssh start

2. 연결 테스트: nc -vz <switch_ip> 22225

3. 필요한 경우 경로 추가: sudo ip route add 192.168.1.0/24 via <gateway_ip>

4. Windows PowerShell에서 포트 프록시:

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

GDB 스텁이 응답하지 않음

• switch_start_session을 호출하기 전에 Yuzu/Switch에서 게임이 실행 중인지 확인하세요.

• Yuzu의 GDB 스텁이 Emulation > Configure > Debug > Enable GDB Stub에서 활성화되어 있는지 확인하세요.

세션이 이미 실행 중인 경우

switch_stop_session을 먼저 호출한 다음 switch_start_session을 다시 호출하세요.

크레딧

• Ipiano/gdb-mcp (Andrew Stelter) — 이 프로젝트가 기반으로 하는 GDB용 업스트림 MCP 서버

• Coolsonickirby/smash-ultimate-research-setup — 이 프로젝트에서 사용된 수정된 .gdbinit.switch 및 attach.py (자동 연결 스크립트)

• blujay — 원본 .gdbinit.switch 명령어

• GradualSyrup — print_addr_setup.py (주소-오프셋 해석)

• Gdbinit (mammon_, elaine, pusillus, mong, zhang le, l0kit, truthix, fG!, gln) — 확장된 .gdbinit 구성

라이선스

MIT — LICENSE를 참조하세요.