MTG Forja

Analiza un mazo de Magic: The Gathering y genera tres cosas: una guía extensa de sinergias, una chuleta imprimible de dos caras y un mapa interactivo navegable.

Funciona de tres maneras: como servidor MCP dentro de Claude, como herramienta de línea de comandos y como web que corre entera en el navegador.

La premisa: las interacciones se comprueban contra el texto de oráculo real que devuelve Scryfall, nunca contra lo que un modelo de lenguaje cree recordar. Los cuatro errores que originaron este proyecto —una carta que se creía que barajaba y mandaba al fondo, una tierra indestructible tomada por condicional— son exactamente los que el motor detecta bien.

Qué genera

Pegas una lista de mazo y salen tres documentos HTML autónomos. Estas capturas son salida real del mazo de ejemplo: 45 cartas y 39 sinergias detectadas.

El mapa del mazo

Un grafo de fuerzas navegable: cada círculo es una carta, su tamaño depende de cuántas copias llevas y el grosor de la línea marca la fuerza de la sinergia. Las líneas rojas discontinuas son cartas que se estorban entre sí. Puedes pulsar cualquier carta para aislar sus conexiones, arrastrarlas y hacer zoom.

Salen todas las cartas del mazo, también las que no tienen ninguna relación detectada: una tierra suelta dice algo del mazo, y esconderla no.

Los filtros por función son acumulables — enciende varios y verás lo que encaje en cualquiera de ellos. Y el botón Ajustes controla la densidad de la red:

El motor sigue calculando todas las sinergias; esto solo decide cuáles se dibujan. Los conflictos no se ocultan con ningún ajuste, porque avisar es el trabajo principal del mapa.

La guía de sinergias

Página larga con cada jugada desarrollada: las piezas ilustradas, la secuencia numerada de ejecución, los avisos y el mazo completo agrupado por función. Pensada para leerla una vez y entender el mazo.

La chuleta

Dos caras A4 densas, sin literatura, para imprimir y tener al lado mientras juegas. Cada línea es una interacción con sus cartas en miniatura y cuándo aplica.

De qué se compone

Qué es MCP. El Model Context Protocol es un estándar abierto para que un modelo pueda llamar a programas externos. Aquí el reparto es deliberado: el servidor aporta los hechos, el modelo aporta el criterio. Por eso detectar_sinergias no devuelve prosa cerrada, sino candidatas con su evidencia: los datos los pone el motor, la redacción y el juicio los pone Claude.

Qué es la skill. Un archivo de instrucciones que Claude lee cuando la tarea lo pide. Si las herramientas le dan capacidad, la skill le da criterio: le prohíbe afirmar nada de memoria, le dice cuándo generar cada documento y cómo escribir los pasos. Funciona sin ella; con ella los análisis salen bastante mejor.

Qué necesitas según cómo lo uses

Instalación

Elige el camino según cómo quieras usarlo. La web no requiere instalar nada; el resto depende de si quieres usarlo desde Claude o desde la terminal.

Requisito previo (salvo para la web)

Todo lo demás necesita Python 3.10 o superior. La forma más cómoda de ejecutarlo es con uv, que descarga y aísla el proyecto por ti sin que tengas que crear entornos a mano:

curl -LsSf https://astral.sh/uv/install.sh | sh

En macOS también vale brew install uv. Si prefieres no instalar uv, más abajo tienes la alternativa con pip.

La web (nada que instalar)

https://grutino.github.io/mtg-forja/

Pegas la lista, pulsas Analizar mazo y sale el mapa. Desde ahí, los botones Guía y Chuleta generan los otros dos documentos. Todo ocurre en tu navegador; no se envía nada a ningún servidor salvo la consulta de cartas a Scryfall. Es la forma más rápida de ver si el proyecto te sirve.

Los archivos que descarga la web son exactamente los mismos que genera la línea de comandos: el mismo renderizador, incrustado en un HTML autónomo.

Claude Desktop

1. Abre el archivo de configuración de conectores:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

   Si no existe, créalo con ese contenido. Si ya tienes otros conectores, añade solo la entrada "mtg-forja" dentro del mcpServers que ya tengas.

2. Pega esto:

{
  "mcpServers": {
    "mtg-forja": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/grutino/mtg-forja", "mtg-forja-mcp"],
      "env": { "MTG_FORJA_SALIDA": "/ruta/donde/quieres/los/html" }
    }
  }
}

Cambia /ruta/donde/quieres/los/html por una carpeta tuya real (por ejemplo /Users/tunombre/Documents/mazos). Ahí es donde aparecerán los documentos generados.

3. Cierra Claude Desktop del todo y vuelve a abrirlo. No basta con cerrar la ventana.

4. Comprueba que ha cargado: en el icono de conectores debe aparecer mtg-forja con sus nueve herramientas. Si no sale, mira Si algo falla.

