Φτιάξτε έναν AI ανιχνευτή καρτών Commander με το Scryfall

Ένας ανιχνευτής καρτών Scryfall Commander μετατρέπει μια περιγραφή της κάρτας που χρειάζεστε σε μια αναζήτηση που μπορείτε να εξετάσετε. Σε αυτό το tutorial, θα φτιάξετε το Open Query, έναν Agent Quickchat AI που εμφανίζει το query Scryfall του, επιστρέφει πραγματικές εγγραφές καρτών και εξηγεί γιατί κάθε υποψήφια κάρτα μπορεί να ταιριάζει στο deck σας.

Ξεκινήστε με μία θέση σε ένα μονοπράσινο deck Commander. Θέλετε ένα πλάσμα με trample και τιμή κάτω από πέντε δολάρια ΗΠΑ. Στο τέλος, θα μπορείτε να πληκτρολογήσετε αυτό το αίτημα, να ανοίξετε τις κάρτες που επιστράφηκαν και να βελτιώσετε την αναζήτηση χωρίς να απομνημονεύσετε κάθε operator.

Το χρήσιμο μέρος έρχεται όταν το αίτημα γίνεται πιο δύσκολο. Το “draw when another creature enters” ακούγεται ακριβές, αλλά μια αναζήτηση για τις λέξεις enters και draw βρίσκει επίσης κάρτες που κάνουν κάτι άλλο. Θα εντοπίσετε αυτή την ασυμφωνία και θα περιορίσετε το query, χρησιμοποιώντας το επιστρεφόμενο κείμενο της κάρτας ως τεκμήριο.

Τι θα φτιάξετε και τι χρειάζεστε;

Θα συνδέσετε ένα μόνο read-only API Action στο Scryfall, θα δώσετε στον Agent τις οδηγίες αναζήτησής του και θα τον δοκιμάσετε σε μια συνομιλία. Το Action καλεί ένα σταθερό URL. Το μοντέλο παρέχει ένα query και έναν αριθμό σελίδας. Το Scryfall επιστρέφει τις εγγραφές από τις οποίες αντλεί η απάντηση.

1. Δημιουργήστε έναν λογαριασμό Quickchat AI και έναν Agent με όνομα Open Query. Χρειάζεστε διαθέσιμα AI credits για συνομιλίες και δοκιμές. Δείτε τα τρέχοντα πλάνα.
2. Κρατήστε διαθέσιμα τα Identity, Actions & MCPs και AI Preview του Agent καθώς εργάζεστε. Δεν απαιτείται ανέβασμα συλλογής καρτών.
3. Χρησιμοποιήστε το δημόσιο API του Scryfall. Δεν χρειάζεστε λογαριασμό ή κλειδί API Scryfall για αυτές τις αναζητήσεις.

Το starter kit περιέχει το Main Prompt, τη συνταγή του Action, τα paths του response filter και τα test messages. Τα παραδείγματα χρησιμοποιούν αγγλικό κείμενο Oracle και τιμές σε USD. Κρατήστε τους operators του query και τα ονόματα καρτών όπως είναι γραμμένα όταν ακολουθείτε σε άλλη γλώσσα.

Βήμα 1: Πώς μετατρέπετε ένα αίτημα κάρτας σε query Scryfall;

Ένα query Scryfall συνδυάζει περιορισμούς που χωρίζονται με κενά. Για το πρώτο μας αίτημα, χρησιμοποιήστε:

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

Δύο μικρές επιλογές έχουν σημασία. Το kw:trample αναζητά το keyword. Το o:trample αναζητά τη λέξη στο κείμενο Oracle. Ένα πλάσμα μπορεί να αναφέρει το trample χωρίς να έχει το ίδιο αυτή την ικανότητα. Δοκιμάσαμε και τα δύο. Η αναζήτηση κειμένου παρήγαγε ένα ευρύτερο σύνολο.

Το “ταιριάζει σε μονοπράσινο deck” διαφέρει επίσης από το “έχει ακριβώς πράσινη ταυτότητα”. Το πρώτο επιτρέπει άχρωμες κάρτες. Χρησιμοποιήστε το id=g για το δεύτερο, ή το id<=ur για αναζήτηση μέσα στα χρώματα ενός μπλε-κόκκινου commander. Αυτοί είναι περιορισμοί ταυτότητας, όχι πλήρης έλεγχος νομιμότητας deck.

