Créez un chercheur de cartes IA Commander avec Scryfall

Un chercheur de cartes Scryfall Commander transforme une description de la carte dont vous avez besoin en une recherche que vous pouvez examiner. Dans ce tutoriel, vous allez créer Open Query, un Agent Quickchat AI qui affiche sa requête Scryfall, renvoie de vraies fiches de cartes et explique pourquoi chaque candidate pourrait convenir à votre deck.

Commencez par un emplacement dans un deck Commander mono-vert. Vous voulez une créature avec le piétinement et un prix inférieur à cinq dollars américains. À la fin, vous pourrez saisir cette demande, ouvrir les cartes renvoyées et affiner la recherche sans mémoriser chaque opérateur.

La partie utile arrive quand la demande devient plus difficile. « Pioche quand une autre créature arrive » semble précis, mais une recherche sur les mots enters et draw trouve aussi des cartes qui font autre chose. Vous allez repérer ce décalage et resserrer la requête, en utilisant le texte de carte renvoyé comme preuve.

Que allez-vous construire, et de quoi avez-vous besoin ?

Vous allez connecter une API Action en lecture seule à Scryfall, donner à l’Agent ses instructions de recherche et le tester dans une conversation. L’Action appelle une URL fixe ; le modèle fournit une requête et un numéro de page. Scryfall renvoie les fiches dont la réponse s’appuie.

1. Créez un compte Quickchat AI et un Agent nommé Open Query. Vous avez besoin de crédits IA disponibles pour les conversations et les tests ; consultez les offres actuelles.
2. Gardez les sections Identity, Actions & MCPs et AI Preview de l’Agent accessibles pendant votre travail. Aucun import de collection de cartes n’est nécessaire.
3. Utilisez l’API publique de Scryfall. Vous n’avez pas besoin d’un compte Scryfall ni d’une clé API pour ces recherches.

Le kit de démarrage contient le Main Prompt, la recette de l’Action, les chemins de filtre de réponse et les messages de test. Les exemples utilisent le texte Oracle en anglais et les prix en USD. Gardez les opérateurs de requête et les noms de cartes tels quels si vous suivez dans une autre langue.

Étape 1 : Comment transformer une demande de carte en requête Scryfall ?

Une requête Scryfall combine des contraintes séparées par des espaces. Pour notre première demande, utilisez :

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

Deux petits choix comptent. kw:trample recherche le mot-clé ; o:trample recherche le mot dans le texte Oracle. Une créature peut mentionner le piétinement sans avoir elle-même cette capacité. Nous avons testé les deux ; la recherche textuelle a produit un ensemble plus large.

« Convient à un deck mono-vert » diffère aussi de « a exactement une identité verte ». Le premier autorise les cartes incolores. Utilisez id=g pour le second, ou id<=ur pour chercher dans les couleurs d’un commandant bleu-rouge. Ce sont des contraintes d’identité, pas une vérification complète de légalité du deck.

La référence de syntaxe de recherche de Scryfall explique ces opérateurs. Pour ce tutoriel, gardez la requête visible dans chaque réponse afin de pouvoir remarquer une couleur omise, une devise inattendue ou une recherche plus large que votre demande.

Étape 2 : Comment connecter l’API Scryfall à votre Agent ?

Créez une API Action qui envoie une requête GET au point de terminaison de recherche de cartes de Scryfall. Ses paramètres fixes choisissent le fournisseur et l’ordre ; ses deux paramètres permettent à l’Agent de choisir la recherche et la page.

1. Ouvrez Actions & MCPs → Add Action → API Action.
2. Utilisez la requête du générateur ci-dessous, puis vérifiez les paramètres générés par rapport à la recette. Le guide du générateur API Action explique le flux de génération et de révision.
3. Réglez API Action Name sur 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.

Définir les deux paramètres

Sous What to ask the user first, ajoutez ces paramètres obligatoires. L’Agent peut les remplir à partir de la conversation ; l’étiquette ne signifie pas qu’il doit vous demander de saisir la syntaxe brute de la requête.

Définir le point de terminaison, les paramètres de requête et les en-têtes

Sélectionnez GET et saisissez :

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

Sous Query Params, ajoutez les quatre lignes ci-dessous. Pour les valeurs dynamiques, utilisez Add AI Data pour sélectionner le paramètre que vous avez créé. La notation {{query}} et {{page}} ci-dessous représente ces puces de paramètre.

Utilisez les champs de paramètres de requête afin que les espaces, les guillemets et les opérateurs soient encodés comme valeurs de paramètre. Gardez l’URL du point de terminaison fixe.

