Bangun Pencari Kartu AI Commander dengan Scryfall

Pencari kartu Scryfall Commander mengubah deskripsi kartu yang Anda butuhkan menjadi pencarian yang bisa Anda periksa. Dalam tutorial ini, Anda akan membangun Open Query, Agent Quickchat AI yang menampilkan kueri Scryfall miliknya, mengembalikan rekaman kartu asli, dan menjelaskan mengapa setiap kandidat mungkin cocok untuk deck Anda.

Mulailah dengan satu slot dalam deck Commander mono-hijau. Anda menginginkan creature dengan trample dan harga di bawah lima dolar AS. Pada akhir tutorial, Anda dapat mengetik permintaan itu, membuka kartu yang dikembalikan, dan mempersempit pencarian tanpa harus menghafal setiap operator.

Bagian yang berguna muncul saat permintaannya menjadi lebih sulit. “Draw when another creature enters” terdengar presisi, tetapi pencarian untuk kata enters dan draw juga menemukan kartu yang melakukan hal lain. Anda akan menangkap ketidakcocokan itu dan mempersempit kuerinya, menggunakan teks kartu yang dikembalikan sebagai bukti.

Apa yang akan Anda bangun, dan apa yang Anda butuhkan?

Anda akan menghubungkan satu API Action baca-saja ke Scryfall, memberi Agent instruksi pencariannya, dan mengujinya dalam percakapan. Action memanggil URL tetap. Model menyediakan kueri dan nomor halaman. Scryfall mengembalikan rekaman yang menjadi dasar jawaban.

1. Buat akun Quickchat AI dan sebuah Agent bernama Open Query. Anda memerlukan kredit AI yang tersedia untuk percakapan dan pengujian. Lihat paket saat ini.
2. Simpan Identity, Actions & MCPs, dan AI Preview milik Agent tetap tersedia saat Anda bekerja. Tidak perlu mengunggah koleksi kartu.
3. Gunakan API publik Scryfall. Anda tidak memerlukan akun atau kunci API Scryfall untuk pencarian ini.

Starter kit berisi Main Prompt, resep Action, path filter respons, dan pesan pengujian. Contohnya menggunakan teks Oracle bahasa Inggris dan harga USD. Biarkan operator kueri dan nama kartu tetap seperti tertulis saat mengikuti tutorial ini dalam bahasa lain.

Langkah 1: Bagaimana Anda mengubah permintaan kartu menjadi kueri Scryfall?

Kueri Scryfall menggabungkan batasan yang dipisahkan oleh spasi. Untuk permintaan pertama kita, gunakan:

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

Dua pilihan kecil penting. kw:trample mencari keyword. o:trample mencari kata itu dalam teks Oracle. Sebuah creature dapat menyebut trample tanpa benar-benar memiliki kemampuan itu. Kami menguji keduanya. Pencarian teks menghasilkan kumpulan yang lebih luas.

“Cocok untuk deck mono-hijau” juga berbeda dari “memiliki identitas tepat hijau.” Yang pertama mengizinkan kartu tak berwarna. Gunakan id=g untuk yang kedua, atau id<=ur untuk mencari dalam warna commander biru-merah. Ini adalah batasan identitas, bukan pemeriksaan legalitas deck yang lengkap.

Referensi sintaks pencarian milik Scryfall menjelaskan operator-operator ini. Untuk tutorial ini, biarkan kueri terlihat di setiap jawaban agar Anda dapat melihat warna yang terlewat, mata uang yang tidak terduga, atau pencarian yang lebih luas daripada permintaan Anda.

Langkah 2: Bagaimana Anda menghubungkan API Scryfall ke Agent Anda?

Buat satu API Action yang mengirim permintaan GET ke endpoint pencarian kartu milik Scryfall. Pengaturan tetapnya memilih penyedia dan urutan. Dua parameternya memungkinkan Agent memilih pencarian dan halaman.

1. Buka Actions & MCPs → Add Action → API Action.
2. Gunakan permintaan builder di bawah ini, lalu tinjau pengaturan yang dihasilkan terhadap resepnya. Panduan builder API Action menjelaskan alur pembuatan dan peninjauan.
3. Atur API Action Name ke 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.

Tentukan dua parameter

Di bawah What to ask the user first, tambahkan parameter wajib berikut. Agent dapat mengisinya dari percakapan. Labelnya tidak berarti Agent harus meminta Anda mengetik sintaks kueri mentah.

Atur endpoint, parameter kueri, dan header

Pilih GET dan masukkan:

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

Di bawah Query Params, tambahkan empat baris di bawah ini. Untuk nilai dinamis, gunakan Add AI Data untuk memilih parameter yang Anda buat. Notasi {{query}} dan {{page}} di bawah ini mewakili chip parameter tersebut.

Gunakan field parameter kueri agar spasi, tanda kutip, dan operator dienkode sebagai nilai parameter. Biarkan URL endpoint tetap.

