MTG MCP Servers

Servidores Magic: The Gathering (MTG) para gerenciamento de decks e busca de cartas usando o protocolo MCP.

Documentação

MTG MCP Servers

Uma implementação em Swift de servidores Magic: The Gathering (MTG) Model Context Protocol (MCP), fornecendo gerenciamento de baralho e busca de cartas através do protocolo MCP.

Visão Geral

Este projeto fornece dois servidores MCP:

MTG Deck Manager (mtg-mcp) - Gerenciamento de estado do jogo, incluindo carregamento de baralho, compra de cartas, mulligans e sideboard
Scryfall API Server (scryfall-mcp) - Recuperação de informações de cartas usando a API Scryfall

Ambos os servidores implementam o protocolo MCP para integração perfeita com clientes compatíveis com MCP, como o Claude Desktop.

Recursos

MTG Deck Manager

Carregamento de Baralho: Analisa e carrega listas de baralho em vários formatos
Gerenciamento de Estado do Jogo: Rastreia o conteúdo do baralho, da mão e do sideboard
Compra de Cartas: Compra cartas do baralho para a mão com embaralhamento adequado
Suporte a Mulligan: Implementação do mulligan de Londres
Sideboard: Troca cartas entre o baralho principal/sideboard e a mão
Reinício do Jogo: Reinicia para o estado inicial do jogo
Estatísticas: Estatísticas em tempo real do baralho e da mão

Scryfall API Server

Busca de Cartas: Busca avançada de cartas usando a sintaxe de consulta do Scryfall
Cartas Aleatórias: Gera cartas aleatórias com filtros opcionais
Consulta por Nome: Encontra cartas por correspondência exata ou aproximada de nome
Dados Ricos de Cartas: Informações completas da carta, incluindo imagens, preços e legalidades

Instalação

Pré-requisitos

Swift 6.2 ou posterior
macOS 13 ou posterior

Compilar a partir do Código Fonte

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

# Build the project
swift build

# Run tests
swift test

Instalar Executáveis

# 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

Executando os 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

Integração MCP

Configuração do Claude Desktop

Adicione os servidores ao arquivo de configuração do Claude Desktop. O arquivo de configuração normalmente está localizado em:

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

Opção 1: Usando Swift Run (Desenvolvimento)

{
  "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"
    }
  }
}

Opção 2: Usando Executáveis Compilados (Produção)

{
  "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"]
    }
  }
}

Exemplo Completo de Configuração

{
  "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"
    }
  }
}

Configuração de Produção (Recomendado)

Primeiro, compile os executáveis:

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

Depois use esta configuração:

{
  "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:

O caminho cwd deve apontar para /Users/ericraio/mcp/mtg-mcp onde o Package.swift existe
Builds de produção são mais rápidos e confiáveis que builds de desenvolvimento
Reinicie o Claude Desktop após atualizar a configuração

Verificando a Configuração

Após adicionar a configuração:

Reinicie o Claude Desktop
Inicie uma nova conversa
Teste a integração pedindo ao Claude para:
- "Mostre-me quais ferramentas MTG estão disponíveis"
- "Carregue um baralho MTG simples e compre algumas cartas"
- "Busque por Lightning Bolt usando Scryfall"
- "Consulte a regra 100.1 do MTG"

Exemplos de Uso de Ferramentas

Uma vez conectado, você pode usar estas ferramentas através do seu cliente MCP:

Gerenciamento Básico de Baralho

# 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 e Aprendizado de Regras

# 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"

Busca e Informações 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"

Cenários Avançados de Jogo

# 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
"

Exemplos de Prompts para o Claude

Aqui estão exemplos de prompts que você pode usar com o Claude Desktop depois que os servidores MCP estiverem configurados:

🎮 Prompts de Gerenciamento de Jogo

"Ajude-me a testar meu baralho 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.

"Simule uma decisão 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 Aprendizado de Regras

"Ensine-me sobre a pilha"

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

"Regras de dano 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 Pesquisa de Cartas

"Encontre cartas para meu baralho 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.

"Inspiração aleatória de baralho"

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

🏆 Prompts de Aprendizado e Estratégia

"Me faça um quiz de regras"

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álise de baralho"

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]

