Vytvořte AI vyhledávač karet Commander pomocí Scryfall

Vyhledávač karet Scryfall Commander převádí popis karty, kterou potřebujete, na hledání, které si můžete prohlédnout. V tomto návodu vytvoříte Open Query, Agenta Quickchat AI, který zobrazuje svůj dotaz Scryfall, vrací skutečné záznamy karet a vysvětluje, proč by každý kandidát mohl do vašeho balíčku zapadnout.

Začněte jedním slotem v monozeleném balíčku Commander. Chcete bytost s trample a cenou pod pět amerických dolarů. Na konci budete moci tento požadavek napsat, otevřít vrácené karty a zpřesnit hledání bez nutnosti pamatovat si každý operátor.

Užitečná část přichází, když je požadavek složitější. „Lízni, když vstoupí jiná bytost“ zní přesně, ale hledání slov enters a draw najde i karty, které dělají něco jiného. Tento nesoulad zachytíte a dotaz zúžíte, přičemž jako důkaz použijete vrácený text karet.

Co budete vytvářet a co k tomu potřebujete?

Připojíte jednu read-only API Action k Scryfall, dáte Agentovi instrukce pro hledání a otestujete ho v konverzaci. Akce volá pevnou URL. Model dodává dotaz a číslo stránky. Scryfall vrací záznamy, ze kterých odpověď vychází.

1. Vytvořte si účet Quickchat AI a Agenta s názvem Open Query. Pro konverzace a testy potřebujete dostupné AI kredity. Viz aktuální tarify.
2. Při práci mějte k dispozici Identity, Actions & MCPs a AI Preview Agenta. Není potřeba nahrávat sbírku karet.
3. Použijte veřejné API Scryfall. Pro tato hledání nepotřebujete účet ani API klíč Scryfall.

Startovací sada obsahuje Main Prompt, recept Akce, cesty filtru odpovědi a testovací zprávy. Příklady používají anglický Oracle text a ceny v USD. Pokud postupujete v jiném jazyce, ponechte operátory dotazu a názvy karet tak, jak jsou napsané.

Krok 1: Jak převedete požadavek na kartu na dotaz Scryfall?

Dotaz Scryfall kombinuje omezení oddělená mezerami. Pro náš první požadavek použijte:

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

Na dvou drobných volbách záleží. kw:trample hledá klíčové slovo. o:trample hledá slovo v Oracle textu. Bytost může trample zmiňovat, aniž by tuto schopnost sama měla. Otestovali jsme obojí. Hledání v textu vrátilo širší sadu.

„Vejde se do monozeleného balíčku“ se také liší od „má přesně zelenou identitu“. První možnost povoluje bezbarvé karty. Pro druhou použijte id=g, nebo id<=ur pro hledání v barvách modro červeného commandera. Jde o omezení barevné identity, nikoli o úplnou kontrolu legality balíčku.

Referenční přehled syntaxe hledání od Scryfall search syntax reference tyto operátory vysvětluje. Pro tento návod ponechte dotaz viditelný v každé odpovědi, abyste si všimli chybějící barvy, nečekané měny nebo hledání, které je širší než váš požadavek.

Krok 2: Jak připojíte API Scryfall ke svému Agentovi?

Vytvořte jednu API Action, která odešle požadavek GET na endpoint pro vyhledávání karet od Scryfall. Její pevná nastavení vybírají poskytovatele a řazení. Její dva parametry umožňují Agentovi zvolit hledání a stránku.

1. Otevřete Actions & MCPs → Add Action → API Action.
2. Použijte níže uvedený požadavek pro builder a potom porovnejte vygenerovaná nastavení s receptem. Průvodce builderem API Action vysvětluje postup generování 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 parametry

V části What to ask the user first přidejte tyto povinné parametry. Agent je může vyplnit z konverzace. Označení neznamená, že vás musí požádat o zadání syrové syntaxe dotazu.

Nastavte endpoint, parametry dotazu a hlavičky

Vyberte GET a zadejte:

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

V části Query Params přidejte čtyři řádky níže. Pro dynamické hodnoty použijte Add AI Data k výběru parametru, který jste vytvořili. Zápis {{query}} a {{page}} níže představuje tyto čipy parametrů.

Použijte pole parametrů dotazu, aby se mezery, uvozovky a operátory kódovaly jako hodnoty parametrů. URL endpointu ponechte pevnou.

Pole Body nechte prázdné. Není potřeba žádné ověřování. User-Agent je identifikační název klienta, nikoli přihlašovací údaj. Při nasazení své verze použijte vlastní vhodný název aplikace a kontaktní URL.

