MTG MCP Servers

Servidores de Magic: The Gathering (MTG) para gestión de mazos y búsqueda de cartas usando el protocolo MCP.

Documentación

MTG MCP Servers

Una implementación en Swift de servidores de Model Context Protocol (MCP) de Magic: The Gathering (MTG), que proporcionan gestión de mazos y búsqueda de cartas a través del protocolo MCP.

Resumen

Este proyecto proporciona dos servidores MCP:

MTG Deck Manager (mtg-mcp) - Gestión del estado del juego, incluyendo carga de mazos, robo de cartas, mulligans y sideboard.
Scryfall API Server (scryfall-mcp) - Recuperación de información de cartas mediante la API de Scryfall.

Ambos servidores implementan el protocolo MCP para una integración perfecta con clientes compatibles con MCP como Claude Desktop.

Características

MTG Deck Manager

Carga de mazos: Analiza y carga listas de mazos en varios formatos.
Gestión del estado del juego: Realiza un seguimiento del contenido del mazo, la mano y el sideboard.
Robo de cartas: Roba cartas del mazo a la mano con barajado adecuado.
Soporte de mulligan: Implementación del mulligan de Londres.
Sideboard: Intercambia cartas entre el mazo principal/sideboard y la mano.
Reinicio del juego: Restablece el estado inicial del juego.
Estadísticas: Estadísticas en tiempo real del mazo y la mano.

Scryfall API Server

Búsqueda de cartas: Búsqueda avanzada de cartas utilizando la sintaxis de consulta de Scryfall.
Cartas aleatorias: Genera cartas aleatorias con filtros opcionales.
Búsqueda por nombre: Encuentra cartas por coincidencia exacta o aproximada del nombre.
Datos completos de la carta: Información completa de la carta, incluyendo imágenes, precios y legalidades.

Instalación

Requisitos previos

Swift 6.2 o posterior
macOS 13 o posterior

Compilar desde el código fuente

# Clone the repository
git clone <repository-url>
cd mtg-mcp

# Build the project
swift build

# Run tests
swift test

Instalar ejecutables

# Build in release mode
swift build -c release

# Install to local bin (optional)
cp .build/release/mtg-mcp /usr/local/bin/
cp .build/release/scryfall-mcp /usr/local/bin/

Uso

Ejecutar los servidores

Servidor MTG Deck Manager

# Run with stdio transport (for MCP integration)
swift run mtg-mcp --transport stdio

# Run standalone for testing
swift run mtg-mcp --transport stdio --verbose

Servidor Scryfall API

# Run with stdio transport
swift run scryfall-mcp --transport stdio

# Run with debug output
swift run scryfall-mcp --transport stdio --verbose

Integración con MCP

Configuración de Claude Desktop

Añade los servidores a tu archivo de configuración de Claude Desktop. El archivo de configuración normalmente se encuentra en:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Opción 1: Usando Swift Run (Desarrollo)

{
  "mcpServers": {
    "mtg-deck-manager": {
      "command": "swift",
      "args": ["run", "mtg-mcp", "--transport", "stdio"],
      "cwd": "/path/to/mtg-mcp"
    },
    "scryfall-api": {
      "command": "swift", 
      "args": ["run", "scryfall-mcp", "--transport", "stdio"],
      "cwd": "/path/to/mtg-mcp"
    },
    "rules-splitter": {
      "command": "swift",
      "args": ["run", "rules-splitter"],
      "cwd": "/path/to/mtg-mcp"
    }
  }
}

Opción 2: Usando ejecutables compilados (Producción)

{
  "mcpServers": {
    "mtg-deck-manager": {
      "command": "/path/to/.build/release/mtg-mcp",
      "args": ["--transport", "stdio"]
    },
    "scryfall-api": {
      "command": "/path/to/.build/release/scryfall-mcp", 
      "args": ["--transport", "stdio"]
    }
  }
}

Ejemplo de configuración completa

