pureikyubu — MCP-сервер

Что это

MCP (Model Context Protocol) — это способ, которым агентское приложение (Claude Desktop, Claude Code, IDE, собственный скрипт) пользуется программой как набором инструментов. Сервер этого эмулятора говорит по протоколу через свои stdin/stdout (транспорт «локального сервера»: клиент запускает эмулятор сам, одно JSON-RPC сообщение на строку), а публикуемые инструменты — это команды отладочного интерфейса, описанные теми спецификациями, которые в эмуляторе уже есть.

MCP-клиент  -- stdio -->  pureikyubu --mcp  -->  Json Debug Interface  -->  эмулятор
     |                          |
     |  tools/call "memdump"    +--> окно остаётся открытым и рабочим (оконные сборки)
     +--------------------------+--> окна нет вообще (headless-сборка)

Команда	Что делает
`pureikyubu --mcp`	Запускает локальный MCP-сервер. Файл в командной строке загружается и запускается до этого, так что клиент подключается к уже работающей игре.
`mcp 1` / `mcp 0`	Включить или выключить сервер на ходу из консоли отладчика; просто `mcp` сообщает, работает ли он.
`McpRequest <json>`	Весь протокол одной отладочной командой: сообщение на вход, сообщение на выход. Транспорт — лишь переносчик этих ответов.

Подключение клиента

Клиент, который запускает свои серверы как дочерние процессы, настраивается на исполняемый файл и --mcp. Для автономной работы (без окна) предназначена headless-сборка; оконная сборка работает так же — если вы хотите видеть эмулятор и сами им пользоваться.

{
  "mcpServers": {
    "pureikyubu": {
      "command": "C:\\pureikyubu\\pureikyubu_headless.exe",
      "args": ["--mcp"]
    }
  }
}

Ни порта, ни слушающего сокета, ни аутентификации: сервер — дочерний процесс своего клиента, поэтому разговаривать с ним может только тот, кто его запустил. Один клиент за раз.

Инструменты

До загрузки машины публикуется около 150 команд, после — около 170: узлы, относящиеся к эмулируемому железу (Flipper, конвейер GFX, привод диска), появляются, когда файл уже работает. У каждого инструмента есть текст подсказки и справка команды, аргументы из её собственной спецификации и описание того, что она возвращает.

Управление

load, unload, reset, run, stop, IsLoaded, GetLoaded, MountIso, OpenLid, DvdRead, DumpFst.

Отладчик Gekko

r (регистры), regs (дамп в Markdown), b/bc (точки останова), u, GekkoDisasm, syms, NameByAddress, dtlb, nop.

DSP

dregs, dreg, dmem, imem, du (дизассемблер), dbrk, dspjit, dspmbox.

Железо

memdump (основная память в Markdown), ramload, gx (состояние всего конвейера GFX), gxregs, gxtex, gxpixel, gxshot (PNG), hwprofile (профайлер интерфейсов).

tools/call  load       { "args": ["D:\\Isos\\zelda.iso"] }
tools/call  run        {}
tools/call  r          { "args": ["pc"] }
tools/call  qd         {}                       <- очередь отладочных сообщений (вывод `r`)
tools/call  memdump    { "address": "0x80000000", "lines": "16" }
tools/call  gxshot     { "filename": "frame.png" }
tools/call  hwprofile  { "value": "text" }

Аргументы можно называть (по подсказкам команды: <address> <lines>) или передать всей командной строкой в args. Команда, которая только печатает отчёт — а таких в отладчике большинство — не возвращает ничего; её отчёт попадает в очередь отладочных сообщений, которую читает инструмент qd.

Почему сделано именно так

Ничего нового учить не нужно

Сервер не реализует второй интерфейс: он публикует тот, которым уже пользуются отладчик, консоль и фронтенды. Команда, работающая в консоли, работает и как инструмент, а команда, добавленная в эмулятор завтра, появится в списке инструментов сама.

Протокол — это команда

McpRequest принимает одно MCP-сообщение и возвращает ответ сервера, поэтому протокол можно прогнать (и протестировать) вообще без транспорта — а stdio-сервер представляет собой сотню строк чтения поверх этого.

Агент — это клиент, а не пользователь

Неудачная команда возвращается как неудачный инструмент, вместе со справкой по команде, так что модель может исправиться, а сессия продолжается. Ошибкой протокола считается только неизвестное имя инструмента.

Ограничения

Ни HTTP, ни SSE, ни ресурсов, ни промптов, ни сэмплинга: это локальный транспорт спецификации, а инструменты — то, что у эмулятора есть. Команды, завершающие процесс (exit и её синонимы), намеренно не являются инструментами — вызов убил бы сервер посреди собственного ответа; клиент вместо этого закрывает поток, и эмулятор завершается сам. Ответ вызова инструмента ограничен 4 МБ текста: иначе команда вроде FileLoad превратила бы целый бинарный файл в Json и втиснула бы его в контекст модели.

Документация

Wiki: MCP-сервер

Вся страница: протокол на одной странице, как спецификация становится инструментом, что возвращает вызов инструмента и чем сервер не является.

Тесты

testing/mcp_test.cpp: рукопожатие, ошибки протокола, таблица инструментов на собственном узле и на всех спецификациях, которые поставляет эмулятор.

Отладочный интерфейс

wiki/main.md описывает поверхность управления эмулятора и командную строку; сами команды объявлены в src/jdispecs.cpp и перечисляются командой help в консоли отладчика.