Laissez Body vide. Aucune authentification n’est nécessaire. Le User-Agent est un nom de client d’identification, pas un identifiant secret ; utilisez le nom d’application et l’URL de contact appropriés à votre propre version lors du déploiement.

Garder une réponse utile

Une page Scryfall peut contenir de nombreux enregistrements. Conservez les champs dont l’Agent a besoin, ainsi que les informations qui lui indiquent s’il existe d’autres pages. Développez Advanced settings et trouvez Response filter. Utilisez Add JSONPath, puis le bouton plus, pour ajouter chaque chemin ci-dessous comme entrée distincte :

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

Conservez card_faces. Certaines cartes placent leur texte sur des faces individuelles plutôt qu’au niveau supérieur. Conservez aussi warnings : un succès HTTP ne signifie pas que Scryfall a interprété chaque clause comme prévu. La référence de l’objet Card décrit ces champs.

Dans API Action Description, collez :

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.

Enregistrez l’Action et vérifiez qu’elle est active. Le guide sur l’anatomie des Actions HTTP explique comment les paramètres, la requête et la description fonctionnent ensemble.

Étape 3 : Comment le chercheur de cartes doit-il expliquer ses résultats ?

L’Agent a besoin d’instructions pour afficher sa requête, ancrer les recommandations dans les fiches renvoyées et distinguer une correspondance de mots d’une interaction de règles. Ouvrez Identity → Main Prompt et collez le prompt complet du kit de démarrage, reproduit ci-dessous.

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.

Ouvrez maintenant AI Preview et envoyez :

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

La démo a interprété l’éligibilité à un deck mono-vert comme vert ou incolore. Pour une identité exactement verte, dites-le explicitement.

Lisez la requête exécutée avant les recommandations. Elle doit conserver Commander, l’identité verte ou incolore, le type créature, le piétinement et un prix en USD inférieur à 5. Ouvrez le lien Scryfall d’une carte et comparez le texte pertinent, l’identité et le prix avec la réponse. Le prix est une observation de consultation pour l’impression renvoyée, pas un prix de paiement.

Les résultats de l’API sont triés par nom, pas classés par pertinence. L’Agent choisit une sélection courte à partir de la page récupérée. unique=cards évite de lister chaque impression comme un résultat distinct ; cela ne signifie pas que la fiche sélectionnée est l’exemplaire le moins cher que vous puissiez acheter.

Étape 4 : Comment corriger une recherche qui trouve la mauvaise interaction ?

Resserrez la requête en lisant un contre-exemple et en ajoutant la condition manquante. Gardez la distinction entre trouver des cartes candidates et confirmer leur texte tout au long de l’affinage.

Demandez :

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

Une recherche large de candidates est :

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

Lors de notre vérification directe Scryfall du 10 novembre 2026, cela a renvoyé 161 candidates, dont Abundant Growth. Sa pioche se produit quand l’Aura elle-même arrive. Elle contient les deux mots, mais elle ne fournit pas le moteur répétable de pioche à l’arrivée d’une créature que la demande suggère.

Essayez cet affinage :

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

La requête plus étroite que nous avons vérifiée était :

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

La recherche affinée a renvoyé quatre candidates. Garruk’s Packleader est une correspondance conditionnelle utile : l’autre créature doit avoir une force de 3 ou plus. Cette distinction doit figurer dans la recommandation. Une stratégie de jetons avec beaucoup de créatures 1/1 peut avoir besoin d’une autre carte.

Ajouter seulement o:"another creature" est moins précis. Notre test a quand même trouvé Disciple of Freyalise, dont sa propre arrivée peut vous amener à sacrifier une autre créature et à piocher. C’est une autre raison d’examiner la capacité entière plutôt que de traiter une phrase supplémentaire comme une preuve.

Répétez la même boucle pour votre propre deck : demande → requête → texte de carte → un affinage. Si le budget élimine toutes les candidates utiles, demandez avant de l’élargir. Si une carte a une restriction, indiquez la restriction au lieu de la retirer discrètement de l’explication.

Étape 5 : Comment tester le chercheur de cartes avant de l’utiliser ?

Testez à la fois la réponse et l’appel API. Une phrase convaincante ne peut pas établir quelle requête a été exécutée ni quelles fiches sont revenues.

