Rakenna tekoälypohjainen Commander-kortinhakija Scryfall:lla

Scryfall Commander -kortinhakija muuntaa tarvitsemasi kortin kuvauksen tarkasteltavaksi hauksi. Tässä oppaassa rakennat Open Query:n, Quickchat AI Agentin, joka näyttää Scryfall-kyselynsä, palauttaa oikeita korttitietueita ja selittää, miksi kukin ehdokas voisi sopia pakkaasi.

Aloita yhdestä korttipaikasta yksivihreässä Commander-pakassa. Haluat olennon, jolla on trample ja jonka hinta on alle viisi Yhdysvaltain dollaria. Lopuksi voit kirjoittaa tuon pyynnön, avata palautetut kortit ja tarkentaa hakua ilman, että sinun tarvitsee muistaa jokaista operaattoria.

Hyödyllinen osa alkaa, kun pyyntö vaikeutuu. “Draw when another creature enters” kuulostaa täsmälliseltä, mutta sanojen enters ja draw haku löytää myös kortteja, jotka tekevät jotain muuta. Havaitset tämän ristiriidan ja kavennat kyselyä käyttämällä palautettua korttitekstiä todisteena.

Mitä rakennat, ja mitä tarvitset?

Yhdistät yhden vain luku -tyyppisen API Action:n Scryfall:een, annat Agentille sen hakuohjeet ja testaat sitä keskustelussa. Action kutsuu kiinteää URL-osoitetta. Malli antaa kyselyn ja sivunumeron. Scryfall palauttaa tietueet, joihin vastaus perustuu.

1. Luo Quickchat AI-tili ja Agent nimeltä Open Query. Tarvitset käytettävissä olevia AI-krediittejä keskusteluihin ja testeihin. Katso nykyiset paketit.
2. Pidä Agentin Identity, Actions & MCPs ja AI Preview saatavilla työn aikana. Korttikokoelman latausta ei tarvita.
3. Käytä Scryfall:n julkista API:a. Et tarvitse Scryfall-tiliä tai API-avainta näihin hakuihin.

Aloituspakkaus sisältää Main Prompt:n, Action-reseptin, vastaussuodattimen polut ja testiviestit. Esimerkeissä käytetään englanninkielistä Oracle-tekstiä ja USD-hintoja. Pidä kyselyoperaattorit ja korttien nimet kirjoitettuina täsmälleen näin, kun seuraat mukana toisella kielellä.

Vaihe 1: Miten muutat korttipyynnön Scryfall-kyselyksi?

Scryfall-kysely yhdistää välilyönneillä erotettuja ehtoja. Käytä ensimmäiseen pyyntöömme tätä:

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

Kaksi pientä valintaa on tärkeää. kw:trample hakee avainsanaa. o:trample hakee sanaa Oracle-tekstistä. Olento voi mainita trample-sanan ilman, että sillä itsellään on tuo kyky. Testasimme molemmat. Tekstihaku tuotti laajemman joukon.

“Sopii yksivihreään pakkaan” eroaa myös ilmaisusta “sillä on täsmälleen vihreä identiteetti.” Ensimmäinen sallii värittömät kortit. Käytä jälkimmäiseen id=g tai id<=ur, jos haluat hakea sini-punaisen komentajan värien sisältä. Nämä ovat identiteettirajoitteita, eivät täydellinen pakan laillisuustarkistus.

Scryfall:n hakusyntaksin viite selittää nämä operaattorit. Tässä oppaassa pidä kysely näkyvissä jokaisessa vastauksessa, jotta huomaat puuttuvan värin, odottamattoman valuutan tai haun, joka on pyyntöäsi laajempi.

Vaihe 2: Miten yhdistät Scryfall API:n Agentiisi?

Luo yksi API Action, joka lähettää GET-pyynnön Scryfall:n kortinhakupäätepisteeseen. Sen kiinteät asetukset valitsevat tarjoajan ja järjestyksen. Sen kaksi parametria antavat Agentin valita haun ja sivun.

1. Avaa Actions & MCPs → Add Action → API Action.
2. Käytä alla olevaa builder-pyyntöä ja tarkista sitten luodut asetukset reseptiä vasten. API Action builder -opas selittää luonti- ja tarkistusprosessin.
3. Aseta API Action Name arvoon 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.

Määritä kaksi parametria

Lisää kohdassa What to ask the user first nämä pakolliset parametrit. Agent voi täyttää ne keskustelun perusteella. Nimike ei tarkoita, että sen täytyy pyytää sinua kirjoittamaan raakaa kyselysyntaksia.

Aseta päätepiste, kyselyparametrit ja otsakkeet

Valitse GET ja kirjoita:

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

Lisää kohdassa Query Params alla olevat neljä riviä. Käytä dynaamisille arvoille Add AI Data valitaksesi luomasi parametrin. Alla oleva merkintä {{query}} ja {{page}} edustaa näitä parametrisiruja.

Käytä kyselyparametrikenttiä, jotta välilyönnit, lainausmerkit ja operaattorit koodataan parametrien arvoiksi. Pidä päätepisteen URL kiinteänä.

