Építs AI-alapú Commander kártyakeresőt a Scryfall használatával

Egy Scryfall Commander kártyakereső a szükséges kártya leírását olyan kereséssé alakítja, amelyet megvizsgálhatsz. Ebben az útmutatóban megépíted a Open Query rendszert, egy Quickchat AI Agentet, amely megmutatja a Scryfall lekérdezését, valódi kártyarekordokat ad vissza, és elmagyarázza, miért illhet az egyes jelöltek közül bármelyik a paklidba.

Kezdj egyetlen hellyel egy monozöld Commander pakliban. Olyan lényt szeretnél, amelynek van trample képessége, és az ára öt amerikai dollár alatt van. A végére be tudod majd írni ezt a kérést, meg tudod nyitni a visszaadott kártyákat, és finomítani tudod a keresést anélkül, hogy minden operátort fejből kellene tudnod.

A hasznos rész akkor jön, amikor a kérés nehezebbé válik. A „draw when another creature enters” pontosnak hangzik, de az enters és draw szavakra keresve olyan kártyákat is találsz, amelyek valami mást csinálnak. El fogod kapni ezt az eltérést, és szűkíteni fogod a lekérdezést, a visszaadott kártyaszöveget bizonyítékként használva.

Mit fogsz megépíteni, és mire van szükséged?

Egy csak olvasható API Action kapcsolatot fogsz összekötni a Scryfall rendszerrel, megadod az Agent keresési utasításait, és egy beszélgetésben teszteled. Az Action egy rögzített URL-t hív meg. A modell egy lekérdezést és oldalszámot ad meg. A Scryfall azokat a rekordokat adja vissza, amelyekből a válasz dolgozik.

1. Hozz létre egy Quickchat AI fiókot, és egy Open Query nevű Agentet. A beszélgetésekhez és tesztekhez elérhető AI kreditekre lesz szükséged. Lásd az aktuális csomagokat.
2. Munka közben tartsd kéznél az Agent Identity, Actions & MCPs és AI Preview részeit. Nincs szükség kártyagyűjtemény feltöltésére.
3. Használd a Scryfall nyilvános API-ját. Ezekhez a keresésekhez nincs szükséged Scryfall fiókra vagy API-kulcsra.

A starter kit tartalmazza a Main Prompt elemet, az Action receptet, a response-filter útvonalakat és a tesztüzeneteket. A példák angol Oracle szöveget és USD árakat használnak. Más nyelven követve is hagyd a lekérdezési operátorokat és a kártyaneveket az eredeti írásmódban.

1. lépés: Hogyan alakítasz egy kártyakérést Scryfall lekérdezéssé?

Egy Scryfall lekérdezés szóközökkel elválasztott feltételeket kombinál. Az első kérésünkhöz ezt használd:

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

Két apró döntés számít. A kw:trample a kulcsszóra keres, a o:trample pedig a szóra az Oracle szövegben. Egy lény említheti a trample-t anélkül, hogy maga rendelkezne ezzel a képességgel. Mindkettőt teszteltük. A szöveges keresés szélesebb találati halmazt adott.

A „belefér egy monozöld pakliba” sem ugyanaz, mint a „pontosan zöld identitású”. Az előbbi megengedi a színtelen kártyákat. Az utóbbihoz használd a id=g értéket, vagy a id<=ur értéket, ha egy kék-vörös commander színein belül keresel. Ezek identity megkötések, nem teljes paklilegalitási ellenőrzések.

A Scryfall keresési szintaxis referenciája elmagyarázza ezeket az operátorokat. Ennél az útmutatónál minden válaszban tartsd láthatóan a lekérdezést, hogy észrevedd a kihagyott színt, a váratlan pénznemet vagy a kérésednél tágabb keresést.

2. lépés: Hogyan kapcsolod a Scryfall API-t az Agentedhez?

Hozz létre egy API Action elemet, amely GET kérést küld a Scryfall kártyakereső végpontjára. A rögzített beállításai kiválasztják a szolgáltatót és a rendezést. A két paramétere lehetővé teszi, hogy az Agent kiválassza a keresést és az oldalt.