Η αναφορά σύνταξης αναζήτησης του Scryfall εξηγεί αυτούς τους operators. Για αυτό το tutorial, κρατήστε το query ορατό σε κάθε απάντηση ώστε να μπορείτε να εντοπίσετε ένα παραλειπόμενο χρώμα, ένα απρόσμενο νόμισμα ή μια αναζήτηση που είναι ευρύτερη από το αίτημά σας.

Βήμα 2: Πώς συνδέετε το API Scryfall με τον Agent σας;

Δημιουργήστε ένα API Action που στέλνει αίτημα GET στο endpoint αναζήτησης καρτών του Scryfall. Οι σταθερές ρυθμίσεις του επιλέγουν τον πάροχο και τη σειρά. Οι δύο παράμετροί του επιτρέπουν στον Agent να επιλέγει την αναζήτηση και τη σελίδα.

1. Ανοίξτε Actions & MCPs → Add Action → API Action.
2. Χρησιμοποιήστε το παρακάτω builder request και έπειτα ελέγξτε τις παραγόμενες ρυθμίσεις σε σχέση με τη συνταγή. Ο οδηγός builder API Action εξηγεί τη ροή δημιουργίας και ελέγχου.
3. Ορίστε το API Action Name σε 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.

Ορίστε τις δύο παραμέτρους

Στην ενότητα What to ask the user first, προσθέστε αυτές τις απαιτούμενες παραμέτρους. Ο Agent μπορεί να τις συμπληρώσει από τη συνομιλία. Η ετικέτα δεν σημαίνει ότι πρέπει να σας ζητήσει να πληκτρολογήσετε ακατέργαστη σύνταξη query.

Ορίστε το endpoint, τις παραμέτρους query και τις κεφαλίδες

Επιλέξτε GET και εισαγάγετε:

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

Στην ενότητα Query Params, προσθέστε τις τέσσερις παρακάτω γραμμές. Για τις δυναμικές τιμές, χρησιμοποιήστε το Add AI Data για να επιλέξετε την παράμετρο που δημιουργήσατε. Η σημειογραφία {{query}} και {{page}} παρακάτω αντιπροσωπεύει αυτά τα chips παραμέτρων.

Χρησιμοποιήστε τα πεδία παραμέτρων query ώστε τα κενά, τα εισαγωγικά και οι operators να κωδικοποιούνται ως τιμές παραμέτρων. Κρατήστε το URL του endpoint σταθερό.

Αφήστε το Body κενό. Δεν απαιτείται authentication. Το User-Agent είναι ένα αναγνωριστικό όνομα client, όχι διαπιστευτήριο. Χρησιμοποιήστε το δικό σας κατάλληλο όνομα εφαρμογής και URL επικοινωνίας όταν αναπτύσσετε τη δική σας έκδοση.

Κρατήστε την απόκριση χρήσιμη

Μια σελίδα Scryfall μπορεί να περιέχει πολλές εγγραφές. Κρατήστε τα πεδία που χρειάζεται ο Agent, μαζί με τις πληροφορίες που του λένε αν υπάρχουν περισσότερες σελίδες. Αναπτύξτε το Advanced settings και βρείτε το Response filter. Χρησιμοποιήστε το Add JSONPath και μετά το κουμπί συν για να προσθέσετε κάθε παρακάτω διαδρομή ως ξεχωριστή καταχώριση:

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

Κρατήστε το card_faces. Ορισμένες κάρτες τοποθετούν το κείμενό τους σε επιμέρους faces αντί στο ανώτερο επίπεδο. Κρατήστε επίσης το warnings: μια επιτυχία HTTP δεν σημαίνει ότι το Scryfall ερμήνευσε κάθε ρήτρα όπως προοριζόταν. Η αναφορά αντικειμένου Card περιγράφει αυτά τα πεδία.

Στο API Action Description, επικολλήστε:

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.