5. Instala además la skill de skill/SKILL.md para que Claude sepa cómo usar las herramientas: qué verificar, cómo redactar los pasos y cuándo generar cada documento. Sin ella funciona, pero con ella los textos salen bastante mejor.

Claude Code

Desde la terminal, en cualquier carpeta:

claude mcp add mtg-forja --scope user --env MTG_FORJA_SALIDA=/ruta/donde/quieres/los/html -- uvx --from git+https://github.com/grutino/mtg-forja mtg-forja-mcp

--scope user lo deja disponible en todos tus proyectos. Si prefieres tenerlo solo en un proyecto concreto, usa --scope project: se guardará en un .mcp.json en la raíz del repositorio, que puedes commitear para que lo tenga todo tu equipo.

Ese .mcp.json es exactamente el mismo formato que el de Claude Desktop, así que también puedes escribirlo a mano:

{
  "mcpServers": {
    "mtg-forja": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/grutino/mtg-forja", "mtg-forja-mcp"],
      "env": { "MTG_FORJA_SALIDA": "/ruta/donde/quieres/los/html" }
    }
  }
}

Otros clientes MCP

El servidor habla MCP sobre stdio, que es el transporte estándar. Sirve tal cual en cualquier programa que soporte MCP —Cursor, Windsurf, Zed, VS Code con una extensión compatible, LM Studio y demás—. Casi todos usan el mismo formato que Claude Desktop; si el tuyo pide los campos por separado, esta es la equivalencia:

Consulta la documentación de tu cliente para saber dónde vive su archivo de configuración; el bloque mcpServers de arriba suele copiarse sin cambios.

Alternativa sin uv

Si no quieres instalar uv, instala el paquete en un entorno propio y apunta al ejecutable por su ruta absoluta:

python3 -m venv ~/.venvs/mtg-forja
~/.venvs/mtg-forja/bin/pip install git+https://github.com/grutino/mtg-forja

Y en la configuración, en lugar de uvx:

{
  "mcpServers": {
    "mtg-forja": {
      "command": "/Users/tunombre/.venvs/mtg-forja/bin/mtg-forja-mcp",
      "args": [],
      "env": { "MTG_FORJA_SALIDA": "/ruta/donde/quieres/los/html" }
    }
  }
}

Usa siempre la ruta absoluta: los clientes MCP no heredan tu PATH, y ese es el motivo más común de que un servidor no arranque.

Línea de comandos

Sin instalar nada de forma permanente:

uvx --from git+https://github.com/grutino/mtg-forja mtg-forja mazo.txt -n "Mi mazo" -o salida

O instalándolo de una vez:

pip install git+https://github.com/grutino/mtg-forja
mtg-forja mazo.txt -n "Mi mazo" -o salida

Genera salida/guia.html, salida/chuleta.html y salida/mapa.html.

Cómo se usa

Desde Claude

Una vez instalado el conector, pídeselo en lenguaje natural y pégale la lista:

«Analiza este mazo y hazme el mapa y la chuleta: 4 Cleansing Wildfire 4 Cascading Cataracts …»

Claude resolverá las cartas contra Scryfall, buscará los patrones de interacción y generará los HTML en la carpeta que pusiste en MTG_FORJA_SALIDA. Vale el formato de exportación de MTG Arena, Moxfield, Archidekt, MTGO, el CSV de ManaBox, o una carta por línea.

Cosas que puedes pedirle, ya que las herramientas están separadas a propósito:

• «¿Qué sinergias detecta este mazo?» — solo el análisis, sin generar documentos.

• «Enséñame las reglas que conoce el motor» — el catálogo de patrones.

• «Genérame solo la chuleta» — un único documento.

• «¿Por qué dice que estas dos cartas se estorban?» — cada sinergia viene con la frase de oráculo exacta que la disparó, así que puedes auditar el razonamiento.

Desde la línea de comandos

mtg-forja mazo.txt -n "Mi mazo" -o salida

Abre los tres HTML en el navegador. Son autónomos: puedes moverlos, enviarlos por correo o imprimir la chuleta directamente desde el navegador.

Desde la web

1. Entra en https://grutino.github.io/mtg-forja/

2. Pega la lista, o pulsa Cargar ejemplo para ver cómo funciona con un mazo de prueba.

3. Pulsa Analizar mazo.

4. Pulsa cualquier carta del grafo para aislar sus conexiones; arrastra para recolocar, rueda del ratón para acercar y los botones de arriba para filtrar por función.

5. Los botones Guía y Chuleta, arriba a la derecha, abren esos documentos en una pestaña nueva. Guárdalos con Ctrl/Cmd + S, o imprime la chuleta directamente: está maquetada en A4 y sale bien del navegador sin tocar nada.

Si algo falla

Herramientas MCP

El reparto es deliberado: el servidor aporta los hechos, el modelo aporta el criterio. Por eso detectar_sinergias devuelve borradores con evidencia en lugar de prosa cerrada.

Cómo funciona el motor

