Crea un cercatore di carte AI Commander con Scryfall

Un cercatore di carte Scryfall Commander trasforma una descrizione della carta di cui hai bisogno in una ricerca che puoi ispezionare. In questo tutorial costruirai Open Query, un Agent Quickchat AI che mostra la sua query Scryfall, restituisce record di carte reali e spiega perché ogni candidato potrebbe adattarsi al tuo mazzo.

Inizia con uno slot in un mazzo Commander monoverde. Vuoi una creatura con travolgere e un prezzo inferiore a cinque dollari USA. Alla fine, potrai digitare quella richiesta, aprire le carte restituite e affinare la ricerca senza memorizzare ogni operatore.

La parte utile arriva quando la richiesta diventa più difficile. “Pescare quando entra un’altra creatura” sembra preciso, ma una ricerca delle parole enters e draw trova anche carte che fanno altro. Individuerai quella discrepanza e restringerai la query, usando il testo delle carte restituite come prova.

Che cosa costruirai e di che cosa hai bisogno?

Collegherai una API Action di sola lettura a Scryfall, darai all’Agent le sue istruzioni di ricerca e lo testerai in una conversazione. L’Action chiama un URL fisso. Il modello fornisce una query e un numero di pagina. Scryfall restituisce i record da cui la risposta attinge.

1. Crea un account Quickchat AI e un Agent chiamato Open Query. Ti servono crediti AI disponibili per conversazioni e test. Consulta i piani attuali.
2. Tieni disponibili Identity, Actions & MCPs e AI Preview dell’Agent mentre lavori. Non è necessario caricare la tua collezione di carte.
3. Usa l’API pubblica di Scryfall. Non ti serve un account Scryfall né una chiave API per queste ricerche.

Lo starter kit contiene il Main Prompt, la ricetta dell’Action, i percorsi del filtro di risposta e i messaggi di test. Gli esempi usano testo Oracle in inglese e prezzi in USD. Mantieni gli operatori di query e i nomi delle carte così come sono scritti quando segui il tutorial in un’altra lingua.

Passaggio 1: Come trasformi una richiesta di carta in una query Scryfall?

Una query Scryfall combina vincoli separati da spazi. Per la nostra prima richiesta, usa:

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

Due piccole scelte contano. kw:trample cerca la parola chiave; o:trample cerca la parola nel testo Oracle. Una creatura può menzionare travolgere senza avere essa stessa quell’abilità. Le abbiamo testate entrambe. La ricerca nel testo ha prodotto un insieme più ampio.

“Si adatta a un mazzo monoverde” è diverso anche da “ha identità esattamente verde”. Il primo consente carte incolori. Usa id=g per il secondo, oppure id<=ur per cercare entro i colori di un comandante blu-rosso. Questi sono vincoli di identità, non un controllo completo di legalità del mazzo.

Il riferimento della sintassi di ricerca di Scryfall spiega questi operatori. Per questo tutorial, mantieni la query visibile in ogni risposta così puoi notare un colore omesso, una valuta inattesa o una ricerca più ampia della tua richiesta.

Passaggio 2: Come colleghi l’API Scryfall al tuo Agent?

Crea una API Action che invii una richiesta GET all’endpoint di ricerca carte di Scryfall. Le sue impostazioni fisse scelgono il fornitore e l’ordinamento. I suoi due parametri permettono all’Agent di scegliere la ricerca e la pagina.

1. Apri Actions & MCPs → Add Action → API Action.
2. Usa la richiesta del builder qui sotto, poi rivedi le impostazioni generate confrontandole con la ricetta. La guida al builder API Action spiega il flusso di generazione e revisione.
3. Imposta API Action Name su 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.

Definisci i due parametri

In What to ask the user first, aggiungi questi parametri obbligatori. L’Agent può compilarli dalla conversazione. L’etichetta non significa che debba chiederti di digitare la sintassi grezza della query.

Imposta l’endpoint, i parametri di query e le intestazioni

Seleziona GET e inserisci:

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

In Query Params, aggiungi le quattro righe qui sotto. Per i valori dinamici, usa Add AI Data per selezionare il parametro che hai creato. La notazione {{query}} e {{page}} qui sotto rappresenta quei chip parametro.

Usa i campi dei parametri di query così spazi, virgolette e operatori vengono codificati come valori di parametro. Mantieni fisso l’URL dell’endpoint.

