Commander Workshop MCP

Commander Workshop es un servidor MCP local-first para construir, verificar, comparar y completar mazos de Commander de Magic: The Gathering. Combina reglas fijas y datos de cartas con tu colección explícitamente importada, mantiene la intención del mazo separada de la propiedad, y convierte un plan completo en extracciones, intercambios, sustitutos, proxies o compras.

El servidor es útil para la creación sin restricciones, construcción priorizando el inventario, planificación de Bracket 3 y mejoras de preconstruidos con presupuesto fijo. Evalúa candidatos completos acotados y dice mejor encontrado bajo estas restricciones en lugar de reclamar una puntuación de poder universal o un mazo matemáticamente perfecto.

Características

Related MCP server: MTG-MCP

Promesa de privacidad

Tus colecciones, nombres de carpetas, ubicaciones y asignaciones de mazos físicos permanecen locales por defecto. Las importaciones locales están restringidas a las raíces configuradas. El servidor no envía mazos, modifica colecciones, reserva cartas, añade artículos del mercado a un carrito ni completa compras. El precio opcional del mercado envía solo los requisitos mínimos de impresión y lee las credenciales del entorno o del almacén secreto del host MCP.

Instalación

Commander Workshop requiere Python 3.11 o superior. Desde un clon del repositorio:

python -m venv .venv
. .venv/bin/activate
python -m pip install -e .

V1 actualmente solo es compatible con sistemas de archivos POSIX. Sus rutas de publicación inmutables requieren descriptores de archivo de directorio, O_DIRECTORY, O_NOFOLLOW, enlaces duros, fsync y bloqueos de asesoramiento; Windows no es compatible. El servidor stdio también espera las entradas locales verificadas preparadas a continuación.

Configuración del catálogo y reglas

V1 deliberadamente no realiza ninguna solicitud de red cuando el servidor se inicia. Descarga el gzip JSONL de Scryfall Default Cards a través de la API de datos masivos documentada de Scryfall, prepara el paquete de reglas de cinco archivos especificado en docs/rules-bundle.md, luego ejecuta el comando de arranque offline probado:

.venv/bin/commander-workshop-bootstrap \
  --data-dir /absolute/path/to/commander-workshop-data \
  --catalog-jsonl-gz /absolute/path/to/default-cards.jsonl.gz \
  --catalog-url https://data.scryfall.io/default-cards.jsonl.gz \
  --catalog-retrieved-at 2026-08-15T12:00:00+00:00 \
  --rules-bundle /absolute/path/to/rules-bundle

Usa la URL de descarga real y la hora de recuperación. --data-dir es una raíz de instalación segura; puede contener archivos no relacionados, que el arranque nunca elimina ni sobrescribe. El comando verifica el gzip y las reglas, construye un entorno con direccionamiento de contenido bajo environments/<sha256>, y publica un marcador READY atómico solo después de que la representación completa sea duradera. Un reintento recupera un entorno incompleto exacto y devuelve la misma versión. Los archivos de catálogo y reglas publicados son copias de bytes exclusivas sin alias de etapa retenidos. Las entradas con enlaces simbólicos, alias de enlaces duros, archivos laterales inesperados y contenido existente conflictivo fallan de forma segura.

Antes de construir, el arranque descubre un entorno READY completamente verificado por su identidad de entrada versionada, por lo que los reintentos normales con la misma entrada no crean una nueva etapa. Las etapas fallidas son inertes y pueden permanecer para inspección manual; el arranque nunca elimina recursivamente contenido de etapa que ya no puede demostrar que posee.

El directorio de datos impreso sigue siendo la raíz de instalación mutable, donde los registros MCP se escriben bajo records/. Las rutas del catálogo y las reglas impresas apuntan a la versión lista atestiguada. Usa los tres valores juntos; los directorios sin un marcador READY válido son estado de arranque incompleto y nunca se devuelven.

Después del arranque, establece COMMANDER_WORKSHOP_IMPORT_ROOTS en uno o más directorios absolutos existentes y usa los valores impresos para las otras variables. Una fuente crítica faltante, desactualizada o inválida falla de forma segura. Consulta la guía de arquitectura para el flujo de datos.

Configuración de Claude, Codex y stdio genérico

Para Claude Desktop u otro host que use la forma JSON común, copia examples/mcp-config.json y reemplaza sus rutas de marcador de posición absolutas.

Codex puede usar el mismo ejecutable desde config.toml:

[mcp_servers.commander_workshop]
command = "/absolute/path/to/commander-workshop-mcp/.venv/bin/commander-workshop-mcp"
args = []