{
  "mcpServers": {
    "mtg-deck-manager": {
      "command": "swift",
      "args": ["run", "mtg-mcp", "--transport", "stdio"],
      "cwd": "/Users/ericraio/mcp/mtg-mcp"
    },
    "scryfall-api": {
      "command": "swift", 
      "args": ["run", "scryfall-mcp", "--transport", "stdio"],
      "cwd": "/Users/ericraio/mcp/mtg-mcp"
    }
  }
}

Configuración de producción (Recomendada)

Primero, compila los ejecutables:

cd /Users/ericraio/mcp/mtg-mcp
swift build -c release

Luego usa esta configuración:

{
  "mcpServers": {
    "mtg-deck-manager": {
      "command": "/Users/ericraio/mcp/mtg-mcp/.build/release/mtg-mcp",
      "args": ["--transport", "stdio"]
    },
    "scryfall-api": {
      "command": "/Users/ericraio/mcp/mtg-mcp/.build/release/scryfall-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Notas importantes:

La ruta cwd debe apuntar a /Users/ericraio/mcp/mtg-mcp donde existe Package.swift
Las compilaciones de producción son más rápidas y fiables que las de desarrollo
Reinicia Claude Desktop después de actualizar la configuración

Verificar la configuración

Después de añadir la configuración:

Reinicia Claude Desktop
Inicia una nueva conversación
Prueba la integración pidiendo a Claude que:
- "Muéstrame qué herramientas de MTG están disponibles"
- "Carga un mazo MTG simple y roba algunas cartas"
- "Busca Lightning Bolt usando Scryfall"
- "Consulta la regla 100.1 de MTG"

Ejemplos de uso de herramientas

Una vez conectado, puedes usar estas herramientas a través de tu cliente MCP:

Gestión básica de mazos

# Load a deck
upload_deck with deck_list: "
Deck
4 Lightning Bolt
4 Counterspell  
4 Island
4 Mountain
44 Basic lands

Sideboard
2 Negate
1 Spell Pierce
"

# Draw opening hand
draw_card with count: 7

# View your hand
view_hand

# Get deck statistics
view_deck_stats

# Play a card
play_card with card_name: "Lightning Bolt"

# Mulligan to 6 cards
mulligan with new_hand_size: 6

Consulta y aprendizaje de reglas

# Look up specific rules
lookup_rule with rule_number: "100.1"
lookup_rule with rule_number: "601.2a"

# Search for rules about concepts
search_rules with concept: "mulligan"
search_rules with concept: "combat"
search_rules with keywords: "cast spell"

# Get comprehensive explanations
explain_concept with concept: "priority"
explain_concept with concept: "triggered abilities"
explain_concept with concept: "stack"

Búsqueda e información de cartas

# Search for cards
search_cards with query: "c:red cmc<=3 t:instant"
search_cards with query: "t:creature pow>=4"

# Get random cards
get_random_card
get_random_card with query: "c:blue t:counterspell"

# Look up specific cards
lookup_card_exact with exact: "Lightning Bolt"
lookup_card_fuzzy with fuzzy: "Jace Mind Sculptor"

Escenarios avanzados de juego

# Sideboarding
sideboard_swap with remove_card: "Lightning Bolt" and add_card: "Negate"

# Reset game state
reset_game

# Commander deck setup
upload_deck with deck_list: "
Commander
1 Atraxa, Praetors' Voice

Deck  
1 Sol Ring
1 Command Tower
98 Forest
"

Ejemplos de prompts para Claude

Aquí tienes ejemplos de prompts que puedes usar con Claude Desktop una vez que los servidores MCP estén configurados:

🎮 Prompts de gestión del juego

"Ayúdame a probar mi mazo de burn"

Load this burn deck and simulate an opening hand:

4 Lightning Bolt
4 Lava Spike  
4 Monastery Swiftspear
4 Eidolon of the Great Revel
20 Mountain
4 Fireblast

Sideboard:
3 Smash to Smithereens
2 Pyroblast

Then draw 7 cards and tell me what kind of opening hand I got.

"Simula una decisión de mulligan"

I want to practice mulligan decisions. Load a competitive deck, draw a 7-card opening hand, and tell me if you think I should keep it or mulligan based on the cards drawn.

📚 Prompts de aprendizaje de reglas

"Enséñame sobre la pila"

I'm confused about how the stack works in Magic. Can you:
1. Look up the official rules about the stack
2. Explain how priority works with it
3. Give me an example of how spells and abilities resolve

"Reglas de daño de combate"

Look up the official MTG rules about combat damage and explain:
- When damage is dealt
- How first strike works
- What happens with deathtouch
- How trample calculates excess damage

🔍 Prompts de investigación de cartas

"Encuentra cartas para mi mazo de combo"

I'm building an artifact combo deck. Search for:
1. Red instants that cost 3 mana or less
2. Artifacts that produce mana
3. Cards that let me draw cards when artifacts enter

Show me the most relevant options.

"Inspiración aleatoria para mazos"

Give me 5 random cards and help me brainstorm a deck theme that could use all of them together.

🏆 Prompts de aprendizaje y estrategia

"Hazme un cuestionario de reglas"

Quiz me on MTG rules! Look up a random rule number and ask me to explain what it means, then show me the official rule text to check my answer.

"Análisis de mazo"

Load this deck list and analyze it:
- What's the mana curve?
- What's the game plan?
- What rules should I know for the key cards?
- What are potential weaknesses?

[paste deck list here]

Soporte de formatos de mazo

El analizador de mazos soporta múltiples formatos:

Formato estándar

Deck
4 Lightning Bolt
4 Counterspell
20 Island

Sideboard
2 Negate
1 Spell Pierce

Formato Commander

Commander
1 Atraxa, Praetors' Voice

Deck
1 Sol Ring
1 Command Tower
98 Forest

Con información de colección

Deck
4 Lightning Bolt (LEA) 
4 Counterspell [7ED]
20 Island

Formato sin encabezado

4 Lightning Bolt
4 Counterspell  
20 Island

Herramientas MCP disponibles

Herramientas de MTG Deck Manager

Herramienta	Descripción	Parámetros
`upload_deck`	Cargar una lista de mazo	`deck_list`: Cadena que contiene la lista del mazo
`draw_card`	Robar cartas del mazo	`count`: Número de cartas a robar (por defecto: 1)
`view_hand`	Obtener el contenido actual de la mano	None
`view_deck_stats`	Obtener estadísticas del mazo	None
`play_card`	Jugar una carta de la mano	`card_name`: Nombre de la carta a jugar
`mulligan`	Hacer mulligan a un nuevo tamaño de mano	`new_hand_size`: Tamaño de la nueva mano (opcional)
`sideboard_swap`	Intercambiar cartas con el sideboard	`remove_card`: Carta a eliminar `add_card`: Carta a añadir
`reset_game`	Restablecer el estado del juego	None
`lookup_rule`	Consultar una regla específica de MTG	`rule_number`: Número de regla (p. ej., "100", "601.2a")
`search_rules`	Buscar reglas de MTG	`keywords`: Palabras clave para buscar (opcional) `concept`: Concepto del juego (opcional)
`explain_concept`	Obtener explicaciones completas de reglas	`concept`: Concepto del juego a explicar

Herramientas de Scryfall API

Herramienta	Descripción	Parámetros
`search_cards`	Buscar cartas	`query`: Consulta de búsqueda de Scryfall `page`: Número de página (opcional)
`get_random_card`	Obtener carta aleatoria	`query`: Consulta de filtro (opcional)
`lookup_card_exact`	Encontrar carta por nombre exacto	`exact`: Nombre exacto de la carta
`lookup_card_fuzzy`	Encontrar carta por nombre aproximado	`fuzzy`: Nombre aproximado de la carta

Herramienta de división de reglas

Herramienta	Descripción	Parámetros
`rules-splitter`	Descargar y dividir las reglas de MTG en secciones	`url`: URL de reglas personalizadas (opcional)

Desarrollo

Estructura del proyecto

mtg-mcp/
├── Sources/
│   ├── mtg-mcp/           # MTG Deck Manager server
│   │   └── mtg_mcp.swift  # Main server with rules integration
│   ├── scryfall-mcp/      # Scryfall API server
│   │   └── scryfall_mcp.swift
│   ├── rules-splitter/    # Rules processing tool
│   │   └── main.swift     # Rule file splitter CLI
│   ├── MTGModels/         # Shared models
│   │   ├── Card.swift
│   │   ├── GameState.swift
│   │   ├── ManaCost.swift
│   │   └── Rarity.swift
│   └── MTGServices/       # Shared services
│       ├── DeckParser.swift
│       └── RulesService.swift  # NEW: Rules lookup service
├── Tests/
│   └── mtg-mcpTests/      # Comprehensive test suite
│       ├── CardModelTests.swift
│       ├── DeckParserTests.swift
│       ├── GameStateTests.swift
│       ├── IntegrationTests.swift
│       ├── TestDataLoader.swift
│       └── TestData/      # Sample deck files
├── rules/                 # Generated MTG rules (144 files)
│   ├── 100_general.md
│   ├── 601_casting_spells.md
│   └── ... (142 more rule files)
└── Package.swift

Dependencias

MCP Swift SDK (0.9.0+) - Implementación del protocolo MCP
SwiftGzip - Soporte de compresión para la API de Scryfall
ArgumentParser - Análisis de argumentos de línea de comandos

Ejecutar pruebas

# Run all tests
swift test

# Run specific test suite
swift test --filter CardModelTests

# Run tests with verbose output
swift test --verbose

Estilo de código

El proyecto sigue las mejores prácticas de Swift:

Actores de Swift para la gestión del estado del juego con seguridad de hilos
Conformidad con el protocolo Sendable para acceso concurrente
Manejo integral de errores con tipos Result
Patrones async/await en todo el código
Pruebas unitarias con >90% de cobertura

Arquitectura

Seguridad de hilos

El estado del juego se gestiona mediante el sistema actor de Swift, garantizando acceso seguro a estado mutable en llamadas concurrentes a herramientas MCP.

Manejo de errores

Manejo integral de errores utilizando el tipo Result de Swift y tipos de error personalizados para diferentes escenarios de fallo.

Integración con MCP

Ambos servidores implementan el protocolo MCP utilizando el SDK oficial de Swift, proporcionando:

Registro y descubrimiento de herramientas
Manejo de solicitudes/respuestas
Abstracción de transporte (stdio, HTTP)
Propagación adecuada de errores

Referencia de la API

Modelo de carta

public struct Card: Identifiable, Equatable, Hashable, Codable, Sendable {
    public let id: String
    public var name: String
    public var manaCostString: String
    public var kind: CardKind
    public var rarity: Rarity
    public var typeLine: String
    public var oracleText: String
    public var power: String?
    public var toughness: String?
    public var loyalty: String?
}

Actor de estado del juego

public actor GameState {
    public func loadDeck(_ deckData: DeckData) async
    public func drawCards(count: Int) async -> [Card]
    public func playCard(named cardName: String) async -> Card?
    public func mulligan(newHandSize: Int) async -> [Card]
    public func sideboardSwap(removeCard: String, addCard: String) async -> (removed: Card?, added: Card?)
    public func resetGame() async
    public func getDeckStats() async -> DeckStats
    public func getHandContents() async -> [String: Int]
}

Contribuciones

Haz un fork del repositorio
Crea una rama de características
Realiza tus cambios
Añade pruebas para la nueva funcionalidad
Asegúrate de que todas las pruebas pasen
Envía una solicitud de extracción (pull request)

Licencia

Este proyecto se proporciona tal cual, con fines educativos y de desarrollo.

Agradecimientos

Protocolo MCP - Por el protocolo estandarizado de integración con IA
API de Scryfall - Por los datos completos de cartas MTG
swift-landlord - Por los modelos de referencia de MTG y la lógica del juego
MCP Swift SDK - Por la implementación oficial de MCP en Swift