Ein Scryfall-Commander-Kartenfinder verwandelt eine Beschreibung der Karte, die du brauchst, in eine Suche, die du prüfen kannst. In diesem Tutorial erstellst du Open Query, einen Quickchat AI-Agenten, der seine Scryfall-Abfrage anzeigt, echte Karteneinträge zurückgibt und erklärt, warum jeder Kandidat in dein Deck passen könnte.
Beginne mit einem Slot in einem monogrünen Commander-Deck. Du willst eine Kreatur mit Trample und einem Preis unter fünf US-Dollar. Am Ende kannst du diese Anfrage eingeben, die zurückgegebenen Karten öffnen und die Suche verfeinern, ohne jeden Operator auswendig zu kennen.
Das Ziel: eine sichtbare Abfrage und eine kleine Menge verknüpfter Karten, die du prüfen kannst. Öffne ein beliebiges Bild, um es in voller Größe anzusehen.
Eine zurückgegebene Karte, geprüft anhand ihres Scryfall-Eintrags. USD 0.35 wurde am 10. November 2026 beobachtet. Kartenillustration von Filip Burburan, © Wizards of the Coast. Bild bereitgestellt von Scryfall. Keiner von beiden unterstützt dieses Tutorial.
Der nützliche Teil beginnt, wenn die Anfrage schwieriger wird. „Ziehe, wenn eine andere Kreatur ins Spiel kommt“ klingt präzise, aber eine Suche nach den Wörtern enters und draw findet auch Karten, die etwas anderes tun. Du wirst diese Abweichung erkennen und die Abfrage eingrenzen, wobei du den zurückgegebenen Kartentext als Beleg nutzt.
Was wirst du bauen, und was brauchst du dafür?
Du verbindest eine schreibgeschützte API Action mit Scryfall, gibst dem Agenten seine Suchanweisungen und testest ihn in einer Unterhaltung. Die Action ruft eine feste URL auf. Das Modell liefert eine Abfrage und eine Seitennummer. Scryfall gibt die Einträge zurück, auf denen die Antwort basiert.
Das Modell interpretiert deine Anfrage. Die Action ruft Einträge ab. Du prüfst, ob der zurückgegebene Text die Interpretation stützt.
- Erstelle ein Quickchat AI-Konto und einen Agenten namens Open Query. Du brauchst verfügbare AI-Credits für Unterhaltungen und Tests. Sieh dir dazu die aktuellen Tarife an.
- Halte beim Arbeiten die Identity, Actions & MCPs und AI Preview des Agenten bereit. Du musst keine Kartensammlung hochladen.
- Nutze die öffentliche API von Scryfall. Für diese Suchen brauchst du weder ein Scryfall-Konto noch einen API-Schlüssel.
Das Starter-Kit enthält den Main Prompt, das Action-Rezept, Response-Filter-Pfade und Testnachrichten. Die Beispiele verwenden englischen Oracle-Text und USD-Preise. Lass die Abfrageoperatoren und Kartennamen so stehen, wie sie geschrieben sind, wenn du in einer anderen Sprache mitmachst.
Schritt 1: Wie verwandelst du eine Kartenanfrage in eine Scryfall-Abfrage?
Eine Scryfall-Abfrage kombiniert Einschränkungen, die durch Leerzeichen getrennt sind. Für unsere erste Anfrage verwende:
f:commander id<=g t:creature kw:trample usd<5
Jede Klausel beantwortet einen Teil der Anfrage. Du kannst eine davon ändern, ohne die anderen neu zu schreiben.
| Abfrageklausel | Was sie verlangt |
|---|---|
f:commander | Karten, die in Commander legal sind. |
id<=g | Farbidentität innerhalb von Grün, einschließlich farblos. |
t:creature | Kreaturenkarten. |
kw:trample | Das Trample-Schlüsselwort. |
usd<5 | Der USD-Preis von Scryfall unter 5. |
Zwei kleine Entscheidungen sind wichtig. kw:trample sucht nach dem Schlüsselwort. o:trample sucht nach dem Wort im Oracle-Text. Eine Kreatur kann Trample erwähnen, ohne diese Fähigkeit selbst zu haben. Wir haben beides getestet. Die Textsuche ergab eine breitere Menge.
„Passt in ein monogrünes Deck“ unterscheidet sich auch von „hat genau grüne Identität“. Ersteres erlaubt farblose Karten. Verwende id=g für Letzteres oder id<=ur, um innerhalb der Farben eines blau-roten Commanders zu suchen. Das sind Identitätseinschränkungen, keine vollständige Prüfung der Decklegalität.
Beide Karten passen zu id<=g. Nur Aggressive Mammoth hat genau die grüne Farbidentität, id=g.
Die Referenz zur Suchsyntax von Scryfall erklärt diese Operatoren. Für dieses Tutorial solltest du die Abfrage in jeder Antwort sichtbar halten, damit dir eine ausgelassene Farbe, eine unerwartete Währung oder eine Suche auffällt, die breiter ist als deine Anfrage.
Schritt 2: Wie verbindest du die Scryfall-API mit deinem Agenten?
Erstelle eine API Action, die eine GET-Anfrage an den Endpunkt für die Kartensuche von Scryfall sendet. Ihre festen Einstellungen wählen den Anbieter und die Sortierung. Ihre zwei Parameter lassen den Agenten Suche und Seite auswählen.
- Öffne Actions & MCPs → Add Action → API Action.
- Verwende die Builder-Anfrage unten und prüfe dann die erzeugten Einstellungen anhand des Rezepts. Der API Action-Builder-Leitfaden erklärt den Ablauf für Erzeugung und Prüfung.
- Setze API Action Name auf
Search Scryfall cards.
Create a read-only Scryfall card-search Action using GET https://api.scryfall.com/cards/search. Add required Text query and Integer page parameters. Map q to query and page to page in Query Params. Fix unique=cards and order=name. Send Accept: application/json and User-Agent: QuickchatTutorialCardFinder/1.0 (+https://quickchat.ai). No authentication and no request body. Fetch one page only. Preserve pagination, warnings, card IDs, names, Oracle text including card_faces, color identity, Commander legality, USD prices and Scryfall links in the response.Definiere die zwei Parameter
Füge unter What to ask the user first diese erforderlichen Parameter hinzu. Der Agent kann sie aus der Unterhaltung ausfüllen. Die Bezeichnung bedeutet nicht, dass er dich bitten muss, rohe Abfragesyntax einzugeben.
| Datentyp | Parametername | Beschreibung | Erforderlich |
|---|---|---|---|
| Text | query | Scryfall-Abfrage, die das bestätigte Format, die Farbidentität, den Kartentyp, die Fähigkeit und den optionalen Währungsfilter widerspiegelt. Verwende die dokumentierte Syntax. | Ja |
| Zahl | page | API-Seitennummer, beginnend bei 1. Erhöhe sie nur, wenn der Leser ausdrücklich die nächste Seite derselben Abfrage anfordert. | Ja |
Die zwei Parameter sind die Werte, die sich zwischen Suchen ändern.
Lege Endpunkt, Abfrageparameter und Header fest
Wähle GET und gib ein:
https://api.scryfall.com/cards/searchFüge unter Query Params die vier Zeilen unten hinzu. Für die dynamischen Werte verwende Add AI Data, um den von dir erstellten Parameter auszuwählen. Die Schreibweise {{query}} und {{page}} unten steht für diese Parameter-Chips.
| Abfrageparameter | Wert |
|---|---|
q | {{query}} |
unique | cards |
order | name |
page | {{page}} |
Der Endpunkt bleibt fest. Die Chips liefern query und page für jeden Aufruf.
Verwende die Felder für Abfrageparameter, damit Leerzeichen, Anführungszeichen und Operatoren als Parameterwerte kodiert werden. Lass die Endpunkt-URL fest.
| HTTP-Header | Wert |
|---|---|
Accept | application/json |
User-Agent | QuickchatTutorialCardFinder/1.0 (+https://quickchat.ai) |
Lass Body leer. Es ist keine Authentifizierung nötig. Das User-Agent ist ein identifizierender Client-Name, keine Zugangsdaten. Verwende beim Bereitstellen deiner Version deinen eigenen passenden Anwendungsnamen und deine Kontakt-URL.
Halte die Antwort nützlich
Eine Scryfall-Seite kann viele Datensätze enthalten. Behalte die Felder, die der Agent benötigt, zusammen mit den Informationen, die ihm sagen, ob weitere Seiten vorhanden sind. Klappe Advanced settings auf und suche Response filter. Verwende Add JSONPath und dann die Plus-Schaltfläche, um jeden untenstehenden Pfad als separaten Eintrag hinzuzufügen:
$.total_cards
$.has_more
$.next_page
$.warnings
$.data[*].id
$.data[*].name
$.data[*].oracle_text
$.data[*].card_faces
$.data[*].color_identity
$.data[*].legalities.commander
$.data[*].prices.usd
$.data[*].scryfall_uri
Behalte die Listenmetadaten ebenso wie die Kartendaten. Eine gefilterte Antwort sollte ihren Umfang weiterhin erklären.
Die ausgewählten Felder hinter einer Empfehlung. USD 0.17 wurden am 10. November 2026 erfasst; der vollständige Datensatz enthält außerdem die ID und den Scryfall-Link.
Behalte card_faces. Manche Karten haben ihren Text auf einzelnen Kartenseiten statt auf der obersten Ebene. Behalte auch warnings: Ein erfolgreicher HTTP-Status bedeutet nicht, dass Scryfall jede Klausel wie beabsichtigt interpretiert hat. Die Referenz zum Kartenobjekt beschreibt diese Felder.
Füge in API Action Description Folgendes ein:
Use when a player wants to find real cards matching a confirmed request. Build an inspectable Scryfall query, fetch one page, and explain matching evidence from returned fields. Show the executed query and any returned warnings. Return at most five initial recommendations, with Scryfall links, relevant Oracle text, color identity and USD price. If more API pages exist, say so and offer the next page; do not claim the first results are exhaustive. Treat broad text searches as candidates until their Oracle text establishes the requested interaction.Speichere die Action und prüfe, dass sie aktiv ist. Der Leitfaden zur Anatomie von HTTP-Actions erklärt, wie Parameter, Anfrage und Beschreibung zusammenarbeiten.
Schritt 3: Wie sollte der Kartenfinder seine Ergebnisse erklären?
Der Agent braucht Anweisungen, um seine Abfrage anzuzeigen, Empfehlungen auf zurückgegebene Einträge zu stützen und einen Worttreffer von einer Regelinteraktion zu unterscheiden. Öffne Identity → Main Prompt und füge den vollständigen Prompt aus dem Starter-Kit ein, der unten wiedergegeben ist.
Den vollständigen Main Prompt kopieren
You are Open Query, a Commander card-search helper. Clarify format, color identity and budget currency when needed. Turn the confirmed request into documented Scryfall syntax, call Search Scryfall cards, and show the executed query in a code block followed by up to five linked results. Recommend only records returned by this Action. Include each card's name, Scryfall link, color identity, returned USD price and the relevant Oracle text. Summarize without inventing text or cards. Use periods or semicolons rather than em dashes. Use text on card_faces when present.
For mono-green deck eligibility use id<=g; this includes colorless. For exactly green identity use id=g. A baseline trample request uses f:commander id<=g t:creature kw:trample usd<5.
Separate word matches from rules interpretation. If a card mentions the requested words but does not establish the requested trigger, label it a candidate to inspect, not a confirmed fit. Prices are provider observations, not seller quotes; a missing price is unknown. Say the total result count and whether more API pages exist. Start at page 1. Fetch the next page only when asked, using the same query and the next page number. Never fetch every page automatically. A shortlist is not exhaustive. If asked for more from this page, fetch the same query and page again, then choose returned cards you have not already shown. The next API page is different.
Do not build a full deck, invent cards, or claim a rules ruling. If a search returns no results or an error, explain it and offer a specific query change for confirmation. Inspect response warnings as well as errors. If Scryfall ignores part of a query, report that warning, do not recommend cards from that broadened result, and ask before changing the query. Do not silently retry an altered query. If rate limited, stop and ask the reader to try later.
Die Anweisungen gelten für die Suche und für die Erklärung, nachdem die Antwort zurückgekommen ist.
Öffne jetzt AI Preview und sende:
Find Commander-legal creatures in mono-green color identity with trample, priced below 5 USD.Die Demo hat die Eignung für ein monogrünes Deck als grün oder farblos interpretiert. Wenn du genau grüne Identität willst, sag das ausdrücklich.
Lies die ausgeführte Abfrage vor den Empfehlungen. Sie sollte Commander, grüne-oder-farblose Identität, Kreaturentyp, Trample und USD unter 5 beibehalten. Öffne den Scryfall-Link einer Karte und vergleiche den relevanten Text, die Identität und den Preis mit der Antwort. Der Preis ist der beim Abruf beobachtete Wert für die jeweilige Druckversion, kein Checkout-Angebot.
Die API-Ergebnisse sind nach Namen sortiert, nicht nach Passgenauigkeit gerankt. Der Agent wählt eine kurze Liste aus der abgerufenen Seite. unique=cards verhindert, dass jede Druckversion als separates Ergebnis aufgeführt wird. Es bedeutet nicht, dass der ausgewählte Eintrag die günstigste Kopie ist, die du kaufen kannst.
Beide Karten erfüllten dieselbe Suchanfrage. Aberrant Manawurm belohnt das Wirken von Spontanzaubern und Hexereien; Aggressive Mammoth gibt deinen anderen Kreaturen Trampelschaden. Lies den Rest der Fähigkeit, bevor du dich entscheidest.
Schritt 4: Wie korrigierst du eine Suche, die die falsche Interaktion findet?
Grenze die Abfrage ein, indem du ein Gegenbeispiel liest und die fehlende Bedingung hinzufügst. Behalte während der Verfeinerung die Unterscheidung zwischen dem Finden von Kandidatenkarten und dem Bestätigen ihres Textes bei.
Frage:
Find green cards that draw when another creature enters, under 5 USD.Eine breite Kandidatensuche ist:
f:commander id<=g o:enters o:draw usd<5Bei unserer direkten Scryfall-Prüfung am 10. November 2026 ergab das 161 Kandidaten, darunter Abundant Growth. Das Ziehen passiert dort, wenn die Aura selbst ins Spiel kommt. Sie enthält beide Wörter, liefert aber nicht die wiederholbare Zieh-Engine beim Ins-Spiel-Kommen von Kreaturen, die die Anfrage nahelegt.
Lies, was das Ziehen auslöst. Zwei passende Wörter belegen die Interaktion nicht.
Versuche diese Verfeinerung:
Keep the same colors and budget. Look for “whenever another creature”, then check the conditions in each returned card's text.Die engere Abfrage, die wir geprüft haben, war:
f:commander id<=g o:"whenever another creature" o:enters o:draw usd<5Die verfeinerte Suche ergab vier Kandidaten. Garruk’s Packleader ist ein nützlicher bedingter Treffer: Die andere Kreatur muss Stärke 3 oder mehr haben. Diese Unterscheidung gehört in die Empfehlung. Eine Token-Strategie mit vielen 1/1-Kreaturen braucht vielleicht eine andere Karte.
Die vier gefundenen Kandidaten haben unterschiedliche Bedingungen. Prüfe die Stärke, den Kartennamen und wer Karten ziehen darf, bevor du eine Karte als passend einstufst.
Nur o:"another creature" hinzuzufügen ist weniger präzise. Unser Test fand immer noch Disciple of Freyalise, bei der ihr eigener Eintritt dazu führen kann, dass du eine andere Kreatur opferst und ziehst. Das ist ein weiterer Grund, die ganze Fähigkeit zu prüfen, statt eine zusätzliche Formulierung als Beweis zu behandeln.
Wiederhole dieselbe Schleife für dein eigenes Deck: Anfrage → Abfrage → Kartentext → eine Verfeinerung. Wenn das Budget jeden nützlichen Kandidaten ausschließt, frage nach, bevor du es erweiterst. Wenn eine Karte eine Einschränkung hat, nenne die Einschränkung, statt sie stillschweigend aus der Erklärung wegzulassen.
Schritt 5: Wie testest du den Kartenfinder, bevor du ihn benutzt?
Teste sowohl die Antwort als auch den API-Aufruf. Ein überzeugender Satz kann nicht belegen, welche Abfrage ausgeführt wurde oder welche Einträge zurückkamen.
- Öffne Testing und erstelle einen Datensatz namens Open Query checks mit Create Dataset → Paste messages. Füge die unabhängigen Testnachrichten aus dem Kit ein.
- Führe die Tests aus. Bewerte, ob die Antwort ihre Abfrage zeigt, zurückgegebene Karten nennt und Unsicherheit erklärt.
- Öffne die passende Unterhaltung in Inbox und prüfe den Action-Aufruf. Kontrolliere Abfrage, Seitennummer, Status und zurückgegebene Felder. Verwende die Steuerung View logs der Action, um einzelne Aufrufe zu finden.
- Teste Verfeinerung und Paginierung in einer fortlaufenden Unterhaltung, in der die vorherige Abfrage verfügbar ist.
Verwende unabhängige Nachrichten für isolierte Prüfungen und eine fortlaufende Unterhaltung für die Verfeinerung.
Prüfe Anfrage und Antwort zusammen. Ein erfolgreicher HTTP-Status allein validiert die Kartenempfehlung nicht.
| Testfall | Was du prüfen solltest |
|---|---|
| Erste Trample-Anfrage | Korrekte Abfrage, Seite 1, echte verknüpfte Karten und relevante Belege aus Schlüsselwort/Text. |
| Anfrage nach Ziehen bei einer anderen Kreatur | Bedingungen wie Stärke 3 oder mehr bleiben in der Antwort erhalten. |
| „Zeig die nächste API-Seite.“ | Dieselbe Abfrage und Seite 2, nur wenn has_more wahr war. |
| „Zeig mehr von dieser Seite.“ | Ein erneuter Aufruf mit derselben Abfrage und Seite, gefolgt von bisher nicht gezeigten Karten. |
| Unmöglicher Kartenname | Kein erfundener Ersatz. Erkläre das leere Ergebnis und schlage eine konkrete Änderung vor. |
| Fehlendes USD-Feld | Preis ist unbekannt, niemals null oder „kostenlos“. |
| Fehlerhafte Abfrage oder Warnung des Anbieters | Erkläre das Problem und frage nach, bevor du die Abfrage erweiterst. |
| Antwort wegen Rate Limit | Stoppe, statt wiederholt neu zu versuchen. |
Für den Test ohne Treffer sende:
Find a Commander card named definitely-not-a-real-card-xyz.
Ein leeres Ergebnis ist eine nützliche Antwort. Es gibt dir eine Abfrage, die du ändern kannst, ohne eine Karte zu erfinden.
Ein direkter API-Test zeigte, warum Warnungen wichtig sind. Die fehlerhafte Abfrage f:commander o:/[/ gab HTTP 200 zurück, aber Scryfall meldete, dass der ungültige Ausdruck ignoriert wurde. Die Ergebnisse waren daher breiter als angefordert. Behalte diese Warnung bei, erkläre den ignorierten Filter und korrigiere die Abfrage, bevor du diese Ergebnisse empfiehlst.
Unsere lokalen Agent-Läufe deckten die Basis, Verfeinerung, leere Ergebnisse und eine Suche über zwei Seiten ab. Separate API-Prüfungen deckten fehlende Preise, Kartenseiten und Syntaxwarnungen ab. Verwende ein kontrolliertes Fixture, um Rate Limiting zu testen, ohne übermäßigen Traffic zu senden.
Die Dokumentation zum Endpunkt für die Kartensuche gibt derzeit zwei Suchanfragen pro Sekunde an. Halte zwischen Anfragen mindestens 500 Millisekunden Abstand. Dieses Tutorial ist ein persönlicher Suchhelfer. Ein öffentlicher Bot für viele Spieler braucht gemeinsames Rate Limiting und Caching. Das Modell zu bitten, langsamer zu werden, erzwingt kein globales Anfrage-Limit.
Kann ChatGPT oder Claude beim Konfigurieren helfen?
Du kannst das Quickchat AI-Plugin für ChatGPT oder den Quickchat AI-Connector für Claude verwenden, um den Agenten über die Verbindung zur Kontoverwaltung zu konfigurieren. Schließe die Anmeldung selbst ab und gib dann dieses Tutorial und sein Starter-Kit mit der folgenden Anfrage weiter:
Use Quickchat AI to create a dedicated Agent called Open Query using the attached tutorial and starter kit. Set its Main Prompt and create the Search Scryfall cards API Action with the exact parameters, headers and response filters. Show me the saved configuration, then run the baseline and impossible-name tests and show their Action call records. Run only those two conversations; they use AI credits. Do not publish the Agent or connect a public channel.Die Dokumentation zur Kontoverwaltung erklärt die Verbindung. Dadurch wird dein Quickchat AI-Konto konfiguriert. Es macht Open Query nicht automatisch als MCP-Tool für andere Personen verfügbar.
Häufig gestellte Fragen
Kann ich Scryfall in natürlicher Sprache durchsuchen?
Ein AI-Assistent kann eine Anfrage in Alltagssprache in die Scryfall-Suchsyntax übersetzen und sie über die Scryfall-API ausführen. Dieses Tutorial erstellt diesen Assistenten in Quickchat AI und sorgt dafür, dass er die Abfrage, verknüpfte Karteneinträge und relevanten Oracle-Text anzeigt, damit du die Interpretation prüfen kannst.
Brauche ich einen Scryfall-API-Schlüssel?
Nein. Der öffentliche Endpunkt für die Kartensuche erfordert weder ein Konto noch einen API-Schlüssel. Sende identifizierende User-Agent- und Accept-Header, halte dich an die Rate Limits von Scryfall und fordere zusätzliche Seiten bewusst an.
Kann dieser AI-Kartenfinder eine Karte halluzinieren?
Die Anweisungen beschränken Empfehlungen auf Einträge, die von der Action zurückgegeben werden, mit Scryfall-Links. Das Modell kann aber trotzdem Fehler machen, also prüfe die zurückgegebene ID und den Oracle-Text und teste einen unmöglichen Kartennamen, bevor du dich auf den Assistenten verlässt.
Was ist der Unterschied zwischen id<=g und id=g bei Scryfall?
id<=g umfasst grüne und farblose Identitäten und eignet sich für die Suche innerhalb der Farben eines monogrünen Commanders. id=g verlangt genau eine grüne Identität. Farbidentität ist etwas anderes als Kartenfarbe. Verwende für den Deckbau in Commander den Identitätsfilter.
Sind Scryfall-Preise garantiert?
Nein. Das Feld prices.usd enthält Preisdaten des Anbieters für den zurückgegebenen Druck, nicht ein Angebot eines Verkäufers. Es kann null sein. Der Filter usd<5 sucht unter fünf US-Dollar. Er legt keine Versandkosten, Verfügbarkeit oder den günstigsten kaufbaren Druck fest.
Liefert eine Suche jede passende Karte zurück?
Eine Suche liefert eine API-Seite zurück. Die Antwort enthält total_cards, has_more und, wenn relevant, next_page. Open Query zeigt bis zu fünf Empfehlungen aus der abgerufenen Seite. Bitte um mehr von dieser Seite oder fordere ausdrücklich die nächste API-Seite an. Eine kurze Liste ist nicht die vollständige Ergebnismenge.
Kann das mein gesamtes Commander-Deck bauen?
Dieses Tutorial erstellt einen Assistenten für die Kartensuche. Er hilft dabei, Kandidaten für einen Deck-Slot zu finden und zu prüfen. Er validiert kein vollständiges 100-Karten-Deck, optimiert keine Deckliste und ersetzt keinen Judge für Regeln.