Skip to main content
Glama

ro-mcp

一个 MCP 服务器,驱动真实的《仙境传说》客户端会话,连接本地 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 Server

要求

要求

说明

Perl 5.34+

macOS 系统自带的 Perl 即可

GNU readline

brew install readline — OpenKore 的 XSTools 链接到它

Xcode 命令行工具

现代 macOS 上 Perl 的 C 头文件位于 SDK 内

Python 3

仅用于运行 OpenKore 自带的 SCons

Node.js 18+

MCP 服务器本身

设置

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

setup.sh 是幂等的。它做了四件标准 OpenKore 构建在 Apple Silicon 上无法无人值守完成的事情:

  1. 将 SConstruct 指向 /opt/homebrew 的 readline 前缀(它只知道 Intel 的 /usr/local 那个)。

  2. 将其指向 macOS SDK 内的 Perl 头文件,因为 Config.pm 报告的是 一个不再包含这些头文件的裸 /System/Library 路径。

  3. 为自带的 SCons 将 python 垫片为 python3。

  4. 安装我们的服务器入口、配置覆盖和 mcpbridge 插件—— 包括将 mcpbridge 添加到 loadPlugins_list,否则控制套接字永远不会打开。

服务器端前置条件

rAthena 实例需要三项设置才能实现无人值守登录:

文件

设置

原因

conf/login_athena.conf

new_account: yes

允许 name_M 在首次登录时自动创建账户

conf/char_athena.conf

pincode_enabled: no

PIN 提示会阻塞 OpenKore 的主循环,从而卡住控制套接字

conf/char_athena.conf

char_new: yes

角色创建

桥接协议

换行分隔的 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 转发到 OpenKore 自己的命令层,而不是重新实现移动或 NPC 逻辑——OpenKore 已经知道如何寻路、重试和恢复,在这里重复实现只会腐烂。

用法

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

通过将其指向 dist/index.js 来向 MCP 客户端注册:

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

RO_MCP_KORE_DIR 和 RO_MCP_PORT 覆盖 OpenKore 位置和桥接端口。

工具

工具

用途

ro_start / ro_stop

启动 / 关闭会话

ro_state

地图、位置、HP/SP、等级、zeny、附近的 NPC 和怪物

ro_prompt / ro_answer

检查并回答 OpenKore 的交互式问题

ro_create_char / ro_select_char

角色创建和选择

ro_walk / ro_warp

在地图内移动 / 前往另一张地图

ro_talk_npc

与 NPC 对话,返回其对话文本和菜单选项

ro_menu_select / ro_dialog_next / ro_close_dialog

驱动对话

ro_attack

攻击附近的怪物

ro_console / ro_command

读取控制台输出 / 逃生舱

关于提示的说明

OpenKore 会在 stdin 上询问一些问题——角色创建、角色选择、密码重试。这些是其主循环内的阻塞读取,因此当有提示挂起时,循环会停止,控制套接字无法响应。因此 MCP 服务器同时拥有子进程的 stdin 和套接字;ro_prompt 会显示挂起的问题,ro_answer 则回复它。如果某个工具超时,请先检查 ro_prompt。

状态

已针对实时服务器端到端验证(scripts/smoke.mjs):

  • 账户自动创建、登录、角色创建和选择

  • ro_state 报告地图、位置、HP/SP、等级、zeny 和附近的角色

  • ro_walk 移动角色并确认到达

  • 不可达的目的地在约 30 毫秒内被拒绝并给出原因,而不是耗尽完整超时——OpenKore 只在控制台上报告这些,因此到达轮询会与该消息竞争

  • 针对 TypeScript 脚本化内容的完整 NPC 对话(scripts/npc-test.mjs):读取对话、解析菜单选项、选择分支并读取回复

尚未测试:ro_attack。

两个值得了解的异步陷阱

角色列表在地图进入后才会填充。 登录后立即执行的 ro_state 合理地报告没有附近的 NPC;请轮询直到它们出现。

