Scryfall के साथ एक AI Commander कार्ड फ़ाइंडर बनाएं

एक Scryfall Commander कार्ड फ़ाइंडर आपके ज़रूरी कार्ड के विवरण को ऐसी खोज में बदल देता है जिसे आप जांच सकें। इस ट्यूटोरियल में, आप Open Query बनाएंगे, जो एक Quickchat AI Agent है और अपनी Scryfall क्वेरी दिखाता है, असली कार्ड रिकॉर्ड लौटाता है, और बताता है कि हर candidate आपके deck में क्यों फिट हो सकता है।

एक mono-green Commander deck में एक slot से शुरुआत करें। आपको trample वाला और पांच US dollars से कम कीमत वाला creature चाहिए। अंत तक, आप वह अनुरोध टाइप कर सकेंगे, लौटाए गए कार्ड खोल सकेंगे, और हर operator याद किए बिना खोज को refine कर सकेंगे।

काम की बात तब सामने आती है जब अनुरोध कठिन हो जाता है। “Draw when another creature enters” सुनने में सटीक लगता है, लेकिन enters और draw शब्दों की खोज ऐसे कार्ड भी ढूंढ लेती है जो कुछ और करते हैं। आप उस mismatch को पकड़ेंगे और क्वेरी को संकीर्ण करेंगे, और लौटाए गए कार्ड टेक्स्ट को प्रमाण की तरह इस्तेमाल करेंगे।

आप क्या बनाएंगे, और आपको क्या चाहिए?

आप एक read-only API Action को Scryfall से जोड़ेंगे, Agent को उसकी search instructions देंगे, और उसे conversation में test करेंगे। Action एक fixed URL को call करता है। Model एक query और page number देता है। Scryfall वे records लौटाता है जिनसे उत्तर तैयार होता है।

1. एक Quickchat AI account बनाएं और Open Query नाम का एक Agent बनाएं। Conversations और tests के लिए आपके पास उपलब्ध AI credits होने चाहिए। current plans देखें।
2. काम करते समय Agent का Identity, Actions & MCPs, और AI Preview उपलब्ध रखें। किसी card collection upload की ज़रूरत नहीं है।
3. Scryfall का public API इस्तेमाल करें। इन searches के लिए आपको Scryfall account या API key की ज़रूरत नहीं है।

starter kit में Main Prompt, Action recipe, response-filter paths, और test messages शामिल हैं। उदाहरण English Oracle text और USD prices का उपयोग करते हैं। किसी दूसरी भाषा में साथ चलते समय query operators और card names को जैसा लिखा है वैसा ही रखें।

चरण 1: आप कार्ड अनुरोध को Scryfall क्वेरी में कैसे बदलते हैं?

एक Scryfall क्वेरी spaces से अलग किए गए constraints को जोड़ती है। हमारे पहले अनुरोध के लिए, यह उपयोग करें:

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

दो छोटी पसंदें महत्वपूर्ण हैं। kw:trample keyword को खोजता है। o:trample Oracle text में उस शब्द को खोजता है। कोई creature trample का उल्लेख कर सकता है, बिना खुद वह ability रखे। हमने दोनों का परीक्षण किया। Text search ने अधिक व्यापक set दिया।

“Mono-green deck में फिट होता है” और “exactly green identity है” भी अलग बातें हैं। पहले वाले में colorless cards की अनुमति होती है। दूसरे के लिए id=g का उपयोग करें, या blue-red commander के रंगों के भीतर खोजने के लिए id<=ur का। ये identity constraints हैं, पूरी deck-legality check नहीं।

Scryfall का search syntax reference इन operators को समझाता है। इस ट्यूटोरियल के लिए, हर उत्तर में क्वेरी दिखाई देती रहनी चाहिए ताकि आप छूटा हुआ color, अप्रत्याशित currency, या आपके अनुरोध से अधिक व्यापक search पहचान सकें।

