Construiește un căutător de cărți AI Commander cu Scryfall

Un căutător de cărți Scryfall Commander transformă o descriere a cărții de care ai nevoie într-o căutare pe care o poți inspecta. În acest tutorial, vei construi Open Query, un Agent Quickchat AI care își afișează interogarea Scryfall, returnează înregistrări reale de cărți și explică de ce fiecare candidat s-ar putea potrivi în pachetul tău.

Începe cu un singur slot într-un pachet mono-verde Commander. Vrei o creatură cu trample și un preț sub cinci dolari SUA. Până la final, vei putea să tastezi acea cerere, să deschizi cărțile returnate și să rafinezi căutarea fără să memorezi fiecare operator.

Partea utilă apare când cererea devine mai dificilă. „Draw when another creature enters” pare precis, dar o căutare după cuvintele enters și draw găsește și cărți care fac altceva. Vei depista această nepotrivire și vei restrânge interogarea, folosind textul cărților returnate ca dovadă.

Ce vei construi și de ce ai nevoie?

Vei conecta o singură API Action doar pentru citire la Scryfall, vei da Agentului instrucțiunile sale de căutare și îl vei testa într-o conversație. Action apelează un URL fix. Modelul furnizează o interogare și un număr de pagină. Scryfall returnează înregistrările din care răspunsul își extrage informațiile.

1. Creează un cont Quickchat AI și un Agent numit Open Query. Ai nevoie de credite AI disponibile pentru conversații și teste. Vezi planurile curente.
2. Păstrează la îndemână Identity, Actions & MCPs și AI Preview ale Agentului pe măsură ce lucrezi. Nu este necesară încărcarea colecției de cărți.
3. Folosește API-ul public al Scryfall. Nu ai nevoie de un cont Scryfall sau de o cheie API pentru aceste căutări.

Kitul de pornire conține Main Prompt, rețeta Action, căile filtrului de răspuns și mesajele de test. Exemplele folosesc text Oracle în engleză și prețuri în USD. Păstrează operatorii de interogare și numele cărților exact așa cum sunt scrise când urmărești tutorialul în altă limbă.

Pasul 1: Cum transformi o cerere de carte într-o interogare Scryfall?

O interogare Scryfall combină constrângeri separate prin spații. Pentru prima noastră cerere, folosește:

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

Două alegeri mici contează. kw:trample caută cuvântul-cheie. o:trample caută cuvântul în textul Oracle. O creatură poate menționa trample fără să aibă ea însăși acea abilitate. Le-am testat pe ambele. Căutarea în text a produs un set mai larg.

„Se potrivește într-un pachet mono-verde” diferă și de „are identitate exact verde”. Prima permite cărți incolore. Folosește id=g pentru a doua, sau id<=ur pentru a căuta în culorile unui comandant albastru-roșu. Acestea sunt constrângeri de identitate, nu o verificare completă a legalității pachetului.

Referința de sintaxă de căutare a lui Scryfall explică acești operatori. Pentru acest tutorial, păstrează interogarea vizibilă în fiecare răspuns, astfel încât să poți observa o culoare omisă, o monedă neașteptată sau o căutare mai largă decât cererea ta.

Pasul 2: Cum conectezi API-ul Scryfall la Agentul tău?

Creează un API Action care trimite o cerere GET către endpointul de căutare a cărților al Scryfall. Setările sale fixe aleg furnizorul și ordonarea. Cei doi parametri ai săi îi permit Agentului să aleagă căutarea și pagina.

1. Deschide Actions & MCPs → Add Action → API Action.
2. Folosește cererea pentru builder de mai jos, apoi verifică setările generate în raport cu rețeta. Ghidul pentru builder API Action explică fluxul de generare și revizuire.
3. Setează API Action Name la 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.

Definește cei doi parametri

Sub What to ask the user first, adaugă acești parametri obligatorii. Agentul îi poate completa din conversație. Eticheta nu înseamnă că trebuie să îți ceară să tastezi sintaxa brută a interogării.

Setează endpointul, parametrii de interogare și antetele

Selectează GET și introdu:

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

Sub Query Params, adaugă cele patru rânduri de mai jos. Pentru valorile dinamice, folosește Add AI Data pentru a selecta parametrul pe care l-ai creat. Notația {{query}} și {{page}} de mai jos reprezintă acele chipuri de parametri.

Folosește câmpurile pentru parametrii de interogare astfel încât spațiile, ghilimelele și operatorii să fie codificați ca valori de parametri. Păstrează URL-ul endpointului fix.

