בנו מאתר קלפים של AI Commander עם Scryfall

מאתר קלפים של Scryfall Commander הופך תיאור של הקלף שאתם צריכים לחיפוש שאפשר לבדוק. במדריך הזה תבנו את Open Query, Agent של Quickchat AI שמציג את שאילתת ה-Scryfall שלו, מחזיר רשומות קלפים אמיתיות, ומסביר מדוע כל מועמד עשוי להתאים לחפיסה שלכם.

התחילו עם משבצת אחת בחפיסת Commander ירוקה מונוצבעית. אתם רוצים יצור עם trample ובמחיר נמוך מחמישה דולרים אמריקאיים. עד סוף המדריך תוכלו להקליד את הבקשה הזאת, לפתוח את הקלפים שהוחזרו, ולדייק את החיפוש בלי לשנן כל אופרטור.

החלק השימושי מגיע כאשר הבקשה נעשית קשה יותר. “Draw when another creature enters” נשמע מדויק, אבל חיפוש אחר המילים enters ו-draw מוצא גם קלפים שעושים משהו אחר. אתם תזהו את חוסר ההתאמה הזה ותצמצמו את השאילתה, תוך שימוש בטקסט הקלף שהוחזר כראיה.

מה תבנו, ומה אתם צריכים?

תחברו API Action אחד לקריאה בלבד אל Scryfall, תתנו ל-Agent את הוראות החיפוש שלו, ותבדקו אותו בשיחה. ה-Action קורא ל-URL קבוע. המודל מספק שאילתה ומספר עמוד. Scryfall מחזיר את הרשומות שעליהן התשובה נשענת.

1. צרו חשבון Quickchat AI ו-Agent בשם Open Query. אתם צריכים קרדיטי AI זמינים לשיחות ולבדיקות. ראו את התוכניות הנוכחיות.
2. השאירו את Identity, Actions & MCPs ו-AI Preview של ה-Agent זמינים בזמן העבודה. אין צורך להעלות אוסף קלפים.
3. השתמשו ב-API הציבורי של Scryfall. אינכם צריכים חשבון או מפתח API של Scryfall עבור החיפושים האלה.

ערכת ה-starter kit כוללת את ה-Main Prompt, מתכון ה-Action, נתיבי מסנן התגובה והודעות בדיקה. הדוגמאות משתמשות בטקסט Oracle באנגלית ובמחירי USD. כאשר אתם עוקבים אחר המדריך בשפה אחרת, השאירו את אופרטורי השאילתה ואת שמות הקלפים כפי שהם כתובים.

שלב 1: איך הופכים בקשת קלף לשאילתת Scryfall?

שאילתת Scryfall משלבת אילוצים המופרדים ברווחים. עבור הבקשה הראשונה שלנו, השתמשו ב:

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

לשתי בחירות קטנות יש חשיבות. kw:trample מחפש את מילת המפתח; o:trample מחפש את המילה בטקסט ה-Oracle. יצור יכול להזכיר trample בלי שתהיה לו היכולת הזאת בעצמו. בדקנו את שתי האפשרויות. חיפוש הטקסט יצר קבוצה רחבה יותר.

“מתאים לחפיסה ירוקה מונוצבעית” שונה גם מ-”יש לו זהות ירוקה בדיוק”. האפשרות הראשונה מתירה קלפים חסרי צבע. השתמשו ב-id=g עבור האפשרות השנייה, או ב-id<=ur כדי לחפש בתוך הצבעים של מפקד כחול-אדום. אלה אילוצי זהות, ולא בדיקת חוקיות מלאה של חפיסה.

ה-search syntax reference של Scryfall מסביר את האופרטורים האלה. לצורך המדריך הזה, השאירו את השאילתה גלויה בכל תשובה, כדי שתוכלו להבחין בצבע שהושמט, במטבע לא צפוי, או בחיפוש רחב יותר מהבקשה שלכם.

שלב 2: איך מחברים את ה-API של Scryfall ל-Agent שלכם?

צרו API Action אחד ששולח בקשת GET לנקודת הקצה לחיפוש קלפים של Scryfall. ההגדרות הקבועות שלו בוחרות את הספק ואת סדר המיון. שני הפרמטרים שלו מאפשרים ל-Agent לבחור את החיפוש ואת העמוד.

1. פתחו את Actions & MCPs → Add Action → API Action.
2. השתמשו בבקשת הבונה שלמטה, ואז בדקו את ההגדרות שנוצרו מול המתכון. מדריך הבונה של 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 יכול למלא אותם מתוך השיחה. התווית אינה אומרת שהוא חייב לבקש מכם להקליד תחביר שאילתה גולמי.

הגדירו את נקודת הקצה, פרמטרי השאילתה והכותרות

בחרו GET והזינו:

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

