Commander Workshop MCP

Commander Workshop ist ein lokaler MCP-Server zum Erstellen, Prüfen, Vergleichen und Umsetzen von Magic: The Gathering Commander-Decks. Er kombiniert festgelegte Regeln und Kartendaten mit Ihrem explizit importierten Sammlungsbestand, hält die Deck-Absicht getrennt vom Besitz und verwandelt einen vollständigen Plan in Entnahmen, Tauschaktionen, Ersatz, Proxys oder Käufe.

Der Server eignet sich für uneingeschränktes Brauen, bestandsorientierten Bau, Bracket-3-Planung und Precon-Upgrades mit festem Budget. Er bewertet begrenzte vollständige Kandidaten und sagt bestes gefunden unter diesen Einschränkungen, anstatt eine universelle Stärkebewertung oder ein mathematisch perfektes Deck zu behaupten.

Funktionen

Related MCP server: MTG-MCP

Datenschutzversprechen

Ihre Sammlungen, Bindernamen, Standorte und physischen Deck-Zuordnungen bleiben standardmäßig lokal. Lokale Importe sind auf konfigurierte Wurzelverzeichnisse beschränkt. Der Server überträgt keine Decks, ändert keine Sammlungen, reserviert keine Karten, fügt keine Marktplatzartikel in einen Warenkorb ein oder schließt Käufe ab. Die optionale Marktplatzpreisermittlung sendet nur die minimalen Druckanforderungen und liest Anmeldeinformationen aus der Umgebung oder dem MCP-Host-Geheimnisspeicher.

Installation

Commander Workshop benötigt Python 3.11 oder neuer. Aus einem Repository-Checkout:

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

V1 unterstützt derzeit nur POSIX-Dateisysteme. Seine unveränderlichen Veröffentlichungspfade erfordern Dateiverzeichnisdeskriptoren, O_DIRECTORY, O_NOFOLLOW, harte Links, fsync und ratschließende Sperren; Windows wird nicht unterstützt. Der stdio-Server erwartet außerdem die als nächstes vorbereiteten verifizierten lokalen Eingaben.

Katalog- und Regelwerkeinrichtung

V1 stellt bewusst keine Netzwerkanfrage beim Serverstart. Laden Sie das Scryfall Default Cards JSONL gzip über Scryfalls dokumentierte Bulk-Daten-API herunter, bereiten Sie das Fünf-Dateien-Regelwerk vor, das in docs/rules-bundle.md spezifiziert ist, und führen Sie dann den getesteten Offline-Bootstrap-Befehl aus:

.venv/bin/commander-workshop-bootstrap \
  --data-dir /absolute/path/to/commander-workshop-data \
  --catalog-jsonl-gz /absolute/path/to/default-cards.jsonl.gz \
  --catalog-url https://data.scryfall.io/default-cards.jsonl.gz \
  --catalog-retrieved-at 2026-08-15T12:00:00+00:00 \
  --rules-bundle /absolute/path/to/rules-bundle

Verwenden Sie die tatsächliche Download-URL und Abrufzeit. --data-dir ist ein sicheres Installationswurzelverzeichnis; es kann bereits nicht zusammenhängende Dateien enthalten, die der Bootstrap niemals entfernt oder überschreibt. Der Befehl überprüft das gzip und das Regelwerk, erstellt eine inhaltsadressierte Umgebung unter environments/<sha256> und veröffentlicht einen atomaren READY-Marker, sobald die vollständige Darstellung dauerhaft ist. Ein erneuter Versuch stellt eine unvollständige Umgebung exakt wieder her und gibt dieselbe Version zurück. Veröffentlichte Katalog- und Regelwerksdateien sind exklusive Byte-Kopien ohne beibehaltene Stufen-Aliasnamen. Symbolische Verknüpfungen als Eingaben, harte Link-Aliasnamen, unerwartete Beilagen und widersprüchliche vorhandene Inhalte schlagen fehl.

Vor dem Bauen erkennt Bootstrap eine vollständig verifizierte READY-Umgebung anhand ihrer versionierten Eingabeidentität, sodass normale Wiederholungen derselben Eingabe keine neue Stufe erzeugen. Fehlgeschlagene Stufen sind inert und können zur manuellen Inspektion verbleiben; Bootstrap löscht niemals rekursiv Stufeninhalte, deren Besitz es nicht mehr nachweisen kann.

