Skip to main content
Glama

ygo-ai

让 LLM agent 通过 MCP 和你打游戏王。 用的是真实的 EDOPro 客户端与 ocgcore,不是规则模拟器: 卡表、脚本、判罚和你在 EDOPro 里看到的一模一样,agent 只是换了个"手"。

Let an LLM agent play Yu-Gi-Oh! against you over MCP, on a real EDOPro client and the real ocgcore. Same cards, same scripts, same rulings — the model just plays instead of you.

EDOPro(你,主机)  ⇄ TCP 127.0.0.1:7911 ⇄ ygo-rs ⇄ MCP(stdio 或 --listen 7912)⇄ agent
  • agent 驱动:每回合看局面、自己选动作,没有任何写死的启发式(可选的策略表只用来省往返)。

  • 一次决策一次往返:ygo_act 把裁决和下一条事件一起带回来;每回合 400 秒的时钟从没被打满过。

  • 可复盘:wire.jsonl 记原始帧,decisions.jsonl 记"当时有哪些选项、选了哪个、谁选的", 两份都能离线重放,逐条比对。

快速开始

0. 你需要

  • Windows(EDOPro 本体只有 Windows/Linux 桌面版,本项目在 Windows 上实测)

  • EDOPro 41.x(代号 Bagooska 及以后;ocgcore 11.x)

  • Rust stable(cargo)

1. 构建

git clone https://github.com/dynamder/ygo-ai.git
cd ygo-ai/ygo-rs
cargo build              # 产物 target/debug/ygo-rs(.exe)

(如果 cargo 在沙箱里写不了全局缓存:CARGO_HOME=$PWD/../.cargo-home cargo build,本项目就是这么自举的。)

2. 起 MCP 服务

./target/debug/ygo-rs mcp                  # stdio:给 MCP host(Claude Desktop / Codex / 自研 agent)用
./target/debug/ygo-rs mcp --listen 7912    # 环回 TCP:给 shell 脚本、调试器用,方便 curl 式手搓

MCP 客户端配置(stdio 形态):

{
  "mcpServers": {
    "ygo": {
      "command": "D:/ygo-ai/ygo-rs/target/release/ygo-rs.exe",
      "args": ["mcp"]
    }
  }
}

3. 在 EDOPro 里开房

EDOPro → 局域网 → 建主机,端口 7911,房间密码随意(下文示例用 1111), 你当 host、deck 随便;对手的 deck 由 .ydk 文件指定(decks/ 里有几套现成的)。

4. 让 agent 接管

ygo_connect {"port": 7911, "password": "1111", "deck": "decks/agent.ydk"}
ygo_next    {"after_event": 0}          # 阻塞到轮到我方,返回事件 + 选项 + 时钟 + 变化
ygo_act     {"event_id": 3, "picks": [1]}   # 裁决,顺手把下一条事件带回来

你按下 EDOPro 的 Start,之后每一手都由 agent 决定。

Related MCP server: ygo-ai

MCP 工具面

工具

作用

ygo_connect

加入局域网房,参数 port/host/password/name/deck;收到主机第一帧才算成功

ygo_next

长轮询到新事件:返回 event(kind/format/reason/min/max/deadline_ms/options[]),外加 new_events(自上次轮询以来的全部日志)与 changes(和上次快照的差异)

ygo_act

按 event_id + picks 裁决,返回下一条事件;cancel:true 取放弃项;raw_hex 给未解码事件兜底;code 用于 announce_card;给 steps 则一次调用跑完一整段

ygo_scene

纯观测:回合/阶段/LP/场上卡号/墓地/牌组/时钟/当前事件

ygo_clock

双方时钟剩余(每回合重置)

ygo_log

完整线性历史分页:since + limit/n,内存里不截断

ygo_card

卡号 → 名称/类型/攻守/卡文(默认给全文);也能按名字搜

ygo_policy

策略表:常规提示零往返(load/show/clear/silence/restore)

ygo_rule

在同一调用里装策略 + 裁决;completion:stop 把控制权交还客户端启发式

ygo_rematch / ygo_surrender / ygo_leave

再战 / 投降 / 断开

ygo_say / ygo_events / ygo_wait / ygo_play

聊天、事件查询、定时等待、录像重放

为什么轮询能看懂发生了什么

日志是只追加不截断的,每次轮询自动带上"上次之后发生了什么"和"盘面差在哪":