1. Nyisd meg a Actions & MCPs → Add Action → API Action menüt.
2. Használd az alábbi builder kérést, majd ellenőrizd a létrehozott beállításokat a recept alapján. A API Action builder útmutató elmagyarázza a létrehozási és ellenőrzési folyamatot.
3. Állítsd a API Action Name értékét erre: 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.

A két paraméter meghatározása

A What to ask the user first alatt add hozzá ezeket a kötelező paramétereket. Az Agent ki tudja tölteni őket a beszélgetés alapján. A címke nem azt jelenti, hogy neked nyers lekérdezési szintaxist kell begépelned.

A végpont, a lekérdezési paraméterek és a fejlécek beállítása

Válaszd a GET lehetőséget, és írd be:

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

A Query Params alatt add hozzá az alábbi négy sort. A dinamikus értékekhez használd a Add AI Data lehetőséget az általad létrehozott paraméter kiválasztásához. Az alábbi {{query}} és {{page}} jelölés ezeket a paraméterchipeket jelenti.

Használd a lekérdezési paramétermezőket, hogy a szóközök, idézőjelek és operátorok paraméterértékként legyenek kódolva. A végpont URL-jét hagyd rögzítve.

A Body mezőt hagyd üresen. Nincs szükség hitelesítésre. A User-Agent egy azonosító kliensnév, nem hitelesítő adat. A saját verziód telepítésekor használd a saját megfelelő alkalmazásnevedet és kapcsolati URL-edet.

Tartsd hasznosnak a választ

Egy Scryfall-oldal sok rekordot tartalmazhat. Tartsd meg azokat a mezőket, amelyekre az Agentnek szüksége van, valamint azokat az információkat, amelyek megmondják neki, hogy vannak-e további oldalak. Nyisd le az Advanced settings részt, és keresd meg a Response filter elemet. Használd az Add JSONPath lehetőséget, majd a plusz gombot, hogy az alábbi útvonalak mindegyikét külön bejegyzésként add hozzá:

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

Tartsd meg a card_faces mezőt. Egyes kártyák a szövegüket külön oldalakon tárolják, nem felső szinten. A warnings mezőt is tartsd meg: a sikeres HTTP válasz nem jelenti azt, hogy a Scryfall minden elemet a szándékod szerint értelmezett. A Card object referencia leírja ezeket a mezőket.

A API Action Description mezőbe illeszd be ezt:

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.

Mentsd el az Actiont, és ellenőrizd, hogy aktív-e. A HTTP Action anatomy útmutató elmagyarázza, hogyan működik együtt a paraméterezés, a kérés és a leírás.

3. lépés: Hogyan magyarázza el a kártyakereső az eredményeit?

Az Agentnek olyan utasításokra van szüksége, amelyek megjelenítik a lekérdezését, a visszaadott rekordokra alapozzák az ajánlásokat, és megkülönböztetik a szóegyezést a szabályinterakciótól. Nyisd meg a Identity → Main Prompt menüt, és illeszd be a starter kit teljes promptját, amelyet alább is közlünk.

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.

Most nyisd meg a AI Preview részt, és küldd el:

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

A demó a monozöld pakliba illeszkedést zöld vagy színtelenként értelmezte. Ha pontosan zöld identitást szeretnél, mondd ki egyértelműen.

Az ajánlások előtt olvasd el a végrehajtott lekérdezést. Meg kell őriznie a Commander elemet, a zöld-vagy-színtelen identitást, a lény típust, a trample-t és az 5 alatti USD árat. Nyisd meg az egyik kártya Scryfall hivatkozását, és hasonlítsd össze a releváns szöveget, identitást és árat a válasszal. Az ár a visszaadott nyomtatásra vonatkozó lekérdezési megfigyelés, nem pénztári ajánlat.

Az API találatai név szerint vannak rendezve, nem illeszkedés szerint rangsorolva. Az Agent a lekért oldalból választ egy rövid listát. A unique=cards megakadályozza, hogy minden nyomtatás külön találatként jelenjen meg. Ez nem jelenti azt, hogy a kiválasztott rekord a legolcsóbb megvásárolható példány.

