Bygg en AI-Commander-kortletare med Scryfall

En Scryfall Commander-kortletare förvandlar en beskrivning av kortet du behöver till en sökning som du kan granska. I den här handledningen bygger du Open Query, en Quickchat AI Agent som visar sin Scryfall-fråga, returnerar riktiga kortposter och förklarar varför varje kandidat kan passa i din lek.

Börja med en plats i en monogrön Commander-lek. Du vill ha en varelse med trample och ett pris under fem amerikanska dollar. När du är klar kan du skriva den förfrågan, öppna de returnerade korten och förfina sökningen utan att memorera varje operator.

Det användbara kommer när förfrågan blir svårare. “Draw when another creature enters” låter precist, men en sökning efter orden enters och draw hittar också kort som gör något annat. Du kommer att fånga den felmatchningen och snäva in frågan, med den returnerade korttexten som bevis.

Vad ska du bygga, och vad behöver du?

Du kommer att koppla en skrivskyddad API Action till Scryfall, ge Agent dess sökinstruktioner och testa den i en konversation. Action anropar en fast URL. Modellen anger en fråga och ett sidnummer. Scryfall returnerar posterna som svaret bygger på.

1. Skapa ett Quickchat AI-konto och en Agent med namnet Open Query. Du behöver tillgängliga AI-krediter för konversationer och tester. Se aktuella planer.
2. Ha Agentens Identity, Actions & MCPs och AI Preview tillgängliga medan du arbetar. Ingen uppladdning av kortsamling behövs.
3. Använd Scryfalls offentliga API. Du behöver inget Scryfall-konto eller någon API-nyckel för dessa sökningar.

Startpaketet innehåller Main Prompt, Action-recept, response-filter-sökvägar och testmeddelanden. Exemplen använder engelsk Oracle-text och priser i USD. Behåll frågeoperatorerna och kortnamnen som de är skrivna när du följer med på ett annat språk.

Steg 1: Hur förvandlar du en kortförfrågan till en Scryfall-fråga?

En Scryfall-fråga kombinerar begränsningar åtskilda med mellanslag. För vår första förfrågan använder du:

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

Två små val spelar roll. kw:trample söker efter nyckelordet. o:trample söker efter ordet i Oracle-texten. En varelse kan nämna trample utan att själv ha den förmågan. Vi testade båda. Textsökningen gav en bredare uppsättning.

“Passar i en monogrön lek” skiljer sig också från “har exakt grön identitet.” Det första tillåter färglösa kort. Använd id=g för det senare, eller id<=ur för att söka inom färgerna för en blå-röd commander. Det här är identitetsbegränsningar, inte en fullständig kontroll av leklegalitet.

Scryfalls referens för söksyntax förklarar dessa operatorer. I den här handledningen ska frågan vara synlig i varje svar så att du kan upptäcka en utelämnad färg, en oväntad valuta eller en sökning som är bredare än din förfrågan.

Steg 2: Hur kopplar du Scryfall API till din Agent?

Skapa en API Action som skickar en GET-begäran till Scryfalls slutpunkt för kortsökning. Dess fasta inställningar väljer leverantör och sortering. Dess två parametrar låter Agent välja sökning och sida.

1. Öppna Actions & MCPs → Add Action → API Action.
2. Använd byggarbegäran nedan och granska sedan de genererade inställningarna mot receptet. API Action-guiden för byggaren förklarar flödet för generering och granskning.
3. Ställ in API Action Name på 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.

Definiera de två parametrarna

Under What to ask the user first lägger du till dessa obligatoriska parametrar. Agent kan fylla i dem från konversationen. Etiketten betyder inte att den måste be dig skriva rå frågesyntax.

Ange slutpunkt, frågeparametrar och rubriker

Välj GET och ange:

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

Under Query Params lägger du till de fyra raderna nedan. För de dynamiska värdena använder du Add AI Data för att välja parametern du skapade. Notationen {{query}} och {{page}} nedan representerar dessa parameterchips.

Använd fälten för frågeparametrar så att mellanslag, citationstecken och operatorer kodas som parametervärden. Behåll slutpunktens URL fast.