对话的最后一条消息在关闭时到达。 脚本通常一次性回答并关闭,因此请将 npc_talk_done 视为“标记为已关闭”,而不是“丢弃缓冲区”——否则对话的结尾,通常是正在断言的部分,恰恰是丢失的部分。

Available Tools

17 tools
ro_answerA

Answer OpenKore's pending interactive question by writing a line to its stdin.

Inputs: answer (required).

ro_attackB

Attack a nearby monster by its binID from ro_state.nearbyMonsters.

Inputs: binID (required), waitMs.

ro_close_dialogB

Close the currently open NPC dialog.

Inputs: no named parameters.

ro_commandA

Escape hatch: run an arbitrary OpenKore console command. Prefer the specific tools; use this for anything they do not cover.

Inputs: cmd (required).

ro_consoleA

Read recent OpenKore console output. Useful when something did not behave as expected.

Inputs: lines.

ro_create_charB

Create a character in the given slot. Only valid while OpenKore is asking for character properties — call ro_prompt first to confirm.

Inputs: name (required), job, sex, slot, +2 more.

ro_dialog_nextC

Advance an NPC dialog that is waiting on a 'next' click.

Inputs: timeoutMs.

ro_gm_warpA

Teleport instantly to a map using the @warp GM command. Requires the account to have a GM group with @warp permission. Unlike ro_warp this needs no walkable route, which matters because some maps (the tutorial grounds, instances) have no path out.

Inputs: map (required), x, y, timeoutMs.

ro_menu_selectB

Choose an option from the NPC's menu, by zero-based index.

Inputs: index (required), timeoutMs.

ro_promptA

Check whether OpenKore is blocked on an interactive question (character creation, character selection, password retry). While a prompt is pending its main loop is stopped, so every other tool will time out until it is answered with ro_answer.

Inputs: no named parameters.

ro_select_charC

Select a character by its slot number and enter the world.

Inputs: slot.

ro_startA

Launch OpenKore and connect to the local rAthena server. Must be called before any other tool. Returns the resulting game state, or the pending prompt if login needs an answer.

Inputs: no named parameters.

ro_stateA

Read the live game state: connection, map, character stats and position, and nearby NPCs/monsters.

Inputs: no named parameters.

ro_stopB

Shut down the OpenKore session.

Inputs: no named parameters.

ro_talk_npcB

Talk to an NPC and return its dialog text plus any menu options. Identify the NPC either by its binID from ro_state, or by map coordinates.

Inputs: x, y, binID, timeoutMs.

ro_walkC

Walk to coordinates on the current map and wait until the character arrives.

Inputs: x (required), y (required), timeoutMs, tolerance.

ro_warpC

Move to another map by name (uses OpenKore's route planner; the path must exist).

Inputs: map (required), x, y, timeoutMs.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (start/stop/state/console, character creation/selection, movement, dialog steps, attack). Minor overlap exists between movement tools (ro_walk vs ro_warp vs ro_gm_warp) and dialog tools (ro_talk_npc, ro_menu_select, ro_dialog_next, ro_close_dialog), but the descriptions clarify when each is appropriate.

    Naming Consistency5/5

    All tools follow the `ro_` prefix with a consistent snake_case verb_noun pattern (e.g., ro_create_char, ro_menu_select, ro_gm_warp). Variations like ro_close_dialog or ro_dialog_next still adhere to the same convention, making the naming predictable and easy to infer.

    Tool Count4/5

    At 17 tools, the server is on the higher end but appropriate for a game automation bot that needs to cover startup, character management, movement, NPC interaction, and combat. The count feels justified given the domain, with only slight overlap (e.g., two warp tools) that could be consolidated.

    Completeness4/5

    The toolset covers the core lifecycle (start/stop/state), character setup, movement, NPC dialogs, and basic combat, with an escape hatch (ro_command) for anything else. Minor gaps exist (e.g., inventory or skill handling) but these are outside the apparent scope and can be addressed via the command tool.

    Related MCP Connectors

    Related MCP Servers