Skip to main content
Glama
Vizier Yu-Gi-Oh! MCP

Vizier Yu-Gi-Oh! MCP

by l3p3r-muo

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。

工具

工具

描述

get_card

按名称(模糊)或 ID 获取一张卡:类型行、数值、效果、各格式的禁限状态、价格

search_cards

对名称/类型/系列/效果文本进行关键词搜索,支持 filter_type 和 min_atk 过滤器

semantic_card_search

通过卡牌功能的自然语言描述进行向量搜索

get_archetype

某系列/卡组的全部卡牌

get_card_prices

市场价格(cardmarket/tcgplayer/ebay/amazon)+ 最便宜的印刷版本

get_printings

完整印刷历史:卡包、罕贵度、版本、价格

get_banlist

某格式和日期的完整禁限卡表快照

check_card_banlist

一张卡在所有格式中的禁限状态 + 历史

banlist_history

某格式可用禁限卡表快照的日期

compare_banlists

比较两个快照:在禁止/限制/准限制之间变动的卡牌

list_banlist_formats

哪些格式有禁限卡表数据

search_rules

对官方完整规则书进行语义搜索

get_rulings

一张卡的官方 OCG 裁定(问答),带有实时获取回退

search_rulings

对裁定语料库进行语义搜索

get_related_cards

通过效果关联的卡牌:检索、召唤、破坏、指定、素材

find_search_targets

一张卡可以从卡组或墓地检索/加入手牌的卡牌

find_summon_targets

一张卡可以召唤/特殊召唤的卡牌

find_cards_that_search

反向:哪些卡牌检索这张卡

find_cards_that_summon

反向:哪些卡牌召唤这张卡

get_card_materials

融合/同调/超量/连接/仪式素材要求

find_cards_using_material

反向:以这张卡为素材的怪兽

find_archetype_support

文本中提及某系列的支持卡牌

combo_guide

内置连招创建剧本:构建连招的精确广度优先流程

card_combo_profile

一张卡的详尽连招档案:召唤方式、每个效果的发动种类/一回合一次/动作、锁定、关联、所需素材、可作素材

extra_deck_options

从当前场上可达的每一个融合/同调/超量/连接/仪式召唤(尽力而为的素材检查)

board_options

当前场上所有合法的下一步操作:所有额外卡组召唤、手牌操作、带排序目标的检索/加入效果、灵摆范围、生效/待生效的锁定。与系列无关

line_search

对场上状态进行有界广度优先搜索:从当前场上到目标(field_levels、field_count、no_locks、reach_field、reach_hand)的完整多步路线

validate_deck

根据格式的禁限卡表验证卡组列表

analyze_deck

卡组分析:主卡组/额外卡组数量、系列混编、每张卡的详情

mcp_guide

每个工具和资源的概述

database_status

已加载的数据:数量、构建时间、格式

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 确认存疑候选。

资源

URI

描述

card://{name_or_id}

卡牌的紧凑摘要(文本格式)

banlist://{format}

某赛制的最新禁限卡表快照(文本格式)

rules://{query}

针对某个问题的规则书顶部章节(语义搜索)

对包含空格的资源参数进行 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 个冒烟测试,覆盖所有工具和资源。

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
      A
      quality
      D
      maintenance
      A Pokemon TCG MCP server that looks up graded cards, manages a local SQLite collection, queries pricing providers, tracks a watchlist with target prices, and snapshots PSA pop counts for trend analysis.
      33
      28 PyPI
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for searching and retrieving Magic: The Gathering card information via the Scryfall API, with support for field presets, multiple output formats, and automatic rate limiting.
      4
      MIT