Scryfall ile bir yapay zeka Commander Kart Bulucu oluşturun

Bir Scryfall Commander kart bulucu, ihtiyacınız olan kartın açıklamasını inceleyebileceğiniz bir aramaya dönüştürür. Bu eğitimde, Scryfall sorgusunu gösteren, gerçek kart kayıtları döndüren ve her adayın destenize neden uyabileceğini açıklayan bir Quickchat AI Agent olan Open Query oluşturacaksınız.

Tek yeşil bir Commander destesindeki tek bir yuvayla başlayın. Trample olan ve fiyatı beş ABD dolarının altında olan bir yaratık istiyorsunuz. Eğitimin sonunda bu isteği yazabilecek, dönen kartları açabilecek ve her operatörü ezberlemeden aramayı daraltabileceksiniz.

İşin faydalı kısmı, istek zorlaştığında ortaya çıkar. “Başka bir yaratık oyuna girdiğinde kart çek” kulağa net gelir, ancak enters ve draw kelimeleri için yapılan bir arama, başka şeyler yapan kartları da bulur. Dönen kart metnini kanıt olarak kullanarak bu uyumsuzluğu yakalayacak ve sorguyu daraltacaksınız.

Ne oluşturacaksınız ve nelere ihtiyacınız var?

Bir salt okunur API Action öğesini Scryfall’a bağlayacak, Agent’a arama talimatlarını verecek ve bunu bir konuşmada test edeceksiniz. Action sabit bir URL çağırır; model bir sorgu ve sayfa numarası sağlar. Scryfall, yanıtın dayandığı kayıtları döndürür.

1. Bir Quickchat AI hesabı oluşturun ve Open Query adlı bir Agent yaratın. Konuşmalar ve testler için kullanılabilir AI kredilerine ihtiyacınız vardır; güncel planlara bakın.
2. Çalışırken Agent’ın Identity, Actions & MCPs ve AI Preview bölümlerini erişilebilir tutun. Kart koleksiyonu yüklemeniz gerekmez.
3. Scryfall’ın herkese açık API’sini kullanın. Bu aramalar için bir Scryfall hesabına veya API anahtarına ihtiyacınız yoktur.

Başlangıç kiti, Main Prompt, Action tarifi, yanıt filtresi yolları ve test mesajlarını içerir. Örneklerde İngilizce Oracle metni ve USD fiyatları kullanılır. Başka bir dilde ilerlerken sorgu operatörlerini ve kart adlarını yazıldığı gibi koruyun.

Adım 1: Bir kart isteğini Scryfall sorgusuna nasıl dönüştürürsünüz?

Bir Scryfall sorgusu, boşluklarla ayrılmış kısıtları birleştirir. İlk isteğimiz için şunu kullanın:

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

İki küçük tercih önemlidir. kw:trample anahtar kelimeyi arar; o:trample ise Oracle metnindeki kelimeyi arar. Bir yaratık trample’dan bahsedebilir ama bu yeteneğe kendisi sahip olmayabilir. İkisini de test ettik; metin araması daha geniş bir küme üretti.

“Tek yeşil bir desteye uyar” ifadesi de “tam olarak yeşil kimliğe sahiptir” ifadesinden farklıdır. İlki renksiz kartlara izin verir. İkincisi için id=g kullanın veya mavi kırmızı bir komutanın renkleri içinde arama yapmak için id<=ur kullanın. Bunlar kimlik kısıtlarıdır, tam bir deste yasallığı kontrolü değildir.

Scryfall’ın arama sözdizimi başvurusu bu operatörleri açıklar. Bu eğitim için sorguyu her yanıtta görünür tutun ki eksik bir rengi, beklenmeyen bir para birimini veya isteğinizden daha geniş bir aramayı fark edebilin.

Adım 2: Scryfall API’sini Agent’ınıza nasıl bağlarsınız?

Scryfall’ın kart arama uç noktasına bir GET isteği gönderen tek bir API Action oluşturun. Sabit ayarları sağlayıcıyı ve sıralamayı seçer; iki parametresi ise Agent’ın aramayı ve sayfayı seçmesine izin verir.

