ro-mcp

MCP-сервер, который управляет реальной клиентской сессией Ragnarok Online против локального сервера rAthena, позволяя агенту входить в игру, перемещаться, разговаривать с NPC и сражаться — и, таким образом, тестировать серверный контент целиком, вместо чтения лог-файлов.

Клиент — OpenKore, управляемый через небольшой управляющий плагин (openkore-plugin/mcpbridge.pl), который предоставляет построчный JSON-сокет.

  Claude ⇄ MCP server (stdio)
         ⇄ JSON over TCP :24390
         OpenKore + mcpbridge plugin
         ⇄ RO protocol (plaintext)
         rAthena  login:6900  char:6121  map:5121

Почему OpenKore, а не самодельный клиент

OpenKore поставляется с точным соответствием версии пакетов, на которой говорит этот сервер: RagexeRE_2021_11_03 присутствует в его деревьях Send и Receive, плюс соответствующая таблица recvpackets. Он уже умеет обрабатывать поиск пути, переподключения, смену карт и инвентарь. Переписывать это было альтернативой; переиспользование было вне конкуренции.

Обфускация пакетов здесь не проблема: rAthena для PACKETVER > 20180307 задаёт нулевые ключи обфускации, что превращает XOR в тождественную операцию. Сервер подтверждает это при запуске сообщением Packet Obfuscation: Enabled. Keys: 0x00000000, 0x00000000, 0x00000000.

Related MCP server: Roblox Executor MCP

Требования

Установка

./setup.sh          # clone OpenKore, patch, build XSTools, install config + plugin

setup.sh идемпотентен. Он делает четыре вещи, которые стандартная сборка OpenKore не может выполнить в автоматическом режиме на Apple Silicon:

1. Указывает SConstruct на префикс readline /opt/homebrew (ему известен только Intel-префикс /usr/local).

2. Указывает SConstruct на заголовки Perl внутри macOS SDK, поскольку Config.pm выдаёт голый путь /System/Library, в котором их больше нет.

3. Подменяет python на python3 для встроенного SCons.

4. Устанавливает нашу серверную точку входа, переопределения конфигурации и плагин mcpbridge — включая добавление mcpbridge в loadPlugins_list, без чего управляющий сокет никогда не откроется.

Требования на стороне сервера

Экземпляру rAthena нужны три настройки для неинтерактивного входа:

Мостовой протокол

JSON, разделённый переводами строк, в обе стороны, на 127.0.0.1:24390 (только loopback — это даёт полный контроль над игровой сессией).

// requests
{"id": 1, "op": "ping"}
{"id": 2, "op": "state"}
{"id": 3, "op": "run", "cmd": "move 155 180"}

// responses
{"id": 1, "ok": true, "pong": 1}
{"id": 3, "ok": false, "error": "unknown or rejected command: ..."}

// events, pushed as they happen
{"event": "npc_talk", "name": "TS Lab", "msg": "Welcome to the V8 smoke test."}
{"event": "npc_talk_responses", "responses": ["Mob spawn", "Reputation", "Cancel"]}
{"event": "map_changed", "map": "prontera"}

op: run передаёт выполнение собственному командному слою OpenKore, а не переписывает логику движения или NPC — OpenKore уже умеет прокладывать путь, повторять попытки и восстанавливаться, а дублировать это здесь означало бы лишь создать код, который будет гнить.

Использование

npm install && npm run build
node scripts/smoke.mjs      # end-to-end check against a running server

Зарегистрируйте MCP-сервер в клиенте, указав ему на dist/index.js:

{ "mcpServers": { "ro": { "command": "node", "args": ["/path/to/ro-mcp/dist/index.js"] } } }

RO_MCP_KORE_DIR и RO_MCP_PORT переопределяют расположение OpenKore и порт моста.

Инструменты

Примечание об интерактивных запросах

OpenKore задаёт некоторые вопросы через stdin — создание персонажа, выбор персонажа, повторный ввод пароля. Это блокирующие чтения внутри его главного цикла, поэтому пока один из них ожидает ответа, цикл остановлен, и управляющий сокет не может отвечать. Поэтому MCP-сервер контролирует как stdin дочернего процесса, так и сокет; ro_prompt показывает ожидающий вопрос, а ro_answer отвечает на него. Если какой-либо инструмент вышел по таймауту, сначала проверьте ro_prompt.

Статус

Проверено сквозным тестированием на живом сервере (scripts/smoke.mjs):

• автоматическое создание аккаунта, вход в игру, создание и выбор персонажа

• ro_state сообщает карту, позицию, HP/SP, уровень, зени и ближайших действующих лиц

• ro_walk перемещает персонажа и подтверждает прибытие

• недостижимые пункты назначения отклоняются за ~30 мс с указанием причины, а не после полного таймаута — OpenKore сообщает о них только в консоли, поэтому опрос прибытия выполняется в гонке с этим сообщением

• полный диалог с NPC с контентом, написанным на TypeScript (scripts/npc-test.mjs): чтение диалога, разбор пунктов меню, выбор ветки и чтение ответа

Пока не опробовано: ro_attack.

Две асинхронные ловушки, о которых стоит знать

Списки действующих лиц заполняются после входа на карту. ro_state, полученный сразу после входа в игру, правомерно сообщает об отсутствии ближайших NPC; опрашивайте, пока они не появятся.

Последнее сообщение диалога приходит в момент его закрытия. Скрипты обычно отвечают и закрывают диалог за один раз, поэтому воспринимайте npc_talk_done как «пометить закрытым», а не как «отбросить буфер» — иначе конец разговора, обычно именно та часть, которую проверяет тест, окажется именно той частью, которая будет потеряна.