Zbuduj wyszukiwarkę kart AI Commander z Scryfall

Wyszukiwarka kart Scryfall Commander zamienia opis potrzebnej karty w wyszukiwanie, które możesz sprawdzić. W tym poradniku zbudujesz Open Query, Agenta Quickchat AI, który pokazuje swoje zapytanie Scryfall, zwraca prawdziwe rekordy kart i wyjaśnia, dlaczego każdy kandydat może pasować do Twojej talii.

Zacznij od jednego miejsca w monozielonej talii Commander. Chcesz stwora z trample i ceną poniżej pięciu dolarów amerykańskich. Pod koniec będziesz w stanie wpisać taką prośbę, otworzyć zwrócone karty i dopracować wyszukiwanie bez zapamiętywania każdego operatora.

Przydatna część zaczyna się wtedy, gdy prośba staje się trudniejsza. „Draw when another creature enters” brzmi precyzyjnie, ale wyszukiwanie słów enters i draw znajduje też karty, które robią coś innego. Wychwycisz to niedopasowanie i zawęzisz zapytanie, używając zwróconego tekstu kart jako dowodu.

Co zbudujesz i czego potrzebujesz?

Połączysz jedno tylko do odczytu API Action z Scryfall, przekażesz Agentowi instrukcje wyszukiwania i przetestujesz go w rozmowie. Action wywołuje stały URL. Model podaje zapytanie i numer strony. Scryfall zwraca rekordy, z których odpowiedź czerpie informacje.

1. Utwórz konto Quickchat AI i Agenta o nazwie Open Query. Potrzebujesz dostępnych kredytów AI do rozmów i testów. Zobacz aktualne plany.
2. Miej pod ręką Identity, Actions & MCPs i AI Preview Agenta podczas pracy. Nie trzeba przesyłać kolekcji kart.
3. Użyj publicznego API Scryfall. Do tych wyszukiwań nie potrzebujesz konta ani klucza API Scryfall.

Pakiet startowy zawiera Main Prompt, recepturę Action, ścieżki filtra odpowiedzi i wiadomości testowe. Przykłady używają angielskiego tekstu Oracle i cen w USD. Podczas pracy w innym języku pozostaw operatory zapytań i nazwy kart zapisane dokładnie tak jak tutaj.

Krok 1: Jak zamienić prośbę o kartę w zapytanie Scryfall?

Zapytanie Scryfall łączy ograniczenia oddzielone spacjami. Dla naszej pierwszej prośby użyj:

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

Znaczenie mają dwa drobne wybory. kw:trample wyszukuje słowo kluczowe. o:trample wyszukuje słowo w tekście Oracle. Stwór może wspominać o trample, sam tej zdolności nie mając. Przetestowaliśmy oba warianty. Wyszukiwanie po tekście dało szerszy zestaw.

„Pasuje do monozielonej talii” różni się też od „ma dokładnie zieloną tożsamość”. To pierwsze dopuszcza karty bezkolorowe. Użyj id=g dla tego drugiego albo id<=ur, aby wyszukiwać w kolorach niebiesko-czerwonego commandera. To ograniczenia tożsamości, a nie pełna kontrola legalności talii.

Odwołanie do składni wyszukiwania w Scryfall wyjaśnia te operatory. Na potrzeby tego poradnika utrzymuj zapytanie widoczne w każdej odpowiedzi, aby zauważyć pominięty kolor, nieoczekiwaną walutę albo wyszukiwanie szersze niż Twoja prośba.

Krok 2: Jak połączyć API Scryfall ze swoim Agentem?

Utwórz jedno API Action, które wysyła żądanie GET do endpointu wyszukiwania kart Scryfall. Jego stałe ustawienia wybierają dostawcę i kolejność sortowania. Dwa parametry pozwalają Agentowi wybrać wyszukiwanie i stronę.

1. Otwórz Actions & MCPs → Add Action → API Action.
2. Użyj poniższego żądania buildera, a następnie porównaj wygenerowane ustawienia z recepturą. Przewodnik po builderze API Action wyjaśnia proces generowania i przeglądu.
3. Ustaw API Action Name na 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.

Zdefiniuj dwa parametry

W sekcji What to ask the user first dodaj te wymagane parametry. Agent może wypełnić je na podstawie rozmowy. Etykieta nie oznacza, że musi prosić Cię o wpisanie surowej składni zapytania.

Ustaw endpoint, parametry zapytania i nagłówki

Wybierz GET i wpisz:

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

W sekcji Query Params dodaj cztery poniższe wiersze. Dla wartości dynamicznych użyj Add AI Data, aby wybrać utworzony parametr. Zapis {{query}} i {{page}} poniżej oznacza te chipy parametrów.

Używaj pól parametrów zapytania, aby spacje, cudzysłowy i operatory były kodowane jako wartości parametrów. Zachowaj stały URL endpointu.

Pozostaw Body puste. Uwierzytelnianie nie jest potrzebne. User-Agent to identyfikująca nazwa klienta, a nie poświadczenie. Przy wdrażaniu swojej wersji użyj własnej odpowiedniej nazwy aplikacji i adresu URL kontaktowego.

