ygo-ai

YGO AI

面向 AI Agent 的游戏王工具集，以 MCP（Model Context Protocol）服务器形式提供。

卡片数据 · 禁限表 · 卡组管理 · OCG 规则引擎 · 决斗推演 · 录像复盘 · YGOPro2 桥接

MCP Client (Agent)
        │  tools/call
        ▼
mcp/server.mjs            薄 MCP 主机（14 个聚合工具）
        │
        ▼
skill/backend/            工具、会话、引擎适配
        │
        ▼
持久引擎主机 127.0.0.1:19981   OCG 规则引擎（按需启动，跨重启保留）

快速开始

npm install          # 安装 @modelcontextprotocol/sdk
node mcp/server.mjs  # 以 stdio 方式启动 MCP 服务器

任意 MCP 客户端的配置：

{
  "mcpServers": {
    "ygo-ai": {
      "command": "node",
      "args": ["<绝对路径>/mcp/server.mjs"]
    }
  }
}

引擎在第一次调用工具时自动启动，并以 detached 进程形式跨客户端重启保留； 不安装、不配置、不注册任何外部服务。

工具一览

类别	工具
卡片	queryCards · manageCardDataSources · getBanlistContext
卡组	manageSessionDeck
决斗	resetGame · observeDuel · executeAction · simulateActions
状态	manageCheckpoint · manageEngineSession
分析	analyzeCombo · analyzeReplay · saveArtifact
桥接	manageYgoPro2

共 14 个聚合工具；每个工具用 action 参数选择子操作。工具的 JSON Schema 由引擎 侧定义，MCP 主机只做转发，不在本进程加载规则引擎。

能力

• 卡片与禁限表：按 ID 或名称查询已验证卡文、类型、数值；读取禁限表与卡库状态。
• 卡组：装载、检查、编辑、导出 YDK；YDK 文本原样交给引擎解析。
• 决斗：创建局面、固定起手、观察合法动作并执行；支持检查点回滚与分支推演。
• 录像：解析 .yrp / .yrp2 / .yrp3d，构建可读的路线上下文。
• YGOPro2 桥接：发现本地 YGOPro2 组件，连接 AI.Server 进行真实对局，导出权威 录像字节。

默认全部在内存中完成，不写日志、报告或工作流文件；只有显式调用 saveArtifact 才会落盘。

目录结构

mcp/          MCP 主机（stdio），唯一对外入口
lib/          其他宿主（可选）的入口适配
skill/backend 工具实现、会话、持久引擎客户端
skill/references  数据来源与决策纪律说明
skill/resources   卡库、脚本、YGOPro2 桥接资源
skill/runtime     内嵌规则运行器
patches/      WindBot 补丁与重建说明

WindBot 补丁

skill/resources/ygopro2-bridge/windbot/ 下的 WindBot 用于 YGOPro2 AI.Server 对局的外部策略模式。上游版本在 GameBehavior.OnNewTurn 里硬编码了 「第 2 回合自动投降」，导致任何多回合对局在第 2 回合被判为 cutoff。

补丁删除了该分支，仓库内附已重建的 WindBot.exe。详见 patches/README.md。

许可

本项目代码以 0BSD 发布。

skill/resources 下的卡片数据库、卡片脚本、禁限表，以及 skill/resources/ygopro2-bridge/windbot 下的 WindBot 源码与二进制， 遵循各自上游项目的许可与分发条款，详见对应目录内的 LICENSE 文件。