gdb-multiarch-mcp

MCP-сервер (Model Context Protocol), который предоставляет ИИ-ассистентам, таким как Claude, прямой доступ к gdb-multiarch для отладки исполняемых файлов Nintendo Switch, запущенных в Yuzu или на реальной консоли с GDB-заглушкой.

Построенный на базе Ipiano/gdb-mcp, этот форк добавляет инструменты отладки, специфичные для Switch: точки останова по смещению, патчинг инструкций (NOP/stub/замена), трассировку стека по указателю кадра и локализацию адресов — всё относительно базового адреса игры ($main).

Что он делает

Когда Claude (или любой другой MCP-клиент) вызывает switch_start_session, сервер:

1. Запускает gdb-multiarch внутри WSL

2. Загружает команды отладки Switch (.gdbinit.switch)

3. Подключается к GDB-заглушке через target extended-remote

4. Ожидает запуска приложения и подключается к нему

5. Автоматически устанавливает $main на базовый адрес cross2_Release.nss

После этого все стандартные операции GDB и инструменты для Switch становятся доступны через вызовы инструментов MCP.

Предварительные требования

• Windows с WSL — gdb-multiarch работает внутри WSL (протестировано на Debian)

• gdb-multiarch, установленный в WSL (sudo apt install gdb-multiarch)

• Python 3.10+ в WSL

• GDB-заглушка — либо встроенная в Yuzu, либо консоль Switch с sys-gdbstub

• Claude Code (или любой другой MCP-совместимый клиент)

Установка

1. Установите gdb-multiarch в WSL

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 для настройки подключения:

Чтобы задать их, добавьте env в вашу конфигурацию MCP:

{
  "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. Убедитесь, что SSH запущен в WSL: 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-заглушка не отвечает

• Убедитесь, что игра запущена в Yuzu/Switch до вызова switch_start_session

• Проверьте, что GDB-заглушка Yuzu включена в Emulation > Configure > Debug > Enable GDB Stub

Сессия уже запущена

Сначала вызовите switch_stop_session, затем снова switch_start_session.

Авторы

• Ipiano/gdb-mcp от Andrew Stelter — исходный MCP-сервер для GDB, на котором построен этот проект

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