Das ausgegebene Datenverzeichnis bleibt das veränderliche Installationswurzelverzeichnis, in dem MCP-Aufzeichnungen unter records/ geschrieben werden. Die ausgegebenen Katalog- und Regelwerkspfade zeigen auf die beglaubigte fertige Version. Verwenden Sie alle drei Werte zusammen; Verzeichnisse ohne gültigen READY-Marker sind unvollständiger Bootstrap-Zustand und werden niemals zurückgegeben.

Setzen Sie nach dem Bootstrap COMMANDER_WORKSHOP_IMPORT_ROOTS auf ein oder mehrere vorhandene absolute Verzeichnisse und verwenden Sie die ausgegebenen Werte für die anderen Variablen. Ein fehlender, veralteter oder ungültiger kritischer Quellwert schlägt fehl. Siehe den Architekturleitfaden für den Datenfluss.

Claude, Codex und generische stdio-Konfiguration

Für Claude Desktop oder einen anderen Host, der die übliche JSON-Struktur verwendet, kopieren Sie examples/mcp-config.json und ersetzen Sie dessen absolute Platzhalterpfade.

Codex kann dieselbe ausführbare Datei aus config.toml verwenden:

[mcp_servers.commander_workshop]
command = "/absolute/path/to/commander-workshop-mcp/.venv/bin/commander-workshop-mcp"
args = []

[mcp_servers.commander_workshop.env]
COMMANDER_WORKSHOP_DATA_DIR = "/absolute/install-root"
COMMANDER_WORKSHOP_CATALOG_CURRENT = "/absolute/install-root/environments/<printed-sha256>/catalog/current.json"
COMMANDER_WORKSHOP_RULESET = "/absolute/install-root/environments/<printed-sha256>/rules/current.json"
COMMANDER_WORKSHOP_IMPORT_ROOTS = "/absolute/path/to/imports"

Jeder MCP-v2-Client kann diese absolute ausführbare Datei der virtuellen Umgebung als lokalen stdio-Subprozess mit diesen Umgebungsvariablen starten. In V1 gibt es keinen HTTP-Dienst oder Kontoeinrichtung. Eine pipx-Installation ist ebenfalls möglich: Verwenden Sie den absoluten Pfad, der von pipx environment --value PIPX_BIN_DIR zurückgegeben wird, verbunden mit commander-workshop-mcp.

End-to-End-Beispiel: Uneingeschränktes Brauen

1. Verwenden Sie search_cards, um den festgelegten Katalog zu durchsuchen, und load_deck für jeden vollständigen Kandidaten-Deck, der während des Brauens erstellt wird.

2. Rufen Sie plan_deck mit der Operation build, dem Kartenpool all_legal, den gewünschten Bracket-/Themen-/Proxy-Dimensionen und einem bis acht vollständigen Kandidaten-Einreichungen auf. Lesen Sie die zurückgegebene commander://plans/...-Ressource.

3. Laden Sie optional eine Sammlung, rufen Sie resolve_availability für den Gewinnerplan auf, dann rufen Sie create_fulfillment_plan auf. Die Verfügbarkeit bleibt hypothetisch; die Erfüllung weist nur innerhalb dieses unveränderlichen Ergebnisses eine Kopie zu.

Dieser Ablauf ist beim Brauen nicht durch den Bestand eingeschränkt, kann aber dennoch zeigen, was vorhanden ist und was fehlt, bevor der Benutzer handelt. Die vollständige plan_deck-Anfragevorlage wird durch die Akzeptanzsuite schemavalidierend geprüft.

End-to-End-Beispiel: Bau nur mit eigenem Bestand

1. Exportieren Sie die physische Sammlung als ManaBox-CSV oder ein CSV mit expliziten Spaltenzuordnungen, rufen Sie dann load_collection_snapshot im strikten Modus auf.

2. Verwenden Sie search_library, um Kandidatenkarten nach Name, Druck, Binder oder zusammengestellter Deck-Zuordnung zu finden.

3. Rufen Sie plan_deck mit dem Kartenpool owned_only und der Sammlungs-Snapshot-ID auf. Ein Kandidat mit einer nicht besessenen Nicht-Basiskarte scheitert an der harten Einschränkung.

4. Lesen Sie die Plan- und Verfügbarkeitsressourcen, um Binder-Entnahmen und Konflikte zu sehen. Eine bereits einem Deck zugeordnete Kopie wird gemeldet, nicht stillschweigend als frei behandelt.

