Vizier Yu-Gi-Oh! MCP

一个用于游戏王卡牌数据的 Model Context Protocol 服务器：卡牌、价格、印刷版本、禁限卡表（历史 + 跨格式）、官方裁定、完整规则、卡牌关联和卡组工具。一切都在本地运行，使用单个 SQLite 数据库，内置向量搜索——查询时无需网络调用。

功能

• 卡牌：按精确 ID 或模糊匹配名称查找，带类型/ATK 过滤的关键词搜索，按效果描述进行语义（向量）搜索，系列列表。

• 价格与印刷版本：当前市场价格（cardmarket / tcgplayer / ebay / amazon），完整的印刷历史，包含罕贵度和价格。

• 禁限卡表：tcg、ocg、ocg-ae、ocg-cn、master-duel、rush、genesys、ocg-genesys、goat、edison 的快照；每张卡在所有格式中的状态，快照之间的历史差异。

• 规则与裁定：对官方完整规则书（380 节）和超过 2,650 条官方 OCG 裁定进行语义搜索；按卡牌查询裁定，并带有实时获取回退。

• 关联：从卡牌文本中挖掘的检索/召唤/破坏/指定关联，融合/同调/超量/连接/仪式素材要求，反向查询，系列支援检测。

• 卡组：根据格式的禁限卡表验证卡组列表，分析主卡组/额外卡组构成和系列混编。

Related MCP server: Scryfall MCP Server

要求

• Python 3.11+

• 约 1 GB 磁盘空间用于下载嵌入模型；构建后的数据库约 75 MB

• 构建期间约 2 GB 内存（嵌入模型）；查询时少得多

数据库路径和数据目录可以通过 VIZIER_DB_PATH 和 VIZIER_DATA_DIR 环境变量覆盖（默认是 <package root>/data/）。

设置

python -m venv .venv
source .venv/bin/activate
pip install -e .

构建数据库

构建过程将缓存的 API 数据（data/cache/）和参考项目（ref/、policy/）导入到 data/vizier.db。除非传入 --fetch，否则不需要网络。

# full build including embeddings (slow: ~15-20 min CPU for 17.6k vectors)
python scripts/build_db.py

# faster variants
python scripts/build_db.py --no-embed      # skip vector embeddings (no semantic search)
python scripts/build_db.py --skip-cards    # skip card ingestion, re-embed only
python scripts/build_db.py --fetch         # download fresh API payloads first

--fetch 从 YGOPRODeck 下载卡牌数据转储。注意：实时 API 当前返回 HTTP 403，因此 data/cache/ 中的缓存转储是权威来源。如果 API 不可达，构建将使用缓存。

运行服务器

服务器通过 stdio 使用 MCP 通信。还有一个控制台脚本：

python -m vizier_mcp

vizier-mcp

客户端配置

将任何 MCP 客户端指向已安装的命令。服务器名称是 vizier-yugioh。

Claude Desktop / Claude Code

{
  "mcpServers": {
    "vizier-yugioh": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "vizier_mcp"]
    }
  }
}

通用客户端

{
  "mcpServers": {
    "vizier-yugioh": {
      "command": "/path/to/.venv/bin/vizier-mcp",
      "args": []
    }
  }
}

使用 venv 的绝对路径。数据库路径相对于包位置（或 VIZIER_DB_PATH）解析，而不是相对于 CWD。

工具

filter_type 示例：monster、spell、trap、effect、fusion、link、pendulum、tuner、normal monster、normal spell、quick-play、counter trap、equip、field、ritual。多词过滤器匹配精确的子类型。

连招创建

服务器附带一个内置的连招创建剧本，将路线构建变成确定性的广度优先流程：枚举每个可能的动作，扩展、加深、剪枝、记录、重复。

1. combo_guide() —— 加载剧本（也可作为 combo 提示词使用）。它定义了连招状态 JSON schema、6 步协议、每张卡的枚举检查清单、工具路由、硬/软一回合一次纪律、锁定检测和终止标准。

2. card_combo_profile() —— 对于你考虑的任何卡牌：召唤选项（通常召唤/解放召唤/灵摆召唤/自身特殊召唤）、每个效果（发动种类 + 一回合一次状态 + 动作动词）、锁定/限制语句、其完整关联图（检索/召唤/破坏/指定/素材）、它所需的素材，以及它可以作为素材的怪兽（指名 + 全系列）。

3. board_options() —— 一次调用返回当前场上所有合法的下一步操作，与系列无关：所有额外卡组召唤（完整的约 2,300 只怪兽池，而不仅是卡组所属系列）、每只手上怪兽的操作（通常召唤/自身特殊召唤/灵摆刻度）、每个检索/加入效果及其目标（系列目标列表列出排名最高的成员）、灵摆召唤范围，以及生效/待生效的锁定。这是防止隧道视野的工具：模型绝不能将自己限制在系列内候选。

4. line_search() —— 服务端有界广度优先搜索，从当前场上到目标（field_levels、field_count、no_locks、reach_field、reach_hand）。返回完整的多步路线，因此模型可以深入规划几步，而不是一次只走一步。

5. extra_deck_options() —— 粘贴你当前的场面（加上手牌/墓地/额外卡组和格式），获取每一个素材要求可满足的融合/同调/超量/连接/仪式怪兽，并附带每个候选者的精确素材推理。

示例——场上有两只等级 4 的 D/D 怪兽：

extra_deck_options(field=["D/D Savant Copernicus", "D/D Ark"], summon_types="xyz")
→ options include D/D/D Wise King Solomon ("2 Level 4 D/D monsters")

尽力而为的素材检查会根据完整关联图进行验证；在最终确定路线之前，始终使用 get_card_materials 确认存疑候选。

资源

对包含空格的资源参数进行 URL 编码（rules://damage%20step）。

数据库布局

data/vizier.db — 使用 sqlite-vec 扩展的 SQLite 数据库。关键表：

• cards — 每张卡一行，包含计算出的类型标志（is_monster、is_quickplay_spell、...）

• card_sets、card_prices — 卡牌印刷版本与市场价格

• card_ban_status、banlist_history — 各赛制的当前状态 + 历史快照

• relations — 卡牌间效果关系及类型

• rulebook_chunks、rulings — 规则与裁定文本

• card_vec、rule_vec、ruling_vec — 用于语义搜索的嵌入表

• meta — 构建时间戳与计数

数据来源

• 卡牌 / 价格 / 禁限卡表：YGOPRODeck 批量 API（缓存在 data/cache/ 中）

• 规则：官方完全规则书（ref/yugioh_comprehensive_rulebook/）

• 裁定：官方 OCG 裁定问答列表 + YGOPEDIA 回退

• 政策：赛事政策文件（policy/）

测试

python -m pytest tests/ -q

针对进程内服务器客户端运行 32 个冒烟测试，覆盖所有工具和资源。