Byg en AI-Commander kortfinder med Scryfall

En Scryfall Commander kortfinder omsætter en beskrivelse af det kort, du har brug for, til en søgning, du kan undersøge. I denne vejledning bygger du Open Query, en Quickchat AI Agent, der viser sin Scryfall forespørgsel, returnerer rigtige kortposter og forklarer, hvorfor hver kandidat kan passe til dit deck.

Start med én plads i et monogrønt Commander deck. Du vil have en creature med trample og en pris under fem amerikanske dollars. Når du er færdig, kan du skrive den forespørgsel, åbne de returnerede kort og forfine søgningen uden at skulle huske alle operatorerne.

Den nyttige del kommer, når forespørgslen bliver sværere. “Draw when another creature enters” lyder præcist, men en søgning efter ordene enters og draw finder også kort, der gør noget andet. Du vil opfange den uoverensstemmelse og indsnævre forespørgslen ved at bruge den returnerede korttekst som bevis.

Hvad bygger du, og hvad har du brug for?

Du forbinder én skrivebeskyttet API Action til Scryfall, giver Agenten dens søgeinstruktioner og tester den i en samtale. Handlingen kalder en fast URL. Modellen leverer en forespørgsel og et sidenummer. Scryfall returnerer de poster, som svaret bygger på.

1. Opret en Quickchat AI konto og en Agent med navnet Open Query. Du skal have tilgængelige AI-kreditter til samtaler og tests. Se de aktuelle planer.
2. Hold Agentens Identity, Actions & MCPs og AI Preview tilgængelige, mens du arbejder. Der er ikke behov for upload af kortsamling.
3. Brug Scryfalls offentlige API. Du behøver ikke en Scryfall konto eller API-nøgle til disse søgninger.

Startpakken indeholder Main Prompt, opskriften på handlingen, response-filter-stier og testbeskeder. Eksemplerne bruger engelsk Oracle-tekst og USD-priser. Behold forespørgselsoperatorerne og kortnavnene som skrevet, når du følger med på et andet sprog.

Trin 1: Hvordan omsætter du en kortforespørgsel til en Scryfall forespørgsel?

En Scryfall forespørgsel kombinerer begrænsninger adskilt af mellemrum. Til vores første forespørgsel skal du bruge:

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

To små valg betyder noget. kw:trample søger efter nøgleordet. o:trample søger efter ordet i Oracle-tekst. En creature kan nævne trample uden selv at have den evne. Vi testede begge dele. Tekstsøgningen gav et bredere sæt.

“Passer i et monogrønt deck” er også forskelligt fra “har præcis grøn identitet.” Det første tillader farveløse kort. Brug id=g til det sidste, eller id<=ur til at søge inden for en blå-rød commanders farver. Det er identitetsbegrænsninger, ikke et komplet tjek af decklovlighed.

Scryfalls reference til søgesyntaks forklarer disse operatorer. I denne vejledning skal du holde forespørgslen synlig i hvert svar, så du kan opdage en udeladt farve, en uventet valuta eller en søgning, der er bredere end din forespørgsel.

Trin 2: Hvordan forbinder du Scryfall API’et til din Agent?

Opret én API Action, der sender en GET forespørgsel til Scryfalls kortsøgnings-endpoint. Dens faste indstillinger vælger udbyder og sortering. Dens to parametre lader Agenten vælge søgningen og siden.

1. Åbn Actions & MCPs → Add Action → API Action.
2. Brug builder-forespørgslen nedenfor, og gennemgå derefter de genererede indstillinger i forhold til opskriften. API Action builder-guiden forklarer genererings- og gennemgangsforløbet.
3. Sæt API Action Name til 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.

Definér de to parametre

Under What to ask the user first skal du tilføje disse påkrævede parametre. Agenten kan udfylde dem ud fra samtalen. Etiketten betyder ikke, at den skal bede dig om at skrive rå forespørgselssyntaks.

Indstil endpoint, forespørgselsparametre og headere

Vælg GET og indtast:

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

Under Query Params skal du tilføje de fire rækker nedenfor. Til de dynamiske værdier skal du bruge Add AI Data til at vælge den parameter, du oprettede. Notationen {{query}} og {{page}} nedenfor repræsenterer disse parameterchips.

Brug felterne til forespørgselsparametre, så mellemrum, anførselstegn og operatorer kodes som parameterværdier. Hold endpoint-URL’en fast.