Biarkan Body kosong. Tidak diperlukan autentikasi. User-Agent adalah nama klien pengenal, bukan kredensial. Gunakan nama aplikasi dan URL kontak Anda sendiri yang sesuai saat menerapkan versi Anda.

Jaga agar respons tetap berguna

Halaman Scryfall dapat berisi banyak rekaman. Pertahankan field yang dibutuhkan Agent, beserta informasi yang memberi tahu apakah masih ada halaman lain. Buka Advanced settings dan temukan Response filter. Gunakan Add JSONPath, lalu tombol plus, untuk menambahkan setiap path di bawah sebagai entri terpisah:

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

Pertahankan card_faces. Beberapa kartu menaruh teksnya pada face individual, bukan di level teratas. Pertahankan juga warnings: keberhasilan HTTP tidak berarti Scryfall menafsirkan setiap klausa sesuai maksud. Referensi Card object menjelaskan field-field ini.

Di API Action Description, tempelkan:

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.

Simpan Action dan periksa bahwa Action tersebut aktif. Panduan anatomi HTTP Action menjelaskan bagaimana parameter, permintaan, dan deskripsi bekerja bersama.

Langkah 3: Bagaimana pencari kartu harus menjelaskan hasilnya?

Agent memerlukan instruksi untuk menampilkan kuerinya, mendasarkan rekomendasi pada rekaman yang dikembalikan, dan membedakan kecocokan kata dari interaksi aturan. Buka Identity → Main Prompt dan tempelkan prompt lengkap dari starter kit, yang direproduksi di bawah ini.

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.

Sekarang buka AI Preview dan kirim:

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

Demo ini menafsirkan kelayakan deck mono-hijau sebagai hijau atau tak berwarna. Untuk identitas tepat hijau, katakan itu secara eksplisit.

Baca kueri yang dijalankan sebelum rekomendasinya. Kueri itu harus mempertahankan Commander, identitas hijau-atau-tak-berwarna, jenis creature, trample, dan USD di bawah 5. Buka tautan Scryfall salah satu kartu dan bandingkan teks, identitas, dan harga yang relevan dengan jawabannya. Harga tersebut adalah observasi hasil lookup untuk cetakan yang dikembalikan, bukan harga checkout.

Hasil API diurutkan berdasarkan nama, bukan diperingkat berdasarkan kecocokan. Agent memilih daftar singkat dari halaman yang diambil. unique=cards menghindari pencantuman setiap cetakan sebagai hasil terpisah. Itu tidak berarti rekaman yang dipilih adalah salinan termurah yang bisa Anda beli.

Langkah 4: Bagaimana Anda memperbaiki pencarian yang menemukan interaksi yang salah?

Persempit kueri dengan membaca contoh tandingan dan menambahkan kondisi yang hilang. Pertahankan perbedaan antara menemukan kandidat kartu dan mengonfirmasi teksnya sepanjang proses penyempurnaan.

Tanyakan:

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

Pencarian kandidat yang luas adalah:

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

Dalam pemeriksaan langsung Scryfall kami pada 10 November 2026, ini mengembalikan 161 kandidat, termasuk Abundant Growth. Draw-nya terjadi saat Aura itu sendiri masuk. Kartu itu memang memuat kedua kata tersebut, tetapi tidak menyediakan mesin draw berulang saat creature masuk seperti yang disiratkan permintaan itu.

Coba penyempurnaan ini:

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

Kueri yang lebih sempit yang kami periksa adalah:

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

Pencarian yang disempurnakan mengembalikan empat kandidat. Garruk’s Packleader adalah kecocokan bersyarat yang berguna: creature lain itu harus memiliki power 3 atau lebih besar. Perbedaan ini harus disebutkan dalam rekomendasi. Strategi token dengan banyak creature 1/1 mungkin memerlukan kartu yang berbeda.

Menambahkan hanya o:"another creature" kurang presisi. Pengujian kami masih menemukan Disciple of Freyalise, yang saat masuknya sendiri dapat membuat Anda mengorbankan creature lain dan draw. Itu alasan lain untuk memeriksa seluruh ability alih-alih menganggap frasa tambahan sebagai bukti.

Ulangi loop yang sama untuk deck Anda sendiri: permintaan → kueri → teks kartu → satu penyempurnaan. Jika anggaran menghapus semua kandidat yang berguna, tanyakan sebelum memperluasnya. Jika sebuah kartu memiliki pembatasan, sebutkan pembatasan itu alih-alih diam-diam menghapusnya dari penjelasan.

Langkah 5: Bagaimana Anda menguji pencari kartu sebelum menggunakannya?

Uji jawaban dan panggilan API-nya. Kalimat yang meyakinkan tidak dapat membuktikan kueri mana yang dijalankan atau rekaman mana yang kembali.

