Vytvorte AI vyhľadávač kariet Commander pomocou Scryfall

Vyhľadávač kariet Scryfall Commander premení opis karty, ktorú potrebujete, na vyhľadávanie, ktoré si môžete prezrieť. V tomto návode vytvoríte Open Query, Agenta Quickchat AI, ktorý zobrazuje svoj dopyt Scryfall, vracia skutočné záznamy kariet a vysvetľuje, prečo by každý kandidát mohol pasovať do vášho balíka.

Začnite jedným miestom v mono-zelenom balíku Commander. Chcete bytosť s trample a cenou pod päť amerických dolárov. Na konci budete môcť zadať túto požiadavku, otvoriť vrátené karty a spresniť vyhľadávanie bez toho, aby ste si museli pamätať každý operátor.

Užitočná časť prichádza, keď je požiadavka zložitejšia. „Lízni, keď vstúpi iná bytosť“ znie presne, ale vyhľadávanie slov enters a draw nájde aj karty, ktoré robia niečo iné. Zachytíte tento nesúlad a zúžite dopyt, pričom ako dôkaz použijete vrátený text kariet.

Čo vytvoríte a čo potrebujete?

Pripojíte jednu read-only API Action k Scryfall, dáte Agentovi pokyny na vyhľadávanie a otestujete ho v konverzácii. Akcia volá pevnú URL. Model dodáva dopyt a číslo stránky. Scryfall vracia záznamy, z ktorých odpoveď vychádza.

1. Vytvorte si účet Quickchat AI a Agenta s názvom Open Query. Na konverzácie a testy potrebujete dostupné AI kredity. Pozrite si aktuálne plány.
2. Počas práce majte k dispozícii Identity, Actions & MCPs a AI Preview Agenta. Nie je potrebné nahrávať zbierku kariet.
3. Použite verejné API služby Scryfall. Na tieto vyhľadávania nepotrebujete účet ani API kľúč Scryfall.

Štartovací balík obsahuje Main Prompt, recept Akcie, cesty filtrov odpovede a testovacie správy. Príklady používajú anglický Oracle text a ceny v USD. Pri sledovaní návodu v inom jazyku ponechajte operátory dopytu a názvy kariet tak, ako sú napísané.

Krok 1: Ako premeníte požiadavku na kartu na dopyt Scryfall?

Dopyt Scryfall kombinuje obmedzenia oddelené medzerami. Pre našu prvú požiadavku použite:

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

Na dvoch malých voľbách záleží. kw:trample vyhľadáva kľúčové slovo. o:trample vyhľadáva slovo v Oracle texte. Bytosť môže spomínať trample bez toho, aby túto schopnosť sama mala. Otestovali sme oboje. Textové vyhľadávanie vrátilo širšiu množinu.

„Hodí sa do mono-zeleného balíka“ sa tiež líši od „má presne zelenú identitu“. Prvé povoľuje bezfarebné karty. Pre druhé použite id=g alebo id<=ur na vyhľadávanie v rámci farieb modro-červeného commandera. Ide o obmedzenia identity, nie o úplnú kontrolu legality balíka.

Referenčný prehľad syntaxe vyhľadávania služby Scryfall search syntax reference vysvetľuje tieto operátory. V tomto návode nechajte dopyt viditeľný v každej odpovedi, aby ste si všimli vynechanú farbu, neočakávanú menu alebo vyhľadávanie, ktoré je širšie než vaša požiadavka.

Krok 2: Ako pripojíte API Scryfall k svojmu Agentovi?

Vytvorte jednu API Action, ktorá odošle požiadavku GET na endpoint vyhľadávania kariet služby Scryfall. Jej pevné nastavenia vyberajú poskytovateľa a poradie. Jej dva parametre umožňujú Agentovi vybrať vyhľadávanie a stránku.

1. Otvorte Actions & MCPs → Add Action → API Action.
2. Použite nižšie uvedenú požiadavku pre builder a potom skontrolujte vygenerované nastavenia podľa receptu. Sprievodca builderom API Action vysvetľuje postup generovania a kontroly.
3. Nastavte API Action Name na 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.

Definujte dva parametre

V časti What to ask the user first pridajte tieto povinné parametre. Agent ich môže vyplniť z konverzácie. Označenie neznamená, že vás musí požiadať o zadanie surovej syntaxe dopytu.

Nastavte endpoint, parametre dopytu a hlavičky

Vyberte GET a zadajte:

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

V časti Query Params pridajte štyri riadky nižšie. Pri dynamických hodnotách použite Add AI Data na výber parametra, ktorý ste vytvorili. Zápis {{query}} a {{page}} nižšie predstavuje tieto čipy parametrov.

Použite polia parametrov dopytu, aby sa medzery, úvodzovky a operátory kódovali ako hodnoty parametrov. URL endpointu ponechajte pevnú.