4. lépés: Hogyan javítasz ki egy keresést, amely rossz interakciót talál?

Szűkítsd a lekérdezést egy ellenpélda elolvasásával és a hiányzó feltétel hozzáadásával. A finomítás során végig tartsd meg a különbséget a jelölt kártyák megtalálása és a szövegük megerősítése között.

Kérdezd ezt:

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

Egy tág jelöltkeresés ez:

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

A 2026. november 10-i közvetlen Scryfall ellenőrzésünkben ez 161 jelöltet adott vissza, köztük a Abundant Growth lapot. Ennél a húzás akkor történik, amikor maga az Aura lép be. Mindkét szót tartalmazza, de nem adja azt az ismételhető lénybelépéses húzómotort, amelyet a kérés sugall.

Próbáld ezt a finomítást:

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

Az általunk ellenőrzött szűkebb lekérdezés ez volt:

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

A finomított keresés négy jelöltet adott vissza. A Garruk’s Packleader hasznos feltételes egyezés: a másik lénynek 3 vagy nagyobb erővel kell rendelkeznie. Ennek a különbségnek szerepelnie kell az ajánlásban. Egy sok 1/1-es lényt használó token stratégia másik kártyát igényelhet.

Csak a o:"another creature" hozzáadása kevésbé pontos. A tesztünk még mindig megtalálta a Disciple of Freyalise lapot, amelynek saját belépése oda vezethet, hogy feláldozol egy másik lényt és húzol. Ez újabb ok arra, hogy a teljes képességet vizsgáld meg, és ne kezelj egy plusz kifejezést bizonyítékként.

Ismételd meg ugyanezt a ciklust a saját paklidhoz: kérés → lekérdezés → kártyaszöveg → egy finomítás. Ha a költségkeret minden hasznos jelöltet kizár, kérdezz rá, mielőtt tágítod. Ha egy kártyának van korlátozása, mondd ki a korlátozást ahelyett, hogy csendben kihagynád a magyarázatból.

5. lépés: Hogyan teszteled a kártyakeresőt, mielőtt használni kezded?

Teszteld a választ és az API-hívást is. Egy meggyőző mondat nem bizonyítja, melyik lekérdezés futott le, vagy milyen rekordok érkeztek vissza.

1. Nyisd meg a Testing részt, és hozz létre egy Open Query checks nevű adathalmazt a Create Dataset → Paste messages használatával. Illeszd be a készletből a független tesztüzeneteket.
2. Futtasd le a teszteket. Értékeld, hogy a válasz megjeleníti-e a lekérdezését, hivatkozik-e a visszaadott kártyákra, és megmagyarázza-e a bizonytalanságot.
3. Nyisd meg a megfelelő beszélgetést a Inbox részben, és vizsgáld meg az Action hívást. Ellenőrizd a lekérdezést, az oldalszámot, az állapotot és a visszaadott mezőket. Az egyes hívások megtalálásához használd az Action View logs vezérlőjét.
4. Teszteld a finomítást és a lapozást egy folytatólagos beszélgetésben, ahol az előző lekérdezés elérhető.

A nincs találat teszthez küldd ezt:

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