src/mtg_forja/reglas.json es una lista de patrones genéricos de interacción. No sabe nada de cartas concretas: describe formas. Por ejemplo, «una carta que destruye una tierra y roba» más «una tierra indestructible» es una sinergia de rampa, se llamen como se llamen.

{
  "id": "tierra-indestructible-cantrip",
  "nombre": "Rampa y robo con tierra indestructible",
  "fuerza": 3,
  "piezas": [
    {"rol": "a", "oracle": "destroy target land",
     "oracle2": "search their library for a basic land", "oracle3": "draw a card"},
    {"rol": "b", "tipo": "Land", "oracle": "indestructible"}
  ],
  "resumen": "{a} apuntado a tu propia {b} no la destruye, pero…"
}

Campos disponibles en cada pieza: oracle, oracle2, oracle3, no_oracle, tipo, no_tipo, coste, mv_min, mv_max, copias_min, copias_max. A nivel de regla, conteo permite condiciones sobre el mazo entero (basicas, tierras, total).

Añadir una regla es añadir un objeto a esa lista. Nada más. Se usa igual desde Python y desde el navegador, porque las dos mitades leen el mismo archivo.

La segunda capa: el léxico de recursos

Escribir una regla por cada pareja de cartas que interactúa no escala a treinta mil naipes. Por eso hay un segundo motor que trabaja al revés: src/mtg_forja/lexico.json no describe parejas, describe recursos. De cada carta deduce qué produce, qué premia y qué rompe.

{
  "id": "cementerio",
  "nombre": "el cementerio",
  "fuerza": 3,
  "produce": {"oracle": ["\\bmills?\\b", "discard(s)? (a|your|two)"],
              "no_oracle": "exile(s)? .{0,40}graveyard",
              "texto": "llena tu cementerio"},
  "premia":  {"oracle": ["\\bDelve\\b", "cards? in your graveyard"],
              "texto": "se alimenta del cementerio"},
  "rompe":   {"oracle": ["exile(s)? .{0,40}graveyard"],
              "texto": "vacía los cementerios"}
}

Las sinergias no se escriben, se deducen: si A produce un recurso y B lo premia, hay sinergia; si A lo rompe y B depende de él, hay conflicto. Un concepto cubre de golpe todas las parejas que lo compartan, así que el esfuerzo crece con las mecánicas del juego y no con el número de mazos. Hoy son 24 conceptos frente a 37 reglas escritas.

Cada bloque acepta los mismos campos que una pieza de regla (oracle, no_oracle, tipo, no_tipo, mv_min, mv_max), y texto es lo que se lee en el resumen.

Dos cosas que se aprendieron a base de falsos positivos, y que el motor ya hace por ti: ignora el texto recordatorio entre paréntesis (el de retrospectiva de Snapcaster Mage dice «exile it» y la carta pasaba por odio al cementerio) y quita el nombre propio de la carta antes de analizar (Lightning Storm casaba con la mecánica Tormenta).

Hasta dónde llega cada camino

Conviene decirlo claro, porque determina qué esperar:

Las reglas escritas no salieron de un motor: salieron de un modelo leyendo el oráculo de cada carta y razonando, y luego alguien congeló esas conclusiones. Por eso ningún motor de patrones las reproduce. Comprobado: sobre el mazo que originó el proyecto, el léxico redescubre 1 de las 18 parejas escritas a mano.

Lo que ningún motor puede ver, y sí ve un modelo con el oráculo delante:

• «apaga los artefactos del rival, pero no los tuyos» — requiere entender la asimetría

• «el barrido no alcanza a tus planeswalkers» — requiere inferir qué queda fuera

• «esa tierra solo es criatura cuando la activas, así que sobrevive» — estados temporales

• «barajar descoloca la carta que pusiste arriba» — posición en la biblioteca

Por eso la herramienta radiografia_del_mazo existe: le da al modelo esos hechos —alcance, tipos que menciona, zonas que toca— para que pueda razonar en vez de adivinar.

Si quieres el análisis bueno de un mazo que nadie ha visto, usa el camino MCP. El CLI y la web no tienen un modelo detrás; ahí el léxico sirve de suelo, para que un mazo desconocido nunca devuelva una página casi vacía.

¿Y las colecciones nuevas?

El léxico no describe cartas ni colecciones: describe recursos. Una carta nueva que llene el cementerio, haga fichas o premie a los dragones encaja en conceptos que ya existen, salga en la colección que salga.

Medido sobre 525 cartas reales de 2023 en adelante: el motor lee el 98 %. Lo que no entiende son equipos y auras que solo dan +X/+X, que apenas tienen señal de sinergia.

Lo que sí se escapa es una mecánica genuinamente nueva — Ferocious pide «controlas una criatura de fuerza 4 o más», y sin un concepto para eso un mazo entero se queda mudo. Suelen ser dos o tres por colección.

Para no depender de que alguien se dé cuenta:

python scripts/auditar_cobertura.py --minimo 25

