Vizier Yu-Gi-Oh! MCP

Ein Model Context Protocol Server für Yu-Gi-Oh!-Kartendaten: Karten, Preise, Druckauflagen, Verbotenenlisten (historisch + formatübergreifend), offizielle Rulings, umfassende Regeln, Kartenbeziehungen und Deck-Tools. Alles läuft lokal aus einer einzigen SQLite-Datenbank mit eingebetteter Vektorsuche – keine Netzwerkaufrufe zur Abfragezeit.

Funktionen

• Karten: Nachschlagen per exakter ID oder unscharf abgeglichenem Namen, Stichwortsuche mit Typ/ATK-Filtern, semantische (Vektor-)Suche nach Effektbeschreibung, Archetyp-Auflistung.

• Preise & Druckauflagen: aktuelle Marktpreise (cardmarket / tcgplayer / ebay / amazon), vollständige Druckauflagen-Historie mit Seltenheiten und Preisen.

• Verbotenenlisten: Momentaufnahmen für tcg, ocg, ocg-ae, ocg-cn, master-duel, rush, genesys, ocg-genesys, goat, edison; Status pro Karte über alle Formate, historische Unterschiede zwischen Momentaufnahmen.

• Regeln & Rulings: semantische Suche über das offizielle umfassende Regelwerk (380 Abschnitte) und über 2.650 offizielle OCG-Rulings; Ruling-Nachschlagewerk pro Karte mit Live-Abruf-Fallback.

• Beziehungen: Such-/Beschwörungs-/Zerstörungs-/Ziel-Beziehungen, die aus Kartentexten gewonnen werden, Fusions-/Synchro-/Xyz-/Link-/Ritual-Materialanforderungen, Rückwärtssuchen, Erkennung von Archetyp-Unterstützung.

• Decks: Ein Decklist gegen die Verbotenenliste eines Formats validieren, Haupt-/Extra-Deck-Zusammensetzung und Archetyp-Mix analysieren.

Related MCP server: Scryfall MCP Server

Anforderungen

• Python 3.11+

• ~1 GB Speicherplatz für den Download des Einbettungsmodells; die erstellte Datenbank ist ~75 MB

• ~2 GB RAM während des Builds (Einbettungsmodell); deutlich weniger zur Abfragezeit

Der Datenbankpfad und das Datenverzeichnis können mit den Umgebungsvariablen VIZIER_DB_PATH und VIZIER_DATA_DIR überschrieben werden (Standard ist <package root>/data/).

Einrichtung

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

Erstellen der Datenbank

Der Build verarbeitet zwischengespeicherte API-Daten (data/cache/) und die Referenzprojekte (ref/, policy/) in data/vizier.db. Kein Netzwerk ist erforderlich, außer Sie übergeben --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 lädt den Kartendump von YGOPRODeck herunter. Hinweis: Die Live-API gibt derzeit HTTP 403 zurück, daher ist der zwischengespeicherte Dump in data/cache/ maßgeblich. Wenn die API nicht erreichbar ist, verwendet der Build den Cache.

Ausführen des Servers

python -m vizier_mcp

Der Server spricht MCP über stdio. Es gibt auch ein Konsolenskript:

vizier-mcp

Client-Konfiguration

Weisen Sie jeden MCP-Client auf den installierten Befehl hin. Der Servername ist vizier-yugioh.

Claude Desktop / Claude Code

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

Generische Clients

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

Verwenden Sie absolute Pfade zur venv. Der DB-Pfad wird relativ zum Paketspeicherort aufgelöst (oder VIZIER_DB_PATH), nicht zum aktuellen Arbeitsverzeichnis.

Tools

filter_type-Beispiele: monster, spell, trap, effect, fusion, link, pendulum, tuner, normal monster, normal spell, quick-play, counter trap, equip, field, ritual. Mehrwortfilter entsprechen dem exakten Untertyp.

Combo-Erstellung

Der Server enthält ein integriertes Playbook zur Combo-Erstellung, das den Linienaufbau in einen deterministischen Breitensuche-Prozess verwandelt: jede mögliche Aktion aufzählen, erweitern, vertiefen, beschneiden, aufzeichnen, wiederholen.

