ro-mcp
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 |
|
Xcode 命令行工具 | 现代 macOS 上 Perl 的 C 头文件位于 SDK 内 |
Python 3 | 仅用于运行 OpenKore 自带的 SCons |
Node.js 18+ | MCP 服务器本身 |
设置
./setup.sh # clone OpenKore, patch, build XSTools, install config + pluginsetup.sh 是幂等的。它做了四件标准 OpenKore 构建在 Apple Silicon 上无法无人值守完成的事情:
将 SConstruct 指向
/opt/homebrew的 readline 前缀(它只知道 Intel 的/usr/local那个)。将其指向 macOS SDK 内的 Perl 头文件,因为
Config.pm报告的是 一个不再包含这些头文件的裸/System/Library路径。为自带的 SCons 将
python垫片为python3。安装我们的服务器入口、配置覆盖和
mcpbridge插件—— 包括将mcpbridge添加到loadPlugins_list,否则控制套接字永远不会打开。
服务器端前置条件
rAthena 实例需要三项设置才能实现无人值守登录:
文件 | 设置 | 原因 |
|
| 允许 |
|
| PIN 提示会阻塞 OpenKore 的主循环,从而卡住控制套接字 |
|
| 角色创建 |
桥接协议
换行分隔的 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 位置和桥接端口。
工具
工具 | 用途 |
| 启动 / 关闭会话 |
| 地图、位置、HP/SP、等级、zeny、附近的 NPC 和怪物 |
| 检查并回答 OpenKore 的交互式问题 |
| 角色创建和选择 |
| 在地图内移动 / 前往另一张地图 |
| 与 NPC 对话,返回其对话文本和菜单选项 |
| 驱动对话 |
| 攻击附近的怪物 |
| 读取控制台输出 / 逃生舱 |
关于提示的说明
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 toolsro_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_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
Scored across 17 tools
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.
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.
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.
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
Launch and verify high-fidelity mobile simulations from an AI agent.
Plan, run and inspect AI-agent drills with synthetic users, hosted tools and cloud worlds.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to interact with a running Roblox game client to execute Lua code, inspect scripts, spy on remotes, and more.66 npm216MIT
- AlicenseAqualityBmaintenanceEnables AI agents to execute Lua code, inspect scripts, spy on remotes, and interact with a running Roblox game client through an MCP interface.42266 npm1MIT
- AlicenseCqualityCmaintenanceEnables MCP-capable AI agents to play The Mana World by logging in, moving around, fighting, trading, and talking to NPCs in real time.46MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with a running Roblox game client, including executing Lua code, inspecting scripts, searching instances, intercepting remote events via Sigma Spy, and controlling the GUI.66 npm1MIT