Crea un buscador de cartas con IA de Commander con Scryfall

Un buscador de cartas de Scryfall Commander convierte una descripción de la carta que necesitas en una búsqueda que puedes inspeccionar. En este tutorial, crearás Open Query, un Agent de Quickchat AI que muestra su consulta de Scryfall, devuelve registros de cartas reales y explica por qué cada candidata podría encajar en tu mazo.

Empieza con un hueco en un mazo monoverde de Commander. Quieres una criatura con arrollar y un precio inferior a cinco dólares estadounidenses. Al final, podrás escribir esa solicitud, abrir las cartas devueltas y refinar la búsqueda sin memorizar todos los operadores.

La parte útil llega cuando la solicitud se vuelve más difícil. “Roba cuando entre otra criatura” suena preciso, pero una búsqueda de las palabras enters y draw también encuentra cartas que hacen otra cosa. Detectarás esa discrepancia y acotarás la consulta, usando el texto devuelto de las cartas como evidencia.

¿Qué vas a construir y qué necesitas?

Conectarás una API Action de solo lectura a Scryfall, le darás al Agent sus instrucciones de búsqueda y lo probarás en una conversación. La Action llama a una URL fija. El modelo proporciona una consulta y un número de página. Scryfall devuelve los registros de los que se nutre la respuesta.

1. Crea una cuenta de Quickchat AI y un Agent llamado Open Query. Necesitas créditos de IA disponibles para conversaciones y pruebas. Consulta los planes actuales.
2. Mantén disponibles el Identity, Actions & MCPs y AI Preview del Agent mientras trabajas. No hace falta subir tu colección de cartas.
3. Usa la API pública de Scryfall. No necesitas una cuenta ni una clave de API de Scryfall para estas búsquedas.

El kit inicial contiene el Main Prompt, la receta de la Action, las rutas del filtro de respuesta y los mensajes de prueba. Los ejemplos usan texto Oracle en inglés y precios en USD. Mantén los operadores de consulta y los nombres de cartas tal como están escritos al seguir el tutorial en otro idioma.

Paso 1: ¿Cómo conviertes una solicitud de carta en una consulta de Scryfall?

Una consulta de Scryfall combina restricciones separadas por espacios. Para nuestra primera solicitud, usa:

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

Dos decisiones pequeñas importan. kw:trample busca la palabra clave. o:trample busca la palabra en el texto Oracle. Una criatura puede mencionar arrollar sin tener ella misma esa habilidad. Probamos ambas. La búsqueda por texto produjo un conjunto más amplio.

“Encaja en un mazo monoverde” también es distinto de “tiene identidad exactamente verde”. Lo primero permite cartas incoloras. Usa id=g para lo segundo, o id<=ur para buscar dentro de los colores de un comandante azul-rojo. Estas son restricciones de identidad, no una comprobación completa de legalidad del mazo.

La referencia de sintaxis de búsqueda de Scryfall explica estos operadores. Para este tutorial, mantén la consulta visible en cada respuesta para que puedas detectar un color omitido, una moneda inesperada o una búsqueda más amplia que tu solicitud.

Paso 2: ¿Cómo conectas la API de Scryfall a tu Agent?

Crea una API Action que envíe una solicitud de GET al endpoint de búsqueda de cartas de Scryfall. Su configuración fija elige el proveedor y el orden. Sus dos parámetros permiten al Agent elegir la búsqueda y la página.

1. Abre Actions & MCPs → Add Action → API Action.
2. Usa la solicitud del generador de abajo y luego revisa la configuración generada frente a la receta. La guía del generador de API Action explica el flujo de generación y revisión.
3. Establece API Action Name en 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.

Define los dos parámetros

En What to ask the user first, añade estos parámetros obligatorios. El Agent puede completarlos a partir de la conversación. La etiqueta no significa que deba pedirte que escribas sintaxis de consulta sin procesar.

Configura el endpoint, los parámetros de consulta y los encabezados

Selecciona GET e introduce:

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

En Query Params, añade las cuatro filas de abajo. Para los valores dinámicos, usa Add AI Data para seleccionar el parámetro que creaste. La notación {{query}} y {{page}} de abajo representa esas fichas de parámetro.

Usa los campos de parámetros de consulta para que los espacios, las comillas y los operadores se codifiquen como valores de parámetro. Mantén fija la URL del endpoint.