Egy közvetlen API-teszt megmutatta, miért fontosak a figyelmeztetések. A hibás f:commander o:/[/ lekérdezés HTTP 200 választ adott, de a Scryfall jelezte, hogy figyelmen kívül hagyta az érvénytelen kifejezést. Az eredmények ezért tágabbak voltak a kértnél. Őrizd meg ezt a figyelmeztetést, magyarázd el a figyelmen kívül hagyott szűrőt, és javítsd a lekérdezést, mielőtt ezekből az eredményekből ajánlasz.

A helyi Agent futtatásaink lefedték az alaphelyzetet, a finomítást, az üres eredményeket és egy kétoldalas keresést. Külön API-ellenőrzések fedték le a hiányzó árakat, a kártyaoldalakat és a szintaxisfigyelmeztetéseket. A sebességkorlátozás teszteléséhez használj ellenőrzött tesztkörnyezetet, anélkül hogy túlzott forgalmat küldenél.

A kártyakereső végpont dokumentációja jelenleg másodpercenként két keresési kérést ír elő. A kérések között tarts legalább 500 milliszekundumot. Ez az útmutató személyes keresési segéd. Egy sok játékost kiszolgáló nyilvános botnak megosztott sebességkorlátozásra és gyorsítótárazásra van szüksége. Attól, hogy megkéred a modellt a lassításra, még nem lesz kikényszerítve egy globális kéréskorlát.

Segíthet a ChatGPT vagy a Claude ennek a beállításában?

Használhatod a Quickchat AI plugint ChatGPT-hez vagy a Quickchat AI csatlakozót Claude-hoz, hogy a fiókkezelési kapcsolaton keresztül beállítsd az Agentet. A bejelentkezést magad végezd el, majd add meg ezt az útmutatót és a starter kitet a következő kéréssel:

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.

A fiókkezelési dokumentáció elmagyarázza a kapcsolatot. Ez a Quickchat AI fiókodat konfigurálja. Nem teszi automatikusan elérhetővé a Open Query rendszert mások számára MCP eszközként.

Gyakran ismételt kérdések

Kereshetek Scryfall-t természetes nyelven?

Egy AI asszisztens képes egy hétköznapi nyelvű kérést Scryfall keresési szintaxissá alakítani, majd azt a Scryfall API-n keresztül végrehajtani. Ez az útmutató ezt az asszisztenst építi meg Quickchat AI alatt, és úgy alakítja ki, hogy megjelenítse a lekérdezést, a hivatkozott kártyarekordokat és a releváns Oracle szöveget, hogy ellenőrizhesd az értelmezést.

Szükségem van Scryfall API-kulcsra?

Nem. A nyilvános kártyakereső végpont nem igényel fiókot vagy API-kulcsot. Küldj azonosító User-Agent és Accept fejléceket, tartsd be a Scryfall sebességkorlátait, és tudatosan kérj további oldalakat.

Hallucinálhat ez az AI kártyakereső egy kártyát?

Az utasítások az ajánlásokat az Action által visszaadott rekordokra korlátozzák, Scryfall hivatkozásokkal. A modell azonban továbbra is hibázhat, ezért ellenőrizd a visszaadott azonosítót és Oracle szöveget, és próbálj ki egy lehetetlen kártyanevet, mielőtt az asszisztensre hagyatkozol.

Mi a különbség az id<=g és az id=g között a Scryfall esetében?

Az id<=g tartalmazza a zöld és a színtelen identitásokat, ami alkalmas egy monozöld commander színein belüli kereséshez. Az id=g pontosan zöld identitást követel meg. A color identity különbözik a kártya színétől. Commander pakliépítéshez az identity szűrőt használd.

Garantáltak a Scryfall árak?

Nem. A prices.usd mező a visszaadott nyomtatás szolgáltatói árazási adata, nem egy eladó ajánlata. Lehet null is. Az usd<5 szűrő az öt amerikai dollár alatti találatokat keresi. Nem állapít meg szállítási költséget, elérhetőséget vagy a legolcsóbban megvásárolható nyomtatást.

Egy keresés minden egyező kártyát visszaad?

Egy keresés egy API-oldalt ad vissza. A válasz tartalmazza a total_cards, has_more és, ha releváns, a next_page mezőket. A Open Query legfeljebb öt ajánlást mutat a lekért oldalról. Kérj többet erről az oldalról, vagy kifejezetten kérd a következő API-oldalt. Egy rövid lista nem a teljes találati halmaz.

Fel tudja ez építeni a teljes Commander paklimat?

Ez az útmutató egy kártyakereső asszisztenst épít. Segít jelölteket találni és megvizsgálni egy paklihelyhez. Nem ellenőriz egy teljes 100 lapos paklit, nem optimalizál paklilistát, és nem helyettesít egy szabálybírót.