Αποθηκεύστε το Action και ελέγξτε ότι είναι ενεργό. Ο οδηγός anatomy του HTTP Action εξηγεί πώς συνεργάζονται οι παράμετροι, το request και η περιγραφή.

Βήμα 3: Πώς πρέπει ο ανιχνευτής καρτών να εξηγεί τα αποτελέσματά του;

Ο Agent χρειάζεται οδηγίες για να εμφανίζει το query του, να στηρίζει τις προτάσεις σε επιστρεφόμενες εγγραφές και να διακρίνει μια λεκτική αντιστοίχιση από μια αλληλεπίδραση κανόνων. Ανοίξτε Identity → Main Prompt και επικολλήστε το πλήρες prompt από το starter kit, που αναπαράγεται παρακάτω.

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.

Τώρα ανοίξτε το AI Preview και στείλτε:

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

Το demo ερμήνευσε την καταλληλότητα για μονοπράσινο deck ως πράσινη ή άχρωμη. Για ακριβώς πράσινη ταυτότητα, πείτε το ρητά.

Διαβάστε το εκτελεσμένο query πριν από τις προτάσεις. Θα πρέπει να διατηρεί το Commander, την πράσινη-ή-άχρωμη ταυτότητα, τον τύπο πλάσματος, το trample και USD κάτω από 5. Ανοίξτε τον σύνδεσμο Scryfall μιας κάρτας και συγκρίνετε το σχετικό κείμενο, την ταυτότητα και την τιμή με την απάντηση. Η τιμή είναι μια παρατήρηση αναζήτησης για το επιστρεφόμενο printing, όχι τιμή checkout.

Τα αποτελέσματα του API ταξινομούνται κατά όνομα, όχι κατά καταλληλότητα. Ο Agent επιλέγει μια σύντομη λίστα από τη σελίδα που ανακτήθηκε. Το unique=cards αποφεύγει να εμφανίζει κάθε printing ως ξεχωριστό αποτέλεσμα. Δεν σημαίνει ότι η επιλεγμένη εγγραφή είναι το φθηνότερο αντίτυπο που μπορείτε να αγοράσετε.

Βήμα 4: Πώς διορθώνετε μια αναζήτηση που βρίσκει τη λάθος αλληλεπίδραση;

Περιορίστε το query διαβάζοντας ένα αντιπαράδειγμα και προσθέτοντας τη συνθήκη που λείπει. Κρατήστε τη διάκριση ανάμεσα στην εύρεση υποψήφιων καρτών και στην επιβεβαίωση του κειμένου τους σε όλη τη βελτίωση.

Ρωτήστε:

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

Μια ευρεία αναζήτηση υποψηφίων είναι:

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

Στον άμεσο έλεγχο Scryfall που κάναμε στις 10 Νοεμβρίου 2026, αυτό επέστρεψε 161 υποψηφίους, συμπεριλαμβανομένου του Abundant Growth. Το draw του συμβαίνει όταν μπαίνει η ίδια η Aura. Περιέχει και τις δύο λέξεις, αλλά δεν παρέχει τον επαναλαμβανόμενο μηχανισμό draw από είσοδο πλάσματος που υπονοεί το αίτημα.

Δοκιμάστε αυτή τη βελτίωση:

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

Το στενότερο query που ελέγξαμε ήταν:

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

Η βελτιωμένη αναζήτηση επέστρεψε τέσσερις υποψηφίους. Το Garruk’s Packleader είναι μια χρήσιμη υπό συνθήκη αντιστοίχιση: το άλλο πλάσμα πρέπει να έχει δύναμη 3 ή μεγαλύτερη. Αυτή η διάκριση ανήκει στην πρόταση. Μια στρατηγική token με πολλά πλάσματα 1/1 μπορεί να χρειάζεται διαφορετική κάρτα.

Η προσθήκη μόνο του o:"another creature" είναι λιγότερο ακριβής. Η δοκιμή μας βρήκε ακόμη το Disciple of Freyalise, του οποίου η δική του είσοδος μπορεί να σας οδηγήσει να θυσιάσετε άλλο πλάσμα και να κάνετε draw. Αυτός είναι άλλος ένας λόγος να εξετάζετε ολόκληρη την ικανότητα αντί να αντιμετωπίζετε μια επιπλέον φράση ως απόδειξη.

