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, 20 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, hacer zoom y filtrar por función.

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 siete 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, el de Moxfield 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.

Después de tocar reglas.json 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 · 12 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                                    # 6 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, texto suelto)
  scryfall.py      resolución con caché en disco y modo sin red
  reglas.json      el paquete de patrones — aquí es donde se crece
  reglas.py        motor de detección
  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       /
    guia.py        \
    chuleta.py      >  cáscaras: incrustan el JS y el documento en un HTML autónomo
    mapa.py        /
  server.py        servidor MCP
  cli.py           línea de comandos
docs/              web de GitHub Pages (lee los mismos reglas.json y renderizadores)
docs/capturas/     las imágenes de este README
skill/SKILL.md     cómo debe usar Claude todo lo anterior

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.

Si usas la API de Scryfall en tu propio despliegue, respeta su ritmo de peticiones (una cada 50-100 ms).