Bouw een AI-Commander-kaartzoeker met Scryfall

Een Scryfall Commander-kaartzoeker zet een beschrijving van de kaart die je nodig hebt om in een zoekopdracht die je kunt inspecteren. In deze tutorial bouw je Open Query, een Quickchat AI-agent die zijn Scryfall-query toont, echte kaartrecords teruggeeft en uitlegt waarom elke kandidaat in je deck zou kunnen passen.

Begin met één slot in een monogroen Commander-deck. Je wilt een creature met trample en een prijs onder vijf Amerikaanse dollar. Aan het einde kun je dat verzoek typen, de teruggegeven kaarten openen en de zoekopdracht verfijnen zonder elke operator uit je hoofd te kennen.

Het nuttige deel komt wanneer het verzoek moeilijker wordt. “Draw when another creature enters” klinkt precies, maar een zoekopdracht naar de woorden enters en draw vindt ook kaarten die iets anders doen. Je zult die mismatch opmerken en de query verfijnen, waarbij je de teruggegeven kaarttekst als bewijs gebruikt.

Wat ga je bouwen, en wat heb je nodig?

Je verbindt één alleen-lezen API Action met Scryfall, geeft de agent zijn zoekinstructies en test hem in een gesprek. De Action roept een vaste URL aan. Het model levert een query en paginanummer. Scryfall geeft de records terug waarop het antwoord is gebaseerd.

1. Maak een Quickchat AI-account en een agent met de naam Open Query. Je hebt beschikbare AI-credits nodig voor gesprekken en tests. Zie de huidige abonnementen.
2. Houd de Identity, Actions & MCPs en AI Preview van de agent beschikbaar terwijl je werkt. Je hoeft geen kaartcollectie te uploaden.
3. Gebruik de openbare API van Scryfall. Je hebt voor deze zoekopdrachten geen Scryfall-account of API-sleutel nodig.

De starterkit bevat de Main Prompt, het Action-recept, response-filterpaden en testberichten. De voorbeelden gebruiken Engelse Oracle-tekst en USD-prijzen. Houd de query-operators en kaartnamen zoals geschreven wanneer je in een andere taal meedoet.

Stap 1: Hoe zet je een kaartverzoek om in een Scryfall-query?

Een Scryfall-query combineert beperkingen die door spaties zijn gescheiden. Gebruik voor ons eerste verzoek:

f:commander id<=g t:creature kw:trample usd<5

Twee kleine keuzes zijn belangrijk. kw:trample zoekt naar het keyword. o:trample zoekt naar het woord in Oracle-tekst. Een creature kan trample noemen zonder die ability zelf te hebben. We hebben beide getest. De tekstzoekopdracht leverde een bredere set op.

“Past in een monogroen deck” verschilt ook van “heeft exact een groene identiteit.” De eerste staat kleurloze kaarten toe. Gebruik id=g voor het tweede, of id<=ur om te zoeken binnen de kleuren van een blauw-rode commander. Dit zijn identiteitsbeperkingen, geen volledige controle op decklegaliteit.

De referentie voor zoeksyntaxis van Scryfall legt deze operators uit. Houd voor deze tutorial de query zichtbaar in elk antwoord, zodat je een weggelaten kleur, een onverwachte valuta of een zoekopdracht die breder is dan je verzoek kunt opmerken.

Stap 2: Hoe verbind je de Scryfall-API met je agent?

Maak één API Action die een GET-verzoek stuurt naar het kaartzoekendpoint van Scryfall. De vaste instellingen kiezen de provider en sortering. De twee parameters laten de agent de zoekopdracht en pagina kiezen.

1. Open Actions & MCPs → Add Action → API Action.
2. Gebruik het builder-verzoek hieronder en controleer daarna de gegenereerde instellingen aan de hand van het recept. De API Action-buildergids legt de generatie- en controleflow uit.
3. Stel API Action Name in op 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.

Definieer de twee parameters

Voeg onder What to ask the user first deze verplichte parameters toe. De agent kan ze vanuit het gesprek invullen. Het label betekent niet dat hij je moet vragen ruwe querysyntaxis te typen.

Stel het endpoint, de queryparameters en headers in

Selecteer GET en voer in:

https://api.scryfall.com/cards/search

Voeg onder Query Params de vier onderstaande rijen toe. Gebruik voor de dynamische waarden Add AI Data om de parameter te selecteren die je hebt gemaakt. De notatie {{query}} en {{page}} hieronder stelt die parameterchips voor.

Gebruik de velden voor queryparameters zodat spaties, aanhalingstekens en operators als parameterwaarden worden gecodeerd. Houd de endpoint-URL vast.

Laat Body leeg. Er is geen authenticatie nodig. De User-Agent is een identificerende clientnaam, geen credential. Gebruik je eigen passende applicatienaam en contact-URL wanneer je jouw versie uitrolt.