Suporte a Formatos de Baralho

O analisador de baralho suporta vários formatos:

Formato Padrão

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

Com Informações de Coleção

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

Formato Sem Cabeçalho

4 Lightning Bolt
4 Counterspell  
20 Island

Ferramentas MCP Disponíveis

Ferramentas do MTG Deck Manager

Ferramenta	Descrição	Parâmetros
`upload_deck`	Carregar uma lista de baralho	`deck_list`: String contendo a lista de baralho
`draw_card`	Comprar cartas do baralho	`count`: Número de cartas para comprar (padrão: 1)
`view_hand`	Obter o conteúdo atual da mão	Nenhum
`view_deck_stats`	Obter estatísticas do baralho	Nenhum
`play_card`	Jogar uma carta da mão	`card_name`: Nome da carta a ser jogada
`mulligan`	Mulligan para novo tamanho de mão	`new_hand_size`: Tamanho da nova mão (opcional)
`sideboard_swap`	Trocar cartas com o sideboard	`remove_card`: Carta a remover `add_card`: Carta a adicionar
`reset_game`	Reiniciar o estado do jogo	Nenhum
`lookup_rule`	Consultar uma regra específica do MTG	`rule_number`: Número da regra (ex.: "100", "601.2a")
`search_rules`	Pesquisar regras do MTG	`keywords`: Palavras-chave para pesquisa (opcional) `concept`: Conceito do jogo (opcional)
`explain_concept`	Obter explicações abrangentes de regras	`concept`: Conceito do jogo a explicar

Ferramentas da API Scryfall

Ferramenta	Descrição	Parâmetros
`search_cards`	Buscar cartas	`query`: Consulta de busca do Scryfall `page`: Número da página (opcional)
`get_random_card`	Obter carta aleatória	`query`: Consulta de filtro (opcional)
`lookup_card_exact`	Encontrar carta por nome exato	`exact`: Nome exato da carta
`lookup_card_fuzzy`	Encontrar carta por nome aproximado	`fuzzy`: Nome aproximado da carta

Ferramenta de Divisão de Regras

Ferramenta	Descrição	Parâmetros
`rules-splitter`	Baixar e dividir as regras do MTG em seções	`url`: URL personalizada das regras (opcional)

Desenvolvimento

Estrutura do Projeto

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

Dependências

MCP Swift SDK (0.9.0+) - Implementação do protocolo MCP
SwiftGzip - Suporte a compressão para a API Scryfall
ArgumentParser - Análise de argumentos de linha de comando

Executando Testes

# 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

O projeto segue as melhores práticas de Swift:

Atores Swift para gerenciamento de estado do jogo com segurança de threads
Conformidade com o protocolo Sendable para acesso concorrente
Tratamento abrangente de erros com tipos Result
Padrões async/await em todo o código
Testes unitários com cobertura >90%

Arquitetura

Segurança de Threads

O estado do jogo é gerenciado usando o sistema de actor do Swift, garantindo acesso seguro a estado mutável em chamadas concorrentes de ferramentas MCP.

Tratamento de Erros

Tratamento abrangente de erros usando o tipo Result do Swift e tipos de erro personalizados para diferentes cenários de falha.

Integração MCP

Ambos os servidores implementam o protocolo MCP usando o SDK oficial do Swift, fornecendo:

Registro e descoberta de ferramentas
Tratamento de requisição/resposta
Abstração de transporte (stdio, HTTP)
Propagação adequada de erros

Referência da 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?
}

Ator de Estado do Jogo

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]
}

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça suas alterações
Adicione testes para novas funcionalidades
Garanta que todos os testes passem
Envie um pull request

Licença

Este projeto é fornecido como está para fins educacionais e de desenvolvimento.

Agradecimentos

Protocolo MCP - Pelo protocolo padronizado de integração com IA
API Scryfall - Pelos dados abrangentes de cartas MTG
swift-landlord - Pelos modelos de referência de MTG e lógica de jogo
MCP Swift SDK - Pela implementação oficial do MCP em Swift