ro-mcp

ローカル rAthena サーバーに対して実際の Ragnarok Online クライアントセッションを操作する MCP サーバーです。エージェントはログイン、歩行、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 を難読化キー0個として解決するため、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 上で無人実行できない4つのことを行います。

1. SConstruct が /opt/homebrew の readline プレフィックスを指すようにします(SConstruct は Intel 用の /usr/local しか認識しないため)。

2. Perl のヘッダーが macOS SDK 内を指すようにします(Config.pm は素の /System/Library パスを報告しますが、そこにはもうヘッダーが存在しないため)。

3. 同梱の SCons のために python を python3 にシャムします。

4. サーバーエントリ、設定オーバーライド、mcpbridge プラグインをインストールします。loadPlugins_list への mcpbridge の追加も含みます。これがないと制御ソケットは開きません。

サーバー側の前提条件

rAthena インスタンスには、無人ログインのために3つの設定が必要です。

ブリッジプロトコル

改行区切りの JSON を、127.0.0.1:24390 上で双方向に送受信します(ループバックのみ — これによりゲームセッションを完全に制御できます)。

// 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 は移動や NPC ロジックを再実装するのではなく、OpenKore 自身のコマンドレイヤーに転送します。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 によるキャラクターの移動と到着の確認

• 到達不能な目的地は ~30ms で理由付きで拒否され、フルタイムアウトを 使い切らない — OpenKore はこれらをコンソールにしか報告しないため、 到着ポーリングはそのメッセージと競わせている

• TypeScript でスクリプト化されたコンテンツに対する完全な NPC 会話 (scripts/npc-test.mjs): ダイアログの読み取り、メニューオプションの解析、 ブランチの選択、返答の読み取り

未検証: ro_attack。

知っておくべき2つの非同期の落とし穴

アクターリストはマップ進入後に投入されます。 ログイン直後に取得した ro_state は、周辺に NPC がいないと正当に報告します。NPC が現れるまでポーリングしてください。

ダイアログの最後のメッセージは、閉じるときに届きます。 スクリプトは通常、回答してから一気に閉じるため、npc_talk_done は「閉じたことを示すマーク」として扱い、「バッファを破棄する」としては決して扱わないでください。そうしないと、会話の終わり、通常は検証対象となる部分が、まさに失われる部分になります。