Udržte odpověď užitečnou

Stránka Scryfall může obsahovat mnoho záznamů. Ponechte pole, která Agent potřebuje, spolu s informací, která mu říká, zda existují další stránky. Rozbalte Advanced settings a najděte Response filter. Pomocí Add JSONPath a poté tlačítka plus přidejte každou níže uvedenou cestu jako samostatnou položku:

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

Ponechte card_faces. Některé karty mají text na jednotlivých stranách místo na nejvyšší úrovni. Ponechte také warnings: úspěch HTTP neznamená, že Scryfall vyložil každou část přesně tak, jak bylo zamýšleno. Referenční přehled objektu Card tato pole popisuje.

Do 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 Akci a zkontrolujte, že je aktivní. Průvodce anatomií HTTP Action vysvětluje, jak spolu fungují parametry, požadavek a popis.

Krok 3: Jak by měl vyhledávač karet vysvětlovat své výsledky?

Agent potřebuje instrukce, aby zobrazoval svůj dotaz, opíral doporučení o vrácené záznamy a rozlišoval mezi shodou slov a interakcí podle pravidel. Otevřete Identity → Main Prompt a vložte kompletní prompt ze startovací sady, znovu uvedený níže.

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.

Nyní otevřete AI Preview a odešlete:

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

Ukázka vyložila způsobilost pro monozelený balíček jako zelenou nebo bezbarvou. Pokud chcete přesně zelenou identitu, řekněte to výslovně.

Před doporučeními si přečtěte provedený dotaz. Měl by zachovat Commander, zelenou nebo bezbarvou identitu, typ bytost, trample a USD pod 5. Otevřete odkaz Scryfall u jedné karty a porovnejte relevantní text, identitu a cenu s odpovědí. Cena je pozorování z vyhledání pro vrácený print, nikoli nabídka při placení.

Výsledky API jsou řazené podle názvu, nikoli podle vhodnosti. Agent vybírá krátký seznam z načtené stránky. unique=cards zabraňuje tomu, aby byl každý print uveden jako samostatný výsledek. Neznamená to, že vybraný záznam je nejlevnější kopie, kterou můžete koupit.

Krok 4: Jak opravíte hledání, které najde špatnou interakci?

Zúžte dotaz tím, že si přečtete protipříklad a přidáte chybějící podmínku. Po celou dobu zpřesňování zachovejte rozdíl mezi hledáním kandidátních karet a potvrzením jejich textu.

Zeptejte se:

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

Široké hledání kandidátů je:

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

Při naší přímé kontrole Scryfall dne 10. listopadu 2026 to vrátilo 161 kandidátů, včetně Abundant Growth. K líznutí dochází, když vstoupí samotná Aura. Obsahuje obě slova, ale neposkytuje opakovatelný engine lízání při vstupu bytostí, který požadavek naznačuje.

Zkuste toto zpřesnění:

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

Užší dotaz, který jsme ověřili, byl:

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

Zpřesněné hledání vrátilo čtyři kandidáty. Garruk’s Packleader je užitečná podmíněná shoda. Druhá bytost musí mít sílu 3 nebo vyšší. Tento rozdíl má být uveden v doporučení. Token strategie se spoustou bytostí 1/1 může potřebovat jinou kartu.

Přidání samotného o:"another creature" je méně přesné. Náš test stále našel Disciple of Freyalise, jehož vlastní vstup vás může dovést k obětování jiné bytosti a líznutí karty. To je další důvod, proč kontrolovat celou schopnost, místo abyste další frázi brali jako důkaz.

Stejný cyklus zopakujte pro svůj vlastní balíček: požadavek → dotaz → text karty → jedno zpřesnění. Pokud rozpočet odstraní všechny užitečné kandidáty, zeptejte se dřív, než ho rozšíříte. Pokud má karta omezení, uveďte toto omezení místo toho, abyste ho tiše vypustili z vysvětlení.

Krok 5: Jak vyhledávač karet otestujete, než ho začnete používat?

Otestujte odpověď i volání API. Přesvědčivá věta sama o sobě nemůže doložit, který dotaz se spustil nebo které záznamy se vrátily.