Lasă Body gol. Nu este necesară autentificarea. User-Agent este un nume de client de identificare, nu o acreditare. Folosește propriul nume de aplicație adecvat și propriul URL de contact când îți implementezi versiunea.

Păstrează răspunsul util

O pagină Scryfall poate conține multe înregistrări. Păstrează câmpurile de care Agent are nevoie, împreună cu informațiile care îi spun dacă există mai multe pagini. Extinde Advanced settings și găsește Response filter. Folosește Add JSONPath, apoi butonul plus, pentru a adăuga fiecare cale de mai jos ca intrare separată:

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

Păstrează card_faces. Unele cărți își pun textul pe fețe individuale, nu la nivelul superior. Păstrează și warnings: un succes HTTP nu înseamnă că Scryfall a interpretat fiecare clauză exact cum ai intenționat. Referința obiectului Card descrie aceste câmpuri.

În API Action Description, lipeș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.

Salvează Action și verifică dacă este activă. Ghidul despre anatomia HTTP Action explică modul în care parametrii, cererea și descrierea funcționează împreună.

Pasul 3: Cum ar trebui căutătorul de cărți să își explice rezultatele?

Agentul are nevoie de instrucțiuni pentru a-și afișa interogarea, pentru a ancora recomandările în înregistrările returnate și pentru a distinge o potrivire de cuvinte de o interacțiune de reguli. Deschide Identity → Main Prompt și lipește promptul complet din kitul de pornire, reprodus mai jos.

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.

Acum deschide AI Preview și trimite:

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

Demonstrația a interpretat eligibilitatea pentru un pachet mono-verde ca verde sau incolor. Pentru identitate exact verde, spune asta explicit.

Citește interogarea executată înainte de recomandări. Ar trebui să păstreze Commander, identitatea verde-sau-incolor, tipul creatură, trample și USD sub 5. Deschide linkul Scryfall al unei cărți și compară textul relevant, identitatea și prețul cu răspunsul. Prețul este o observație de căutare pentru tipărirea returnată, nu o ofertă finală de cumpărare.

Rezultatele API sunt ordonate după nume, nu clasificate după potrivire. Agentul alege o listă scurtă din pagina preluată. unique=cards evită listarea fiecărei tipăriri ca rezultat separat. Nu înseamnă că înregistrarea selectată este cea mai ieftină copie pe care o poți cumpăra.

Pasul 4: Cum repari o căutare care găsește interacțiunea greșită?

Restrânge interogarea citind un contraexemplu și adăugând condiția lipsă. Păstrează distincția dintre găsirea cărților candidate și confirmarea textului lor pe tot parcursul rafinării.

Întreabă:

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

O căutare largă de candidați este:

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

În verificarea noastră directă Scryfall din 10 noiembrie 2026, aceasta a returnat 161 de candidați, inclusiv Abundant Growth. Efectul său de draw are loc când Aura însăși intră. Conține ambele cuvinte, dar nu oferă motorul repetabil de draw la intrarea unei creaturi pe care îl sugerează cererea.

Încearcă această rafinare:

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

Interogarea mai restrânsă pe care am verificat-o a fost:

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

Căutarea rafinată a returnat patru candidați. Garruk’s Packleader este o potrivire condiționată utilă: cealaltă creatură trebuie să aibă putere 3 sau mai mare. Distincția trebuie să apară în recomandare. O strategie de tokeni cu multe creaturi 1/1 poate avea nevoie de o altă carte.

Adăugarea doar a lui o:"another creature" este mai puțin precisă. Testul nostru a găsit totuși Disciple of Freyalise, a cărei proprie intrare te poate face să sacrifici o altă creatură și să tragi o carte. Acesta este încă un motiv să inspectezi întreaga abilitate, în loc să tratezi o expresie suplimentară drept dovadă.

Repetă aceeași buclă pentru propriul tău pachet: cerere → interogare → textul cărții → o rafinare. Dacă bugetul elimină fiecare candidat util, întreabă înainte să îl lărgești. Dacă o carte are o restricție, spune restricția în loc să o elimini discret din explicație.

Pasul 5: Cum testezi căutătorul de cărți înainte să îl folosești?

Testează atât răspunsul, cât și apelul API. O propoziție convingătoare nu poate stabili ce interogare a rulat sau ce înregistrări au revenit.

