ScryfallでAI Commanderカードファインダーを構築する

Scryfall Commanderカードファインダーは、必要なカードの説明を、確認できる検索に変換します。このチュートリアルでは、Scryfallクエリを表示し、実際のカードレコードを返し、各候補がなぜあなたのデッキに合うかを説明するQuickchat AI Agent、Open Queryを構築します。

まずは単色緑のCommanderデッキの1枠から始めましょう。あなたはトランプルを持ち、価格が5米ドル未満のクリーチャーを求めています。最後には、その要求を入力し、返されたカードを開き、すべての演算子を暗記しなくても検索を絞り込めるようになります。

本当に役立つのは、要求が難しくなったときです。「他のクリーチャーが戦場に出たときに引く」は正確に聞こえますが、entersとdrawという単語で検索すると、別のことをするカードも見つかります。返されたカードテキストを根拠として使いながら、その不一致を見つけてクエリを絞り込みます。

何を構築し、何が必要ですか。

読み取り専用のAPI Actionを1つScryfallに接続し、Agentに検索指示を与え、会話でテストします。Actionは固定URLを呼び出し、モデルがクエリとページ番号を指定します。Scryfallは、回答の根拠となるレコードを返します。

1. Quickchat AIアカウントを作成し、Open Queryという名前のAgentを作成します。会話とテストには利用可能なAIクレジットが必要です。詳細は現在のプランを参照してください。
2. 作業中は、AgentのIdentity、Actions & MCPs、AI Previewをすぐ見られるようにしておいてください。カードコレクションのアップロードは不要です。
3. Scryfallの公開APIを使います。これらの検索にScryfallアカウントやAPIキーは必要ありません。

スターターキットには、Main Prompt、Actionレシピ、レスポンスフィルターのパス、テストメッセージが含まれています。例では英語のOracleテキストとUSD価格を使います。別の言語で進める場合でも、クエリ演算子とカード名は書かれているとおりに保ってください。

ステップ1: カード要求をどうやってScryfallクエリに変換しますか。

Scryfallクエリは、スペースで区切られた制約を組み合わせます。最初の要求には次を使います。

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

小さな選択が2つ重要です。kw:trampleはキーワードを検索し、o:trampleはOracleテキスト内の単語を検索します。 クリーチャー自身がその能力を持っていなくても、トランプルに言及していることがあります。両方を試したところ、テキスト検索のほうがより広い集合になりました。

「単色緑デッキに入る」も「ちょうど緑のアイデンティティを持つ」とは異なります。 前者は無色カードを許します。後者にはid=gを使い、青赤の統率者の色の範囲内で検索するならid<=urを使ってください。これらはアイデンティティ制約であり、完全なデッキ適法性チェックではありません。

Scryfallの検索構文リファレンスでは、これらの演算子を説明しています。このチュートリアルでは、すべての回答でクエリを見えるようにしておき、色の抜け、予想外の通貨、要求より広い検索に気づけるようにします。

ステップ2: Scryfall APIをAgentにどう接続しますか。

Scryfallのカード検索エンドポイントにGETリクエストを送るAPI Actionを1つ作成します。固定設定でプロバイダーと並び順を選び、2つのパラメーターで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.

2つのパラメーターを定義する

What to ask the user first の下で、以下の必須パラメーターを追加します。Agentは会話からこれらを埋められます。このラベルは、あなたに生のクエリ構文を入力させなければならないという意味ではありません。

エンドポイント、クエリパラメーター、ヘッダーを設定する

GETを選択し、次を入力します。

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

Query Params の下で、以下の4行を追加します。動的な値には、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 referenceでこれらのフィールドを説明しています。

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 anatomy guideでは、パラメーター、リクエスト、説明がどのように連携するかを説明しています。

ステップ3: カードファインダーは結果をどう説明すべきですか。

Agentには、クエリを表示し、返されたレコードに基づいておすすめを行い、単語一致とルール上の相互作用を区別するための指示が必要です。Identity → Main 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、緑または無色のアイデンティティ、クリーチャー・タイプ、トランプル、USD 5未満が保たれているはずです。1枚のカードのScryfallリンクを開き、関連するテキスト、アイデンティティ、価格を回答と比較してください。価格は返された刷り版に対する参照時点の観測値であり、購入時の見積もりではありません。

API結果は適合度で順位付けされておらず、名前順に並んでいます。Agentは取得したページから短い候補一覧を選びます。unique=cardsは、すべての刷り版を別々の結果として並べることを避けますが、選ばれたレコードが購入できる最安の1枚であることを意味しません。

ステップ4: 間違った相互作用を見つける検索はどう修正しますか。

反例を読み、欠けている条件を追加してクエリを絞り込みます。絞り込みの全体を通して、候補カードを見つけることと、そのテキストを確認することの区別を保ってください。

次のように尋ねます。

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

広めの候補検索は次のとおりです。

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

2026年11月10日に行った直接のScryfall確認では、これは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

絞り込んだ検索は4件の候補を返しました。Garruk’s Packleaderは有用な条件付き一致です。他のクリーチャーはパワー3以上である必要があります。この違いはおすすめの中に含めるべきです。1/1クリーチャーを大量に使うトークン戦略なら、別のカードが必要かもしれません。

