Scryfall로 AI Commander 카드 찾기 도구 만들기

Scryfall Commander 카드 찾기 도구는 필요한 카드에 대한 설명을 확인 가능한 검색으로 바꿔 줍니다. 이 튜토리얼에서는 Open Query를 만들게 됩니다. 이것은 Quickchat AI Agent로, 자신의 Scryfall 쿼리를 보여 주고, 실제 카드 기록을 반환하며, 각 후보가 왜 당신의 덱에 맞을 수 있는지 설명합니다.

단색 녹색 Commander 덱의 슬롯 하나에서 시작해 봅시다. 당신은 돌진이 있고 가격이 5 미국 달러 미만인 생물을 원합니다. 끝날 때쯤이면 그 요청을 입력하고, 반환된 카드를 열어 보고, 모든 연산자를 외우지 않고도 검색을 다듬을 수 있게 됩니다.

유용한 부분은 요청이 더 어려워질 때 드러납니다. “다른 생물이 들어올 때 드로우”는 정확해 보이지만, enters와 draw라는 단어를 검색하면 다른 일을 하는 카드도 함께 나옵니다. 반환된 카드 텍스트를 근거로 삼아 그 불일치를 잡아내고 쿼리를 좁히는 방법을 배우게 됩니다.

무엇을 만들고, 무엇이 필요한가요?

읽기 전용 API Action 하나를 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

작은 선택 두 가지가 중요합니다. kw:trample는 키워드를 검색하고, o:trample는 Oracle 텍스트 안의 단어를 검색합니다. 생물이 돌진을 언급할 수는 있어도, 그 능력을 스스로 가지고 있지는 않을 수 있습니다. 우리는 둘 다 테스트했고, 텍스트 검색이 더 넓은 집합을 만들어 냈습니다.

“단색 녹색 덱에 들어간다”는 것 역시 “정확히 녹색 정체성을 가진다”와 다릅니다. 전자는 무색 카드를 허용합니다. 후자에는 id=g를 사용하고, 청적 커맨더의 색 안에서 검색하려면 id<=ur를 사용하세요. 이것들은 정체성 제약일 뿐, 완전한 덱 합법성 검사는 아닙니다.

Scryfall의 검색 문법 참고 자료는 이런 연산자들을 설명합니다. 이 튜토리얼에서는 모든 답변에 쿼리를 보이게 유지해서, 빠진 색, 예상치 못한 통화, 또는 요청보다 더 넓은 검색을 알아차릴 수 있게 하세요.

2단계: Scryfall API를 Agent에 어떻게 연결하나요?

Scryfall의 카드 검색 엔드포인트로 GET 요청을 보내는 API Action 하나를 만드세요. 고정 설정은 공급자와 정렬 방식을 선택하고, 두 개의 매개변수는 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.

두 개의 매개변수 정의하기

What to ask the user first 아래에 다음 필수 매개변수를 추가하세요. Agent는 대화에서 이를 채울 수 있으며, 이 라벨이 사용자가 반드시 원시 쿼리 문법을 직접 입력해야 한다는 뜻은 아닙니다.

엔드포인트, 쿼리 매개변수, 헤더 설정하기

GET을 선택하고 다음을 입력하세요.

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

Query Params 아래에 아래 네 행을 추가하세요. 동적 값에는 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가 모든 절을 의도대로 해석했다는 뜻은 아닙니다. 카드 객체 참고 자료는 이 필드들을 설명합니다.

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 구조 가이드는 매개변수, 요청, 설명이 어떻게 함께 작동하는지 설명합니다.

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 미만이 유지되어 있어야 합니다. 카드 하나의 Scryfall 링크를 열고 관련 텍스트, 정체성, 가격을 답변과 비교하세요. 가격은 반환된 인쇄본에 대한 조회 관찰값이지 결제 견적이 아닙니다.

API 결과는 적합도 순위가 아니라 이름순으로 정렬됩니다. Agent는 가져온 페이지에서 짧은 후보 목록을 고릅니다. unique=cards는 모든 인쇄본을 각각 별도 결과로 나열하지 않게 해 줄 뿐, 선택된 기록이 당신이 살 수 있는 가장 싼 사본이라는 뜻은 아닙니다.

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

정제된 검색은 네 개의 후보를 반환했습니다. Garruk’s Packleader는 유용한 조건부 일치입니다. 다른 생물의 공격력이 3 이상이어야 합니다. 이 차이는 추천에 포함되어야 합니다. 1/1 생물이 많은 토큰 전략이라면 다른 카드가 필요할 수 있습니다.

o:"another creature"만 추가하는 것은 덜 정확합니다. 우리의 테스트에서는 여전히 Disciple of Freyalise를 찾았는데, 이 카드는 자기 자신이 들어오면서 다른 생물을 희생하고 드로우하게 만들 수 있습니다. 이것 역시 추가 문구 하나를 증거로 취급하지 말고 능력 전체를 확인해야 하는 이유입니다.

자신의 덱에도 같은 반복 과정을 적용하세요. 요청 → 쿼리 → 카드 텍스트 → 한 번의 정제입니다. 예산 때문에 유용한 후보가 모두 사라진다면, 예산을 넓히기 전에 먼저 물어보세요. 카드에 제한이 있다면, 설명에서 조용히 빼지 말고 그 제한을 말하세요.

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 실행은 기본 동작, 정제, 빈 결과, 두 페이지 검색을 다뤘습니다. 별도의 API 점검은 누락된 가격, 카드 면, 문법 경고를 다뤘습니다. 과도한 트래픽을 보내지 않고 속도 제한을 테스트하려면 통제된 픽스처를 사용하세요.

카드 검색 엔드포인트 문서는 현재 초당 두 번의 검색 요청을 명시하고 있습니다. 요청 간격은 최소 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 미국 달러 미만을 검색할 뿐이며, 배송비, 재고 여부, 또는 실제로 구매 가능한 가장 저렴한 인쇄본을 보장하지 않습니다.

한 번의 검색으로 일치하는 카드를 모두 반환하나요?

검색은 API 페이지 하나를 반환합니다. 응답에는 total_cards, has_more, 그리고 관련이 있을 때 next_page가 포함됩니다. Open Query는 가져온 페이지에서 최대 다섯 개의 추천을 보여줍니다. 그 페이지에서 더 보여 달라고 하거나 다음 API 페이지를 명시적으로 요청하세요. 짧은 추천 목록은 전체 결과 집합이 아닙니다.

이걸로 제 Commander 덱 전체를 만들 수 있나요?

이 튜토리얼은 카드 검색 어시스턴트를 만듭니다. 덱 슬롯에 들어갈 후보를 찾고 확인하는 데 도움을 줍니다. 완전한 100장 덱을 검증하거나, 덱 리스트를 최적화하거나, 룰 저지를 대체하지는 않습니다.