Изградете AI търсачка за карти Commander с Scryfall

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

Започнете с едно място в моно-зелено тесте Commander. Искате същество с trample и цена под пет щатски долара. До края ще можете да въведете тази заявка, да отворите върнатите карти и да прецизирате търсенето, без да запомняте всеки оператор.

Полезната част идва, когато заявката стане по-трудна. „Тегли, когато друго същество влезе“ звучи точно, но търсене за думите enters и draw намира и карти, които правят нещо друго. Ще уловите това несъответствие и ще стесните заявката, като използвате върнатия текст на картата като доказателство.

Какво ще изградите и от какво се нуждаете?

Ще свържете едно read-only 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 за тези търсения.

Стартовият комплект съдържа 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. Използвайте заявката за билдъра по-долу, след което прегледайте генерираните настройки спрямо рецептата. Ръководството за билдъра 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 и поставете пълния 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 са подредени по име, а не класирани по пригодност. 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 и създайте dataset с име 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 чрез връзката за управление на акаунта. Завършете влизането сами, след което предоставете този урок и стартовия комплект със следната заявка:

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. Моделът все пак може да допусне грешки, затова проверете върнатия 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 карти, не оптимизира списък с тесте и не замества съдия по правилата.