Επαναλάβετε τον ίδιο κύκλο για το δικό σας deck: αίτημα → query → κείμενο κάρτας → μία βελτίωση. Αν το budget αφαιρεί κάθε χρήσιμο υποψήφιο, ρωτήστε πριν το διευρύνετε. Αν μια κάρτα έχει περιορισμό, αναφέρετε τον περιορισμό αντί να τον αφαιρείτε σιωπηλά από την εξήγηση.

Βήμα 5: Πώς δοκιμάζετε τον ανιχνευτή καρτών πριν τον χρησιμοποιήσετε;

Δοκιμάστε τόσο την απάντηση όσο και την κλήση API. Μια πειστική πρόταση δεν μπορεί να αποδείξει ποιο query εκτελέστηκε ή ποιες εγγραφές επέστρεψαν.

1. Ανοίξτε το Testing και δημιουργήστε ένα dataset με όνομα Open Query checks χρησιμοποιώντας Create Dataset → Paste messages. Επικολλήστε τα ανεξάρτητα test messages από το kit.
2. Εκτελέστε τα tests. Αξιολογήστε αν η απάντηση εμφανίζει το query της, παραθέτει επιστρεφόμενες κάρτες και εξηγεί την αβεβαιότητα.
3. Ανοίξτε την αντίστοιχη συνομιλία στο Inbox και εξετάστε την κλήση Action. Ελέγξτε το query, τον αριθμό σελίδας, το status και τα επιστρεφόμενα πεδία. Χρησιμοποιήστε το control View logs του Action για να βρείτε μεμονωμένες κλήσεις.
4. Δοκιμάστε βελτίωση και pagination σε μια συνεχιζόμενη συνομιλία, όπου το προηγούμενο query είναι διαθέσιμο.

Για το test χωρίς αντιστοιχία, στείλτε:

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