Verwenden Sie die vollständige Nur-eigener-Bestand-Anfragevorlage, nachdem Sie deren Deck- und Sammlungs-IDs durch vorherige Tool-Ergebnisse ersetzt haben.

End-to-End-Beispiel: Bracket 3 USD/EUR 50 Precon-Upgrade

1. Exportieren oder fügen Sie das Precon ein und rufen Sie load_deck auf; es bleibt Deck-Absicht, kein Besitzanspruch.

2. Laden Sie vollständige Upgraded-Kandidaten und rufen Sie plan_deck mit der Operation upgrade, dem Precon als starting_deck_id, Bracket 3 und entweder der precon-upgrade-50-usd- oder precon-upgrade-50-eur-Szenario-Voreinstellungssemantik auf.

3. Überprüfen Sie genaue Hinzufügungen/Streichungen, datierte Bracket-Belege, Game Changers, Themenfakten und die garantierte Beschaffungsobergrenze in der nativen Währung. Fehlende erforderliche Preisbelege können die Obergrenze nicht als Null passieren.

4. Lösen Sie optional den Bestand auf, wählen Sie Entnahmen/Tausch/Ersatz/Proxys mit create_fulfillment_plan, rufen Sie dann price_purchases für die verbleibenden Kaufpositionen auf. Die Preisermittlung dient nur zur Information und gibt niemals eine Bestellung auf.

Die USD-50-Anfragevorlage enthält das vollständige Szenario, Kandidatenbelege, Bewertungsdefinitionen, Bracket-Richtlinie und das Startdeck-Feld. Ändern Sie sowohl Währung als auch Gesamtrichtlinie für die EUR-Voreinstellung.

Unterstützte Importe

• ManaBox-Sammlungs-CSV, das physische Binder und registrierte Decks von Wunschlisten oder anderen Nicht-Besitz-Listen trennt.

• Generisches Sammlungs-CSV mit einer expliziten Zuordnung für Menge und genaue Kartenidentität, plus optionalen Druck- und Standortfeldern.

• Arena-artiger und üblicher Mengen-/Name-/Set-/Sammelnummern-Decktext.

• Benutzerexportierter Decktext von Moxfield, Archidekt, Deckbox, Deckstats, TopDecked und ähnlichen Hosts, wenn er dem unterstützten Textdialekt entspricht.

Fügen Sie einen Export ein oder wählen Sie ihn aus, den Sie verwenden dürfen. V1 durchsucht keine Kontoseiten, verwendet keine Browser-Cookies wieder oder ruft undokumentierte Deck-Host-Endpunkte auf. Direkte gehostete URLs geben unsupported_source zurück; exportieren Sie das Deck und importieren Sie dessen Text.

Tools

Die öffentliche Oberfläche umfasst genau elf Tools:

Jedes Tool gibt einen versionierten Umschlag mit einer stabilen Ergebnis-ID, Status, prägnanter Zusammenfassung, Problemen, Quellstempeln und normalerweise einem Ressourcen-URI zurück.

Ressourcen

commander://cards/{oracle_id}
commander://searches/{result_id}
commander://collections/{snapshot_id}
commander://decks/{deck_id}
commander://plans/{plan_id}
commander://availability/{resolution_id}
commander://prices/{snapshot_id}
commander://fulfillment/{plan_id}
commander://rules/current
commander://presets

Aufzeichnungen sind unveränderlich und inhaltsadressiert. Sammlungen und breite Suchen sind begrenzt und paginiert; Tool-Zusammenfassungen vermeiden das Wiederholen von Sammlungsinhalten.

Szenariodimensionen

Ein Planungsszenario setzt diese unabhängigen Entscheidungen zusammen:

• operation: build, upgrade oder analyze;

• bracket: 1 bis 5, mit datiertem Zug- und Game-Changer-Beleg;

• card pool: all_legal, prefer_owned oder owned_only;

• budget: nativer Währungsbetrag und optionales Pro-Karten-Limit, einschließlich USD/EUR 50 Precon-Upgrade-Voreinstellungen;

• proxy policy: none, owned-once oder unlimited, wo die Spielgruppe es erlaubt;

• theme policy: strict contract, flexible preference oder strength-oriented;

• geschützte zusammengestellte Decks, festgelegtes Regelwerk und deterministischer Seed.

Bracket-Fit und strategische Stärke werden nicht zu einer einzigen Bewertung zusammengefasst. Offizielle Commander-Regeln bleiben maßgeblich, und Rule-Zero-Überschreibungen müssen explizit sein.