[mcp_servers.commander_workshop.env]
COMMANDER_WORKSHOP_DATA_DIR = "/absolute/install-root"
COMMANDER_WORKSHOP_CATALOG_CURRENT = "/absolute/install-root/environments/<printed-sha256>/catalog/current.json"
COMMANDER_WORKSHOP_RULESET = "/absolute/install-root/environments/<printed-sha256>/rules/current.json"
COMMANDER_WORKSHOP_IMPORT_ROOTS = "/absolute/path/to/imports"

Cualquier cliente MCP v2 puede lanzar ese ejecutable absoluto del entorno virtual como un subproceso stdio local con esas variables de entorno. No hay servicio HTTP ni configuración de cuenta en v1. Una instalación con pipx también es viable: usa la ruta absoluta devuelta por pipx environment --value PIPX_BIN_DIR unida con commander-workshop-mcp.

Ejemplo completo: creación sin restricciones

1. Usa search_cards para inspeccionar el catálogo fijo y load_deck para cada mazo candidato completo producido durante la creación.

2. Llama a plan_deck con operación build, grupo de cartas all_legal, las dimensiones deseadas de bracket/tema/proxy, y de una a ocho presentaciones de candidatos completos. Lee el recurso commander://plans/... devuelto.

3. Opcionalmente carga una colección, llama a resolve_availability para el plan ganador, luego llama a create_fulfillment_plan. La disponibilidad sigue siendo hipotética; el cumplimiento asigna una copia solo dentro de ese resultado inmutable.

Este flujo no está restringido por el inventario durante la creación, pero aún puede mostrar lo que se tiene y lo que falta antes de que el usuario decida actuar. La plantilla de solicitud plan_deck completa está validada por esquema mediante el conjunto de aceptación.

Ejemplo completo: construcción solo con propiedad

1. Exporta la colección física como CSV de ManaBox o un CSV con mapeos de columnas explícitos, luego llama a load_collection_snapshot en modo estricto.

2. Usa search_library para localizar cartas candidatas por nombre, impresión, carpeta o asignación de mazo ensamblado.

3. Llama a plan_deck con grupo de cartas owned_only y el ID de la instantánea de colección. Un candidato con una carta no básica no poseída falla la restricción dura.

4. Lee los recursos del plan y disponibilidad para ver extracciones de carpetas y conflictos. Una copia ya asignada a un mazo se informa, no se trata silenciosamente como libre.

Usa la plantilla de solicitud solo-propiedad completa después de reemplazar sus IDs de mazo y colección con resultados de herramientas anteriores.

Ejemplo completo: mejora de preconstruido Bracket 3 de 50 USD/EUR

1. Exporta o pega el preconstruido y llama a load_deck; sigue siendo intención de mazo, no una reclamación de propiedad.

2. Carga candidatos mejorados completos y llama a plan_deck con operación upgrade, el preconstruido como starting_deck_id, Bracket 3, y la semántica preestablecida del escenario precon-upgrade-50-usd o precon-upgrade-50-eur.

3. Inspecciona las adiciones/cortes exactos, evidencia de bracket fechada, Game Changers, hechos temáticos y el límite de adquisición garantizado en moneda nativa. La evidencia de precio requerida faltante no puede pasar el límite como cero.

4. Opcionalmente resuelve el inventario, elige extracciones/intercambios/sustitutos/proxies con create_fulfillment_plan, luego llama a price_purchases para las líneas de compra restantes. El precio es informativo y nunca realiza un pedido.

La plantilla de solicitud de 50 USD contiene el escenario completo, evidencia del candidato, definiciones de puntuación, política de bracket y campo de mazo inicial. Cambia tanto la moneda como la política total para el preajuste en EUR.

Importaciones compatibles

• CSV de colección de ManaBox, separando carpetas físicas y mazos registrados de listas de deseos u otras listas no propietarias.

• CSV de colección genérico con un mapeo explícito para cantidad e identidad exacta de la carta, más campos opcionales de impresión y ubicación.

• Texto de mazo estilo Arena y común de cantidad/nombre/colección/número de coleccionista.

• Texto de mazo exportado por el usuario desde Moxfield, Archidekt, Deckbox, Deckstats, TopDecked y hosts similares cuando coincide con el dialecto de texto compatible.

Pega o selecciona una exportación que estés autorizado a usar. V1 no extrae páginas de cuentas, reutiliza cookies del navegador ni llama a endpoints no documentados de hosts de mazos. Las URL directas alojadas devuelven unsupported_source; exporta el mazo e importa su texto.

Herramientas

La superficie pública son exactamente once herramientas:

Cada herramienta devuelve un sobre versionado con un ID de resultado estable, estado, resumen conciso, problemas, sellos de origen y generalmente un URI de recurso.

Recursos

commander://cards/{oracle_id}
commander://searches/{result_id}
commander://collections/{snapshot_id}
commander://decks/{deck_id}
commander://plans/{plan_id}
commander://availability/{resolution_id}
commander://prices/{snapshot_id}
commander://fulfillment/{plan_id}
commander://rules/current
commander://presets