Lämna Body tomt. Ingen autentisering behövs. User-Agent är ett identifierande klientnamn, inte en inloggningsuppgift. Använd ditt eget lämpliga programnamn och kontakt-URL när du distribuerar din version.

Behåll svaret användbart

En Scryfall-sida kan innehålla många poster. Behåll de fält som Agent behöver, tillsammans med informationen som talar om för den om fler sidor finns. Expandera Advanced settings och hitta Response filter. Använd Add JSONPath och sedan plusknappen för att lägga till varje sökväg nedan som en separat post:

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

Behåll card_faces. Vissa kort lägger sin text på enskilda faces i stället för på toppnivån. Behåll också warnings: en lyckad HTTP-status betyder inte att Scryfall tolkade varje del som avsett. Referensen för Card object beskriver dessa fält.

I API Action Description klistrar du in:

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.

Spara Action och kontrollera att den är aktiv. Guiden till HTTP Action anatomy förklarar hur parametrarna, begäran och beskrivningen fungerar tillsammans.

Steg 3: Hur ska kortletaren förklara sina resultat?

Agent behöver instruktioner för att visa sin fråga, förankra rekommendationer i returnerade poster och skilja en ordmatchning från en regelinteraktion. Öppna Identity → Main Prompt och klistra in hela prompten från startpaketet, återgiven nedan.

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.

Öppna nu AI Preview och skicka:

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

Demot tolkade behörighet för monogrön lek som grön eller färglös. För exakt grön identitet, säg det uttryckligen.

Läs den körda frågan före rekommendationerna. Den ska bevara Commander, grön-eller-färglös identitet, varelsetyp, trample och USD under 5. Öppna ett korts Scryfall-länk och jämför relevant text, identitet och pris med svaret. Priset är en observerad uppslagning för den returnerade tryckningen, inte ett pris i kassan.

API-resultaten sorteras efter namn, inte efter hur väl de passar. Agent väljer en kortlista från den hämtade sidan. unique=cards undviker att lista varje tryckning som ett separat resultat. Det betyder inte att den valda posten är det billigaste exemplaret du kan köpa.

Steg 4: Hur rättar du en sökning som hittar fel interaktion?

Snäva in frågan genom att läsa ett motexempel och lägga till det villkor som saknas. Behåll skillnaden mellan att hitta kandidatkort och att bekräfta deras text genom hela förfiningen.

Fråga:

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

En bred kandidatsökning är:

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

I vår direkta kontroll i Scryfall den 10 november 2026 returnerade detta 161 kandidater, inklusive Abundant Growth. Dess draw sker när Auran själv kommer in. Den innehåller båda orden, men den ger inte den upprepningsbara draw-motor vid varelseinträde som förfrågan antyder.

Prova denna förfining:

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

Den smalare fråga vi kontrollerade var:

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

Den förfinade sökningen returnerade fyra kandidater. Garruk’s Packleader är en användbar villkorad matchning: den andra varelsen måste ha styrka 3 eller högre. Den skillnaden hör hemma i rekommendationen. En tokenstrategi med många 1/1-varelser kan behöva ett annat kort.

Att bara lägga till o:"another creature" är mindre precist. Vårt test hittade fortfarande Disciple of Freyalise, vars eget inträde kan leda till att du offrar en annan varelse och drar ett kort. Det är ytterligare ett skäl att granska hela förmågan i stället för att behandla en extra fras som bevis.

Upprepa samma loop för din egen lek: förfrågan → fråga → korttext → en förfining. Om budgeten tar bort alla användbara kandidater, fråga innan du breddar den. Om ett kort har en begränsning, säg begränsningen i stället för att tyst utelämna den från förklaringen.

Steg 5: Hur testar du kortletaren innan du använder den?

Testa både svaret och API-anropet. En övertygande mening kan inte fastställa vilken fråga som kördes eller vilka poster som kom tillbaka.

1. Öppna Testing och skapa en datamängd med namnet Open Query checks med Create Dataset → Paste messages. Klistra in de oberoende testmeddelandena från paketet.
2. Kör testerna. Bedöm om svaret visar sin fråga, citerar returnerade kort och förklarar osäkerhet.
3. Öppna den matchande konversationen i Inbox och granska Action-anropet. Kontrollera fråga, sidnummer, status och returnerade fält. Använd Actions kontroll View logs för att hitta enskilda anrop.
4. Testa förfining och sidindelning i en fortsatt konversation, där den tidigare frågan är tillgänglig.