תחת Query Params, הוסיפו את ארבע השורות שלמטה. עבור הערכים הדינמיים, השתמשו ב-Add AI Data כדי לבחור את הפרמטר שיצרתם. הסימון {{query}} ו-{{page}} למטה מייצג את שבבי הפרמטרים האלה.

השתמשו בשדות של פרמטרי השאילתה כדי שרווחים, מרכאות ואופרטורים יקודדו כערכי פרמטרים. השאירו את כתובת ה-URL של נקודת הקצה קבועה.

השאירו את Body ריק. אין צורך באימות. ה-User-Agent הוא שם לקוח מזהה, ולא אישור גישה. כאשר אתם פורסים את הגרסה שלכם, השתמשו בשם יישום וב-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. יש קלפים שממקמים את הטקסט שלהם על פאות נפרדות ולא ברמה העליונה. שמרו גם את warnings: הצלחת HTTP אינה אומרת ש-Scryfall פירש כל סעיף כפי שהתכוונתם. הפניית Card object מתארת את השדות האלה.

ב-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 ובדקו שהוא פעיל. מדריך המבנה של HTTP Action מסביר איך הפרמטרים, הבקשה והתיאור עובדים יחד.

שלב 3: איך מאתר הקלפים צריך להסביר את התוצאות שלו?

ה-Agent צריך הוראות כדי להציג את השאילתה שלו, לעגן המלצות ברשומות שהוחזרו, ולהבחין בין התאמת מילה לבין אינטראקציה חוקית. פתחו את Identity → Main 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.

ההדגמה פירשה התאמה לחפיסה ירוקה מונוצבעית כירוק או חסר צבע. עבור זהות ירוקה בדיוק, אמרו זאת במפורש.

קראו את השאילתה שבוצעה לפני ההמלצות. היא צריכה לשמר את Commander, זהות ירוקה או חסרת צבע, סוג יצור, trample, ו-USD מתחת ל-5. פתחו את קישור ה-Scryfall של אחד הקלפים והשוו את הטקסט הרלוונטי, הזהות והמחיר לתשובה. המחיר הוא תצפית חיפוש עבור ההדפסה שהוחזרה, ולא הצעת תשלום בקופה.

תוצאות ה-API מסודרות לפי שם, ולא מדורגות לפי התאמה. ה-Agent בוחר רשימה קצרה מתוך העמוד שנשלף. unique=cards מונע הצגה של כל הדפסה כתוצאה נפרדת. זה לא אומר שהרשומה שנבחרה היא העותק הזול ביותר שאפשר לקנות.

שלב 4: איך מתקנים חיפוש שמוצא אינטראקציה שגויה?

צמצמו את השאילתה על ידי קריאת דוגמה נגדית והוספת התנאי החסר. לאורך כל תהליך הדיוק, שמרו על ההבחנה בין מציאת קלפים מועמדים לבין אימות הטקסט שלהם.

שאלו:

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. השליפה שלו מתרחשת כאשר ה-Aura עצמה נכנסת. הוא מכיל את שתי המילים, אבל הוא אינו מספק את מנוע השליפה החוזר על כניסת יצור שהבקשה מרמזת עליו.

נסו את הדיוק הבא:

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

השאילתה המצומצמת יותר שבדקנו הייתה:

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

החיפוש המדויק החזיר ארבעה מועמדים. Garruk’s Packleader הוא התאמה מותנית שימושית: היצור האחר צריך כוח 3 או יותר. ההבחנה הזאת שייכת להמלצה. אסטרטגיית טוקנים עם הרבה יצורי 1/1 עשויה להזדקק לקלף אחר.

הוספה של o:"another creature" בלבד פחות מדויקת. הבדיקה שלנו עדיין מצאה את Disciple of Freyalise, שהכניסה העצמית שלו יכולה להוביל אתכם להקריב יצור אחר ולשלוף. זו עוד סיבה לבדוק את כל היכולת, במקום להתייחס לביטוי נוסף כהוכחה.

חזרו על אותו מחזור עבור החפיסה שלכם: בקשה → שאילתה → טקסט קלף → דיוק אחד. אם התקציב מסיר כל מועמד שימושי, שאלו לפני שאתם מרחיבים אותו. אם לקלף יש הגבלה, ציינו את ההגבלה במקום להשמיט אותה בשקט מההסבר.

שלב 5: איך בודקים את מאתר הקלפים לפני שמשתמשים בו?

בדקו גם את התשובה וגם את קריאת ה-API. משפט משכנע אינו יכול להוכיח איזו שאילתה רצה או אילו רשומות חזרו.

1. פתחו את Testing וצרו מערך נתונים בשם Open Query checks באמצעות Create Dataset → Paste messages. הדביקו את הודעות הבדיקה העצמאיות מהערכה.
2. הריצו את הבדיקות. דרגו אם התשובה מציגה את השאילתה שלה, מצטטת קלפים שהוחזרו, ומסבירה אי ודאות.
3. פתחו את השיחה התואמת ב-Inbox ובדקו את קריאת ה-Action. בדקו את השאילתה, מספר העמוד, הסטטוס והשדות שהוחזרו. השתמשו בפקד View logs של ה-Action כדי למצוא קריאות בודדות.
4. בדקו דיוק ועימוד בשיחה מתמשכת, שבה השאילתה הקודמת זמינה.