Lad Body være tom. Der er ikke brug for autentificering. User-Agent er et identificerende klientnavn, ikke en legitimationsoplysning. Brug dit eget passende applikationsnavn og kontakt-URL, når du udruller din version.

Bevar et nyttigt svar

En Scryfall-side kan indeholde mange poster. Behold de felter, som Agent har brug for, sammen med de oplysninger, der fortæller den, om der findes flere sider. Udvid Advanced settings og find Response filter. Brug Add JSONPath og derefter plusknappen til at tilføje hver sti nedenfor 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

Behold card_faces. Nogle kort placerer deres tekst på individuelle faces i stedet for på øverste niveau. Behold også warnings: en vellykket HTTP-status betyder ikke, at Scryfall fortolkede hvert led som tilsigtet. Referencen til Card object beskriver disse felter.

I API Action Description skal du indsætte:

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.

Gem handlingen, og kontroller, at den er aktiv. Guiden HTTP Action anatomy forklarer, hvordan parametrene, forespørgslen og beskrivelsen arbejder sammen.

Trin 3: Hvordan bør kortfinderen forklare sine resultater?

Agenten har brug for instruktioner til at vise sin forespørgsel, forankre anbefalinger i returnerede poster og skelne mellem et ordmatch og en regelinteraktion. Åbn Identity → Main Prompt og indsæt den komplette prompt fra startpakken, gengivet nedenfor.

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.

Åbn nu AI Preview og send:

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

Demoen fortolkede monogrøn decklovlighed som grøn eller farveløs. Hvis du vil have præcis grøn identitet, så sig det udtrykkeligt.

Læs den udførte forespørgsel før anbefalingerne. Den bør bevare Commander, grøn-eller-farveløs identitet, creature-type, trample og USD under 5. Åbn ét korts Scryfall link, og sammenlign den relevante tekst, identitet og pris med svaret. Prisen er en opslagobservation for det returnerede tryk, ikke et tilbud ved checkout.

API-resultaterne er sorteret efter navn, ikke rangeret efter egnethed. Agenten vælger en kortliste fra den hentede side. unique=cards undgår at liste hvert tryk som et separat resultat. Det betyder ikke, at den valgte post er det billigste eksemplar, du kan købe.

Trin 4: Hvordan retter du en søgning, der finder den forkerte interaktion?

Indsnævr forespørgslen ved at læse et modeksempel og tilføje den manglende betingelse. Bevar skellet mellem at finde kandidatkort og at bekræfte deres tekst gennem hele forfinelsen.

Spørg:

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

En bred kandidatsøgning er:

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

I vores direkte Scryfall kontrol den 10. november 2026 returnerede dette 161 kandidater, inklusive Abundant Growth. Dets draw sker, når Auraen selv kommer ind. Det indeholder begge ord, men det giver ikke den gentagelige creature-entry draw-motor, som forespørgslen antyder.

Prøv denne forfinelse:

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

Den smallere forespørgsel, vi kontrollerede, var:

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

Den forfinede søgning returnerede fire kandidater. Garruk’s Packleader er et nyttigt betinget match. Den anden creature skal have power 3 eller højere. Den forskel hører med i anbefalingen. En token-strategi med mange 1/1 creatures kan have brug for et andet kort.

At tilføje kun o:"another creature" er mindre præcist. Vores test fandt stadig Disciple of Freyalise, hvis egen indgang kan få dig til at ofre en anden creature og draw. Det er endnu en grund til at undersøge hele evnen i stedet for at behandle en ekstra frase som bevis.

Gentag den samme løkke for dit eget deck: forespørgsel → query → korttekst → én forfinelse. Hvis budgettet fjerner alle nyttige kandidater, så spørg, før du udvider det. Hvis et kort har en begrænsning, så nævn begrænsningen i stedet for stille og roligt at udelade den fra forklaringen.

Trin 5: Hvordan tester du kortfinderen, før du bruger den?

Test både svaret og API-kaldet. En overbevisende sætning kan ikke fastslå, hvilken forespørgsel der blev kørt, eller hvilke poster der kom tilbage.