Pregunta a Scryfall qué mecánicas existen hoy, cuántas cartas usa cada una, y avisa de las que ningún concepto menciona. De las 371 del juego, 295 tienen menos de veinte cartas: son residuales de colecciones antiguas. Las que merecen un concepto son unas quince, y el guion las ordena por uso real.

Hay además una acción que lo ejecuta cada lunes y abre un aviso en el repositorio si aparece algo nuevo que se use de verdad.

Cómo saber si TU mazo está bien analizado

Un porcentaje de cobertura puede mentir. El caso real que lo enseñó: un mazo de dragones daba «100 %, el motor cubre las mecánicas de este mazo» mientras la carta que lo sostenía —una que abarata las criaturas con volar— aparecía en el mapa completamente suelta, sin una sola línea.

Las dos razones, y las dos están corregidas:

1. Volar estaba en la lista de «palabras de combate que no definen sinergias». Es cierto hasta que una carta se fija en ellas; entonces es el eje del mazo.

2. La mecánica Flurry («lanzas tu segundo hechizo del turno») no la etiqueta Scryfall como palabra clave, así que ningún recuento la veía. Y tiene menos de 25 cartas en todo Magic: la auditoría global tampoco la habría sacado nunca, aunque en ese mazo concreto fuera la mitad de la lista.

La lección es que contar mecánicas no mide comprensión. La señal que sí la mide es la que se ve de un vistazo en el mapa, y ahora sale también en el informe:

cartas_sin_relacion: ["Momo, Friendly Flier", ...]

Si una carta importante del mazo sale ahí, falta un concepto. Es la comprobación que conviene hacer con cualquier mazo de una colección recién salida.

Cuando el mapa sale casi vacío

Un mazo blanco agresivo de los de siempre —Mother of Runes, Worship, Soltari, Rishadan Port— salía con cuatro líneas y casi todo suelto. Las tres cosas que faltaban dicen bastante de dónde falla un motor de patrones:

Ninguna era un caso raro: eran dependencias entre una carta y un tipo, y el motor solo sabía emparejar cartas con cartas. Ahora un tutor casa con lo que dice buscar —y solo con eso, nunca con una criatura— y un efecto que exige controlar una criatura casa con las criaturas que llevas.

El mazo pasa de 4 sinergias a 26, y las dos cartas que siguen sueltas son Swords to Plowshares y Disenchant: removal puro, que en ese mazo de verdad no se apoya en nada. Eso es lo que debe quedar suelto.

Tres fuentes que no somos nosotros

El motor deduce leyendo el oráculo con patrones propios. Eso es una sola opinión, y conviene contrastarla con quien no seamos nosotros:

Las tres degradan sin romper nada: sin red, el análisis sigue.

Las etiquetas funcionales se consultan con el operador otag: de la API pública de Scryfall, y valen sobre todo para ver lo que se nos escapa. Sobre el mazo de Stiflenought:

drawback     Phyrexian Dreadnought
phasing      Vision Charm
pitch-spell  Foil, Misdirection
counterspell Counterspell, Daze, Foil, Stifle, Thwart

drawback en Phyrexian Dreadnought es exactamente el concepto que habíamos escrito a mano — dos fuentes independientes de acuerdo. Y pitch-spell señala un grupo que el motor todavía no relaciona.

No hay catálogo público de etiquetas, así que se descubren probando:

python scripts/etiquetas_descubrir.py

Una advertencia que costó un bug: cuando una consulta falla, eso no es una ausencia. Tragarse un 429 y dar la etiqueta por vacía convierte un fallo de red en un dato, y el informe pasa a mentir con toda la confianza del mundo. Por eso salen aparte, en etiquetas_sin_comprobar.

Lo que el contraste destapó al usarlo

La primera vez que se pasó el contraste por los cuatro mazos, marcó cinco parejas como «había con qué comprobarlo y no salió nada». Las cinco eran falsos positivos, y de dos clases:

Un peaje no es un recurso. Sage of the Skies tiene vínculo vital y Sacred Foundry dice «paga 2 vidas o entra girada». Emparejarlos haría que cualquier mazo con tierras de choque saliera unido a cualquier criatura con lifelink. La vida como recurso es Necropotence, no un peaje de dos vidas en el turno uno.

Sacrificarse a sí misma no llena el cementerio. El patrón cazaba cualquier Sacrifice this, así que Maelstrom of the Spirit Dragon —que se sacrifica para buscar un Dragón— salía emparejada con el flashback de Daydream. Esa tierra en el cementerio no hace nada por Daydream, que llega ahí por lanzarse.

Ese segundo arreglo se llevó por delante, de una vez, las dos parejas del Stiflenought que ya sospechábamos a mano días antes. Después: 12 de 12 reforzadas y ninguna sospechosa.

La lección es sobre el contraste, no sobre las cartas: sirve porque cada aviso señala un sitio concreto donde mirar. Si se hubiera calibrado para que todo saliera verde, no habría encontrado nada.