1. Buka Testing dan buat dataset bernama Open Query checks menggunakan Create Dataset → Paste messages. Tempelkan pesan pengujian independen dari kit.
2. Jalankan pengujian. Nilai apakah jawaban menampilkan kuerinya, mengutip kartu yang dikembalikan, dan menjelaskan ketidakpastian.
3. Buka percakapan yang cocok di Inbox dan periksa panggilan Action. Periksa kueri, nomor halaman, status, dan field yang dikembalikan. Gunakan kontrol View logs milik Action untuk menemukan panggilan individual.
4. Uji penyempurnaan dan pagination dalam percakapan berkelanjutan, saat kueri sebelumnya tersedia.

Untuk pengujian tanpa kecocokan, kirim:

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

Satu pengujian API langsung menunjukkan mengapa peringatan itu penting. Kueri cacat f:commander o:/[/ mengembalikan HTTP 200, tetapi Scryfall melaporkan bahwa ekspresi yang tidak valid telah diabaikan. Karena itu, hasilnya lebih luas daripada yang diminta. Pertahankan peringatan itu, jelaskan filter yang diabaikan, dan perbaiki kuerinya sebelum merekomendasikan hasil tersebut.

Pengujian Agent lokal kami mencakup baseline, penyempurnaan, hasil kosong, dan pencarian dua halaman. Pemeriksaan API terpisah mencakup harga yang hilang, face kartu, dan peringatan sintaks. Gunakan fixture terkontrol untuk menguji batas laju tanpa mengirim lalu lintas berlebih.

Dokumentasi endpoint pencarian kartu saat ini menetapkan dua permintaan pencarian per detik. Beri jarak antar permintaan setidaknya 500 milidetik. Tutorial ini adalah alat bantu pencarian pribadi. Bot publik yang melayani banyak pemain memerlukan pembatasan laju bersama dan caching. Meminta model untuk melambat tidak menegakkan batas permintaan global.

Bisakah ChatGPT atau Claude membantu mengonfigurasi ini?

Anda dapat menggunakan plugin Quickchat AI untuk ChatGPT atau connector Quickchat AI untuk Claude untuk mengonfigurasi Agent melalui koneksi manajemen akun. Selesaikan proses sign-in sendiri, lalu berikan tutorial ini dan starter kit-nya dengan permintaan berikut:

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.

Dokumentasi manajemen akun menjelaskan koneksinya. Ini mengonfigurasi akun Quickchat AI Anda. Ini tidak secara otomatis membuat Open Query tersedia bagi orang lain sebagai alat MCP.

Pertanyaan yang sering diajukan

Bisakah saya mencari Scryfall dengan bahasa alami?

Asisten AI dapat menerjemahkan permintaan berbahasa biasa menjadi sintaks pencarian Scryfall dan menjalankannya melalui API Scryfall. Tutorial ini membangun asisten tersebut di Quickchat AI dan membuatnya menampilkan kueri, rekaman kartu yang tertaut, dan teks Oracle yang relevan agar Anda dapat memeriksa interpretasinya.

Apakah saya memerlukan kunci API Scryfall?

Tidak. Endpoint pencarian kartu publik tidak memerlukan akun atau kunci API. Kirim header User-Agent dan Accept yang mengidentifikasi, ikuti batas laju Scryfall, dan minta halaman tambahan dengan sengaja.

Bisakah pencari kartu AI ini berhalusinasi tentang sebuah kartu?

Instruksinya membatasi rekomendasi pada rekaman yang dikembalikan oleh Action, dengan tautan Scryfall. Model tetap bisa membuat kesalahan, jadi periksa ID dan teks Oracle yang dikembalikan, lalu uji nama kartu yang mustahil sebelum mengandalkan asisten ini.

Apa perbedaan antara id<=g dan id=g di Scryfall?

id<=g mencakup identitas hijau dan tak berwarna, cocok untuk mencari dalam warna commander mono-hijau. id=g mensyaratkan identitas tepat hijau. Identitas warna berbeda dari warna kartu. Gunakan filter identitas untuk konstruksi deck Commander.

Apakah harga Scryfall dijamin?

Tidak. Field prices.usd adalah data harga penyedia untuk cetakan yang dikembalikan, bukan penawaran dari penjual. Nilainya bisa null. Filter usd<5 mencari di bawah lima dolar AS. Itu tidak menetapkan biaya pengiriman, ketersediaan, atau cetakan termurah yang benar-benar bisa dibeli.

Apakah satu pencarian mengembalikan setiap kartu yang cocok?

Satu pencarian mengembalikan satu halaman API. Respons mencakup total_cards, has_more, dan, jika relevan, next_page. Open Query menampilkan hingga lima rekomendasi dari halaman yang diambil. Minta lebih banyak dari halaman itu atau secara eksplisit minta halaman API berikutnya. Daftar singkat bukan keseluruhan kumpulan hasil.

Bisakah ini membangun seluruh deck Commander saya?

Tutorial ini membangun asisten pencarian kartu. Ini membantu menemukan dan memeriksa kandidat untuk satu slot deck. Ini tidak memvalidasi deck lengkap 100 kartu, mengoptimalkan daftar deck, atau menggantikan judge aturan.