1. Åbn Testing og opret et datasæt med navnet Open Query checks ved hjælp af Create Dataset → Paste messages. Indsæt de uafhængige testbeskeder fra pakken.
2. Kør testene. Vurder, om svaret viser sin forespørgsel, citerer returnerede kort og forklarer usikkerhed.
3. Åbn den matchende samtale i Inbox, og undersøg handlingskaldet. Tjek forespørgslen, sidenummeret, status og returnerede felter. Brug handlingens kontrol View logs til at finde individuelle kald.
4. Test forfinelse og paginering i en fortsat samtale, hvor den tidligere forespørgsel er tilgængelig.

Til testen uden match skal du sende:

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

Én direkte API-test viste, hvorfor advarsler betyder noget. Den fejlformede forespørgsel f:commander o:/[/ returnerede HTTP 200, men Scryfall rapporterede, at den havde ignoreret det ugyldige udtryk. Resultaterne var derfor bredere end ønsket. Bevar den advarsel, forklar det ignorerede filter, og ret forespørgslen, før du anbefaler de resultater.

Vores lokale Agent-kørsler dækkede grundforløbet, forfinelse, tomme resultater og en søgning på to sider. Separate API-kontroller dækkede manglende priser, kortfaces og syntaksadvarsler. Brug et kontrolleret fixture til at teste hastighedsbegrænsning uden at sende for meget trafik.

Dokumentationen til kortsøgnings-endpointet angiver i øjeblikket to søgeforespørgsler pr. sekund. Hold mindst 500 millisekunder mellem forespørgslerne. Denne vejledning er en personlig søgehjælper. En offentlig bot, der betjener mange spillere, har brug for delt hastighedsbegrænsning og caching. At bede modellen om at sætte farten ned håndhæver ikke en global forespørgselsgrænse.

Kan ChatGPT eller Claude hjælpe med at konfigurere dette?

Du kan bruge Quickchat AI plugin til ChatGPT eller Quickchat AI connector til Claude til at konfigurere Agenten gennem forbindelsen til kontoadministration. Gennemfør selv login, og giv derefter denne vejledning og dens startpakke med følgende forespørgsel:

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 til kontoadministration forklarer forbindelsen. Dette konfigurerer din Quickchat AI konto. Det gør ikke automatisk Open Query tilgængelig for andre som et MCP-værktøj.

Ofte stillede spørgsmål

Kan jeg søge i Scryfall med naturligt sprog?

En AI-assistent kan oversætte en forespørgsel i almindeligt sprog til Scryfall søgesyntaks og køre den gennem Scryfall API’et. Denne vejledning bygger den assistent i Quickchat AI og får den til at vise forespørgslen, linkede kortposter og relevant Oracle-tekst, så du kan kontrollere fortolkningen.

Har jeg brug for en Scryfall API-nøgle?

Nej. Det offentlige kortsøgnings-endpoint kræver ikke en konto eller API-nøgle. Send identificerende User-Agent og Accept-headere, følg Scryfalls hastighedsgrænser, og anmod bevidst om ekstra sider.

Kan denne AI-kortfinder hallucinere et kort?

Instruktionerne begrænser anbefalinger til poster returneret af handlingen, med Scryfall links. Modellen kan stadig tage fejl, så tjek det returnerede ID og Oracle-tekst, og test et umuligt kortnavn, før du stoler på assistenten.

Hvad er forskellen på id<=g og id=g på Scryfall?

id<=g inkluderer grønne og farveløse identiteter, hvilket er velegnet til søgning inden for en monogrøn commanders farver. id=g kræver præcis grøn identitet. Farveidentitet er forskellig fra kortfarve. Brug identitetsfilteret til Commander deckbygning.

Er Scryfall priser garanterede?

Nej. Feltet prices.usd er prisdata fra udbyderen for det returnerede tryk, ikke et tilbud fra en sælger. Det kan være null. Filteret usd<5 søger under fem amerikanske dollars. Det fastslår ikke fragtomkostninger, tilgængelighed eller det billigste tryk, der kan købes.

Returnerer én søgning alle matchende kort?

En søgning returnerer én API-side. Svaret inkluderer total_cards, has_more og, når det er relevant, next_page. Open Query viser op til fem anbefalinger fra den hentede side. Bed om flere fra den side, eller anmod udtrykkeligt om den næste API-side. En kortliste er ikke det komplette resultatsæt.

Kan dette bygge hele mit Commander deck?

Denne vejledning bygger en kortsøgningsassistent. Den hjælper med at finde og undersøge kandidater til en plads i et deck. Den validerer ikke et komplet deck på 100 kort, optimerer ikke en deckliste og erstatter ikke en dommer i reglerne.