Cuando la comunidad ve algo que el motor no

Demonic Consultation + Thassa's Oracle gana la partida en el sitio y es de los combos más conocidos que existen. El motor no lo deduce: hace falta saber que vaciarte la biblioteca convierte el disparo del Oráculo en victoria, y eso no está escrito en ninguna de las dos cartas.

El catálogo sí lo sabe. Así que entra en los documentos, marcado como venido de la comunidad y con fuerza 5, por encima de lo que deduce el motor:

mtg-forja mazo.txt              # consulta el catálogo
mtg-forja mazo.txt --sin-combos # no lo consulta

Solo entran los combos completos —todas sus piezas dentro del mazo—. Los casi_completos nombran cartas que no llevas: son sugerencias de construcción, y dibujarían líneas hacia cartas que no existen en la lista.

Dos límites que conviene tener claros:

La web no puede. La API del catálogo no envía cabeceras CORS, así que el navegador bloquea la petición. Por eso los combos entran solo por la línea de comandos y por MCP. El motor sigue siendo idéntico en los dos sitios —la prueba de paridad lo vigila sobre cuatro mazos—, pero la terminal consulta una fuente extra que el navegador no alcanza.

El mapa no los distingue del todo. La guía y la chuleta llevan el aviso de que esa jugada no sale del oráculo; en el mapa, la evidencia que se muestra por carta es la de la primera sinergia que la menciona, así que a veces enseña el texto de oráculo en vez de la procedencia. Está pendiente darle a esas líneas un estilo propio.

La comunidad manda

Hay un orden de precedencia, y el motor está el último:

1. Un ruling oficial. Es la regla escrita por Wizards. Si contradice una sinergia detectada, se descarta la sinergia.

2. Un combo catalogado por la comunidad. Son jugadas que alguien ha visto funcionar en una mesa. Si el catálogo une dos cartas del mazo y el motor no, el hueco es nuestro: sale en la_comunidad_ve_lo_que_nosotros_no y cuenta como sinergia aunque no aparezca en el mapa.

3. Lo que deduce el motor. Lo último, y solo cuando nadie más ha hablado.

Por eso cada pareja detectada sale con veredicto: reforzada por ruling oficial, reforzada por etiquetas, o sin apoyo. Y el campo que más conviene mirar es sin_apoyo_pero_comprobables: parejas donde sí había con qué contrastar y no salió nada. Sobre el mazo de Stiflenought señala dos, y son exactamente las dos que ya sospechábamos a mano.

Distinguir «nadie lo ha comprobado» de «nadie lo respalda» es la mitad del valor: un concepto sin etiqueta equivalente no es sospechoso, es que no hay por dónde mirarlo. Forzar el mapeo para que todo salga verde destruiría el aviso — un premio tribal no es un lord, así que ese concepto no se mapea y punto.

Pagar un hechizo con algo que no es maná

