ro-mcp

Ein MCP-Server, der eine echte Ragnarok-Online-Client-Sitzung gegen einen lokalen rAthena-Server steuert, sodass ein Agent sich anmelden, herumlaufen, mit NPCs sprechen und kämpfen kann – und so Serverinhalte Ende-zu-Ende testen kann, anstatt Logdateien zu lesen.

Der Client ist OpenKore, gesteuert über ein kleines Steuerungs-Plugin (openkore-plugin/mcpbridge.pl), das einen zeilenorientierten JSON-Socket bereitstellt.

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

Warum OpenKore statt eines selbst gebauten Clients

OpenKore bietet eine exakte Übereinstimmung für die Paketversion, die dieser Server spricht – RagexeRE_2021_11_03 existiert in seinen Send- und Receive-Bäumen sowie einer passenden recvpackets-Tabelle – und es übernimmt bereits Wegfindung, Wiederverbindungen, Kartenwechsel und Inventar. Das neu zu implementieren war die Alternative; es wiederzuverwenden war nicht annähernd so gut.

Paketverschleierung ist hier kein Thema: rAthena löst PACKETVER > 20180307 zu null Verschleierungsschlüsseln auf, was die XOR-Operation zur Identität macht. Der Server bestätigt dies beim Start mit Packet Obfuscation: Enabled. Keys: 0x00000000, 0x00000000, 0x00000000.

Related MCP server: Roblox Executor MCP

Voraussetzungen

Einrichtung

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

setup.sh ist idempotent. Es erledigt vier Dinge, die der Standard-OpenKore-Build auf Apple Silicon nicht unbeaufsichtigt tun kann:

1. Weist SConstruct auf das /opt/homebrew-readline-Präfix hin (es kennt nur das Intel-/usr/local-Präfix).

2. Weist es auf Perls Header im macOS-SDK hin, da Config.pm einen nackten /System/Library-Pfad meldet, der sie nicht mehr enthält.

3. Ersetzt python durch python3 für das gebündelte SCons.

4. Installiert unseren Server-Eintrag, Konfigurationsüberschreibungen und das mcpbridge-Plugin – einschließlich des Hinzufügens von mcpbridge zu loadPlugins_list, ohne das der Steuerungssocket nie geöffnet wird.

Serverseitige Voraussetzungen

Die rAthena-Instanz benötigt drei Einstellungen für unbeaufsichtigte Anmeldung:

Das Bridge-Protokoll

Zeilengetrenntes JSON, in beide Richtungen, auf 127.0.0.1:24390 (nur Loopback – dies gewährt volle Kontrolle über eine Spielsitzung).

// 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 leitet an OpenKore's eigene Befehlsebene weiter, anstatt Bewegungs- oder NPC-Logik neu zu implementieren – OpenKore weiß bereits, wie man Pfade findet, wiederholt und sich erholt, und das hier zu duplizieren würde nur verrotten.

Verwendung

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

Registrieren Sie sich bei einem MCP-Client, indem Sie ihn auf dist/index.js verweisen:

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

RO_MCP_KORE_DIR und RO_MCP_PORT überschreiben den OpenKore-Speicherort und den Bridge-Port.

Werkzeuge

Ein Hinweis zu Eingabeaufforderungen

OpenKore stellt einige Fragen auf stdin – Charaktererstellung, Charakterauswahl, Passwortwiederholung. Das sind blockierende Lesevorgänge in seiner Hauptschleife. Solange eine aussteht, ist die Schleife angehalten und der Steuerungssocket kann nicht antworten. Der MCP-Server besitzt daher sowohl das stdin des Kindprozesses als auch den Socket; ro_prompt zeigt eine ausstehende Frage an und ro_answer antwortet darauf. Wenn ein Tool jemals eine Zeitüberschreitung hat, prüfen Sie zuerst ro_prompt.

Status

Ende-zu-Ende gegen einen Live-Server verifiziert (scripts/smoke.mjs):

• automatische Kontoerstellung, Anmeldung, Charaktererstellung und -auswahl

• ro_state meldet Karte, Position, HP/SP, Level, Zeny und nahe Akteure

• ro_walk bewegt den Charakter und bestätigt die Ankunft

• unerreichbare Ziele werden in ~30ms mit dem Grund abgelehnt, anstatt das volle Timeout zu verbrauchen – OpenKore meldet diese nur auf der Konsole, daher wird die Ankunftsabfrage gegen diese Nachricht abgeglichen

• ein vollständiges NPC-Gespräch gegen TypeScript-skriptete Inhalte (scripts/npc-test.mjs): Dialog lesen, Menüoptionen parsen, einen Zweig wählen und die Antwort lesen

Noch nicht getestet: ro_attack.

Zwei asynchrone Fallstricke, die man kennen sollte

Akteurslisten werden nach dem Kartenwechsel befüllt. Ein ro_state direkt nach der Anmeldung meldet zu Recht keine nahen NPCs; fragen Sie ab, bis sie erscheinen.

Die letzte Nachricht eines Dialogs kommt an, wenn er geschlossen wird. Skripte antworten und schließen oft in einem Zug, behandeln Sie npc_talk_done also als „als geschlossen markieren“, niemals als „Puffer verwerfen“ – sonst ist das Ende eines Gesprächs, normalerweise der Teil, auf den geprüft wird, genau der Teil, der verloren geht.