ro-mcp

실제 Ragnarok Online 클라이언트 세션을 로컬 rAthena 서버에 연결해 구동하는 MCP 서버입니다. 에이전트는 로그인하고, 돌아다니고, NPC와 대화하고, 전투할 수 있습니다. 즉, 로그 파일을 읽는 대신 서버 콘텐츠를 종단 간 테스트할 수 있습니다.

클라이언트는 OpenKore이며, 줄 단위 JSON 소켓을 노출하는 작은 제어 플러그인(openkore-plugin/mcpbridge.pl)으로 구동됩니다.

  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이 OpenKore의 송신 및 수신 트리와 일치하는 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에서 무인으로 수행할 수 없는 네 가지 작업을 처리합니다.

1. SConstruct가 /opt/homebrew readline 접두사를 가리키도록 합니다. (SConstruct는 Intel의 /usr/local만 알고 있습니다.)

2. macOS SDK 안에 있는 Perl 헤더를 가리키도록 합니다. Config.pm이 더 이상 헤더가 들어 있지 않은 /System/Library 경로를 보고하기 때문입니다.

3. 번들된 SCons를 위해 python → python3 심(shim)을 만듭니다.

4. 서버 엔트리, 구성 재정의, mcpbridge 플러그인을 설치합니다. loadPlugins_list에 mcpbridge를 추가하는 것도 포함하며, 이를 추가하지 않으면 제어 소켓이 절대 열리지 않습니다.

서버 측 사전 요구 사항

무인 로그인을 위해 rAthena 인스턴스에 세 가지 설정이 필요합니다.

브리지 프로토콜

127.0.0.1:24390에서 새 줄로 구분된 JSON을 양방향으로 주고받습니다(루프백 전용 — 게임 세션을 완전히 제어할 수 있습니다).

// 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 스크립트 콘텐츠(scripts/npc-test.mjs)에 대한 전체 NPC 대화: 대화 읽기, 메뉴 옵션 파싱, 분기 선택, 응답 읽기

아직 테스트하지 않음: ro_attack.

알아 두어야 할 두 가지 비동기 함정

맵 진입 후에 액터 목록이 채워집니다. 로그인 직후에 가져온 ro_state는 주변 NPC가 없다고 정당하게 보고합니다. 나타날 때까지 폴링하세요.

대화의 마지막 메시지는 대화가 닫힐 때 도착합니다. 스크립트는 흔히 응답과 닫기를 한 번에 수행하므로 npc_talk_done을 "닫힘으로 표시"로 취급하고 "버퍼를 버리라"고 취급하지 마세요. 그렇지 않으면 대화의 끝 — 보통 검증 대상인 부분 — 이 정확히 손실됩니다.