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

Related MCP server: mtg-mcp-server

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.

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 · 14 sinergias y dejar tres HTML en /tmp/forja-prueba. Ábrelos en el navegador.

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.

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.