Створіть AI-пошук карт Commander за допомогою Scryfall

Пошук карт Scryfall Commander перетворює опис потрібної вам карти на пошук, який можна перевірити. У цьому посібнику ви створите Open Query, агента Quickchat AI, який показує свій запит Scryfall, повертає справжні записи карт і пояснює, чому кожен кандидат може підійти вашій колоді.

Почніть з одного слота в моно-зеленій колоді Commander. Вам потрібна істота з trample і ціною нижче п’яти доларів США. Наприкінці ви зможете ввести такий запит, відкрити повернуті карти й уточнити пошук, не запам’ятовуючи кожен оператор.

Корисна частина починається тоді, коли запит стає складнішим. «Draw when another creature enters» звучить точно, але пошук за словами enters і draw також знаходить карти, які роблять щось інше. Ви виявите цю невідповідність і звузите запит, використовуючи повернутий текст карти як доказ.

Що ви створите і що вам потрібно?

Ви підключите одну read-only API Action до Scryfall, дасте Агенту інструкції для пошуку і протестуєте його в розмові. Action викликає фіксований URL. Модель передає запит і номер сторінки. Scryfall повертає записи, на яких ґрунтується відповідь.

1. Створіть обліковий запис Quickchat AI і Агента з назвою Open Query. Вам потрібні доступні AI-кредити для розмов і тестів. Дивіться актуальні плани.
2. Тримайте під рукою Identity, Actions & MCPs і AI Preview Агента під час роботи. Завантаження колекції карт не потрібне.
3. Використовуйте публічний API Scryfall. Для цих пошуків вам не потрібні обліковий запис Scryfall чи API-ключ.

Стартовий набір містить 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 для пошуку в межах кольорів синьо-червоноого командира. Це обмеження ідентичності, а не повна перевірка легальності колоди.

У довідці із синтаксису пошуку від Scryfall пояснюються ці оператори. Для цього посібника залишайте запит видимим у кожній відповіді, щоб помітити пропущений колір, неочікувану валюту або пошук, який ширший за ваш запит.

Крок 2: Як підключити API Scryfall до вашого Агента?

Створіть один API Action, який надсилає запит GET до endpoint пошуку карт Scryfall. Його фіксовані налаштування вибирають постачальника й порядок сортування. Його два параметри дають Агенту змогу вибирати пошук і сторінку.

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 додайте ці обов’язкові параметри. Агент може заповнювати їх із розмови. Позначка не означає, що він обов’язково має просити вас вводити сирий синтаксис запиту.

Налаштуйте endpoint, параметри запиту та заголовки

Виберіть GET і введіть:

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

У розділі Query Params додайте чотири рядки нижче. Для динамічних значень використовуйте Add AI Data, щоб вибрати створений вами параметр. Позначення {{query}} і {{page}} нижче представляють ці чипи параметрів.

Використовуйте поля параметрів запиту, щоб пробіли, лапки й оператори кодувалися як значення параметрів. URL endpoint має залишатися фіксованим.

Залиште 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 описує ці поля.

У 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: Як пошук карт має пояснювати свої результати?

Агенту потрібні інструкції, щоб показувати свій запит, прив’язувати рекомендації до повернутих записів і відрізняти збіг слова від взаємодії за правилами. Відкрийте Identity → Main Prompt і вставте повний prompt зі стартового набору, відтворений нижче.

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 впорядковані за назвою, а не за відповідністю. Агент вибирає короткий список із завантаженої сторінки. 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. Його draw відбувається, коли входить сама 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 повідомив, що проігнорував недійсний вираз. Тому результати були ширшими, ніж запитувалося. Збережіть це попередження, поясніть проігнорований фільтр і виправте запит, перш ніж рекомендувати ці результати.

Запуски нашого локального Агента охопили базовий сценарій, уточнення, порожні результати та пошук на двох сторінках. Окремі перевірки API охопили відсутні ціни, грані карт і попередження синтаксису. Для тестування ліміту швидкості використовуйте контрольований фікстур, не надсилаючи зайвий трафік.

У документації endpoint пошуку карт наразі вказано два пошукові запити за секунду. Тримайте інтервал між запитами щонайменше 500 мілісекунд. Цей посібник є персональним помічником для пошуку. Публічному боту, який обслуговує багатьох гравців, потрібні спільне обмеження швидкості та кешування. Прохання до моделі сповільнитися не забезпечує глобального ліміту запитів.

Чи можуть ChatGPT або Claude допомогти налаштувати це?

Ви можете використати плагін Quickchat AI для ChatGPT або конектор Quickchat AI для Claude, щоб налаштувати Агента через з’єднання керування обліковим записом. Самостійно завершіть вхід, а потім надайте цей посібник і його стартовий набір із таким запитом:

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?

Ні. Публічний endpoint пошуку карт не потребує облікового запису чи API-ключа. Надсилайте ідентифікаційні заголовки User-Agent і Accept, дотримуйтеся лімітів швидкості Scryfall і запитуйте додаткові сторінки свідомо.

Чи може цей AI-пошук карт вигадати карту?

Інструкції обмежують рекомендації записами, повернутими Action, з посиланнями Scryfall. Модель усе одно може помилятися, тож перевіряйте повернений ID і текст 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 карт, не оптимізує список колоди і не замінює суддю з правил.