1. combo_guide() — das Playbook laden (auch als combo-Prompt verfügbar). Es definiert ein JSON-Schema für Combo-Zustände, das 6-Schritte-Protokoll, Checklisten zur Aufzählung pro Karte, Tool-Routing, harte/weiche Einspielbarkeits-Disziplin, Sperr-Erkennung und Abbruchkriterien.

2. card_combo_profile() — für jede in Betracht gezogene Karte: Beschwörungsmöglichkeiten (normal/Tribut/Pendel/Selbst-Spezialbeschwörung), jeder Effekt mit Aktivierungsart + Einspielbarkeits-Status + Aktionsverben, Sperr-/Einschränkungssätze, ihr vollständiger Beziehungsgraph (Suchen/Beschwörungen/Zerstörungen/Ziele/Material), benötigtes Material und Monster, für die sie Material sein kann (namentlich + archetypweit).

3. board_options() — ein Aufruf, der JEDEN legalen nächsten Zug vom aktuellen Spielfeld zurückgibt, archetyp-agnostisch: alle Extra-Deck-Beschwörungen (der vollständige Pool von ~2.300 Monstern, nicht nur der Archetyp des Decks), jede Handmonster-Aktion (Normale Beschwörung / Selbst-Spezialbeschwörung / Pendelskala), jeder Such-/Hinzufügen-Effekt mit seinen Zielen (Archetyp-Ziellisten mit den bestbewerteten Mitgliedern zuerst), der Pendelbeschwörungsbereich und aktive/ausstehende Sperren. Dies ist das Anti-Tunnelblick-Tool: Das Modell darf sich nicht auf Kandidaten innerhalb des Archetyps beschränken.

4. line_search() — serverseitige begrenzte Breitensuche vom aktuellen Spielfeld zu einem Ziel (field_levels, field_count, no_locks, reach_field, reach_hand). Gibt vollständige mehrstufige Linien zurück, sodass das Modell mehrere Schritte im Voraus plant, statt einen Zug nach dem anderen.

5. extra_deck_options() — fügen Sie Ihr aktuelles Spielfeld (plus Hand/Friedhof/Extra-Deck und Format) ein und erhalten Sie jedes Fusions-/Synchro-/Xyz-/Link-/Ritual-Monster, dessen Materialanforderung erfüllbar ist, mit der genauen Materialbegründung für jeden Kandidaten.

Beispiel — zwei Monster der Stufe 4 von D/D auf dem Spielfeld:

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

Materialprüfungen nach bestem Ermessen werden gegen den vollständigen Beziehungsgraphen validiert; bestätigen Sie Grenzfälle vor der Finalisierung einer Linie immer mit get_card_materials.

Ressourcen

URL-kodieren Sie Ressourcenparameter, die Leerzeichen enthalten (rules://damage%20step).

Datenbankaufbau

data/vizier.db — SQLite mit sqlite-vec-Erweiterung. Wichtige Tabellen:

• cards — eine Zeile pro Karte mit berechneten Typ-Flags (is_monster, is_quickplay_spell, ...)

• card_sets, card_prices — Drucke und Marktpreise

• card_ban_status, banlist_history — aktueller Status pro Format + historische Schnappschüsse

• relations — Karte-zu-Karte-Effektbeziehungen mit Typen

• rulebook_chunks, rulings — Regelbuch- und Regelentscheidungstexte

• card_vec, rule_vec, ruling_vec — Einbettungstabellen für die semantische Suche

• meta — Build-Zeitstempel und Zählwerte

Datenquellen

• Karten / Preise / Banlists: YGOPRODeck-Bulk-API (zwischengespeichert in data/cache/)

• Regeln: offizielles umfassendes Regelbuch (ref/yugioh_comprehensive_rulebook/)

• Regelentscheidungen: offizielle OCG-Fragen-und-Antworten-Liste + YGOPEDIA-Fallback

• Turnierrichtlinien: Turnierrichtliniendokumente (policy/)

Tests

python -m pytest tests/ -q

Führt 32 Smoke-Tests gegen einen In-Process-Server-Client aus und deckt dabei jedes Tool und jede Ressource ab.