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

要求

设置

./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 实例需要三项设置才能实现无人值守登录：

桥接协议

换行分隔的 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 位置和桥接端口。

工具

关于提示的说明

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 视为“标记为已关闭”，而不是“丢弃缓冲区”——否则对话的结尾，通常是正在断言的部分，恰恰是丢失的部分。