Pole Body nechajte prázdne. Nie je potrebná žiadna autentifikácia. User-Agent je identifikačný názov klienta, nie prihlasovací údaj. Pri nasadení svojej verzie použite vlastný vhodný názov aplikácie a kontaktnú URL.

Zachovajte užitočnosť odpovede

Stránka Scryfall môže obsahovať mnoho záznamov. Ponechajte polia, ktoré Agent potrebuje, spolu s informáciou, ktorá mu hovorí, či existujú ďalšie stránky. Rozbaľte Advanced settings a nájdite Response filter. Použite Add JSONPath a potom tlačidlo plus na pridanie každej nižšie uvedenej cesty ako samostatnej položky:

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

Ponechajte card_faces. Niektoré karty majú svoj text na jednotlivých stranách namiesto najvyššej úrovne. Ponechajte aj warnings: úspech HTTP neznamená, že Scryfall interpretoval každú časť presne podľa zámeru. Referenčný popis objektu Card opisuje tieto polia.

Do poľa API Action Description vložte:

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.

Uložte Akciu a skontrolujte, či je aktívna. Sprievodca anatómiou HTTP Action vysvetľuje, ako spolu fungujú parametre, požiadavka a popis.

Krok 3: Ako má vyhľadávač kariet vysvetľovať svoje výsledky?

Agent potrebuje pokyny, aby zobrazoval svoj dopyt, opieral odporúčania o vrátené záznamy a rozlišoval medzi zhodou slov a interakciou podľa pravidiel. Otvorte Identity → Main Prompt a vložte kompletný prompt zo štartovacieho balíka, reprodukovaný nižšie.

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.

Teraz otvorte AI Preview a odošlite:

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

Ukážka interpretovala vhodnosť pre mono-zelený balík ako zelenú alebo bezfarebnú. Ak chcete presne zelenú identitu, povedzte to výslovne.

Pred odporúčaniami si prečítajte vykonaný dopyt. Mal by zachovať Commander, zelenú alebo bezfarebnú identitu, typ bytosť, trample a cenu v USD pod 5. Otvorte odkaz Scryfall jednej karty a porovnajte relevantný text, identitu a cenu s odpoveďou. Cena je pozorovanie z vyhľadania pre vrátený printing, nie cenová ponuka pri nákupe.

Výsledky API sú zoradené podľa názvu, nie podľa vhodnosti. Agent vyberá krátky zoznam z načítanej stránky. unique=cards zabraňuje tomu, aby bol každý printing uvedený ako samostatný výsledok. Neznamená to, že vybraný záznam je najlacnejšia kópia, ktorú si môžete kúpiť.

Krok 4: Ako opravíte vyhľadávanie, ktoré nájde nesprávnu interakciu?

Zúžte dopyt tak, že si prečítate proti-príklad a pridáte chýbajúcu podmienku. Počas celého spresňovania zachovajte rozdiel medzi hľadaním kandidátnych kariet a potvrdzovaním ich textu.

Spýtajte sa:

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

Široké vyhľadávanie kandidátov je:

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

Pri našej priamej kontrole Scryfall z 10. novembra 2026 to vrátilo 161 kandidátov vrátane Abundant Growth. Jeho lízanie nastáva, keď vstúpi samotná Aura. Obsahuje obe slová, ale neposkytuje opakovateľný engine lízania pri vstupe bytosti, ktorý požiadavka naznačuje.

Skúste toto spresnenie:

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

Užší dopyt, ktorý sme overili, bol:

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

Spresnené vyhľadávanie vrátilo štyroch kandidátov. Garruk’s Packleader je užitočná podmienená zhoda: druhá bytosť musí mať silu 3 alebo viac. Tento rozdiel má patriť do odporúčania. Tokenová stratégia s množstvom bytostí 1/1 môže potrebovať inú kartu.

Pridanie samotného o:"another creature" je menej presné. Náš test stále našiel Disciple of Freyalise, ktorého vlastný vstup vás môže priviesť k obetovaniu inej bytosti a líznutiu karty. To je ďalší dôvod, prečo kontrolovať celú schopnosť namiesto toho, aby sa dodatočná fráza považovala za dôkaz.

Rovnaký cyklus zopakujte pre svoj vlastný balík: požiadavka → dopyt → text karty → jedno spresnenie. Ak rozpočet vyradí všetkých užitočných kandidátov, spýtajte sa skôr, než ho rozšírite. Ak má karta obmedzenie, uveďte toto obmedzenie namiesto toho, aby ste ho potichu vynechali z vysvetlenia.

Krok 5: Ako otestujete vyhľadávač kariet pred použitím?

Testujte odpoveď aj volanie API. Presvedčivá veta nemôže potvrdiť, ktorý dopyt sa spustil ani ktoré záznamy sa vrátili.