1. Actions & MCPs → Add Action → API Action yolunu açın.
2. Aşağıdaki oluşturucu isteğini kullanın, ardından üretilen ayarları tarifle karşılaştırarak gözden geçirin. API Action oluşturucu kılavuzu, üretim ve gözden geçirme akışını açıklar.
3. API Action Name değerini Search Scryfall cards olarak ayarlayın.

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.

İki parametreyi tanımlayın

What to ask the user first altında bu zorunlu parametreleri ekleyin. Agent bunları konuşmadan doldurabilir; etiket, sizden ham sorgu sözdizimini yazmanızı istemesi gerektiği anlamına gelmez.

Uç noktayı, sorgu parametrelerini ve başlıkları ayarlayın

GET seçin ve şunu girin:

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

Query Params altında aşağıdaki dört satırı ekleyin. Dinamik değerler için oluşturduğunuz parametreyi seçmek üzere Add AI Data kullanın. Aşağıdaki {{query}} ve {{page}} gösterimi, bu parametre çiplerini temsil eder.

Boşlukların, tırnak işaretlerinin ve operatörlerin parametre değerleri olarak kodlanması için sorgu parametresi alanlarını kullanın. Uç nokta URL’sini sabit tutun.

Body alanını boş bırakın. Kimlik doğrulama gerekmez. User-Agent, bir kimlik bilgisi değil tanımlayıcı bir istemci adıdır; sürümünüzü dağıtırken kendi uygun uygulama adınızı ve iletişim URL’nizi kullanın.

Yanıtı kullanışlı tutun

Bir Scryfall sayfası birçok kayıt içerebilir. Agentin ihtiyaç duyduğu alanları, ayrıca daha fazla sayfa olup olmadığını ona söyleyen bilgilerle birlikte tutun. Advanced settings bölümünü genişletin ve Response filter öğesini bulun. Add JSONPath seçeneğini, ardından artı düğmesini kullanarak aşağıdaki her yolu ayrı bir giriş olarak ekleyin:

$.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 alanını koruyun. Bazı kartlar metinlerini üst düzeyde değil, tek tek yüzlerde taşır. warnings alanını da koruyun: bir HTTP başarısı, Scryfall’ün her koşulu amaçlandığı gibi yorumladığı anlamına gelmez. Kart nesnesi başvurusu bu alanları açıklar.

API Action Description içine şunu yapıştırın:

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’ı kaydedin ve etkin olduğunu kontrol edin. HTTP Action anatomy guide, parametrelerin, isteğin ve açıklamanın birlikte nasıl çalıştığını açıklar.

Adım 3: Kart bulucu sonuçlarını nasıl açıklamalı?

Agent’ın sorgusunu göstermesi, önerileri dönen kayıtlara dayandırması ve bir kelime eşleşmesi ile bir kural etkileşimini ayırt etmesi için talimatlara ihtiyacı vardır. Identity → Main Prompt yolunu açın ve aşağıda yeniden verilen başlangıç kitindeki tam prompt’u yapıştırın.

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.

Şimdi AI Preview bölümünü açın ve şunu gönderin:

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

Demo, tek yeşil deste uygunluğunu yeşil veya renksiz olarak yorumladı. Tam olarak yeşil kimlik için bunu açıkça belirtin.

Önerilerden önce çalıştırılan sorguyu okuyun. Sorgu, Commander, yeşil veya renksiz kimlik, yaratık türü, trample ve 5 USD altını korumalıdır. Bir kartın Scryfall bağlantısını açın ve ilgili metni, kimliği ve fiyatı yanıtla karşılaştırın. Fiyat, dönen baskı için bir arama gözlemidir, ödeme ekranı teklifi değildir.

API sonuçları uygunluğa göre sıralanmaz, ada göre sıralanır. Agent, getirilen sayfadan kısa bir liste seçer. unique=cards, her baskının ayrı bir sonuç olarak listelenmesini önler; seçilen kaydın satın alabileceğiniz en ucuz kopya olduğu anlamına gelmez.