לבדיקת ללא התאמה, שלחו:

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

בדיקת API ישירה אחת הראתה מדוע אזהרות חשובות. השאילתה הפגומה f:commander o:/[/ החזירה HTTP 200, אבל Scryfall דיווח שהיא התעלמה מהביטוי הלא תקין. לכן התוצאות היו רחבות יותר מהמבוקש. שמרו את האזהרה הזאת, הסבירו את המסנן שהתעלמו ממנו, ותקנו את השאילתה לפני שאתם ממליצים על התוצאות האלה.

הרצות ה-Agent המקומיות שלנו כיסו את קו הבסיס, את הדיוק, תוצאות ריקות וחיפוש של שני עמודים. בדיקות API נפרדות כיסו מחירים חסרים, פאות קלף ואזהרות תחביר. השתמשו במתקן מבוקר כדי לבדוק מגבלת קצב בלי לשלוח תעבורה עודפת.

תיעוד נקודת הקצה לחיפוש קלפים מציין כרגע שתי בקשות חיפוש בשנייה. שמרו על מרווח של לפחות 500 מילישניות בין בקשות. המדריך הזה הוא עוזר חיפוש אישי. בוט ציבורי שמשרת שחקנים רבים צריך מגבלת קצב משותפת ומטמון. בקשה מהמודל להאט אינה אוכפת מגבלת בקשות גלובלית.

האם ChatGPT או Claude יכולים לעזור להגדיר את זה?

אפשר להשתמש ב-תוסף Quickchat AI עבור ChatGPT או ב-מחבר Quickchat AI עבור Claude כדי להגדיר את ה-Agent דרך חיבור ניהול החשבון. השלימו את ההתחברות בעצמכם, ואז ספקו את המדריך הזה ואת ה-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. במדריך הזה תבנו את העוזר הזה ב-Quickchat AI ותגרמו לו להציג את השאילתה, את רשומות הקלפים המקושרות ואת טקסט ה-Oracle הרלוונטי, כדי שתוכלו לבדוק את הפרשנות.

האם אני צריך מפתח API של Scryfall?

לא. נקודת הקצה הציבורית לחיפוש קלפים אינה דורשת חשבון או מפתח API. שלחו כותרות User-Agent ו-Accept מזהות, פעלו לפי מגבלות הקצב של Scryfall, ובקשו עמודים נוספים במכוון.

האם מאתר הקלפים הזה מבוסס AI יכול להזות קלף?

ההוראות מגבילות את ההמלצות לרשומות שהוחזרו על ידי ה-Action, עם קישורי Scryfall. המודל עדיין יכול לטעות, לכן בדקו את המזהה שהוחזר ואת טקסט ה-Oracle, ובחנו שם קלף בלתי אפשרי לפני שאתם מסתמכים על העוזר.

מה ההבדל בין id<=g לבין id=g ב-Scryfall?

id<=g כולל זהויות צבע ירוקות וחסרות צבע, ולכן הוא מתאים לחיפוש בתוך הצבעים של מפקד ירוק מונוצבעי. id=g דורש זהות ירוקה בדיוק. זהות צבע שונה מצבע הקלף עצמו. השתמשו במסנן הזהות לצורך בניית חפיסת Commander.

האם המחירים של Scryfall מובטחים?

לא. השדה prices.usd הוא נתון תמחור של ספק עבור ההדפסה שהוחזרה, ולא הצעה ממוכר. הערך שלו יכול להיות null. המסנן usd<5 מחפש מתחת לחמישה דולרים אמריקאיים. הוא אינו קובע עלויות משלוח, זמינות, או מהי ההדפסה הזולה ביותר שאפשר בפועל לרכוש.

האם חיפוש אחד מחזיר כל קלף תואם?

חיפוש מחזיר עמוד API אחד. התגובה כוללת את total_cards, את has_more, וכאשר זה רלוונטי גם את next_page. Open Query מציג עד חמש המלצות מתוך העמוד שנשלף. בקשו עוד תוצאות מאותו עמוד, או בקשו במפורש את עמוד ה-API הבא. רשימה קצרה אינה קבוצת התוצאות המלאה.

האם זה יכול לבנות את כל חפיסת ה-Commander שלי?

המדריך הזה בונה עוזר לחיפוש קלפים. הוא עוזר למצוא ולבדוק מועמדים למשבצת בחפיסה. הוא אינו מאמת חפיסה מלאה של 100 קלפים, אינו ממטב רשימת חפיסה, ואינו מחליף שופט חוקים.