För testet utan träffar, skicka:

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

Ett direkt API-test visade varför varningar spelar roll. Den felaktiga frågan f:commander o:/[/ returnerade HTTP 200, men Scryfall rapporterade att det hade ignorerat det ogiltiga uttrycket. Resultaten var därför bredare än begärt. Bevara den varningen, förklara det ignorerade filtret och rätta frågan innan du rekommenderar dessa resultat.

Våra lokala Agent-körningar täckte baslinjen, förfining, tomma resultat och en sökning över två sidor. Separata API-kontroller täckte saknade priser, kortfaces och syntaxvarningar. Använd en kontrollerad fixture för att testa hastighetsbegränsning utan att skicka överdriven trafik.

Dokumentationen för slutpunkten för kortsökning anger för närvarande två sökbegäranden per sekund. Håll minst 500 millisekunder mellan begäranden. Den här handledningen är en personlig sökhjälp. En offentlig bot som betjänar många spelare behöver delad hastighetsbegränsning och cachning. Att be modellen sakta ner upprätthåller inte en global begärandegräns.

Kan ChatGPT eller Claude hjälpa till att konfigurera detta?

Du kan använda pluginet Quickchat AI för ChatGPT eller kopplingen Quickchat AI för Claude för att konfigurera Agent via anslutningen för kontohantering. Slutför inloggningen själv och ge sedan denna handledning och dess startpaket tillsammans med följande förfrågan:

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.

Dokumentationen för kontohantering förklarar anslutningen. Detta konfigurerar ditt Quickchat AI-konto. Det gör inte automatiskt Open Query tillgängligt för andra personer som ett MCP-verktyg.

Vanliga frågor

Kan jag söka i Scryfall med naturligt språk?

En AI-assistent kan översätta en förfrågan på vanlig engelska till Scryfall-söksyntax och köra den via Scryfall API. Den här handledningen bygger den assistenten i Quickchat AI och får den att visa frågan, länkade kortposter och relevant Oracle-text så att du kan kontrollera tolkningen.

Behöver jag en Scryfall API-nyckel?

Nej. Den offentliga slutpunkten för kortsökning kräver inget konto eller någon API-nyckel. Skicka identifierande User-Agent- och Accept-rubriker, följ Scryfalls hastighetsgränser och begär fler sidor medvetet.

Kan den här AI-kortletaren hallucinera fram ett kort?

Instruktionerna begränsar rekommendationer till poster som returneras av Action, med Scryfall-länkar. Modellen kan fortfarande göra misstag, så kontrollera det returnerade ID:t och Oracle-texten, och testa ett omöjligt kortnamn innan du förlitar dig på assistenten.

Vad är skillnaden mellan id<=g och id=g på Scryfall?

id<=g inkluderar gröna och färglösa identiteter, vilket passar för att söka inom färgerna för en monogrön commander. id=g kräver exakt grön identitet. Färgidentitet skiljer sig från kortfärg. Använd identitetsfiltret för Commander-lekbygge.

Är Scryfall-priser garanterade?

Nej. Fältet prices.usd är prisdata från leverantören för den returnerade tryckningen, inte ett erbjudande från en säljare. Det kan vara null. Filtret usd<5 söker under fem amerikanska dollar. Det fastställer inte fraktkostnader, tillgänglighet eller den billigaste tryckning som går att köpa.

Returnerar en sökning alla matchande kort?

En sökning returnerar en API-sida. Svaret innehåller total_cards, has_more och, när det är relevant, next_page. Open Query visar upp till fem rekommendationer från den hämtade sidan. Be om fler från den sidan eller begär uttryckligen nästa API-sida. En kortlista är inte hela resultatmängden.

Kan detta bygga hela min Commander-lek?

Den här handledningen bygger en assistent för kortsökning. Den hjälper dig att hitta och granska kandidater för en plats i leken. Den validerar inte en fullständig lek med 100 kort, optimerar inte en kortlista och ersätter inte en domare.