Lascia Body vuoto. Non è necessaria alcuna autenticazione. Il User-Agent è un nome client identificativo, non una credenziale. Usa un nome applicazione appropriato e un URL di contatto tuoi quando distribuisci la tua versione.

Mantieni utile la risposta

Una pagina di Scryfall può contenere molti record. Mantieni i campi di cui l’Agent ha bisogno, insieme alle informazioni che gli dicono se esistono altre pagine. Espandi Advanced settings e trova Response filter. Usa Add JSONPath, poi il pulsante più, per aggiungere ciascun percorso qui sotto come voce separata:

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

Mantieni card_faces. Alcune carte mettono il loro testo su singole facce invece che al livello superiore. Mantieni anche warnings: un successo HTTP non significa che Scryfall abbia interpretato ogni clausola come previsto. Il riferimento dell’oggetto Card descrive questi campi.

In API Action Description, incolla:

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.

Salva l’Action e verifica che sia attiva. La guida all’anatomia delle HTTP Action spiega come parametri, richiesta e descrizione lavorano insieme.

Passaggio 3: Come dovrebbe spiegare i suoi risultati il cercatore di carte?

L’Agent ha bisogno di istruzioni per mostrare la sua query, fondare le raccomandazioni sui record restituiti e distinguere una corrispondenza di parole da un’interazione di regole. Apri Identity → Main Prompt e incolla il prompt completo dallo starter kit, riprodotto qui sotto.

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.

Ora apri AI Preview e invia:

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

La demo ha interpretato l’idoneità per un mazzo monoverde come verde o incolore. Per un’identità esattamente verde, dillo esplicitamente.

Leggi la query eseguita prima delle raccomandazioni. Dovrebbe preservare Commander, identità verde-o-incolore, tipo creatura, travolgere e USD sotto 5. Apri il link Scryfall di una carta e confronta il testo pertinente, l’identità e il prezzo con la risposta. Il prezzo è un’osservazione di ricerca per la stampa restituita, non un preventivo di acquisto.

I risultati dell’API sono ordinati per nome, non classificati per aderenza. L’Agent sceglie una selezione breve dalla pagina recuperata. unique=cards evita di elencare ogni stampa come risultato separato. Non significa che il record selezionato sia la copia più economica che puoi comprare.

Passaggio 4: Come correggi una ricerca che trova l’interazione sbagliata?

Restringi la query leggendo un controesempio e aggiungendo la condizione mancante. Mantieni la distinzione tra trovare carte candidate e confermare il loro testo durante tutto l’affinamento.

Chiedi:

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

Una ricerca ampia di candidati è:

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

Nel nostro controllo diretto Scryfall del 10 novembre 2026, questo ha restituito 161 candidati, incluso Abundant Growth. La sua pescata avviene quando entra l’Aura stessa. Contiene entrambe le parole, ma non fornisce il motore ripetibile di pescata all’ingresso di creature che la richiesta suggerisce.

Prova questo affinamento:

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

La query più ristretta che abbiamo controllato era:

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

La ricerca affinata ha restituito quattro candidati. Garruk’s Packleader è una corrispondenza condizionale utile: l’altra creatura deve avere forza pari o superiore a 3. La distinzione appartiene alla raccomandazione. Una strategia token con molte creature 1/1 potrebbe aver bisogno di una carta diversa.

Aggiungere solo o:"another creature" è meno preciso. Il nostro test ha comunque trovato Disciple of Freyalise, il cui ingresso può portarti a sacrificare un’altra creatura e pescare. Questo è un altro motivo per ispezionare l’intera abilità invece di trattare una frase aggiuntiva come prova.

Ripeti lo stesso ciclo per il tuo mazzo: richiesta → query → testo della carta → un affinamento. Se il budget elimina ogni candidato utile, chiedi prima di ampliarlo. Se una carta ha una restrizione, indica la restrizione invece di ometterla silenziosamente dalla spiegazione.

Passaggio 5: Come testi il cercatore di carte prima di usarlo?

Testa sia la risposta sia la chiamata API. Una frase convincente non può stabilire quale query sia stata eseguita o quali record siano tornati.

