Соберите ИИ-поисковик карт Commander с помощью Scryfall

Поисковик карт Scryfall Commander на базе ИИ превращает описание нужной вам карты в поиск, который можно проверить. В этом руководстве вы соберете Open Query, Agent для Quickchat AI, который показывает свой запрос Scryfall, возвращает реальные записи карт и объясняет, почему каждый кандидат может подойти вашей колоде.

Начните с одного слота в моно-зеленой колоде Commander. Вам нужно существо с trample и ценой ниже пяти долларов США. К концу вы сможете ввести такой запрос, открыть возвращенные карты и уточнить поиск, не запоминая каждый оператор.

Полезная часть начинается, когда запрос становится сложнее. «Draw when another creature enters» звучит точно, но поиск по словам enters и draw также находит карты, которые делают что-то другое. Вы поймаете это несоответствие и сузите запрос, используя возвращенный текст карт как доказательство.

Что вы соберете и что вам понадобится?

Вы подключите один read-only API Action к Scryfall, зададите Agent инструкции для поиска и протестируете его в разговоре. Action вызывает фиксированный URL. Модель передает запрос и номер страницы. Scryfall возвращает записи, на которые опирается ответ.

1. Создайте аккаунт Quickchat AI и Agent с именем Open Query. Для разговоров и тестов вам нужны доступные AI credits. См. актуальные тарифы.
2. Держите под рукой Identity, Actions & MCPs и AI Preview Agent во время работы. Загружать коллекцию карт не нужно.
3. Используйте публичный API Scryfall. Для этих поисков вам не нужен аккаунт или API-ключ Scryfall.

Стартовый набор содержит Main Prompt, рецепт Action, пути response filter и тестовые сообщения. В примерах используются английский текст 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 к вашему Agent?

Создайте один API Action, который отправляет запрос GET к эндпоинту поиска карт Scryfall. Его фиксированные настройки выбирают поставщика и сортировку, а два параметра позволяют Agent выбирать поиск и страницу.

1. Откройте Actions & MCPs → Add Action → API Action.
2. Используйте запрос для builder ниже, затем сверьте сгенерированные настройки с рецептом. Руководство по 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 может заполнять их из разговора. Метка не означает, что он обязан просить вас вводить сырой синтаксис запроса.

Задайте эндпоинт, параметры запроса и заголовки

Выберите GET и введите:

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

В разделе Query Params добавьте четыре строки ниже. Для динамических значений используйте Add AI Data, чтобы выбрать созданный вами параметр. Обозначения {{query}} и {{page}} ниже представляют эти chips параметров.

Используйте поля параметров запроса, чтобы пробелы, кавычки и операторы кодировались как значения параметров. 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 описывает эти поля.

В 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 и вставьте полный 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, зеленую-или-бесцветную идентичность, тип creature, 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 охватывали отсутствующие цены, лицевые стороны карт и предупреждения синтаксиса. Для тестирования rate limiting используйте контролируемый fixture, не создавая лишний трафик.

В документации эндпоинта поиска карт сейчас указано два поисковых запроса в секунду. Держите интервал между запросами не менее 500 миллисекунд. Это руководство предназначено для личного помощника по поиску. Публичному боту для многих игроков понадобятся общее ограничение скорости и кэширование. Просьба к модели замедлиться не обеспечивает глобальный лимит запросов.

Может ли ChatGPT или Claude помочь настроить это?

Вы можете использовать плагин Quickchat AI для ChatGPT или коннектор Quickchat AI для Claude, чтобы настроить Agent через подключение управления аккаунтом. Самостоятельно завершите вход в систему, затем передайте это руководство и его стартовый набор со следующим запросом:

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 на естественном языке?

ИИ-помощник может перевести запрос на обычном языке в синтаксис поиска Scryfall и выполнить его через API Scryfall. В этом руководстве вы соберете такого помощника в Quickchat AI и настроите его так, чтобы он показывал запрос, связанные записи карт и релевантный текст Oracle, чтобы вы могли проверить интерпретацию.

Нужен ли мне API-ключ Scryfall?

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

Может ли этот ИИ-поисковик карт галлюцинировать карту?

Инструкции ограничивают рекомендации записями, возвращенными 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 карт, не оптимизирует деклист и не заменяет судью по правилам.