Jätä Body tyhjäksi. Tunnistautumista ei tarvita. User-Agent on tunnistava asiakasnimi, ei tunnistetieto. Käytä omaa sopivaa sovellusnimeäsi ja yhteys-URL-osoitettasi, kun otat oman version käyttöön.

Pidä vastaus hyödyllisenä

Scryfall-sivu voi sisältää paljon tietueita. Säilytä kentät, joita Agent tarvitsee, sekä tiedot, jotka kertovat sille, onko sivuja lisää. Laajenna Advanced settings ja etsi Response filter. Käytä Add JSONPath-toimintoa ja sitten pluspainiketta lisätäksesi jokaisen alla olevan polun erillisenä merkintänä:

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

Säilytä card_faces. Joillakin korteilla teksti on yksittäisillä puolilla eikä ylätasolla. Säilytä myös warnings: HTTP-onnistuminen ei tarkoita, että Scryfall tulkitsi jokaisen ehdon tarkoitetulla tavalla. Korttiobjektin viite kuvaa nämä kentät.

Liitä kohtaan 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.

Tallenna Action ja tarkista, että se on aktiivinen. HTTP Action anatomy guide selittää, miten parametrit, pyyntö ja kuvaus toimivat yhdessä.

Vaihe 3: Miten kortinhakijan pitäisi selittää tuloksensa?

Agent tarvitsee ohjeet näyttääkseen kyselynsä, ankkuroidakseen suositukset palautettuihin tietueisiin ja erottaakseen sanahaun sääntövuorovaikutuksesta. Avaa Identity → Main Prompt ja liitä aloituspakkauksen täydellinen prompti, joka on toistettu alla.

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.

Avaa nyt AI Preview ja lähetä:

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

Demo tulkitsi yksivihreään pakkaan sopivuuden vihreäksi tai värittömäksi. Jos haluat täsmälleen vihreän identiteetin, sano se nimenomaisesti.

Lue suoritettu kysely ennen suosituksia. Sen pitäisi säilyttää Commander, vihreä-tai-väritön identiteetti, olentotyyppi, trample ja USD alle 5. Avaa yhden kortin Scryfall-linkki ja vertaa olennaista tekstiä, identiteettiä ja hintaa vastaukseen. Hinta on palautetun painoksen hakuhavainto, ei kassalla annettava tarjous.

API-tulokset järjestetään nimen mukaan, ei sopivuuden mukaan rankattuina. Agent valitsee lyhytlistan haetulta sivulta. unique=cards estää jokaista painosta näkymästä erillisenä tuloksena. Se ei tarkoita, että valittu tietue olisi halvin ostettavissa oleva kappale.

Vaihe 4: Miten korjaat haun, joka löytää väärän vuorovaikutuksen?

Kavenna kyselyä lukemalla vastaesimerkki ja lisäämällä puuttuva ehto. Säilytä koko tarkennuksen ajan ero ehdokaskorttien löytämisen ja niiden tekstin vahvistamisen välillä.

Kysy:

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

Laaja ehdokashaku on:

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

Suorassa Scryfall-tarkistuksessamme 10. marraskuuta 2026 tämä palautti 161 ehdokasta, mukaan lukien Abundant Growth. Sen kortinnosto tapahtuu, kun Aura itse tulee peliin. Se sisältää molemmat sanat, mutta ei tarjoa pyynnön vihjaamaa toistuvaa olennon sisääntuloon perustuvaa kortinnostomoottoria.

Kokeile tätä tarkennusta:

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

Tarkempi kysely, jonka tarkistimme, oli:

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

Tarkennettu haku palautti neljä ehdokasta. Garruk’s Packleader on hyödyllinen ehdollinen osuma: toisella olennolla täytyy olla voimaa 3 tai enemmän. Tämä ero kuuluu suositukseen. Token-strategia, jossa on paljon 1/1-olentoja, voi tarvita toisen kortin.

Pelkkä o:"another creature":n lisääminen on epätarkempaa. Testissämme löytyi silti Disciple of Freyalise, jonka oma sisääntulo voi johtaa siihen, että uhraat toisen olennon ja nostat kortin. Tämä on toinen syy tarkistaa koko kyky sen sijaan, että pitäisit lisälausetta todisteena.

Toista sama silmukka omalle pakallesi: pyyntö → kysely → korttiteksti → yksi tarkennus. Jos budjetti poistaa kaikki hyödylliset ehdokkaat, kysy ennen kuin laajennat sitä. Jos kortilla on rajoitus, kerro rajoitus sen sijaan, että jättäisit sen hiljaa pois selityksestä.

Vaihe 5: Miten testaat kortinhakijan ennen käyttöä?

Testaa sekä vastaus että API-kutsu. Vakuuttava lause ei voi osoittaa, mikä kysely suoritettiin tai mitkä tietueet palautuivat.