o:"another creature"だけを追加するのでは精度が低めです。私たちのテストでは、依然としてDisciple of Freyaliseが見つかりました。このカードは自身が戦場に出たことで、別のクリーチャーを生け贄に捧げてカードを引く流れにつながることがあります。これも、追加の語句を証拠扱いするのではなく、能力全体を確認すべき理由です。

あなた自身のデッキでも同じ流れを繰り返してください。要求 → クエリ → カードテキスト → 1回の絞り込み。予算のせいで有用な候補がすべて消えるなら、広げる前に確認してください。カードに制約があるなら、説明から黙って落とすのではなく、その制約を述べてください。

ステップ5: 使う前にカードファインダーをどうテストしますか。

回答とAPI呼び出しの両方をテストしてください。もっともらしい文章だけでは、どのクエリが実行され、どのレコードが返ったかを確定できません。

1. Testing を開き、Create Dataset → Paste messages を使って Open Query checks という名前のデータセットを作成します。キットにある独立したテストメッセージを貼り付けてください。
2. テストを実行します。回答がクエリを表示しているか、返されたカードを引用しているか、不確実性を説明しているかを評価します。
3. Inbox で対応する会話を開き、Action呼び出しを確認します。クエリ、ページ番号、ステータス、返されたフィールドを確認してください。個々の呼び出しを見つけるには、ActionのView logsコントロールを使います。
4. 前のクエリが利用できる継続中の会話で、絞り込みとページネーションをテストします。

一致なしテストでは、次を送信します。

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

ある直接APIテストでは、警告が重要な理由が分かりました。不正なクエリf:commander o:/[/はHTTP 200を返しましたが、Scryfallは無効な式を無視したと報告しました。したがって結果は要求より広くなっていました。その警告を保持し、無視されたフィルターを説明し、それらの結果をおすすめする前にクエリを修正してください。

私たちのローカルAgent実行では、ベースライン、絞り込み、空結果、2ページ検索をカバーしました。別個のAPI確認では、価格欠落、カードの面、構文警告をカバーしました。過剰なトラフィックを送らずにレート制限をテストするには、制御されたフィクスチャを使ってください。

カード検索エンドポイントのドキュメントでは、現在1秒あたり2回の検索リクエストを指定しています。リクエスト間隔は少なくとも500ミリ秒空けてください。このチュートリアルは個人用の検索補助です。多くのプレイヤーに提供する公開ボットには、共有のレート制限とキャッシュが必要です。モデルにゆっくり動くよう頼んでも、グローバルなリクエスト制限は強制されません。

ChatGPTやClaudeはこの設定を手伝えますか。

ChatGPT用のQuickchat AIプラグインまたはClaude用のQuickchat AIコネクターを使って、アカウント管理接続経由で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検索構文に変換し、Scryfall API経由で実行できます。このチュートリアルでは、そのアシスタントをQuickchat AIで構築し、クエリ、リンク付きカードレコード、関連するOracleテキストを表示して、解釈を確認できるようにします。

Scryfall APIキーは必要ですか。

いいえ。公開カード検索エンドポイントにはアカウントもAPIキーも必要ありません。識別用のUser-AgentヘッダーとAcceptヘッダーを送り、Scryfallのレート制限に従い、追加ページは意図的にリクエストしてください。

このAIカードファインダーは存在しないカードをでっち上げることがありますか。

指示では、おすすめをActionが返したレコードに限定し、Scryfallリンクを付けています。モデルはそれでも間違えることがあるので、返されたIDとOracleテキストを確認し、ありえないカード名でも試してからアシスタントを信用してください。

Scryfallにおけるid<=gとid=gの違いは何ですか。

id<=gは緑と無色の統率者カラー・アイデンティティを含み、単色緑の統率者の色の範囲内で検索するのに適しています。id=gはちょうど緑のアイデンティティだけを要求します。カラー・アイデンティティはカードの色とは別物です。Commanderのデッキ構築では、アイデンティティフィルターを使ってください。

Scryfallの価格は保証されていますか。

いいえ。prices.usdフィールドは、返された刷り版に対するプロバイダーの価格データであり、販売者からの提示価格ではありません。nullになることもあります。usd<5フィルターは5米ドル未満を検索しますが、送料、在庫、または購入可能な最安の刷り版を保証するものではありません。

1回の検索で一致するカードをすべて返しますか。

検索は1つのAPIページを返します。レスポンスにはtotal_cards、has_more、そして該当する場合はnext_pageが含まれます。Open Queryは取得したページから最大5件のおすすめを表示します。そのページからさらに表示するよう頼むか、次のAPIページを明示的に要求してください。短い候補一覧は完全な結果セットではありません。

これでCommanderデッキ全体を組めますか。

このチュートリアルで構築するのはカード検索アシスタントです。デッキの枠に入れる候補を見つけて確認する助けになります。100枚の完全なデッキを検証したり、デッキリストを最適化したり、ジャッジの代わりになったりはしません。