Deja Body vacío. No se necesita autenticación. El User-Agent es un nombre identificativo del cliente, no una credencial. Usa tu propio nombre de aplicación apropiado y una URL de contacto al desplegar tu versión.

Mantén útil la respuesta

Una página de Scryfall puede contener muchos registros. Conserva los campos que el Agent necesita, junto con la información que le indica si existen más páginas. Expande Advanced settings y busca Response filter. Usa Add JSONPath y luego el botón más para agregar cada ruta de abajo como una entrada independiente:

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

Conserva card_faces. Algunas cartas ponen su texto en caras individuales en lugar de en el nivel superior. Conserva también warnings: un éxito HTTP no significa que Scryfall haya interpretado cada cláusula como se pretendía. La referencia del objeto Card describe estos campos.

En API Action Description, pega:

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.

Guarda la Action y comprueba que esté activa. La guía de anatomía de HTTP Action explica cómo funcionan juntos los parámetros, la solicitud y la descripción.

Paso 3: ¿Cómo debe explicar sus resultados el buscador de cartas?

El Agent necesita instrucciones para mostrar su consulta, fundamentar las recomendaciones en registros devueltos y distinguir una coincidencia de palabras de una interacción de reglas. Abre Identity → Main Prompt y pega el prompt completo del kit inicial, reproducido abajo.

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.

Ahora abre AI Preview y envía:

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

La demo interpretó la elegibilidad para mazo monoverde como verde o incoloro. Para identidad exactamente verde, dilo explícitamente.

Lee la consulta ejecutada antes de las recomendaciones. Debe conservar Commander, identidad verde o incolora, tipo criatura, arrollar y USD por debajo de 5. Abre el enlace de Scryfall de una carta y compara el texto relevante, la identidad y el precio con la respuesta. El precio es una observación de consulta para la impresión devuelta, no una cotización de compra.

Los resultados de la API están ordenados por nombre, no clasificados por encaje. El Agent elige una lista corta de la página obtenida. unique=cards evita listar cada impresión como un resultado separado. No significa que el registro seleccionado sea la copia más barata que puedes comprar.

Paso 4: ¿Cómo corriges una búsqueda que encuentra la interacción equivocada?

Acota la consulta leyendo un contraejemplo y añadiendo la condición que falta. Mantén durante todo el refinamiento la distinción entre encontrar cartas candidatas y confirmar su texto.

Pregunta:

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

Una búsqueda amplia de candidatas es:

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

En nuestra comprobación directa de Scryfall del 10 de noviembre de 2026, esto devolvió 161 candidatas, incluida Abundant Growth. Su robo ocurre cuando entra el propio Aura. Contiene ambas palabras, pero no proporciona el motor repetible de robo por entrada de criatura que sugiere la solicitud.

Prueba este refinamiento:

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

La consulta más acotada que comprobamos fue:

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

La búsqueda refinada devolvió cuatro candidatas. Garruk’s Packleader es una coincidencia condicional útil: la otra criatura necesita fuerza 3 o más. Esa distinción debe figurar en la recomendación. Una estrategia de fichas con muchas criaturas 1/1 puede necesitar otra carta.

Añadir solo o:"another creature" es menos preciso. Nuestra prueba siguió encontrando Disciple of Freyalise, cuya propia entrada puede llevarte a sacrificar otra criatura y robar. Esa es otra razón para inspeccionar la habilidad completa en lugar de tratar una frase adicional como prueba.

Repite el mismo ciclo para tu propio mazo: solicitud → consulta → texto de la carta → un refinamiento. Si el presupuesto elimina todas las candidatas útiles, pregunta antes de ampliarlo. Si una carta tiene una restricción, menciona la restricción en lugar de omitirla discretamente de la explicación.

Paso 5: ¿Cómo pruebas el buscador de cartas antes de usarlo?

Prueba tanto la respuesta como la llamada a la API. Una frase convincente no puede establecer qué consulta se ejecutó ni qué registros volvieron.

1. Abre Testing y crea un conjunto de datos llamado Open Query checks usando Create Dataset → Paste messages. Pega los mensajes de prueba independientes del kit.
2. Ejecuta las pruebas. Evalúa si la respuesta muestra su consulta, cita cartas devueltas y explica la incertidumbre.
3. Abre la conversación correspondiente en Inbox e inspecciona la llamada a la Action. Comprueba la consulta, el número de página, el estado y los campos devueltos. Usa el control View logs de la Action para encontrar llamadas individuales.
4. Prueba el refinamiento y la paginación en una conversación continua, donde la consulta anterior esté disponible.