चरण 2: आप Scryfall API को अपने Agent से कैसे जोड़ते हैं?

एक API Action बनाएं जो Scryfall के card-search endpoint पर GET request भेजे। इसकी fixed settings provider और ordering चुनती हैं। इसके दो parameters Agent को search और page चुनने देते हैं।

1. Actions & MCPs → Add Action → API Action खोलें।
2. नीचे दिया गया builder request इस्तेमाल करें, फिर generated settings को recipe के साथ मिलाकर देखें। API Action builder guide generation और review flow समझाती है।
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.

दो parameters परिभाषित करें

What to ask the user first के अंतर्गत, ये required parameters जोड़ें। Agent इन्हें conversation से भर सकता है। Label का मतलब यह नहीं कि उसे आपसे raw query syntax टाइप करने को कहना ही होगा।

Endpoint, query parameters, और headers सेट करें

GET चुनें और दर्ज करें:

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

Query Params के अंतर्गत, नीचे दी गई चार rows जोड़ें। Dynamic values के लिए, बनाए गए parameter को चुनने हेतु Add AI Data का उपयोग करें। नीचे दिया गया notation {{query}} और {{page}} उन parameter chips को दर्शाता है।

Query-parameter fields का उपयोग करें ताकि spaces, quotes, और operators parameter values के रूप में encode हों। Endpoint URL को fixed रखें।

Body खाली छोड़ें। Authentication की ज़रूरत नहीं है। User-Agent एक identifying client name है, credential नहीं। अपना version deploy करते समय अपना उपयुक्त application name और contact URL इस्तेमाल करें।

Response को उपयोगी बनाए रखें

एक Scryfall पेज में कई रिकॉर्ड हो सकते हैं। वे फ़ील्ड रखें जिनकी Agent को ज़रूरत है, साथ ही वह जानकारी भी जो उसे बताती है कि क्या और पेज मौजूद हैं। Advanced settings खोलें और Response filter ढूंढें। Add JSONPath का उपयोग करें, फिर प्लस बटन का, ताकि नीचे दिए गए हर path को अलग एंट्री के रूप में जोड़ा जा सके:

$.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 को रखें। कुछ cards अपना text top level पर नहीं, बल्कि individual faces पर रखते हैं। warnings को भी रखें: HTTP success का मतलब यह नहीं कि Scryfall ने हर clause को इच्छित रूप में interpret किया। Card object reference इन fields का वर्णन करता है।

API Action Description में यह paste करें:

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 को save करें और जांचें कि वह active है। HTTP Action anatomy guide बताती है कि parameters, request, और description मिलकर कैसे काम करते हैं।

चरण 3: कार्ड फ़ाइंडर को अपने परिणाम कैसे समझाने चाहिए?

Agent को ऐसे निर्देश चाहिए जो उससे उसकी query दिखवाएं, recommendations को लौटाए गए records पर आधारित रखें, और word match तथा rules interaction के बीच अंतर करें। Identity → Main Prompt खोलें और starter kit से पूरा prompt paste करें, जो नीचे फिर से दिया गया है।

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 ने mono-green deck eligibility की व्याख्या green या colorless के रूप में की। बिल्कुल green identity के लिए, इसे स्पष्ट रूप से कहें।

Recommendations से पहले executed query पढ़ें। इसमें Commander, green-or-colorless identity, creature type, trample, और USD 5 से कम सुरक्षित रहना चाहिए। एक card का Scryfall link खोलें और answer के साथ relevant text, identity, और price की तुलना करें। Price लौटाई गई printing के लिए lookup observation है, checkout quote नहीं।

API results fit के आधार पर rank नहीं किए जाते, बल्कि name के अनुसार ordered होते हैं। Agent fetched page से एक shortlist चुनता है। unique=cards हर printing को अलग result के रूप में सूचीबद्ध होने से बचाता है। इसका मतलब यह नहीं कि चुना गया record वह सबसे सस्ती copy है जिसे आप खरीद सकते हैं।