"new_events": [
  {"seq": 812, "line": "[move] 88453933 手牌 -> 怪兽区"},
  {"seq": 815, "line": "[damage] 我方 -2400 (LP 5600)"}
],
"changes": [
  "回合 4→5,阶段 主要1→战斗",
  "LP: 我方 8000→5600,对方 8000→8000",
  "对方怪兽 +[位2 Parlor Dragonmaid (88453933) 500/1700]",
  "手牌: 我方 6→5,对方 3→2"
]

同一阶段里宿主会把同一组可发动项反复再问(一张盖牌一回合能被问二十次),这种重复窗口会被内联放弃 (decisions.jsonl 里记 by: "echo"),不占 agent 的往返预算。

它是怎么工作的

三层,边界很清楚:

  1. 线路层:直接说 EDOPro 的 TCP 协议([len:u16][opcode:u8][body]),跑的是官方客户端 + ocgcore。 所以规则不是我们"实现"的,是核心给的;我们只负责读懂 MSG_* 和写对 CTOS_RESPONSE。

  2. 票据层:核心卡在哪个提示上,就把它变成一张只能答一次的票(长轮询等它、event_id 对不上就拒答), 绝不去猜"现在大概该干什么"。

  3. 决策层:agent 通过 MCP 看局面、下决定。可选的策略表负责把"每次都想按放弃"的常规提示压成零往返。

细节见 docs/mcp-design.md;协议事实(逐条从 EDOPro 源码和真机帧核实)见 docs/duel-log.md。

真机验证

不是 demo 级验证:真机打过 5 局,赢 3 输 2。

局

对手

结果

1–3

各种

3 胜(其中一局 6 回合清场,LP 7500 vs -300)

4–5

纯半龙女仆

2 负(都是第 7 回合被打穿,原因是我这边操作失误,不是协议问题)

四、五局暴露的工具问题当时就修了:日志环形缓冲会丢历史(→ 改成只追加 + 轮询带差异)、 重复连锁窗口每次花一个往返(→ echo 内联放弃)、纯发动型连锁不显示卡名、ygo_rule 顶层 action 静默无效……复盘写在 docs/duel-log.md。

已知不足

  • 只测了 Windows + EDOPro 41.0.2;协议版本对不上会直接报错退出(这是故意的,猜版本比报错更糟)。

  • 仍然有一种提示没解码:MSG_SORT_CHAIN(异步连锁排序)。遇到时它会带着原始字节升级成 unsupported 事件,用 ygo_act raw_hex 兜底,不会被静默吞掉。

  • 卡名/卡文依赖 EDOPro 自带的 cards.cdb 与 config/strings.conf;换卡表要指过去(YGO_CDB)。

  • 不做自动组牌,也不内置对局策略——下棋的是模型。

仓库结构

ygo-rs/          Rust 实现(协议、票据、MCP 服务、重放)
  src/proto.rs     帧编解码、常量(相位/区域/种族/属性)
  src/msg.rs       MSG_* 解码
  src/respond.rs   提示 → 选项 → 响应字节
  src/session.rs   连接、票据、时钟、自动应答
  src/mcp.rs       MCP 工具面
  src/replay.rs    离线重放 / 回归
decks/           .ydk(agent 用的几套牌)
policies/        策略表样例
skills/          agent skill 描述(给支持 skill 的 host 用)
debug/           调试脚本与抓包(mcpcli.py、mockhost、抓帧工具)
docs/            设计文档与开发记录
src/, test/      早期 TypeScript 原型(已被 ygo-rs 取代,保留作为参考)

License

MIT,见 LICENSE。

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to play Disney Lorcana TCG matches over MCP, with tools for card search, deck validation, match creation, state observation, legal actions, and moves. Supports AI-vs-AI play and a live spectator board.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides Yu-Gi-Oh! card data, banlist, deck management, OCG rules engine, duel simulation, replay analysis, and YGOPro2 bridge for AI agents via MCP.
      5
      BSD Zero Clause
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to adjudicate Yu-Gi-Oh! rulings against real ocgcore Lua scripts and engine simulations, build and validate banlist-legal decks, analyze matchups and meta trends, and compare card prices across US/JP/AE markets. It also supports card and rulebook lookup, tournament paperwork, and custom-card tooling.
      4
      56
      314 npm
      AGPL 3.0