Además de las tierras, hay 80 cartas cuyo coste alternativo se cobra en otra moneda: sacrificar criaturas (Delraich, Demon of Death's Gate), taparlas (el ciclo de Masques), exiliar cartas de la mano, pagar vida.

El motor empareja cada una con lo que su texto dice que se lleva por delante, no con cualquier permanente: un coste que pide criaturas no se paga con un artefacto.

Una regla escrita mirando una carta

Daze devuelve una Isla para lanzarse gratis, y había una regla para eso. Decía literalmente return an Island, así que en un mazo con cuatro hechizos de esa familia solo enseñaba uno: Gush devuelve dos Islas, Thwart tres, y Foil la descarta en vez de devolverla.

Preguntando a Scryfall salen 32 cartas con costes que se pagan con tierras, y es un ciclo por los cinco colores con tres verbos: devolver, descartar y sacrificar —Fireblast sacrifica dos Montañas, Abolish descarta un Llano—.

Generalizarla como regla escrita no valía: allí el tipo de la segunda pieza va fijo, así que habría emparejado Foil con una Montaña. Pasa a ser concepto del léxico, que sí casa por subtipo: cada hechizo con la tierra que de verdad nombra.

La moraleja se repite tanto que conviene decirla: una regla escrita mirando una carta describe esa carta, no el efecto. El singular, el verbo concreto y el tipo fijo son las tres formas de que se note.

Compartir etiqueta no es tener sinergia

Es la trampa más fácil de esta fuente, y estuve a punto de caer en ella.

Foil y Misdirection comparten otag:pitch-spell, así que parece que van juntas. No van: esa etiqueta las clasifica, igual que agrupa a Counterspell con Daze. De hecho compiten — las dos se pagan con cartas de la mano, el mismo recurso, y por eso el mazo lleva una Misdirection y no cuatro.

Ninguna otra fuente las une tampoco: Misdirection tiene cuatro rulings y ninguno menciona nada parecido, y Commander Spellbook no devuelve nada.

Lo que sí es una sinergia estaba al lado, y es de otra clase:

Gush → "return two Islands you control to their owner's hand"
Foil → "discard an Island card ... rather than pay this spell's mana cost"

Gush te pone Islas en la mano; Foil necesita descartar una Isla de la mano para lanzarse gratis. Gush paga literalmente el coste de Foil, y eso también vale para Daze y Thwart, que devuelven Islas igual.

La diferencia importa y da la regla general: una categoría agrupa cartas que se parecen; una sinergia es un recurso que pasa de una carta a otra. Convertir categorías en líneas es exactamente cómo Misdirection acabó con nueve conexiones que no significaban nada.

Por eso las etiquetas se usan para buscar dónde mirar, nunca como sinergia directa. Señalaron el sitio correcto por el motivo equivocado, y eso ya es útil.

Contrastar contra la fuente oficial

Un combo conocido desde hace veinte años no debería costar deducirlo. Y no hace falta: suele estar explicado en el ruling oficial de la propia carta, que es la mejor prueba que existe — no es la opinión de nadie, es la regla.

Los rulings de Phyrexian Dreadnought documentan las dos mitades del combo:

«Reverted to its original wording, this now has an "enters" triggered ability.» — por eso Stifle lo contrarresta

«Phasing in does not trigger "enters" abilities, so you don't have to sacrifice again if it phases in.» — por eso Vision Charm funciona

Por eso hay una herramienta que coge las sinergias detectadas y busca qué dice Wizards sobre ellas. Sobre ese mazo respalda las dos piezas del combo.

Dos avisos, porque importan:

• Empareja por vocabulario, así que señala rulings relacionados. No demuestra la jugada: la lee un humano —o el modelo, por MCP— y decide.

• Que una pareja no traiga apoyo no la vuelve falsa. La mayoría de las cartas apenas tienen rulings, y la ausencia no dice nada.

Si un ruling contradice una sinergia detectada, gana el ruling.

Por qué no vale Commander Spellbook aquí. Ya está integrada y es buena, pero es una base de datos de Commander: preguntada por este mazo de Legacy devuelve cero. Los rulings, en cambio, no saben de formatos.

No todo disparo al entrar es bueno

Phyrexian Dreadnought es un 12/12 por {1} con una letra pequeña: al entrar, lo sacrificas salvo que sacrifiques doce puntos de fuerza. El mazo entero existe para cancelar ese disparo — Stifle lo contrarresta, Vision Charm hace desvanecerse el artefacto — y el motor no encontraba ninguna de las dos.

La razón de fondo: daba por hecho que un disparo al entrar es valor. Aquí es un lastre. Ahora hay un concepto para el disparo que te cobra un precio y para quien lo neutraliza, y el emparejado por tipo sabe quién apunta a quién: en un tutor apunta el que busca, en una respuesta apunta el que contesta. Por eso Vision Charm solo vale contra un artefacto, que es lo único que puede hacer desvanecerse.

Una carta cualquiera no es una sinergia

En ese mismo mazo, Misdirection salía como el nudo principal con nueve conexiones. Se lanza exiliando «a blue card», y en un mazo monoazul eso lo cumplen las quince cartas: nueve líneas para decir que el mazo es azul.

El consejo que sí vale —cada uso te cuesta dos cartas— habla de Misdirection sola. No es una pareja, así que ahora es una nota de una carta y no dibuja ninguna línea. Un mapa donde una carta conecta con todo no dice nada de ninguna.

Una jugada imposible no es una jugada floja

En el mazo de dragones salía Daydream emparejado con Seam Rip. El razonamiento del motor era correcto por separado y absurdo junto: «Daydream vuelve a meter permanentes en juego» más «Seam Rip tiene un disparo al entrar».

Lo que nunca comprobó es si Daydream puede apuntarla. Dice «exile target creature you control», y Seam Rip es un encantamiento.

Ahora un efecto solo alcanza a los tipos que su propio texto dice alcanzar:

La misma comprobación sirve para los tutores, que solo encuentran lo que dicen buscar. Daydream conserva sus tres criaturas con disparo al entrar y pierde el encantamiento.

Un aviso falso es peor que ningún aviso

La regla «doble símbolo de color con tierras incoloras» decía solo produce incoloro pero nunca comprobaba lo de solo. Maelstrom of the Spirit Dragon dice «Add {C}», y también «{T}: Add one mana of any color» sin coste extra, para pagar dragones. El motor avisaba contra los tres dragones a los que esa tierra existe justo para lanzar.

Salió a la luz al emitir todas las parejas: pasó de una línea roja a tres, y tres ya cantaban. Ahora la regla exige que la tierra no produzca color gratis. El aviso legítimo sigue: Cascading Cataracts cobra {5} por el color, así que en los primeros turnos es incolora de verdad.

Una regla, todas las cartas que encajen

Las reglas escritas a mano ya eran genéricas —«cualquier tierra indestructible», no una carta concreta— pero el motor emitía una sola pareja por regla: elegía la carta más representativa del papel y descartaba el resto.

En el mazo de ejemplo hay dos tierras indestructibles. Cascading Cataracts se llevaba la única línea y Rustvale Bridge, de la que van cuatro copias, colgaba suelto en el mapa pese a hacer exactamente la misma jugada:

Apuntas Cleansing Wildfire a tu propia tierra indestructible. No se destruye, pero el objetivo sigue siendo legal: buscas la básica y robas igualmente.

Ahora una regla emite todas las combinaciones que encajen, con un tope de doce por regla para que una laxa no llene el mapa. Es el mismo arreglo que ya se hizo en el léxico cuando una carta eje aparecía con dos de sus seis compañeros.

La trampa de las palabras clave

El texto entre paréntesis de una carta —el recordatorio— se descarta antes de analizarla, porque repite reglas genéricas y disparaba falsos positivos. El precio es sutil: en una mecánica con nombre, el significado vive justo ahí.

Voice of Victory dice «Mobilize 2», y todo lo demás —que crea dos fichas de criatura al atacar— está en el recordatorio. El motor veía una palabra sin contenido, y una carta de la que llevas cuatro copias colgaba de un solo hilo.

Por eso los conceptos reconocen también el nombre de la mecánica, no solo su efecto redactado: Mobilize, Amass, Fabricate, Populate, Ferocious, Flurry. Es la forma de que una palabra clave nueva entre con una línea de más.

No todas merecen concepto, y decir que no también es una decisión:

Dos límites que conviene conocer

El motor solo encuentra lo que se le ha enseñado. Si analizas un mazo y salen dos sinergias, casi nunca es un fallo de resolución: es que el paquete no cubre ese arquetipo todavía. Para comprobarlo, mira cartas_sin_resolver en la salida — si viene vacío, las cartas se leyeron bien y lo que falta son patrones. Escribir la regla que falta es el trabajo, y es el trabajo que hace crecer esto.

El banquillo no entra en la detección. Las cartas de reserva se resuelven contra Scryfall y aparecen en el documento, pero las reglas solo cruzan el mazo principal. Una sinergia que dependa de una carta del banquillo no se detecta.

Después de tocar reglas.json, lexico.json, grafo.css o cualquiera de los renderizadores .js, sincroniza la web:

python scripts/sync_docs.py

Montarlo entero en tu máquina

Si quieres tenerlo todo funcionando en local —la web, la línea de comandos y el servidor MCP— sin depender de GitHub Pages, estos son los pasos completos.

Requisitos previos

No hace falta Node, ni npm, ni ningún servidor: la web es HTML y JavaScript estáticos, y el único servidor que se levanta es el que trae Python de serie. Tampoco hace falta uv para esto; uv solo simplifica el arranque del conector MCP.

Sobre la conexión: aunque todo corra en tu máquina, los nombres de carta y las imágenes se piden a Scryfall. Sin internet, el motor no puede resolver el mazo. Para trabajar sin red existe MTG_FORJA_FIXTURE, pensado para las pruebas.

Paso 1 — Clonar e instalar

git clone https://github.com/grutino/mtg-forja
cd mtg-forja
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

En Windows, la tercera y cuarta línea son py -m venv .venv y .venv\Scripts\activate.

El -e instala en modo editable: si tocas el código, no hay que reinstalar. Si usas conda, crea igualmente el venv: mezclar ambos da problemas.

Paso 2 — Comprobar que funciona

pip install pytest
pytest -q

Deben pasar las pruebas, y no tocan la red: usan el fixture de ejemplos/. Si fallan aquí, no sigas: algo está mal en la instalación, no en tu mazo.

Ahora una prueba de verdad, contra Scryfall:

mtg-forja ejemplos/prueba.txt -n "Prueba" -o /tmp/forja-prueba

Debe imprimir un resumen del tipo 30 cartas · 15 sinergias y dejar tres HTML en /tmp/forja-prueba. Ábrelos en el navegador.

Hay un segundo mazo de ejemplo, uno real de 60 cartas —Boros de dragones— que es el que destapó dos fallos de bulto y ahora vive aquí como regresión:

mtg-forja ejemplos/dragones-boros.txt -n "Dragones Boros" -o /tmp/forja-dragones

Salen 60 cartas · 28 sinergias. Trae su propio fixture, así que también corre sin red:

MTG_FORJA_FIXTURE=ejemplos/fixture-dragones.json mtg-forja ejemplos/dragones-boros.txt -o /tmp/salida

Paso 3 — Levantar la web en local

python scripts/sync_docs.py
python -m http.server -d docs 8000

Y abre http://localhost:8000.

Eso es todo: ya tienes la web completa —mapa, guía y chuleta— corriendo en tu máquina, sin pasar por GitHub. sync_docs.py copia a docs/ el paquete de reglas y los renderizadores que comparten las dos mitades del proyecto; ejecútalo siempre que toques reglas.json o cualquiera de los .js de src/mtg_forja/render/, o la web se quedará con la versión vieja.

Para parar el servidor, Ctrl + C.

Paso 4 (opcional) — Conectar tu Claude a esta copia local

Si quieres que Claude use tu copia en lugar de descargarla de GitHub, apunta el conector al ejecutable de tu entorno virtual, con ruta absoluta:

{
  "mcpServers": {
    "mtg-forja": {
      "command": "/ruta/completa/a/mtg-forja/.venv/bin/mtg-forja-mcp",
      "args": [],
      "env": { "MTG_FORJA_SALIDA": "/ruta/donde/quieres/los/html" }
    }
  }
}

Averigua la ruta exacta con which mtg-forja-mcp (con el entorno activado). En Windows es .venv\Scripts\mtg-forja-mcp.exe. Así los cambios que hagas en el código los ve Claude en cuanto reinicies la aplicación.

Resumen

git clone https://github.com/grutino/mtg-forja && cd mtg-forja
python3 -m venv .venv && source .venv/bin/activate
pip install -e . pytest
pytest -q                                    # 16 pruebas, sin red
python scripts/sync_docs.py                  # sincroniza reglas y renderizadores
python -m http.server -d docs 8000           # web completa en localhost:8000

Desarrollo

# prueba sin red, con el fixture de ejemplo
MTG_FORJA_FIXTURE=ejemplos/fixture-pruebas.json mtg-forja ejemplos/prueba.txt -o /tmp/salida

Variables de entorno:

Publicar la web

En los ajustes del repositorio, Pages → Source: Deploy from a branch → main / docs.

Estructura

src/mtg_forja/
  modelo.py        cartas, mazo, parseo de listas (Arena, Moxfield, Archidekt, ManaBox…)
  scryfall.py      resolución con caché en disco y modo sin red
  reglas.json      patrones escritos a mano — parejas concretas de cartas
  reglas.py        motor de detección de esos patrones
  lexico.json      conceptos de recurso — aquí es donde se crece de verdad
  lexico.py        motor deductivo: cruza productores con premiadores
  hechos.py        radiografía objetiva del mazo (alcance, zonas, base de maná)
  combos.py        cliente de Commander Spellbook, con caché y degradación limpia
  render/
    comun.js       paleta y utilidades compartidas
    guia.js        \
    chuleta.js      >  el diseño de los tres documentos, en una sola implementación
    grafo.js       /
    grafo.css      estilos del mapa, compartidos con la web
    guia.py        \
    chuleta.py      >  cáscaras: incrustan el JS y el documento en un HTML autónomo
    mapa.py        /
  server.py        servidor MCP — las nueve herramientas
  cli.py           línea de comandos
docs/              web de GitHub Pages (lee los mismos datos y renderizadores)
docs/motor.js      gemelo en JavaScript de modelo + scryfall + reglas + lexico
docs/capturas/     las imágenes de este README
skill/SKILL.md     cómo debe usar Claude todo lo anterior
tests/             16 pruebas, todas sin red

Los renderizadores no están duplicados. El diseño de cada documento existe una sola vez, en su .js. Python no lo reimplementa: incrusta ese archivo junto al documento en JSON y deja que el navegador lo pinte. Por eso la web y la línea de comandos producen el mismo archivo, byte a byte, y no pueden separarse con el tiempo. sync_docs.py es lo que mantiene docs/ al día.

Por qué no hay más fuentes

Se probaron, una por una, y estos son los resultados reales:

La conclusión, tras revisarlas una a una: solo dos aportan algo, y las dos están dentro. Scryfall pone el oráculo real y los rulings oficiales de Wizards; Commander Spellbook pone los combos ya catalogados. El resto son precios, popularidad, listas de mazos o —como edh-combos.com— reempaquetados de las anteriores.

Ninguna se descartó por estar cerrada sin más: se descartaron porque no responden a esta pregunta. Entender por qué dos cartas interactúan exige leer lo que dicen, y eso solo lo dan el texto de la carta y las aclaraciones de quien escribe las reglas.

Créditos y licencia

Código bajo licencia MIT, en LICENSE.

Los datos y las imágenes de carta vienen de la API pública de Scryfall y se enlazan, no se copian; las capturas de este README son la excepción, por necesidad. Magic: The Gathering es propiedad de Wizards of the Coast. Este es un proyecto de aficionado sin ánimo de lucro, amparado por la Fan Content Policy de Wizards, y no está patrocinado ni respaldado por Wizards ni por Scryfall.

Los combos catalogados de combos_conocidos vienen de Commander Spellbook, curados por su comunidad. No están afiliados a este proyecto. Si construyes sobre esto, cítalos.

Si usas la API de Scryfall en tu propio despliegue, respeta su ritmo de peticiones (una cada 50-100 ms). Con Commander Spellbook, combos.py hace una sola petición por mazo y la cachea en disco; su robots.txt desaconseja rastrear el backend, así que no lo conviertas en un bucle. Ninguna de las dos requiere clave.