चरण 4: आप ऐसी खोज को कैसे ठीक करते हैं जो गलत interaction ढूंढ लेती है?

Counterexample पढ़कर और missing condition जोड़कर query को संकीर्ण करें। Refinement के दौरान candidate cards खोजने और उनके text की पुष्टि करने के बीच का अंतर बनाए रखें।

पूछें:

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

एक broad candidate search यह है:

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

10 नवंबर 2026 को हमारी direct Scryfall जांच में, इससे 161 candidates लौटे, जिनमें Abundant Growth शामिल था। इसका draw तब होता है जब Aura खुद enter करती है। इसमें दोनों शब्द हैं, लेकिन यह वह repeatable creature-entry draw engine नहीं देता जिसकी ओर अनुरोध संकेत करता है।

यह refinement आज़माएं:

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

हमने जो narrower query जांची, वह यह थी:

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

Refined search ने चार candidates लौटाए। Garruk’s Packleader एक उपयोगी conditional match है। दूसरी creature की power 3 या उससे अधिक होनी चाहिए। यह अंतर recommendation में होना चाहिए। बहुत सारे 1/1 creatures वाली token strategy को शायद कोई दूसरा card चाहिए।

केवल o:"another creature" जोड़ना कम सटीक है। हमारे test में फिर भी Disciple of Freyalise मिला, जिसकी अपनी entry आपको दूसरी creature sacrifice करने और draw करने तक ले जा सकती है। यही एक और कारण है कि पूरी ability जांची जाए, किसी अतिरिक्त phrase को proof मानकर नहीं।

अपने deck के लिए भी यही loop दोहराएं: request → query → card text → one refinement। अगर budget हर उपयोगी candidate को हटा देता है, तो उसे बढ़ाने से पहले पूछें। अगर किसी card पर restriction है, तो explanation से उसे चुपचाप हटाने के बजाय restriction बताएं।

चरण 5: इस्तेमाल करने से पहले आप कार्ड फ़ाइंडर का परीक्षण कैसे करते हैं?

उत्तर और API call, दोनों का परीक्षण करें। एक भरोसेमंद लगने वाला वाक्य यह स्थापित नहीं कर सकता कि कौन सी query चली या कौन से records वापस आए।

1. Testing खोलें और Create Dataset → Paste messages का उपयोग करके Open Query checks नाम का dataset बनाएं। Kit से independent test messages paste करें.
2. Tests चलाएं। जांचें कि answer अपनी query दिखाता है, लौटाए गए cards का हवाला देता है, और uncertainty समझाता है या नहीं.
3. Inbox में matching conversation खोलें और Action call जांचें। Query, page number, status, और returned fields देखें। Individual calls खोजने के लिए Action के View logs control का उपयोग करें.
4. Refinement और pagination को continuing conversation में test करें, जहां prior query उपलब्ध हो।

No-match test के लिए, यह भेजें:

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