Zachowaj użyteczność odpowiedzi

Strona Scryfall może zawierać wiele rekordów. Zachowaj pola, których Agent potrzebuje, wraz z informacją mówiącą mu, czy istnieją kolejne strony. Rozwiń Advanced settings i znajdź Response filter. Użyj Add JSONPath, a następnie przycisku plus, aby dodać każdą poniższą ścieżkę jako osobny wpis:

$.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

Zachowaj card_faces. Niektóre karty umieszczają swój tekst na poszczególnych stronach zamiast na najwyższym poziomie. Zachowaj też warnings: sukces HTTP nie oznacza, że Scryfall zinterpretował każdą klauzulę zgodnie z zamiarem. Opis obiektu Card przedstawia te pola.

W sekcji API Action Description wklej:

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.

Zapisz Action i sprawdź, czy jest aktywne. Przewodnik po anatomii HTTP Action wyjaśnia, jak parametry, żądanie i opis współpracują ze sobą.

Krok 3: Jak wyszukiwarka kart powinna wyjaśniać swoje wyniki?

Agent potrzebuje instrukcji, aby pokazywać swoje zapytanie, opierać rekomendacje na zwróconych rekordach i odróżniać dopasowanie słowa od interakcji zasad. Otwórz Identity → Main Prompt i wklej pełny prompt z pakietu startowego, odtworzony poniżej.

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.

Teraz otwórz AI Preview i wyślij:

Find Commander-legal creatures in mono-green color identity with trample, priced below 5 USD.

Demo zinterpretowało możliwość gry w monozielonej talii jako zieloną lub bezkolorową tożsamość. Jeśli chcesz dokładnie zieloną tożsamość, powiedz to wprost.

Przeczytaj wykonane zapytanie przed rekomendacjami. Powinno zachować Commander, zieloną-lub-bezkolorową tożsamość, typ stwora, trample i USD poniżej 5. Otwórz link Scryfall jednej karty i porównaj odpowiedni tekst, tożsamość i cenę z odpowiedzią. Cena jest obserwacją z odczytu dla zwróconego wydruku, a nie ofertą przy kasie.

Wyniki API są sortowane według nazwy, a nie według dopasowania. Agent wybiera krótką listę z pobranej strony. unique=cards pozwala uniknąć wypisywania każdego wydruku jako osobnego wyniku. Nie oznacza to, że wybrany rekord jest najtańszą kopią, jaką możesz kupić.

Krok 4: Jak naprawić wyszukiwanie, które znajduje złą interakcję?

Zawęź zapytanie, czytając kontrprzykład i dodając brakujący warunek. Podczas całego dopracowywania zachowuj rozróżnienie między znajdowaniem kart kandydatów a potwierdzaniem ich tekstu.

Zapytaj:

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

Szerokie wyszukiwanie kandydatów to:

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

W naszym bezpośrednim sprawdzeniu Scryfall z 10 listopada 2026 r. zwróciło to 161 kandydatów, w tym Abundant Growth. Dobranie następuje tam, gdy sama Aura wchodzi na pole bitwy. Zawiera oba słowa, ale nie zapewnia powtarzalnego silnika dobierania przy wejściu stwora, jaki sugeruje prośba.

Wypróbuj takie dopracowanie:

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

Węższe zapytanie, które sprawdziliśmy, brzmiało:

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

Dopracowane wyszukiwanie zwróciło czterech kandydatów. Garruk’s Packleader jest użytecznym warunkowym dopasowaniem. Ten drugi stwór musi mieć siłę 3 lub większą. To rozróżnienie powinno znaleźć się w rekomendacji. Strategia tokenów z wieloma stworami 1/1 może potrzebować innej karty.

Dodanie samego o:"another creature" jest mniej precyzyjne. Nasz test nadal znalazł Disciple of Freyalise, którego własne wejście może doprowadzić Cię do poświęcenia innego stwora i dobrania karty. To kolejny powód, by sprawdzać całą zdolność zamiast traktować dodatkową frazę jako dowód.

Powtórz tę samą pętlę dla własnej talii: prośba → zapytanie → tekst karty → jedno dopracowanie. Jeśli budżet usuwa wszystkich użytecznych kandydatów, zapytaj, zanim go poszerzysz. Jeśli karta ma ograniczenie, podaj to ograniczenie zamiast po cichu usuwać je z wyjaśnienia.

Krok 5: Jak przetestować wyszukiwarkę kart przed użyciem?

Przetestuj zarówno odpowiedź, jak i wywołanie API. Przekonujące zdanie nie może potwierdzić, jakie zapytanie zostało uruchomione ani jakie rekordy wróciły.