1. Apri Testing e crea un dataset chiamato Open Query checks usando Create Dataset → Paste messages. Incolla i messaggi di test indipendenti dal kit.
2. Esegui i test. Valuta se la risposta mostra la sua query, cita le carte restituite e spiega l’incertezza.
3. Apri la conversazione corrispondente in Inbox e ispeziona la chiamata Action. Controlla query, numero di pagina, stato e campi restituiti. Usa il controllo View logs dell’Action per trovare le singole chiamate.
4. Testa affinamento e paginazione in una conversazione continua, dove la query precedente è disponibile.

Per il test senza corrispondenze, invia:

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

Un test API diretto ha mostrato perché gli avvisi contano. La query malformata f:commander o:/[/ ha restituito HTTP 200, ma Scryfall ha segnalato di aver ignorato l’espressione non valida. I risultati erano quindi più ampi del richiesto. Mantieni quell’avviso, spiega il filtro ignorato e correggi la query prima di raccomandare quei risultati.

Le esecuzioni del nostro Agent locale hanno coperto il caso base, l’affinamento, i risultati vuoti e una ricerca su due pagine. Controlli API separati hanno coperto prezzi mancanti, facce delle carte e avvisi di sintassi. Usa un fixture controllato per testare il limite di frequenza senza inviare traffico eccessivo.

La documentazione dell’endpoint di ricerca carte attualmente specifica due richieste di ricerca al secondo. Mantieni almeno 500 millisecondi tra le richieste. Questo tutorial è un aiuto personale per la ricerca. Un bot pubblico che serve molti giocatori ha bisogno di limitazione condivisa della frequenza e caching. Chiedere al modello di rallentare non impone un limite globale alle richieste.

ChatGPT o Claude possono aiutare a configurarlo?

Puoi usare il plugin Quickchat AI per ChatGPT o il connettore Quickchat AI per Claude per configurare l’Agent tramite la connessione di gestione account. Completa tu stesso l’accesso, poi fornisci questo tutorial e il suo starter kit con la seguente richiesta:

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.

La documentazione di gestione account spiega la connessione. Questo configura il tuo account Quickchat AI. Non rende automaticamente Open Query disponibile ad altre persone come strumento MCP.

Domande frequenti

Posso cercare Scryfall in linguaggio naturale?

Un assistente AI può tradurre una richiesta in linguaggio semplice nella sintassi di ricerca Scryfall ed eseguirla tramite l’API Scryfall. Questo tutorial costruisce quell’assistente in Quickchat AI e gli fa mostrare la query, i record delle carte collegati e il testo Oracle pertinente così puoi verificare l’interpretazione.

Ho bisogno di una chiave API Scryfall?

No. L’endpoint pubblico di ricerca carte non richiede un account né una chiave API. Invia intestazioni User-Agent e Accept identificative, rispetta i limiti di frequenza di Scryfall e richiedi pagine aggiuntive in modo deliberato.

Questo cercatore di carte AI può allucinare una carta?

Le istruzioni limitano le raccomandazioni ai record restituiti dall’Action, con link Scryfall. Il modello può comunque sbagliare, quindi controlla l’ID restituito e il testo Oracle, e prova un nome di carta impossibile prima di fare affidamento sull’assistente.

Qual è la differenza tra id<=g e id=g su Scryfall?

id<=g include identità verdi e incolori, adatte per cercare entro i colori di un comandante monoverde. id=g richiede un’identità esattamente verde. L’identità di colore è distinta dal colore della carta. Usa il filtro di identità per la costruzione del mazzo Commander.

I prezzi Scryfall sono garantiti?

No. Il campo prices.usd è un dato di prezzo del fornitore per la stampa restituita, non un’offerta di un venditore. Può essere null. Il filtro usd<5 cerca sotto i cinque dollari USA. Non stabilisce costi di spedizione, disponibilità o la stampa acquistabile più economica.

Una ricerca restituisce ogni carta corrispondente?

Una ricerca restituisce una pagina API. La risposta include total_cards, has_more e, quando pertinente, next_page. Open Query mostra fino a cinque raccomandazioni dalla pagina recuperata. Chiedi altre carte da quella pagina oppure richiedi esplicitamente la pagina API successiva. Una selezione breve non è l’intero insieme dei risultati.

Può costruire il mio intero mazzo Commander?

Questo tutorial costruisce un assistente di ricerca carte. Aiuta a trovare e ispezionare candidati per uno slot del mazzo. Non convalida un mazzo completo di 100 carte, non ottimizza una decklist e non sostituisce un judge delle regole.