एक direct API test ने दिखाया कि warnings क्यों महत्वपूर्ण हैं। Malformed query f:commander o:/[/ ने HTTP 200 लौटाया, लेकिन Scryfall ने बताया कि उसने invalid expression को ignore कर दिया था। इसलिए results अनुरोध से अधिक व्यापक थे। उस warning को सुरक्षित रखें, ignored filter समझाएं, और उन results की recommendation देने से पहले query ठीक करें।

हमारे local Agent runs में baseline, refinement, empty results, और two-page search शामिल थे। अलग API checks ने missing prices, card faces, और syntax warnings को cover किया। Excess traffic भेजे बिना rate limiting test करने के लिए controlled fixture का उपयोग करें।

card-search endpoint documentation वर्तमान में प्रति सेकंड दो search requests निर्दिष्ट करती है। Requests के बीच कम से कम 500 milliseconds का अंतर रखें। यह ट्यूटोरियल एक personal search helper है। कई players को सेवा देने वाले public bot को shared rate limiting और caching चाहिए। Model से धीमा होने को कहना global request limit लागू नहीं करता।

क्या ChatGPT या Claude इसे configure करने में मदद कर सकते हैं?

आप account-management connection के माध्यम से Agent configure करने के लिए ChatGPT के लिए Quickchat AI plugin या Claude के लिए Quickchat AI connector का उपयोग कर सकते हैं। Sign-in स्वयं पूरा करें, फिर यह ट्यूटोरियल और उसका 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.

account-management documentation इस connection को समझाती है। यह आपके Quickchat AI account को configure करता है। यह अपने आप Open Query को अन्य लोगों के लिए MCP tool के रूप में उपलब्ध नहीं कराता।

अक्सर पूछे जाने वाले प्रश्न

क्या मैं Scryfall को प्राकृतिक भाषा में खोज सकता हूं?

एक AI सहायक साधारण भाषा वाले अनुरोध को Scryfall खोज सिंटैक्स में बदल सकता है और उसे Scryfall API के माध्यम से चला सकता है। यह ट्यूटोरियल उस सहायक को Quickchat AI में बनाता है और उससे क्वेरी, लिंक किए गए कार्ड रिकॉर्ड, और प्रासंगिक Oracle टेक्स्ट दिखवाता है ताकि आप उसकी व्याख्या की जांच कर सकें।

क्या मुझे Scryfall API key की ज़रूरत है?

नहीं। सार्वजनिक कार्ड-खोज endpoint के लिए account या API key की आवश्यकता नहीं है। पहचान बताने वाले User-Agent और Accept headers भेजें, Scryfall की rate limits का पालन करें, और अतिरिक्त pages सोच-समझकर मांगें।

क्या यह AI कार्ड फ़ाइंडर किसी कार्ड की कल्पना कर सकता है?

निर्देश सिफारिशों को Action द्वारा लौटाए गए रिकॉर्ड तक सीमित करते हैं, जिनमें Scryfall links होते हैं। मॉडल फिर भी गलतियाँ कर सकता है, इसलिए सहायक पर भरोसा करने से पहले लौटाया गया ID और Oracle टेक्स्ट जांचें, और किसी असंभव कार्ड नाम से परीक्षण करें।

Scryfall पर id<=g और id=g में क्या अंतर है?

id<=g में हरी और रंगहीन identities शामिल होती हैं, जो mono-green commander के रंगों के भीतर खोजने के लिए उपयुक्त है। id=g के लिए identity बिल्कुल हरी होनी चाहिए। Color identity, card color से अलग होती है। Commander deck construction के लिए identity filter का उपयोग करें।

क्या Scryfall की कीमतें गारंटीड हैं?

नहीं। prices.usd field लौटाई गई printing के लिए provider pricing data है, किसी seller का offer नहीं। यह null हो सकता है। usd<5 filter पांच US dollars से कम की खोज करता है। यह shipping costs, availability, या खरीदी जा सकने वाली सबसे सस्ती printing स्थापित नहीं करता।

क्या एक खोज हर matching card लौटा देती है?

एक खोज एक API page लौटाती है। Response में total_cards, has_more, और जहां प्रासंगिक हो, next_page शामिल होते हैं। Open Query fetched page से अधिकतम पांच सिफारिशें दिखाता है। उस page से और मांगें, या स्पष्ट रूप से अगला API page मांगें। एक shortlist पूरा result set नहीं होती।

क्या यह मेरा पूरा Commander deck बना सकता है?

यह ट्यूटोरियल एक card-search assistant बनाता है। यह deck slot के लिए candidates खोजने और जांचने में मदद करता है। यह पूरे 100-card deck को validate नहीं करता, deck list को optimize नहीं करता, और rules judge का विकल्प नहीं है।