Vizier Yu-Gi-Oh! MCP

Un servidor de Model Context Protocol para datos de cartas Yu-Gi-Oh!: cartas, precios, listas de prohibidas, reglas oficiales, relaciones entre cartas y herramientas de mazos. Todo se ejecuta localmente desde una única base de datos SQLite con búsqueda vectorial integrada — sin llamadas de red en tiempo de consulta.

Características

• Cartas: búsqueda por id exacto o nombre con coincidencia difusa, búsqueda por palabras clave con filtros de tipo/ATK, búsqueda semántica (vectorial) por descripción de efecto, listado de arquetipos.

• Precios y ediciones: precios de mercado actuales (cardmarket / tcgplayer / ebay / amazon), historial completo de ediciones con rarezas y precios.

• Listas de prohibidas: instantáneas para tcg, ocg, ocg-ae, ocg-cn, master-duel, rush, genesys, ocg-genesys, goat, edison; estado por carta en todos los formatos, diferencias históricas entre instantáneas.

• Reglas y resoluciones: búsqueda semántica sobre el Reglamento Oficial Completo (380 secciones) y más de 2.650 resoluciones oficiales de la OCG; consulta de resoluciones por carta con recuperación en vivo.

• Relaciones: búsqueda de relaciones de buscar/invocar/destruir/seleccionar extraídas del texto de las cartas, requisitos de material de Fusión/Sincronía/Xyz/Enlace/Ritual, búsquedas inversas, detección de soporte de arquetipo.

• Mazos: valida un mazo contra la lista de prohibidas de un formato, analiza la composición del principal/extra y la mezcla de arquetipos.

Related MCP server: Scryfall MCP Server

Requisitos

• Python 3.11+

• ~1 GB de disco para la descarga del modelo de embeddings; la base de datos construida ocupa ~75 MB

• ~2 GB de RAM durante la construcción (modelo de embeddings); mucho menos en tiempo de consulta

La ruta de la base de datos y el directorio de datos se pueden sobrescribir con las variables de entorno VIZIER_DB_PATH y VIZIER_DATA_DIR (el valor predeterminado es <package>/data/).

Configuración

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

Construcción de la base de datos

La construcción ingiere los datos de API en caché (data/cache/) y los proyectos de referencia (ref/, policy/) en data/vizier.db. No se requiere red a menos que se pase --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 descarga el volcado de cartas desde YGOPRODeck. Nota: la API en vivo actualmente devuelve HTTP 403, por lo que el volcado en caché en data/cache/ es la fuente autoritativa. Si la API no está disponible, la construcción usa la caché.

Ejecución del servidor

python -m vizier_mcp

El servidor habla MCP sobre stdio. También hay un script de consola:

vizier-mcp

Configuración del cliente

Apunta cualquier cliente MCP al comando instalado. El nombre del servidor es vizier-yugioh.

Claude Desktop / Claude Code

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

Clientes genéricos

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

Usa rutas absolutas al entorno virtual. La ruta de la base de datos se resuelve relativa a la ubicación del paquete (o VIZIER_DB_PATH), no al directorio de trabajo actual.

Herramientas

Ejemplo — dos monstruos D/D de Nivel 4 en el campo:

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")

Las verificaciones de material de mejor esfuerzo se validan contra el grafo de relaciones completo; confirma siempre los candidatos dudosos con get_card_materials antes de finalizar una línea.

Recursos

Codifica en URL los parámetros de recursos que contengan espacios (rules://damage%20step).

Diseño de la base de datos

data/vizier.db — SQLite con la extensión sqlite-vec. Tablas clave:

• cards — una fila por carta con indicadores de tipo calculados (is_monster, is_quickplay_spell, ...)

• card_sets, card_prices — impresiones y precios de mercado

• card_ban_status, banlist_history — estado actual por formato + instantáneas históricas

• relations — relaciones de efectos entre cartas con tipos

• rulebook_chunks, rulings — texto de reglas y resoluciones

• card_vec, rule_vec, ruling_vec — tablas de incrustaciones para búsqueda semántica

• meta — marca de tiempo de compilación y recuentos

Fuentes de datos

• Cartas / precios / listas de prohibidas: API masiva de YGOPRODeck (almacenada en caché en data/cache/)

• Reglas: libro de reglas oficial completo (ref/yugioh_comprehensive_rulebook/)

• Resoluciones: lista oficial de preguntas y respuestas de resoluciones OCG + respaldo de YGOPEDIA

• Política: documentos de política de torneos (policy/)

Pruebas

python -m pytest tests/ -q

Ejecuta 32 pruebas de humo contra un cliente de servidor en proceso, cubriendo todas las herramientas y recursos.