1. Deschide Testing și creează un set de date numit Open Query checks folosind Create Dataset → Paste messages. Lipește mesajele de test independente din kit.
2. Rulează testele. Evaluează dacă răspunsul își afișează interogarea, citează cărțile returnate și explică incertitudinea.
3. Deschide conversația corespunzătoare în Inbox și inspectează apelul Action. Verifică interogarea, numărul paginii, starea și câmpurile returnate. Folosește controlul View logs al Action pentru a găsi apeluri individuale.
4. Testează rafinarea și paginarea într-o conversație continuă, unde interogarea anterioară este disponibilă.

Pentru testul fără potriviri, trimite:

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

Un test API direct a arătat de ce avertismentele contează. Interogarea malformată f:commander o:/[/ a returnat HTTP 200, dar Scryfall a raportat că a ignorat expresia invalidă. Prin urmare, rezultatele au fost mai largi decât s-a cerut. Păstrează acel avertisment, explică filtrul ignorat și corectează interogarea înainte de a recomanda acele rezultate.

Rulările Agentului nostru local au acoperit baza, rafinarea, rezultatele goale și o căutare pe două pagini. Verificări API separate au acoperit prețurile lipsă, fețele cărților și avertismentele de sintaxă. Folosește un fixture controlat pentru a testa limitarea ratei fără a trimite trafic în exces.

Documentația endpointului de căutare a cărților specifică în prezent două cereri de căutare pe secundă. Păstrează cel puțin 500 de milisecunde între cereri. Acest tutorial este un ajutor personal de căutare. Un bot public care deservește mulți jucători are nevoie de limitare de rată partajată și caching. A-i cere modelului să încetinească nu impune o limită globală de cereri.

Pot ChatGPT sau Claude să ajute la configurarea acestuia?

Poți folosi pluginul Quickchat AI pentru ChatGPT sau conectorul Quickchat AI pentru Claude pentru a configura Agentul prin conexiunea de administrare a contului. Finalizează autentificarea chiar tu, apoi furnizează acest tutorial și kitul său de pornire împreună cu următoarea cerere:

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.

Documentația de administrare a contului explică conexiunea. Aceasta configurează contul tău Quickchat AI. Nu face automat ca Open Query să fie disponibil altor persoane ca instrument MCP.

Întrebări frecvente

Pot căuta Scryfall în limbaj natural?

Un asistent AI poate traduce o cerere în limbaj obișnuit în sintaxa de căutare Scryfall și o poate executa prin API-ul Scryfall. Acest tutorial construiește acel asistent în Quickchat AI și îl face să afișeze interogarea, înregistrările de cărți conectate și textul Oracle relevant, astfel încât să poți verifica interpretarea.

Am nevoie de o cheie API Scryfall?

Nu. Endpointul public de căutare a cărților nu necesită cont sau cheie API. Trimite antetele de identificare User-Agent și Accept, respectă limitele de rată ale Scryfall și solicită pagini suplimentare în mod deliberat.

Poate acest căutător de cărți AI să halucineze o carte?

Instrucțiunile restricționează recomandările la înregistrările returnate de Action, cu linkuri Scryfall. Modelul tot poate face greșeli, așa că verifică ID-ul returnat și textul Oracle și testează un nume de carte imposibil înainte să te bazezi pe asistent.

Care este diferența dintre id<=g și id=g pe Scryfall?

id<=g include identități verzi și incolore, potrivite pentru căutarea în culorile unui comandant mono-verde. id=g cere identitate exact verde. Identitatea de culoare este distinctă de culoarea cărții. Folosește filtrul de identitate pentru construirea pachetului Commander.

Sunt garantate prețurile Scryfall?

Nu. Câmpul prices.usd este date de preț de la furnizor pentru tipărirea returnată, nu o ofertă de la un vânzător. Poate fi null. Filtrul usd<5 caută sub cinci dolari SUA. Nu stabilește costurile de livrare, disponibilitatea sau cea mai ieftină tipărire care poate fi cumpărată.

O singură căutare returnează toate cărțile potrivite?

O căutare returnează o pagină API. Răspunsul include total_cards, has_more și, când este relevant, next_page. Open Query afișează până la cinci recomandări din pagina preluată. Cere mai multe din acea pagină sau solicită explicit următoarea pagină API. O listă scurtă nu este setul complet de rezultate.

Poate asta să-mi construiască întregul pachet Commander?

Acest tutorial construiește un asistent de căutare a cărților. Te ajută să găsești și să inspectezi candidați pentru un slot din pachet. Nu validează un pachet complet de 100 de cărți, nu optimizează o listă de pachet și nu înlocuiește un arbitru de reguli.