Houd het antwoord bruikbaar

Een Scryfall-pagina kan veel records bevatten. Bewaar de velden die de Agent nodig heeft, samen met de informatie die aangeeft of er meer pagina’s zijn. Vouw Advanced settings uit en zoek Response filter. Gebruik Add JSONPath en daarna de plusknop om elk pad hieronder als een afzonderlijke invoer toe te voegen:

$.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

Bewaar card_faces. Sommige kaarten plaatsen hun tekst op afzonderlijke faces in plaats van op het hoogste niveau. Bewaar ook warnings: een HTTP-succes betekent niet dat Scryfall elke clausule heeft geïnterpreteerd zoals bedoeld. De Card object reference beschrijft deze velden.

Plak in API Action Description:

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.

Sla de Action op en controleer of hij actief is. De gids over de anatomie van HTTP Actions legt uit hoe de parameters, het verzoek en de beschrijving samenwerken.

Stap 3: Hoe moet de kaartzoeker zijn resultaten uitleggen?

De agent heeft instructies nodig om zijn query te tonen, aanbevelingen te baseren op teruggegeven records en onderscheid te maken tussen een woordmatch en een regelsinteractie. Open Identity → Main Prompt en plak de volledige prompt uit de starterkit, hieronder opnieuw weergegeven.

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.

Open nu AI Preview en verstuur:

Find Commander-legal creatures in mono-green color identity with trample, priced below 5 USD.

De demo interpreteerde geschiktheid voor een monogroen deck als groen of kleurloos. Zeg dat expliciet als je exact een groene identiteit wilt.

Lees de uitgevoerde query vóór de aanbevelingen. Die moet Commander, groen-of-kleurloze identiteit, creature-type, trample en USD onder 5 behouden. Open de Scryfall-link van één kaart en vergelijk de relevante tekst, identiteit en prijs met het antwoord. De prijs is een lookup-waarneming voor de teruggegeven printing, geen checkout-offerte.

De API-resultaten zijn geordend op naam, niet gerangschikt op geschiktheid. De agent kiest een shortlist uit de opgehaalde pagina. unique=cards voorkomt dat elke printing als apart resultaat wordt vermeld. Het betekent niet dat het geselecteerde record de goedkoopste kopie is die je kunt kopen.

Stap 4: Hoe los je een zoekopdracht op die de verkeerde interactie vindt?

Verfijn de query door een tegenvoorbeeld te lezen en de ontbrekende voorwaarde toe te voegen. Houd tijdens de verfijning het onderscheid vast tussen kandidaatkaarten vinden en hun tekst bevestigen.

Vraag:

Find green cards that draw when another creature enters, under 5 USD.

Een brede kandidaatzoekopdracht is:

f:commander id<=g o:enters o:draw usd<5

In onze directe Scryfall-controle op 10 november 2026 leverde dit 161 kandidaten op, waaronder Abundant Growth. De draw gebeurt wanneer de Aura zelf binnenkomt. De kaart bevat beide woorden, maar levert niet de herhaalbare draw-engine bij creature-entry die het verzoek suggereert.

Probeer deze verfijning:

Keep the same colors and budget. Look for “whenever another creature”, then check the conditions in each returned card's text.

De smallere query die wij controleerden was:

f:commander id<=g o:"whenever another creature" o:enters o:draw usd<5

De verfijnde zoekopdracht gaf vier kandidaten terug. Garruk’s Packleader is een nuttige voorwaardelijke match: het andere creature moet power 3 of meer hebben. Dat onderscheid hoort in de aanbeveling thuis. Een tokenstrategie met veel 1/1-creatures heeft mogelijk een andere kaart nodig.

Alleen o:"another creature" toevoegen is minder precies. Onze test vond nog steeds Disciple of Freyalise, waarvan de eigen binnenkomst ertoe kan leiden dat je een ander creature offert en een kaart trekt. Dat is nog een reden om de volledige ability te inspecteren in plaats van een extra zinsdeel als bewijs te behandelen.

Herhaal dezelfde lus voor je eigen deck: verzoek → query → kaarttekst → één verfijning. Als het budget elke bruikbare kandidaat uitsluit, vraag dan eerst voordat je het verruimt. Als een kaart een beperking heeft, noem die beperking dan in plaats van haar stilzwijgend uit de uitleg weg te laten.

Stap 5: Hoe test je de kaartzoeker voordat je hem gebruikt?

Test zowel het antwoord als de API-aanroep. Een overtuigende zin kan niet vaststellen welke query is uitgevoerd of welke records zijn teruggekomen.

