Vizier Yu-Gi-Oh! MCP

Сервер Model Context Protocol для данных карт Yu-Gi-Oh!: карты, цены, издания, бан-листы (исторические и кросс-форматные), официальные рулинги, полный свод правил, связи карт и инструменты для колод. Всё работает локально из единой базы данных 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; поиск рулинга для конкретной карты с запасным вариантом прямой загрузки.

• Связи: связи поиск/призыв/уничтожение/выбор цели, извлечённые из текста карт, требования материалов Fusion/Synchro/Xyz/Link/Ritual, обратные запросы, определение поддержки архетипа.

• Колоды: проверка списка колоды на соответствие бан-листу формата, анализ состава основной и дополнительной колоды, сочетание архетипов.

Related MCP server: Scryfall MCP Server

Требования

• Python 3.11+

• ~1 ГБ на диске для загрузки модели; готовая база данных — ~75 МБ

• ~2 ГБ ОЗУ во время загрузки(embedding-модель); при запросах — значительно меньше

Путь к базе данных и каталог данных можно задать через переменные окружения 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 недоступен, сборка используется в какие данные.

Запуск сервера

python -m vizier_mcp

Сервер общается через MCP по протоколу stdio. Также доступна консольный вариант:

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": []
    }
  }
}

Используйте абсолютные пути к виртуальному окружению. Путь к базе данных определяется относительно расположения пакета (или из VIZIER_DB_PATH), а не текущей рабочей директории.

Инструменты

Примеры filter_type: monster, spell, trap, effect, fusion, link, pendulum, tuner, normal monster, normal spell, quick-play, counter trap, equip, field, ritual. Многословные фильтры соответствуют точному подтипу.

Создание комбо

Сервер поставляется с встроенным плейбуком построения комбо ('combo-creation playbook'), который превращает построение линии в детерминированный процесс BFS-обхода: перечислите каждое возможное действие, расширьте, углубляйте, оставляйте подходящее, записывайте, повторяйте..

1. combo_guide() — загружает плейбук (также доступен как combo-сценарий). В нём задаётся JSON-схема состояний комбо, протокол из 6 шагов, пошаговый алгоритм, перечисления check-листов для каждой карты, роутинг инструментов, дисциплина OPT (hard/soft), определение локов и критерии завершения.

2. card_combo_profile() — для любой карты, которую вы рассматриваете: варианты призыва (нормальный/ритуальный/призыв для ррения/сам-спец-призыв), каждый эффект с типом активации + одноразовым статусом и глаголом действия, фразы с ограничениями/блокировками, полный граф связей (искание/призывов/уничтожений/целей/материалов), материалы, которые он требует, и монстров, материалом для которых он может быть (персональных + архетипные).

3. board_options() — один вызов, который возвращает КАЖДЫЙ легальный следующий ход с текущего поля, архетип-независимо: все призывы из теверсидной пулы (~2 3,2× оборот, не только архетип колоды), все действия монстра из руки (обычные призывы / сам-специального призыв / pendulum), все эффекты поиска/добавления с их контрольными целями, а также диапазон Pendulum и активный/ожидающий локов. Это инструмент против сужения. /Это точно не?

4. line_search() — серверный ограниченный поиск в ширину по состоянием поля от текущего поля до цели (field_levels, field_count, no_locks, reach_field, reach_hand). Возвращает полные многоходовые линии, поэтому модель планирует на несколько шагов вперёд, а не по одному шагу.

5. extra_deck_options() — вставить ваше текущее поле (плюс hand/граveyard/extra deck и формат) и получить каждого монстра Fusion/Synchro, чьи требования материалов выполнимы, с точным вычислением материалов для каждого кандидата.

Пример — два монстра Level 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 с расширением sqlite-vec. Ключевые таблицы:

• 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 bulk API (кэшируется в data/cache/)

• Правила: официальный Comprehensive Rulebook (ref/yugioh_comprehensive_rulebook/)

• Рулинги: официальный список Q&A по рулингам OCG + запасной вариант YGOPEDIA

• Политика: документы турнирной политики (policy/)

Тесты

python -m pytest tests/ -q

Запускает 32 смоук-теста против внутрипроцессного клиента сервера, покрывая каждый инструмент и ресурс.