Adım 4: Yanlış etkileşimi bulan bir aramayı nasıl düzeltirsiniz?

Bir karşı örneği okuyup eksik koşulu ekleyerek sorguyu daraltın. Daraltma boyunca aday kartları bulmak ile metinlerini doğrulamak arasındaki ayrımı koruyun.

Şunu sorun:

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

Geniş bir aday araması şöyledir:

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

10 Kasım 2026 tarihindeki doğrudan Scryfall kontrolümüzde bu arama 161 aday döndürdü; bunlara Abundant Growth da dahildi. Bunun kart çekmesi Aura’nın kendisi oyuna girdiğinde gerçekleşir. Her iki kelimeyi de içerir, ancak isteğin ima ettiği tekrar edilebilir yaratık girişli kart çekme motorunu sağlamaz.

Şu daraltmayı deneyin:

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

Kontrol ettiğimiz daha dar sorgu şuydu:

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

Daraltılmış arama dört aday döndürdü. Garruk’s Packleader faydalı bir koşullu eşleşmedir: diğer yaratığın gücünün 3 veya daha fazla olması gerekir. Bu ayrım öneride yer almalıdır. Çok sayıda 1/1 yaratık içeren bir token stratejisi farklı bir karta ihtiyaç duyabilir.

Yalnızca o:"another creature" eklemek daha az kesindir. Testimiz yine, kendi oyuna girişi sizi başka bir yaratığı feda etmeye ve kart çekmeye götürebilen Disciple of Freyalise kartını buldu. Bu da, ek bir ifadeyi kanıt saymak yerine tüm yeteneği incelemeniz için başka bir nedendir.

Kendi desteniz için de aynı döngüyü tekrarlayın: istek → sorgu → kart metni → bir daraltma. Bütçe tüm faydalı adayları eliyorsa, bunu genişletmeden önce sorun. Bir kartın bir kısıtlaması varsa, açıklamadan sessizce çıkarmak yerine kısıtlamayı söyleyin.

Adım 5: Kart bulucuyu kullanmadan önce nasıl test edersiniz?

Hem yanıtı hem de API çağrısını test edin. İkna edici bir cümle, hangi sorgunun çalıştığını veya hangi kayıtların geri döndüğünü kanıtlayamaz.

1. Testing bölümünü açın ve Create Dataset → Paste messages yolunu kullanarak Open Query checks adlı bir veri kümesi oluşturun. Kitteki bağımsız test mesajlarını yapıştırın.
2. Testleri çalıştırın. Yanıtın sorgusunu gösterip göstermediğini, dönen kartlara atıf yapıp yapmadığını ve belirsizliği açıklayıp açıklamadığını değerlendirin.
3. Eşleşen konuşmayı Inbox içinde açın ve Action çağrısını inceleyin. Sorguyu, sayfa numarasını, durumu ve dönen alanları kontrol edin. Tekil çağrıları bulmak için Action’ın View logs denetimini kullanın.
4. Önceki sorgunun erişilebilir olduğu devam eden bir konuşmada daraltmayı ve sayfalamayı test edin.

Eşleşme olmayan test için şunu gönderin:

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