Los registros son inmutables y están direccionados por contenido. Las colecciones y búsquedas amplias están acotadas y paginadas; los resúmenes de herramientas evitan repetir los contenidos de la colección.

Dimensiones del escenario

Un escenario de planificación compone estas elecciones independientes:

• operación: build, upgrade o analyze;

• bracket: del 1 al 5, con evidencia de turno fechada y Game Changer;

• grupo de cartas: all_legal, prefer_owned o owned_only;

• presupuesto: total en moneda nativa y límite opcional por carta, incluyendo preajustes de mejora de preconstruido de 50 USD/EUR;

• política de proxies: ninguna, poseído-una-vez o ilimitado donde el grupo de juego lo permita;

• política temática: contrato estricto, preferencia flexible u orientado a fuerza;

• mazos ensamblados protegidos, conjunto de reglas fijo y semilla determinista.

El ajuste de categoría y el poder estratégico no se colapsan en una sola puntuación. Las reglas oficiales de Commander siguen siendo autoritativas, y las anulaciones de la Regla Cero deben ser explícitas.

Semántica de precios

price_purchases separa el subtotal de artículos, el subtotal del proveedor, el envío y el total estimado de llegada. Los artículos o envíos desconocidos permanecen como null, nunca cero. Un presupuesto garantizado solo puede aprobarse cuando cada compra requerida tiene evidencia conocida elegible bajo la política seleccionada.

Los valores del catálogo de Scryfall son observaciones indicativas de PriceEstimate, no cotizaciones de pago. Los listados de CardTrader son observaciones de solo lectura de PurchaseQuote. Las estimaciones de planificación utilizan una ventana de frescura declarada de como máximo 24 horas; CardTrader puede usar una vida útil de listado más corta. Las observaciones parciales y obsoletas conllevan problemas explícitos de unknown_price, autenticación, interrupción o límite de tasa.

Limitaciones del proveedor

• Las estimaciones de Scryfall provienen del catálogo local verificado, pueden carecer de moneda, acabado, condición, idioma, cantidad o envío, y no son comprables.

• CardTrader es opcional, requiere CARDTRADER_API_TOKEN, utiliza solo endpoints GET fijos documentados, no sigue redirecciones y no optimiza una cesta perfecta de múltiples vendedores.

• Cardmarket y TCGplayer no están habilitados por defecto; las restricciones de acceso y los términos del proveedor deben ser respetados por cualquier adaptador futuro.

• Ningún proveedor puede cambiar la legalidad del mazo, la propiedad de la colección, la política de proxies o el inventario reservado. Ningún proveedor expone operaciones de carrito o compra.

Las pruebas normales y la CI no realizan solicitudes en vivo a mercados o anfitriones de mazos.

Desarrollo

python -m pip install -e '.[test]'
python scripts/check_public_tree.py
ruff check src tests scripts
pytest -q
python -m build

El escáner de privacidad inspecciona el árbol rastreado en busca de rutas privadas, credenciales, bases de datos, exportaciones de datos inseguras, enlaces simbólicos y fixtures no documentados o de gran tamaño. Todos los datos de prueba son sintéticos y deterministas.

Arquitectura

Consulte docs/architecture.md para conocer los límites de los componentes, el almacenamiento inmutable, los límites de confianza, el flujo de planificación/ejecución y los puntos de extensión.

Reporte de seguridad

Siga SECURITY.md. Use un aviso de seguridad privado y una reproducción sintética mínima; nunca adjunte una exportación de colección, inventario de carpeta, token u otros datos personales.

Atribución

Los nombres de cartas, el texto de reglas y los metadatos del catálogo pueden derivarse de Scryfall, cuyos datos y requisitos de atribución se aplican. Las reglas de Magic: The Gathering y la política de categorías de Commander son publicadas por Wizards of the Coast. Los nombres de los proveedores y los datos del mercado siguen siendo propiedad de sus respectivos dueños.

No afiliación

Commander Workshop MCP es un software de fans no oficial. No está afiliado, respaldado, patrocinado ni aprobado por Wizards of the Coast, Scryfall, CardTrader ni ningún otro anfitrión de mazos o mercado. Magic: The Gathering, Commander y las marcas relacionadas pertenecen a Wizards of the Coast y sus respectivos propietarios.

Commander Workshop MCP es contenido de fans no oficial permitido bajo la Política de Contenido de Fans. No aprobado/respaldado por Wizards. Partes de los materiales utilizados son propiedad de Wizards of the Coast. ©Wizards of the Coast LLC.

Licencia

El software se publica bajo la Licencia MIT. Los datos de cartas, reglas y mercados de terceros siguen sujetos a sus propios términos y licencias.