1. Open Testing en maak een dataset met de naam Open Query checks via Create Dataset → Paste messages. Plak de onafhankelijke testberichten uit de kit.
2. Voer de tests uit. Beoordeel of het antwoord zijn query toont, teruggegeven kaarten citeert en onzekerheid uitlegt.
3. Open het bijbehorende gesprek in Inbox en inspecteer de Action-aanroep. Controleer de query, het paginanummer, de status en de teruggegeven velden. Gebruik de View logs-bediening van de Action om afzonderlijke aanroepen te vinden.
4. Test verfijning en paginering in een doorlopend gesprek, waarin de vorige query beschikbaar is.

Verstuur voor de test zonder match:

Find a Commander card named definitely-not-a-real-card-xyz.

Eén directe API-test liet zien waarom waarschuwingen belangrijk zijn. De ongeldige query f:commander o:/[/ gaf HTTP 200 terug, maar Scryfall meldde dat de ongeldige expressie was genegeerd. De resultaten waren daardoor breder dan gevraagd. Bewaar die waarschuwing, leg de genegeerde filter uit en corrigeer de query voordat je die resultaten aanbeveelt.

Onze lokale agentruns dekten de basislijn, verfijning, lege resultaten en een zoekopdracht van twee pagina’s. Afzonderlijke API-controles dekten ontbrekende prijzen, kaartfaces en syntaxiswaarschuwingen. Gebruik een gecontroleerde fixture om snelheidslimieten te testen zonder overmatig verkeer te versturen.

De documentatie van het kaartzoekendpoint specificeert momenteel twee zoekverzoeken per seconde. Houd minstens 500 milliseconden tussen verzoeken. Deze tutorial is een persoonlijke zoekhulp. Een publieke bot voor veel spelers heeft gedeelde snelheidsbegrenzing en caching nodig. Het model vragen om langzamer te werken dwingt geen globale verzoekslimiet af.

Kan ChatGPT of Claude helpen dit te configureren?

Je kunt de Quickchat AI-plugin voor ChatGPT of de Quickchat AI-connector voor Claude gebruiken om de agent te configureren via de accountbeheerverbinding. Rond het inloggen zelf af en geef daarna deze tutorial en de starterkit mee met het volgende verzoek:

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.

De documentatie voor accountbeheer legt de verbinding uit. Dit configureert je Quickchat AI-account. Het maakt Open Query niet automatisch beschikbaar voor andere mensen als MCP-tool.

Veelgestelde vragen

Kan ik Scryfall in natuurlijke taal doorzoeken?

Een AI-assistent kan een verzoek in gewone taal vertalen naar Scryfall-zoeksyntaxis en die uitvoeren via de Scryfall-API. Deze tutorial bouwt die assistent in Quickchat AI en laat hem de query, gekoppelde kaartrecords en relevante Oracle-tekst tonen zodat je de interpretatie kunt controleren.

Heb ik een Scryfall-API-sleutel nodig?

Nee. Het openbare kaartzoekendpoint vereist geen account of API-sleutel. Verstuur identificerende User-Agent- en Accept-headers, volg de snelheidslimieten van Scryfall en vraag extra pagina’s bewust op.

Kan deze AI-kaartzoeker een kaart hallucineren?

De instructies beperken aanbevelingen tot records die door de Action zijn teruggegeven, met Scryfall-links. Het model kan nog steeds fouten maken, dus controleer het teruggegeven ID en de Oracle-tekst, en test een onmogelijke kaartnaam voordat je op de assistent vertrouwt.

Wat is het verschil tussen id<=g en id=g op Scryfall?

id<=g omvat groene en kleurloze identiteiten, geschikt om te zoeken binnen de kleuren van een monogroene commander. id=g vereist exact een groene identiteit. Kleuridentiteit verschilt van kaartkleur. Gebruik het identiteitsfilter voor de deckconstructie van Commander.

Zijn Scryfall-prijzen gegarandeerd?

Nee. Het veld prices.usd is prijsdata van de provider voor de teruggegeven printing, geen aanbod van een verkoper. Het kan null zijn. De filter usd<5 zoekt onder vijf Amerikaanse dollar. Die stelt geen verzendkosten, beschikbaarheid of de goedkoopste koopbare printing vast.

Geeft één zoekopdracht elke overeenkomende kaart terug?

Een zoekopdracht geeft één API-pagina terug. Het antwoord bevat total_cards, has_more en, wanneer relevant, next_page. Open Query toont maximaal vijf aanbevelingen van de opgehaalde pagina. Vraag om meer van die pagina of vraag expliciet om de volgende API-pagina. Een shortlist is niet de volledige resultatenset.

Kan dit mijn volledige Commander-deck bouwen?

Deze tutorial bouwt een kaartzoekassistent. Hij helpt kandidaten voor een deckslot te vinden en te bekijken. Hij valideert geen volledig deck van 100 kaarten, optimaliseert geen decklijst en vervangt geen rules judge.