1. Avaa Testing ja luo dataset nimeltä Open Query checks käyttäen kohtaa Create Dataset → Paste messages. Liitä mukaan pakkauksen riippumattomat testiviestit.
2. Suorita testit. Arvioi, näyttääkö vastaus kyselynsä, viittaako se palautettuihin kortteihin ja selittääkö se epävarmuuden.
3. Avaa vastaava keskustelu kohdassa Inbox ja tarkasta Action-kutsu. Tarkista kysely, sivunumero, tila ja palautetut kentät. Käytä Actionin View logs-ohjainta yksittäisten kutsujen löytämiseen.
4. Testaa tarkennusta ja sivutusta jatkuvassa keskustelussa, jossa aiempi kysely on saatavilla.

Lähetä ei-osumia-testissä:

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

Yksi suora API-testi osoitti, miksi varoitukset ovat tärkeitä. Virheellinen kysely f:commander o:/[/ palautti HTTP 200, mutta Scryfall ilmoitti, että se oli ohittanut virheellisen lausekkeen. Tulokset olivat siis pyydettyä laajemmat. Säilytä tuo varoitus, selitä ohitettu suodatin ja korjaa kysely ennen kuin suosittelet näitä tuloksia.

Paikallisen Agentimme ajot kattoivat perustapauksen, tarkennuksen, tyhjät tulokset ja kaksisivuisen haun. Erilliset API-tarkistukset kattoivat puuttuvat hinnat, kortin puolet ja syntaksivaroitukset. Käytä hallittua testiympäristöä nopeusrajoituksen testaamiseen lähettämättä liikaa liikennettä.

Kortinhakupäätepisteen dokumentaatio määrittää tällä hetkellä kaksi hakupyyntöä sekunnissa. Pidä pyyntöjen välillä vähintään 500 millisekuntia. Tämä opas on henkilökohtainen hakuapu. Julkinen botti, joka palvelee monia pelaajia, tarvitsee jaetun nopeusrajoituksen ja välimuistin. Mallin pyytäminen hidastamaan ei pakota globaalia pyyntörajaa.

Voivatko ChatGPT tai Claude auttaa tämän määrittämisessä?

Voit käyttää Quickchat AI-lisäosaa ChatGPT:lle tai Quickchat AI-liitintä Claudelle Agentin määrittämiseen tilinhallintayhteyden kautta. Suorita kirjautuminen itse ja anna sitten tämä opas ja sen aloituspakkaus seuraavan pyynnön kanssa:

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.

Tilinhallinnan dokumentaatio selittää yhteyden. Tämä määrittää Quickchat AI-tilisi. Se ei automaattisesti tee Open Query:sta muiden ihmisten käytettävissä olevaa MCP-työkalua.

Usein kysytyt kysymykset

Voinko hakea Scryfall luonnollisella kielellä?

Tekoälyavustaja voi kääntää selkokielisen pyynnön Scryfall-hakusyntaksiksi ja suorittaa sen Scryfall API:n kautta. Tässä oppaassa rakennetaan tuo avustaja Quickchat AI:ssa ja laitetaan se näyttämään kysely, linkitetyt korttitietueet ja olennainen Oracle-teksti, jotta voit tarkistaa tulkinnan.

Tarvitsenko Scryfall API-avaimen?

Et. Julkinen kortinhakupäätepiste ei vaadi tiliä tai API-avainta. Lähetä tunnistavat User-Agent- ja Accept-otsakkeet, noudata Scryfall:n nopeusrajoja ja pyydä lisäsivuja harkitusti.

Voiko tämä tekoälykortinhakija hallusinoida kortin?

Ohjeet rajoittavat suositukset Actionin palauttamiin tietueisiin, joissa on Scryfall-linkit. Malli voi silti tehdä virheitä, joten tarkista palautettu tunniste ja Oracle-teksti, ja testaa mahdotonta kortinnimeä ennen kuin luotat avustajaan.

Mitä eroa on Scryfall:ssa ehdoilla id<=g ja id=g?

id<=g sisältää vihreän ja värittömät identiteetit, joten se sopii hakuun yksivihreän komentajan värien sisällä. id=g vaatii täsmälleen vihreän identiteetin. Väri-identiteetti eroaa kortin väristä. Käytä identiteettisuodatinta Commander-pakanrakennuksessa.

Ovatko Scryfall-hinnat taattuja?

Eivät. prices.usd-kenttä on palautetun painoksen tarjoajahintadataa, ei myyjän tarjous. Se voi olla null. Suodatin usd<5 hakee alle viiden Yhdysvaltain dollarin hintoja. Se ei määritä toimituskuluja, saatavuutta tai halvinta ostettavissa olevaa painosta.

Palauttaako yksi haku kaikki osuvat kortit?

Haku palauttaa yhden API-sivun. Vastaus sisältää kentät total_cards, has_more ja tarvittaessa next_page. Open Query näyttää enintään viisi suositusta haetulta sivulta. Pyydä lisää tältä sivulta tai pyydä nimenomaisesti seuraava API-sivu. Lyhytlista ei ole koko tulosjoukko.

Voiko tämä rakentaa koko Commander-pakkani?

Tässä oppaassa rakennetaan kortinhakuavustaja. Se auttaa löytämään ja tarkastamaan ehdokkaita pakan korttipaikkaan. Se ei validoi kokonaista 100 kortin pakkaa, optimoi pakka-listaa eikä korvaa sääntötuomaria.