1. Ouvrez Testing et créez un jeu de données nommé Open Query checks en utilisant Create Dataset → Paste messages. Collez les messages de test indépendants du kit.
2. Exécutez les tests. Évaluez si la réponse affiche sa requête, cite les cartes renvoyées et explique l’incertitude.
3. Ouvrez la conversation correspondante dans Inbox et examinez l’appel d’Action. Vérifiez la requête, le numéro de page, le statut et les champs renvoyés. Utilisez le contrôle View logs de l’Action pour trouver des appels individuels.
4. Testez l’affinage et la pagination dans une conversation continue, où la requête précédente est disponible.

Pour le test sans correspondance, envoyez :

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

Un test API direct a montré pourquoi les avertissements comptent. La requête mal formée f:commander o:/[/ a renvoyé HTTP 200, mais Scryfall a signalé qu’elle avait ignoré l’expression invalide. Les résultats étaient donc plus larges que demandé. Conservez cet avertissement, expliquez le filtre ignoré et corrigez la requête avant de recommander ces résultats.

Les exécutions de notre Agent local ont couvert la base, l’affinage, les résultats vides et une recherche sur deux pages. Des vérifications API séparées ont couvert les prix manquants, les faces de carte et les avertissements de syntaxe. Utilisez un dispositif contrôlé pour tester la limitation de débit sans envoyer un trafic excessif.

La documentation du point de terminaison de recherche de cartes spécifie actuellement deux requêtes de recherche par seconde. Gardez au moins 500 millisecondes entre les requêtes. Ce tutoriel est une aide personnelle à la recherche ; un bot public au service de nombreux joueurs a besoin d’une limitation de débit partagée et de mise en cache. Demander au modèle de ralentir n’impose pas une limite globale de requêtes.

ChatGPT ou Claude peuvent-ils aider à configurer cela ?

Vous pouvez utiliser le plugin Quickchat AI pour ChatGPT ou le connecteur Quickchat AI pour Claude pour configurer l’Agent via la connexion de gestion de compte. Effectuez vous-même la connexion, puis fournissez ce tutoriel et son kit de démarrage avec la demande suivante :

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 documentation de gestion de compte explique la connexion. Cela configure votre compte Quickchat AI ; cela ne rend pas automatiquement Open Query disponible pour d’autres personnes comme outil MCP.

Questions fréquentes

Puis-je rechercher Scryfall en langage naturel ?

Un assistant IA peut traduire une demande en langage courant en syntaxe de recherche Scryfall et l’exécuter via l’API Scryfall. Ce tutoriel construit cet assistant dans Quickchat AI et lui fait afficher la requête, les fiches de cartes liées et le texte Oracle pertinent afin que vous puissiez vérifier l’interprétation.

Ai-je besoin d’une clé API Scryfall ?

Non. Le point de terminaison public de recherche de cartes ne nécessite ni compte ni clé API. Envoyez des en-têtes User-Agent et Accept d’identification, respectez les limites de débit de Scryfall et demandez délibérément les pages supplémentaires.

Ce chercheur de cartes IA peut-il halluciner une carte ?

Les instructions limitent les recommandations aux fiches renvoyées par l’Action, avec des liens Scryfall. Le modèle peut quand même se tromper, alors vérifiez l’ID renvoyé et le texte Oracle, et testez un nom de carte impossible avant de vous fier à l’assistant.

Quelle est la différence entre id<=g et id=g sur Scryfall ?

id<=g inclut les identités vertes et incolores, ce qui convient pour chercher dans les couleurs d’un commandant mono-vert. id=g exige une identité exactement verte. L’identité couleur est distincte de la couleur de la carte. Utilisez le filtre d’identité pour la construction de deck Commander.

Les prix Scryfall sont-ils garantis ?

Non. Le champ prices.usd correspond aux données tarifaires du fournisseur pour l’impression renvoyée, pas à une offre d’un vendeur. Il peut être null. Le filtre usd<5 recherche en dessous de cinq dollars américains. Il n’établit ni les frais de port, ni la disponibilité, ni l’impression achetable la moins chère.

Une seule recherche renvoie-t-elle toutes les cartes correspondantes ?

Une recherche renvoie une page d’API. La réponse inclut total_cards, has_more et, le cas échéant, next_page. Open Query affiche jusqu’à cinq recommandations issues de la page récupérée. Demandez-en davantage depuis cette page ou demandez explicitement la page API suivante. Une sélection courte n’est pas l’ensemble complet des résultats.

Cela peut-il construire tout mon deck Commander ?

Ce tutoriel construit un assistant de recherche de cartes. Il aide à trouver et à examiner des candidates pour un emplacement du deck. Il ne valide pas un deck complet de 100 cartes, n’optimise pas une liste de deck et ne remplace pas un arbitre de règles.