Para la prueba sin coincidencias, envía:

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

Una prueba directa de la API mostró por qué importan las advertencias. La consulta malformada f:commander o:/[/ devolvió HTTP 200, pero Scryfall informó de que había ignorado la expresión no válida. Por tanto, los resultados eran más amplios de lo solicitado. Conserva esa advertencia, explica el filtro ignorado y corrige la consulta antes de recomendar esos resultados.

Las ejecuciones de nuestro Agent local cubrieron la línea base, el refinamiento, los resultados vacíos y una búsqueda de dos páginas. Las comprobaciones separadas de la API cubrieron precios ausentes, caras de cartas y advertencias de sintaxis. Usa un entorno controlado para probar el límite de velocidad sin enviar tráfico excesivo.

La documentación del endpoint de búsqueda de cartas especifica actualmente dos solicitudes de búsqueda por segundo. Mantén al menos 500 milisegundos entre solicitudes. Este tutorial es un asistente de búsqueda personal. Un bot público que atienda a muchos jugadores necesita limitación de velocidad compartida y caché. Pedirle al modelo que vaya más despacio no impone un límite global de solicitudes.

¿Pueden ChatGPT o Claude ayudar a configurar esto?

Puedes usar el plugin de Quickchat AI para ChatGPT o el conector de Quickchat AI para Claude para configurar el Agent mediante la conexión de gestión de cuenta. Completa tú mismo el inicio de sesión y luego proporciona este tutorial y su kit inicial con la siguiente solicitud:

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.

La documentación de gestión de cuenta explica la conexión. Esto configura tu cuenta de Quickchat AI. No hace que Open Query esté disponible automáticamente para otras personas como herramienta MCP.

Preguntas frecuentes

¿Puedo buscar Scryfall en lenguaje natural?

Un asistente de IA puede traducir una solicitud en lenguaje natural a la sintaxis de búsqueda de Scryfall y ejecutarla mediante la API de Scryfall. Este tutorial crea ese asistente en Quickchat AI y hace que muestre la consulta, los registros de cartas enlazados y el texto Oracle relevante para que puedas comprobar la interpretación.

¿Necesito una clave de API de Scryfall?

No. El endpoint público de búsqueda de cartas no requiere cuenta ni clave de API. Envía encabezados identificativos de User-Agent y Accept, respeta los límites de velocidad de Scryfall y solicita páginas adicionales de forma deliberada.

¿Puede este buscador de cartas con IA alucinar una carta?

Las instrucciones restringen las recomendaciones a registros devueltos por la Action, con enlaces de Scryfall. El modelo aún puede cometer errores, así que comprueba el ID devuelto y el texto Oracle, y prueba un nombre de carta imposible antes de confiar en el asistente.

¿Cuál es la diferencia entre id<=g e id=g en Scryfall?

id<=g incluye identidades verdes e incoloras, adecuado para buscar dentro de los colores de un comandante monoverde. id=g exige identidad exactamente verde. La identidad de color es distinta del color de la carta. Usa el filtro de identidad para la construcción de mazos de Commander.

¿Están garantizados los precios de Scryfall?

No. El campo prices.usd es un dato de precios del proveedor para la impresión devuelta, no una oferta de un vendedor. Puede ser null. El filtro usd<5 busca por debajo de cinco dólares estadounidenses. No establece costes de envío, disponibilidad ni la impresión comprable más barata.

¿Una búsqueda devuelve todas las cartas que coinciden?

Una búsqueda devuelve una página de la API. La respuesta incluye total_cards, has_more y, cuando corresponde, next_page. Open Query muestra hasta cinco recomendaciones de la página obtenida. Pide más de esa página o solicita explícitamente la siguiente página de la API. Una lista corta no es el conjunto completo de resultados.

¿Puede esto construir todo mi mazo de Commander?

Este tutorial crea un asistente de búsqueda de cartas. Ayuda a encontrar e inspeccionar candidatas para un hueco del mazo. No valida un mazo completo de 100 cartas, no optimiza una lista de mazo ni sustituye a un juez de reglas.