1. Otvorte Testing a vytvorte dataset s názvom Open Query checks pomocou Create Dataset → Paste messages. Vložte nezávislé testovacie správy zo sady.
2. Spustite testy. Hodnoťte, či odpoveď zobrazuje svoj dopyt, cituje vrátené karty a vysvetľuje neistotu.
3. Otvorte zodpovedajúcu konverzáciu v Inbox a skontrolujte volanie Akcie. Overte dopyt, číslo stránky, stav a vrátené polia. Na nájdenie jednotlivých volaní použite ovládací prvok Akcie View logs.
4. Otestujte spresňovanie a stránkovanie v pokračujúcej konverzácii, kde je predchádzajúci dopyt k dispozícii.

Pre test bez zhody odošlite:

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

Jeden priamy test API ukázal, prečo sú upozornenia dôležité. Chybný dopyt f:commander o:/[/ vrátil HTTP 200, ale Scryfall oznámil, že neplatný výraz ignoroval. Výsledky preto boli širšie, než sa požadovalo. Toto upozornenie zachovajte, vysvetlite ignorovaný filter a opravte dopyt skôr, než tieto výsledky odporučíte.

Naše lokálne spustenia Agenta pokryli základ, spresnenie, prázdne výsledky a dvojstranové vyhľadávanie. Samostatné kontroly API pokryli chýbajúce ceny, strany kariet a upozornenia na syntax. Na testovanie limitu rýchlosti použite kontrolovaný fixture bez posielania nadmernej prevádzky.

Dokumentácia endpointu na vyhľadávanie kariet momentálne uvádza dve vyhľadávacie požiadavky za sekundu. Medzi požiadavkami zachovajte aspoň 500 milisekúnd. Tento návod je osobný pomocník na vyhľadávanie. Verejný bot pre mnohých hráčov potrebuje zdieľané obmedzovanie rýchlosti a cache. Požiadanie modelu, aby spomalil, nevynucuje globálny limit požiadaviek.

Môže s konfiguráciou pomôcť ChatGPT alebo Claude?

Na konfiguráciu Agenta môžete použiť plugin Quickchat AI pre ChatGPT alebo connector Quickchat AI pre Claude cez pripojenie na správu účtu. Prihlásenie dokončite sami a potom tomuto návodu a jeho štartovaciemu balíku pridajte nasledujúcu požiadavku:

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.

Dokumentácia správy účtu vysvetľuje toto pripojenie. Týmto sa konfiguruje váš účet Quickchat AI. Neznamená to, že sa Open Query automaticky sprístupní iným ľuďom ako nástroj MCP.

Často kladené otázky

Môžem vyhľadávať Scryfall prirodzeným jazykom?

AI asistent dokáže preložiť požiadavku v bežnom jazyku do syntaxe vyhľadávania Scryfall a vykonať ju cez API Scryfall. Tento návod vytvorí tohto asistenta v Quickchat AI a zabezpečí, aby zobrazoval dopyt, prepojené záznamy kariet a relevantný Oracle text, takže si môžete overiť interpretáciu.

Potrebujem API kľúč Scryfall?

Nie. Verejný endpoint na vyhľadávanie kariet nevyžaduje účet ani API kľúč. Posielajte identifikačné hlavičky User-Agent a Accept, dodržiavajte limity rýchlosti služby Scryfall a ďalšie stránky vyžadujte zámerne.

Môže si tento AI vyhľadávač kariet vymyslieť kartu?

Pokyny obmedzujú odporúčania na záznamy vrátené Akciou, s odkazmi Scryfall. Model sa však stále môže mýliť, preto predtým, než sa na asistenta spoľahnete, skontrolujte vrátené ID a Oracle text a otestujte nemožný názov karty.

Aký je rozdiel medzi id<=g a id=g na Scryfall?

id<=g zahŕňa zelenú aj bezfarebné identity, čo je vhodné na vyhľadávanie v rámci farieb mono-zeleného commandera. id=g vyžaduje presne zelenú identitu. Farebná identita sa líši od farby karty. Pri stavbe balíka Commander používajte filter identity.

Sú ceny Scryfall zaručené?

Nie. Pole prices.usd je cenový údaj poskytovateľa pre vrátený printing, nie ponuka predajcu. Môže byť null. Filter usd<5 vyhľadáva pod piatimi americkými dolármi. Nestanovuje náklady na dopravu, dostupnosť ani najlacnejší kúpiteľný printing.

Vráti jedno vyhľadávanie každú zodpovedajúcu kartu?

Vyhľadávanie vráti jednu stránku API. Odpoveď obsahuje total_cards, has_more a podľa potreby aj next_page. Open Query zobrazuje až päť odporúčaní z načítanej stránky. Požiadajte o ďalšie z tejto stránky alebo výslovne vyžiadajte ďalšiu stránku API. Krátky výber nie je úplná množina výsledkov.

Môže mi toto zostaviť celý balík Commander?

Tento návod vytvára asistenta na vyhľadávanie kariet. Pomáha nájsť a preskúmať kandidátov na miesto v balíku. Neoveruje kompletný 100-kartový balík, neoptimalizuje decklist ani nenahrádza rozhodcu pravidiel.