Ένας άμεσος έλεγχος API έδειξε γιατί τα warnings έχουν σημασία. Το κακοσχηματισμένο query f:commander o:/[/ επέστρεψε HTTP 200, αλλά το Scryfall ανέφερε ότι είχε αγνοήσει την άκυρη έκφραση. Τα αποτελέσματα ήταν επομένως ευρύτερα από όσο ζητήθηκε. Διατηρήστε αυτό το warning, εξηγήστε το φίλτρο που αγνοήθηκε και διορθώστε το query πριν προτείνετε αυτά τα αποτελέσματα.

Οι εκτελέσεις του τοπικού Agent μας κάλυψαν τη βασική περίπτωση, τη βελτίωση, τα κενά αποτελέσματα και μια αναζήτηση δύο σελίδων. Ξεχωριστοί έλεγχοι API κάλυψαν ελλείπουσες τιμές, faces καρτών και warnings σύνταξης. Χρησιμοποιήστε ένα ελεγχόμενο fixture για να δοκιμάσετε το rate limiting χωρίς να στέλνετε υπερβολική κίνηση.

Η τεκμηρίωση του endpoint αναζήτησης καρτών ορίζει επί του παρόντος δύο αιτήματα αναζήτησης ανά δευτερόλεπτο. Κρατήστε τα αιτήματα σε απόσταση τουλάχιστον 500 milliseconds. Αυτό το tutorial είναι ένας προσωπικός βοηθός αναζήτησης. Ένα δημόσιο bot που εξυπηρετεί πολλούς παίκτες χρειάζεται κοινόχρηστο rate limiting και caching. Το να ζητήσετε από το μοντέλο να επιβραδύνει δεν επιβάλλει ένα καθολικό όριο αιτημάτων.

Μπορούν το ChatGPT ή το Claude να βοηθήσουν στη ρύθμιση αυτού;

Μπορείτε να χρησιμοποιήσετε το plugin Quickchat AI για το ChatGPT ή το connector Quickchat AI για το Claude για να ρυθμίσετε τον Agent μέσω της σύνδεσης διαχείρισης λογαριασμού. Ολοκληρώστε μόνοι σας τη σύνδεση και έπειτα δώστε αυτό το tutorial και το starter kit του με το ακόλουθο αίτημα:

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.

Η τεκμηρίωση διαχείρισης λογαριασμού εξηγεί τη σύνδεση. Αυτό ρυθμίζει τον λογαριασμό σας Quickchat AI. Δεν καθιστά αυτόματα το Open Query διαθέσιμο σε άλλους ανθρώπους ως εργαλείο MCP.

Συχνές ερωτήσεις

Μπορώ να κάνω αναζήτηση στο Scryfall με φυσική γλώσσα;

Ένας βοηθός AI μπορεί να μεταφράσει ένα αίτημα σε απλή γλώσσα σε σύνταξη αναζήτησης Scryfall και να την εκτελέσει μέσω του API Scryfall. Αυτό το tutorial φτιάχνει αυτόν τον βοηθό στο Quickchat AI και τον κάνει να εμφανίζει το query, συνδεδεμένες εγγραφές καρτών και σχετικό κείμενο Oracle ώστε να μπορείτε να ελέγξετε την ερμηνεία.

Χρειάζομαι κλειδί API Scryfall;

Όχι. Το δημόσιο endpoint αναζήτησης καρτών δεν απαιτεί λογαριασμό ή κλειδί API. Στείλτε αναγνωριστικές κεφαλίδες User-Agent και Accept, ακολουθήστε τα όρια ρυθμού του Scryfall και ζητήστε επιπλέον σελίδες σκόπιμα.

Μπορεί αυτός ο AI ανιχνευτής καρτών να επινοήσει μια κάρτα;

Οι οδηγίες περιορίζουν τις προτάσεις σε εγγραφές που επιστρέφονται από το Action, με συνδέσμους Scryfall. Το μοντέλο μπορεί παρ’ όλα αυτά να κάνει λάθη, γι’ αυτό ελέγξτε το επιστρεφόμενο ID και το κείμενο Oracle, και δοκιμάστε ένα αδύνατο όνομα κάρτας πριν βασιστείτε στον βοηθό.

Ποια είναι η διαφορά μεταξύ id<=g και id=g στο Scryfall;

Το id<=g περιλαμβάνει πράσινες και άχρωμες ταυτότητες, κατάλληλο για αναζήτηση μέσα στα χρώματα ενός μονοπράσινου commander. Το id=g απαιτεί ακριβώς πράσινη ταυτότητα. Η ταυτότητα χρώματος διαφέρει από το χρώμα της κάρτας. Χρησιμοποιήστε το φίλτρο ταυτότητας για κατασκευή deck Commander.

Είναι εγγυημένες οι τιμές Scryfall;

Όχι. Το πεδίο prices.usd είναι δεδομένα τιμολόγησης παρόχου για το επιστρεφόμενο printing, όχι προσφορά από πωλητή. Μπορεί να είναι null. Το φίλτρο usd<5 αναζητά κάτω από πέντε δολάρια ΗΠΑ. Δεν καθορίζει κόστος αποστολής, διαθεσιμότητα ή το φθηνότερο printing που μπορεί να αγοραστεί.

Επιστρέφει μία αναζήτηση κάθε κάρτα που ταιριάζει;

Μια αναζήτηση επιστρέφει μία σελίδα API. Η απόκριση περιλαμβάνει total_cards, has_more και, όταν είναι σχετικό, next_page. Το Open Query εμφανίζει έως πέντε προτάσεις από τη σελίδα που ανακτήθηκε. Ζητήστε περισσότερες από εκείνη τη σελίδα ή ζητήστε ρητά την επόμενη σελίδα API. Μια σύντομη λίστα δεν είναι το πλήρες σύνολο αποτελεσμάτων.

Μπορεί αυτό να φτιάξει ολόκληρο το deck μου Commander;

Αυτό το tutorial φτιάχνει έναν βοηθό αναζήτησης καρτών. Βοηθά να βρείτε και να εξετάσετε υποψήφιες κάρτες για μια θέση στο deck. Δεν επικυρώνει ένα πλήρες deck 100 καρτών, δεν βελτιστοποιεί μια λίστα deck και δεν αντικαθιστά έναν rules judge.