Preissemantik

price_purchases trennt Artikelzwischensumme, Anbieterzwischensumme, Versand und geschätzte Gesamtsumme inklusive Einfuhrabgaben. Unbekannte Artikel oder Versand bleiben null, niemals null. Ein garantiertes Budget kann nur dann durchgehen, wenn jeder erforderliche Kauf unter der ausgewählten Richtlinie über einen berechtigten, bekannten Nachweis verfügt.

Scryfall-Katalogwerte sind indikative PriceEstimate-Beobachtungen, keine Checkout-Angebote. CardTrader-Einträge sind schreibgeschützte PurchaseQuote-Beobachtungen. Planungsschätzungen verwenden ein deklariertes Aktualitätsfenster von höchstens 24 Stunden; CardTrader kann eine kürzere Listungslebensdauer verwenden. Teilweise und veraltete Beobachtungen enthalten explizite unknown_price-, Authentifizierungs-, Ausfall- oder Ratenbegrenzungsprobleme.

Anbieterbeschränkungen

• Scryfall-Schätzungen stammen aus dem verifizierten lokalen Katalog, können eine Währung, Veredelung, Zustand, Sprache, Menge oder Versand vermissen lassen und sind nicht käuflich.

• CardTrader ist optional, erfordert CARDTRADER_API_TOKEN, verwendet nur feste dokumentierte GET-Endpunkte, folgt keinen Weiterleitungen und optimiert keinen perfekten Multi-Verkäufer-Warenkorb.

• Cardmarket und TCGplayer sind standardmäßig nicht aktiviert; Zugriffsbeschränkungen und Anbieterbedingungen müssen von jedem zukünftigen Adapter respektiert werden.

• Kein Anbieter kann Deck-Legalität, Sammlungsbesitz, Proxy-Richtlinie oder Reservebestand ändern. Kein Anbieter stellt Warenkorb- oder Kaufvorgänge bereit.

Normale Tests und CI stellen keine Live-Marktplatz- oder Deck-Host-Anfragen.

Entwicklung

python -m pip install -e '.[test]'
python scripts/check_public_tree.py
ruff check src tests scripts
pytest -q
python -m build

Der Datenschutz-Scanner durchsucht den verfolgten Baum nach privaten Pfaden, Anmeldeinformationen, Datenbanken, unsicheren Datenexporten, Symlinks und undokumentierten/überdimensionierten Testdaten. Alle Testdaten sind synthetisch und deterministisch.

Architektur

Siehe docs/architecture.md für Komponentengrenzen, unveränderlichen Speicher, Vertrauensgrenzen, Planungs-/Erfüllungsablauf und Erweiterungspunkte.

Sicherheitsmeldungen

Folgen Sie SECURITY.md. Verwenden Sie eine private Sicherheitsberatung und eine minimale synthetische Reproduktion; fügen Sie niemals einen Sammlungsexport, Binderbestand, Token oder andere persönliche Daten bei.

Namensnennung

Kartennamen, Regeltexte und Katalogmetadaten können von Scryfall abgeleitet sein, dessen Daten- und Namensnennungsanforderungen gelten. Magic: The Gathering-Regeln und Commander-Bracket-Richtlinie werden von Wizards of the Coast veröffentlicht. Anbieternamen und Marktplatzdaten bleiben Eigentum ihrer jeweiligen Inhaber.

Keine Zugehörigkeit

Commander Workshop MCP ist inoffizielle Fan-Software. Sie ist nicht mit Wizards of the Coast, Scryfall, CardTrader oder einem anderen Deck-Host oder Marktplatz verbunden, von diesen empfohlen, gesponsert oder genehmigt. Magic: The Gathering, Commander und verwandte Marken gehören Wizards of the Coast und ihren jeweiligen Inhabern.

Commander Workshop MCP ist inoffizieller Fan-Inhalt, der gemäß der Fan-Content-Richtlinie erlaubt ist. Nicht von Wizards genehmigt/empfohlen. Teile des verwendeten Materials sind Eigentum von Wizards of the Coast. ©Wizards of the Coast LLC.

Lizenz

Die Software wird unter der MIT-Lizenz veröffentlicht. Daten von Drittanbietern zu Karten, Regeln und Marktplätzen unterliegen weiterhin ihren eigenen Bedingungen und Lizenzen.