Doğrudan yapılan bir API testi, uyarıların neden önemli olduğunu gösterdi. Bozuk sorgu f:commander o:/[/ HTTP 200 döndürdü, ancak Scryfall geçersiz ifadeyi yok saydığını bildirdi. Bu nedenle sonuçlar istenenden daha genişti. Bu uyarıyı koruyun, yok sayılan filtreyi açıklayın ve bu sonuçları önermeden önce sorguyu düzeltin.

Yerel Agent çalıştırmalarımız temel senaryoyu, daraltmayı, boş sonuçları ve iki sayfalı bir aramayı kapsadı. Ayrı API kontrolleri eksik fiyatları, kart yüzlerini ve sözdizimi uyarılarını kapsadı. Fazla trafik göndermeden oran sınırlamasını test etmek için kontrollü bir fixture kullanın.

Kart arama uç noktası belgeleri şu anda saniyede iki arama isteği belirtmektedir. İstekler arasında en az 500 milisaniye bırakın. Bu eğitim kişisel bir arama yardımcısıdır; çok sayıda oyuncuya hizmet veren herkese açık bir botun paylaşılan oran sınırlaması ve önbellekleme kullanması gerekir. Modele yavaşlamasını söylemek, genel bir istek sınırını uygulamaz.

ChatGPT veya Claude bunu yapılandırmaya yardımcı olabilir mi?

Agent’ı hesap yönetimi bağlantısı üzerinden yapılandırmak için ChatGPT için Quickchat AI eklentisini veya Claude için Quickchat AI bağlayıcısını kullanabilirsiniz. Oturum açmayı kendiniz tamamlayın, ardından bu eğitimi ve başlangıç kitini aşağıdaki istekle birlikte sağlayın:

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.

Hesap yönetimi belgeleri bağlantıyı açıklar. Bu, Quickchat AI hesabınızı yapılandırır; Open Query’ün diğer kişiler için otomatik olarak bir MCP aracı olarak kullanılabilir hale gelmesini sağlamaz.

Sık sorulan sorular

Scryfall için doğal dilde arama yapabilir miyim?

Bir yapay zeka asistanı, düz dille yazılmış bir isteği Scryfall arama sözdizimine çevirebilir ve bunu Scryfall API üzerinden çalıştırabilir. Bu eğitim, bu asistanı Quickchat AI içinde oluşturur ve yorumu kontrol edebilmeniz için sorguyu, bağlantılı kart kayıtlarını ve ilgili Oracle metnini göstermesini sağlar.

Scryfall API anahtarına ihtiyacım var mı?

Hayır. Herkese açık kart arama uç noktası bir hesap veya API anahtarı gerektirmez. Tanımlayıcı User-Agent ve Accept başlıkları gönderin, Scryfall oran sınırlarına uyun ve ek sayfaları bilinçli şekilde isteyin.

Bu yapay zeka kart bulucu olmayan bir kart uydurabilir mi?

Talimatlar, önerileri Action tarafından döndürülen kayıtlarla ve Scryfall bağlantılarıyla sınırlar. Model yine de hata yapabilir, bu yüzden asistana güvenmeden önce dönen kimliği ve Oracle metnini kontrol edin ve imkansız bir kart adıyla test yapın.

Scryfall üzerinde id<=g ile id=g arasındaki fark nedir?

id<=g, yeşil ve renksiz kimlikleri içerir; bu da tek yeşil bir komutanın renkleri içinde arama yapmak için uygundur. id=g ise tam olarak yeşil kimlik gerektirir. Renk kimliği, kart renginden farklıdır; Commander deste oluştururken kimlik filtresini kullanın.

Scryfall fiyatları garanti midir?

Hayır. prices.usd alanı, dönen baskı için sağlayıcı fiyat verisidir; bir satıcının teklifi değildir. null olabilir. usd<5 filtresi beş ABD dolarının altını arar; kargo maliyetlerini, bulunabilirliği veya satın alınabilir en ucuz baskıyı belirlemez.

Tek bir arama eşleşen tüm kartları döndürür mü?

Bir arama bir API sayfası döndürür. Yanıt total_cards, has_more ve uygun olduğunda next_page içerir. Open Query, getirilen sayfadan en fazla beş öneri gösterir. O sayfadan daha fazlasını isteyin veya açıkça bir sonraki API sayfasını talep edin; kısa liste tam sonuç kümesi değildir.

Bu, tüm Commander destemi kurabilir mi?

Bu eğitim bir kart arama asistanı oluşturur. Bir deste yuvası için adayları bulup incelemeye yardımcı olur. Tam 100 kartlık bir desteyi doğrulamaz, deste listesini optimize etmez veya bir kural hakeminin yerini almaz.