Swift Tarot

Swift Tarot MCP Server

Um servidor Model Context Protocol (MCP) que fornece funcionalidade de leitura de cartas de tarô. Este servidor permite que assistentes de IA sorteiem cartas de tarô, realizem leituras com múltiplas cartas e acessem o baralho completo de tarô.

Recursos

LLMs são notoriamente ruins em aleatoriedade, semelhantes aos humanos. Este servidor MCP fornece geração de números aleatórios mais confiável para leituras de tarô.

• Sorteio Flexível de Cartas: Sorteie de 1 a 78 cartas de tarô em uma única solicitação
• Acesso Completo ao Baralho: Veja todas as 78 cartas do baralho de tarô tradicional
• Imagens das Cartas: Obtenha imagens codificadas em base64 para cartas de tarô
• Testes Determinísticos: Usa geração de números aleatórios com semente para testes consistentes
• Validação Abrangente: Validação de entrada com tratamento adequado de erros

Instalação

Pré-requisitos

• Swift 5.9 ou posterior
• macOS 13.0 ou posterior
• Just executor de comandos (opcional, mas recomendado)

Instalar Just (Opcional)

brew install just

Compilar e Instalar

1. Clone o repositório:

git clone <repository-url>
cd swift-tarot-MCP

2. Compile e instale o servidor:

just install

Isso compilará a versão de lançamento e a instalará em /usr/local/bin/swift-tarot-MCP.

Alternativamente, você pode compilar manualmente:

swift build -c release
sudo cp .build/release/swift-tarot-MCP /usr/local/bin/

Configuração do Claude Desktop

Para usar este servidor MCP com o Claude Desktop, adicione o seguinte ao seu arquivo de configuração do Claude Desktop:

Configuração do macOS

Edite ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tarot": {
      "command": "swift-tarot-MCP",
      "args": []
    }
  }
}

Após a Configuração

1. Reinicie o Claude Desktop
2. As ferramentas de tarô agora devem estar disponíveis em suas conversas
3. Você pode pedir ao Claude para sortear cartas de tarô, realizar leituras ou mostrar o baralho completo

Ferramentas Disponíveis

draw_cards

Sorteia uma ou mais cartas de tarô para leituras.

Parâmetros:

• count (opcional): Número de cartas a sortear (1-78, padrão: 1)

Exemplo de uso no Claude:

"Sorteie uma carta de tarô para mim" "Sorteie 5 cartas de tarô para uma leitura"

get_full_deck

Retorna todas as 78 cartas do baralho de tarô.

Exemplo de uso no Claude:

"Mostre-me o baralho de tarô completo"

fetch_images

Obtém imagens codificadas em base64 para URIs de cartas de tarô.

Parâmetros:

• uris: Array de URIs de cartas de tarô para obter imagens

Exemplo de uso no Claude:

"Mostre-me a imagem da carta O Louco"

Desenvolvimento

Comandos Disponíveis

Se você tiver o Just instalado, pode usar estes comandos:

# Build the project (debug by default)
just build

# Build for release
just build release

# Run tests
just test

# Run tests with verbose output
just test --verbose

# Lint the code
just lint

# Auto-fix linting issues
just lint --fix

# Run the server locally
just run

# Clean build artifacts
just clean

# Install to system PATH
just install

# Remove from system PATH
just uninstall

Comandos Manuais

Sem o Just, você pode usar estes comandos Swift:

# Build debug
swift build

# Build release
swift build -c release

# Run tests
swift test

# Run linting
swift package plugin --allow-writing-to-package-directory swiftlint

Testes

O projeto inclui testes abrangentes cobrindo:

• Estruturas de dados e validação de cartas de tarô
• Composição do baralho e sorteio de cartas
• Funcionalidade do manipulador do servidor
• Conformidade com o protocolo MCP
• Comportamento determinístico com RNG com semente

Execute os testes com:

just test
# or
swift test

Arquitetura

O projeto está estruturado como:

• TarotMCPCore: Biblioteca principal contendo a lógica das cartas de tarô e a implementação do servidor MCP
• TarotMCP: Executável que executa o servidor MCP usando transporte stdio

Componentes Principais

• TarotCard: Enum que representa cartas de arcano maior e menor
• TarotDeck: Métodos estáticos para sorteio de cartas e gerenciamento do baralho
• TarotServer: Implementação do servidor MCP
• TarotServerHandler: Lida com chamadas de ferramentas MCP e roteamento

Formato das Cartas

As cartas são retornadas como objetos JSON com detalhes da carta:

[
  {
    "name": "The Fool",
    "imageURI": "tarot://card/major/0"
  },
  {
    "name": "Two of Cups",
    "imageURI": "tarot://card/minor/cups/2"
  },
  {
    "name": "King of Swords",
    "imageURI": "tarot://card/minor/swords/14"
  }
]

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.