1. Otevřete Testing a vytvořte dataset s názvem Open Query checks pomocí Create Dataset → Paste messages. Vložte nezávislé testovací zprávy ze sady.
2. Spusťte testy. Hodnoťte, zda odpověď zobrazuje svůj dotaz, cituje vrácené karty a vysvětluje nejistotu.
3. Otevřete odpovídající konverzaci v Inbox a prohlédněte si volání Akce. Zkontrolujte dotaz, číslo stránky, stav a vrácená pole. K nalezení jednotlivých volání použijte ovládací prvek View logs u Akce.
4. Otestujte zpřesňování a stránkování v navazující konverzaci, kde je předchozí dotaz k dispozici.

Pro test bez shody odešlete:

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

Jeden přímý test API ukázal, proč jsou varování důležitá. Chybný dotaz f:commander o:/[/ vrátil HTTP 200, ale Scryfall oznámil, že neplatný výraz ignoroval. Výsledky proto byly širší, než bylo požadováno. Toto varování zachovejte, vysvětlete ignorovaný filtr a před doporučováním těchto výsledků dotaz opravte.

Naše běhy lokálního Agenta pokryly základ, zpřesnění, prázdné výsledky a dvoustránkové hledání. Samostatné kontroly API pokryly chybějící ceny, strany karet a varování syntaxe. Pro testování limitu rychlosti použijte řízený fixture, aniž byste posílali nadměrný provoz.

Dokumentace endpointu pro vyhledávání karet aktuálně uvádí dva vyhledávací požadavky za sekundu. Mezi požadavky ponechte alespoň 500 milisekund. Tento návod je osobní pomocník pro hledání. Veřejný bot pro mnoho hráčů potřebuje sdílené omezení rychlosti a cache. Požádat model, aby zpomalil, nevynucuje globální limit požadavků.

Může s nastavením pomoci ChatGPT nebo Claude?

K nastavení Agenta můžete použít plugin Quickchat AI pro ChatGPT nebo konektor Quickchat AI pro Claude přes připojení pro správu účtu. Přihlášení dokončete sami a potom poskytněte tento návod a jeho startovací sadu s následujícím požadavkem:

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.

Dokumentace ke správě účtu toto připojení vysvětluje. Tímto se nastavuje váš účet Quickchat AI. Neznamená to, že se Open Query automaticky zpřístupní ostatním lidem jako nástroj MCP.

Často kladené otázky

Mohu v Scryfall vyhledávat přirozeným jazykem?

AI asistent může převést požadavek v běžném jazyce do vyhledávací syntaxe Scryfall a spustit ji přes API Scryfall. Tento návod takového asistenta vytvoří v Quickchat AI a zajistí, aby zobrazoval dotaz, propojené záznamy karet a relevantní Oracle text, takže si můžete ověřit, jak požadavek vyložil.

Potřebuji API klíč Scryfall?

Ne. Veřejný endpoint pro vyhledávání karet nevyžaduje účet ani API klíč. Posílejte identifikační hlavičky User-Agent a Accept, dodržujte limity rychlosti Scryfall a další stránky vyžadujte záměrně.

Může si tento AI vyhledávač karet vymyslet kartu?

Instrukce omezují doporučení na záznamy vrácené Akcí, s odkazy Scryfall. Model se ale stále může mýlit, takže než se na asistenta spolehnete, zkontrolujte vrácené ID a Oracle text a vyzkoušejte nemožný název karty.

Jaký je na Scryfall rozdíl mezi id<=g a id=g?

id<=g zahrnuje zelenou i bezbarvou identitu, což se hodí pro hledání v barvách monozeleného commandera. id=g vyžaduje přesně zelenou identitu. Barevná identita se liší od barvy karty. Pro stavbu balíčku Commander používejte filtr identity.

Jsou ceny Scryfall zaručené?

Ne. Pole prices.usd obsahuje cenová data poskytovatele pro vrácený print, nikoli nabídku prodejce. Může být null. Filtr usd<5 hledá pod pěti americkými dolary. Nestanovuje náklady na dopravu, dostupnost ani nejlevnější koupitelný print.

Vrátí jedno hledání všechny odpovídající karty?

Jedno hledání vrátí jednu stránku API. Odpověď obsahuje total_cards, has_more a případně next_page. Open Query zobrazuje až pět doporučení z načtené stránky. Požádejte o další z této stránky nebo výslovně o další stránku API. Krátký výběr není úplná množina výsledků.

Může mi tohle postavit celý balíček Commander?

Tento návod vytváří asistenta pro vyhledávání karet. Pomáhá najít a prohlédnout kandidáty na místo v balíčku. Neověřuje kompletní balíček o 100 kartách, neoptimalizuje decklist a nenahrazuje rozhodčího pravidel.