1. Otwórz Testing i utwórz zbiór danych o nazwie Open Query checks za pomocą Create Dataset → Paste messages. Wklej niezależne wiadomości testowe z pakietu.
2. Uruchom testy. Oceń, czy odpowiedź pokazuje swoje zapytanie, cytuje zwrócone karty i wyjaśnia niepewność.
3. Otwórz pasującą rozmowę w Inbox i sprawdź wywołanie Action. Sprawdź zapytanie, numer strony, status i zwrócone pola. Użyj kontrolki View logs Action, aby znaleźć pojedyncze wywołania.
4. Przetestuj dopracowanie i paginację w kontynuowanej rozmowie, gdzie poprzednie zapytanie jest dostępne.

Dla testu bez dopasowań wyślij:

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

Jedno bezpośrednie sprawdzenie API pokazało, dlaczego ostrzeżenia mają znaczenie. Błędne zapytanie f:commander o:/[/ zwróciło HTTP 200, ale Scryfall zgłosiło, że zignorowało nieprawidłowe wyrażenie. Wyniki były więc szersze niż żądano. Zachowaj to ostrzeżenie, wyjaśnij zignorowany filtr i popraw zapytanie, zanim zarekomendujesz te wyniki.

Nasze lokalne uruchomienia Agenta obejmowały bazowy przypadek, dopracowanie, puste wyniki i wyszukiwanie na dwóch stronach. Osobne sprawdzenia API obejmowały brakujące ceny, strony kart i ostrzeżenia składni. Użyj kontrolowanego fixture do testowania limitu szybkości bez wysyłania nadmiernego ruchu.

Dokumentacja endpointu wyszukiwania kart obecnie określa dwa żądania wyszukiwania na sekundę. Zachowuj co najmniej 500 milisekund odstępu między żądaniami. Ten poradnik to osobisty pomocnik wyszukiwania. Publiczny bot obsługujący wielu graczy potrzebuje współdzielonego ograniczania szybkości i cache. Proszenie modelu, by zwolnił, nie wymusza globalnego limitu żądań.

Czy ChatGPT lub Claude mogą pomóc to skonfigurować?

Możesz użyć wtyczki Quickchat AI do ChatGPT albo konektora Quickchat AI do Claude, aby skonfigurować Agenta przez połączenie do zarządzania kontem. Samodzielnie dokończ logowanie, a następnie przekaż ten poradnik i jego pakiet startowy wraz z następującą prośbą:

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.

Dokumentacja zarządzania kontem wyjaśnia to połączenie. To konfiguruje Twoje konto Quickchat AI. Nie sprawia automatycznie, że Open Query staje się dostępne dla innych osób jako narzędzie MCP.

Często zadawane pytania

Czy mogę przeszukiwać Scryfall w języku naturalnym?

Asystent AI może przetłumaczyć prośbę zapisaną zwykłym językiem na składnię wyszukiwania Scryfall i wykonać ją przez API Scryfall. Ten poradnik buduje takiego asystenta w Quickchat AI i sprawia, że pokazuje on zapytanie, połączone rekordy kart oraz odpowiedni tekst Oracle, aby można było sprawdzić interpretację.

Czy potrzebuję klucza API Scryfall?

Nie. Publiczny endpoint wyszukiwania kart nie wymaga konta ani klucza API. Wysyłaj identyfikujące nagłówki User-Agent i Accept, przestrzegaj limitów szybkości Scryfall i świadomie żądaj kolejnych stron.

Czy ta wyszukiwarka kart AI może halucynować kartę?

Instrukcje ograniczają rekomendacje do rekordów zwróconych przez Action, z linkami Scryfall. Model nadal może popełniać błędy, więc sprawdź zwrócone ID i tekst Oracle oraz przetestuj niemożliwą nazwę karty, zanim zaczniesz polegać na asystencie.

Jaka jest różnica między id<=g a id=g w Scryfall?

id<=g obejmuje zielone i bezkolorowe tożsamości, co nadaje się do wyszukiwania w kolorach monozielonego commandera. id=g wymaga dokładnie zielonej tożsamości. Tożsamość kolorów różni się od koloru karty. Do budowy talii Commander używaj filtra tożsamości.

Czy ceny Scryfall są gwarantowane?

Nie. Pole prices.usd to dane cenowe dostawcy dla zwróconego wydruku, a nie oferta sprzedawcy. Może mieć wartość null. Filtr usd<5 wyszukuje poniżej pięciu dolarów amerykańskich. Nie określa kosztów wysyłki, dostępności ani najtańszego możliwego do kupienia wydruku.

Czy jedno wyszukiwanie zwraca każdą pasującą kartę?

Wyszukiwanie zwraca jedną stronę API. Odpowiedź zawiera total_cards, has_more oraz, gdy ma to zastosowanie, next_page. Open Query pokazuje do pięciu rekomendacji z pobranej strony. Poproś o więcej z tej strony albo wyraźnie zażądaj następnej strony API. Krótka lista nie jest pełnym zestawem wyników.

Czy to może zbudować całą moją talię Commander?

Ten poradnik buduje asystenta do wyszukiwania kart. Pomaga znajdować i sprawdzać kandydatów do miejsca w talii. Nie weryfikuje kompletnej talii 100 kart, nie optymalizuje decklisty i nie zastępuje sędziego zasad.