ro-mcp

Un servidor MCP que controla una sesión real de cliente de Ragnarok Online contra un servidor local rAthena, de modo que un agente pueda iniciar sesión, caminar, hablar con NPCs y luchar — y por tanto probar el contenido del servidor de extremo a extremo en lugar de leer archivos de registro.

El cliente es OpenKore, controlado mediante un pequeño plugin de control (openkore-plugin/mcpbridge.pl) que expone un socket JSON orientado a líneas.

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

Por qué OpenKore y no un cliente hecho a medida

OpenKore incluye una coincidencia exacta para la versión de paquetes que habla este servidor — RagexeRE_2021_11_03 existe en sus árboles Send y Receive, además de una tabla recvpackets correspondiente — y ya gestiona pathfinding, reconexiones, cambios de mapa e inventario. La alternativa era reimplementar todo eso; reutilizarlo no estaba ni cerca.

La ofuscación de paquetes no es ningún problema aquí: rAthena resuelve PACKETVER > 20180307 a cero claves de ofuscación, lo que hace que el XOR sea una operación identidad. El servidor lo confirma al arrancar con Packet Obfuscation: Enabled. Keys: 0x00000000, 0x00000000, 0x00000000.

Related MCP server: Roblox Executor MCP

Requisitos

Configuración

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

setup.sh es idempotente. Hace cuatro cosas que la compilación estándar de OpenKore no puede hacer sin supervisión en Apple Silicon:

1. Apunta SConstruct al prefijo de readline de /opt/homebrew (solo conoce el de Intel /usr/local).

2. Lo apunta a las cabeceras de Perl dentro del SDK de macOS, ya que Config.pm devuelve una ruta /System/Library sin prefijo que ya no las contiene.

3. Añade un shim de python → python3 para el SCons incluido.

4. Instala nuestra entrada de servidor, las sobrescrituras de configuración y el plugin mcpbridge — incluido añadir mcpbridge a loadPlugins_list, sin lo cual el socket de control nunca se abre.

Requisitos previos del lado del servidor

La instancia de rAthena necesita tres ajustes para el inicio de sesión sin supervisión:

El protocolo del puente

JSON delimitado por saltos de línea, en ambas direcciones, en 127.0.0.1:24390 (solo loopback — esto otorga control total de una sesión de juego).

// 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 reenvía a la propia capa de comandos de OpenKore en lugar de reimplementar el movimiento o la lógica de NPC — OpenKore ya sabe trazar rutas, reintentar y recuperarse, y duplicar eso aquí solo acabaría pudriéndose.

Uso

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

Regístralo en un cliente MCP apuntándolo a dist/index.js:

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

RO_MCP_KORE_DIR y RO_MCP_PORT sobrescriben la ubicación de OpenKore y el puerto del puente.

Herramientas

Una nota sobre los prompts

OpenKore hace algunas preguntas por stdin — creación de personajes, selección de personaje, reintento de contraseña. Son lecturas bloqueantes dentro de su bucle principal, por lo que mientras una esté pendiente, el bucle se detiene y el socket de control no puede responder. El servidor MCP es, por tanto, el dueño tanto del stdin del proceso hijo como del socket; ro_prompt expone una pregunta pendiente y ro_answer responde a ella. Si alguna herramienta agota el tiempo de espera, comprueba ro_prompt primero.

Estado

Verificado de extremo a extremo contra un servidor real (scripts/smoke.mjs):

• creación automática de cuentas, inicio de sesión, creación y selección de personajes

• ro_state informando de mapa, posición, HP/SP, nivel, zeny y actores cercanos

• ro_walk moviendo al personaje y confirmando la llegada

• destinos inalcanzables rechazados en ~30ms con el motivo, en lugar de agotar el tiempo de espera completo — OpenKore solo los notifica por consola, así que la comprobación de llegada compite con ese mensaje

• una conversación completa con un NPC contra contenido escrito en TypeScript (scripts/npc-test.mjs): leer el diálogo, parsear las opciones de menú, elegir una rama y leer la respuesta

Aún no probado: ro_attack.

Dos trampas asíncronas que conviene conocer

Las listas de actores se rellenan después de entrar en el mapa. Es normal que un ro_state tomado inmediatamente después del inicio de sesión no reporte NPCs cercanos; sondea hasta que aparezcan.

El último mensaje de un diálogo llega cuando se cierra. Los scripts normalmente responden y cierran de una sola vez, así que trata npc_talk_done como "marcar como cerrado", nunca como "descartar el búfer" — de lo contrario, el final de una conversación, normalmente la parte que se está comprobando, es exactamente la parte que se pierde.