D&D 5E MCP Server

Servidor MCP D&D 5E

Um servidor MCP (Model Context Protocol) que fornece acesso ao conteúdo da 5ª Edição de D&D por meio da API REST Open5e. Este servidor permite que assistentes de IA e outros clientes MCP recuperem informações abrangentes de D&D 5E, incluindo magias, classes, raças, monstros e equipamentos.

Ferramentas Disponíveis

Busca Universal

• unified_search - Busca em todos os tipos de conteúdo de D&D com classificação inteligente
  • Parâmetro query obrigatório para termos de busca
  • Filtro opcional content_types para conteúdo específico (magias, monstros, raças, etc.)
  • fuzzy_threshold opcional para sensibilidade de correspondência
  • Retorna resultados classificados em todos os tipos de conteúdo

Ferramentas de Magias

• search_spells - Busca magias por nome ou recupera todas as magias
  • Parâmetro opcional query para filtrar por nome de magia
  • Retorna informações básicas da magia (nome, nível, escola, tempo de conjuração, etc.)
• get_spell_details - Obtém detalhes abrangentes sobre uma magia específica
  • Requer o parâmetro spell_name
  • Retorna descrição completa da magia, componentes, duração e listas de classes
• get_spell_by_level - Obtém todas as magias de um nível específico (0-9)
  • Requer o parâmetro level (0 para truques, 1-9 para níveis de magia)
• get_spells_by_class - Obtém todas as magias disponíveis para uma classe específica
  • Requer o parâmetro class_name (ex.: "mago", "clérigo", "bardo")

Ferramentas de Classes

• search_classes - Obtém uma lista de todas as classes disponíveis de D&D 5E
  • Retorna informações básicas para todas as classes principais
• get_class_details - Obtém informações detalhadas sobre uma classe específica
  • Requer o parâmetro class_name
  • Retorna dado de vida, testes de resistência, descrição e subclasses disponíveis

Ferramentas de Raças

• search_races - Obtém uma lista de todas as raças disponíveis de D&D 5E
  • Retorna informações básicas de raça da página de linhagem
• get_race_details - Obtém informações detalhadas sobre uma raça específica
  • Requer o parâmetro race_name
  • Retorna tamanho, deslocamento, aumentos de valor de habilidade, traços e descrição

Ferramentas de Monstros

• search_monsters - Busca monstros com opções de filtro
  • Parâmetro opcional query para nomes de monstros
  • Filtro opcional challenge_rating
  • Retorna estatísticas e informações básicas do monstro
• get_monsters_by_cr - Obtém todos os monstros de um desafio específico
• get_monsters_by_cr_range - Obtém monstros dentro de uma faixa de ND para planejamento de encontros

Ferramentas de Equipamentos

• search_weapons - Busca armas com filtro de propriedades
  • Filtros opcionais para armas marciais/versáteis
• search_armor - Busca armaduras com filtro de CA e categoria
• search_magic_items - Busca itens mágicos com filtro de raridade
• get_magic_item_details - Obtém informações detalhadas de itens mágicos

Ferramentas de Criação de Personagem

• search_feats - Busca talentos de personagem
• get_feat_details - Obtém informações detalhadas de talentos
• search_backgrounds - Busca antecedentes de personagem
• get_background_details - Obtém informações detalhadas de antecedentes
• generate_character_build - Gera builds de personagem otimizados
• compare_character_builds - Compara múltiplas opções de build de personagem
• get_build_recommendations - Obtém recomendações de build para composição de grupo

Ferramentas do Mestre

• build_encounter - Monta encontros equilibrados para o grupo especificado
  • Requer party_size, party_level e difficulty
  • Filtros opcionais para ambiente, tipos de monstros, faixa de ND
  • Retorna encontro equilibrado com cálculos de XP
• calculate_encounter_difficulty - Calcula a dificuldade de encontros personalizados
  • Requer informações do grupo e lista de monstros com quantidades
  • Retorna classificação de dificuldade do encontro e detalhamento de XP

Ferramentas de Regras e Referência

• search_conditions - Busca condições de status e efeitos
• get_condition_details - Obtém informações detalhadas de condições
• get_all_conditions - Obtém todas as condições para referência rápida
• search_sections - Busca seções de regras para consultas rápidas
• get_section_details - Obtém informações detalhadas de seções de regras
• search_spell_lists - Busca listas de magias por classe
• get_spell_list_details - Obtém lista detalhada de magias para classes específicas

Instalação

1. Clone este repositório:

   git clone <repository-url>
   cd dnd-mcp
   

2. Instale as dependências:

   npm install
   

3. Compile o projeto:

   npm run build
   

Uso

Executando o Servidor

npm start

Modo de Desenvolvimento

npm run dev

Configuração do Cliente MCP

Adicione à configuração do seu cliente MCP (ex.: mcp.json):

{
  "mcpServers": {
    "dnd-5e": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/dnd-mcp"
    }
  }
}

Exemplo de Uso de Ferramentas MCP

O servidor implementa o Model Context Protocol, expondo ferramentas que podem ser chamadas por clientes MCP. Aqui estão alguns exemplos de chamadas de ferramentas:

Busca Universal

{
  "name": "unified_search",
  "arguments": {
    "query": "fireball",
    "content_types": ["spells", "magic-items"]
  }
}

Montar Encontro

{
  "name": "build_encounter",
  "arguments": {
    "party_size": 4,
    "party_level": 5,
    "difficulty": "medium",
    "environment": "dungeon"
  }
}

Gerar Build de Personagem

{
  "name": "generate_character_build",
  "arguments": {
    "playstyle": "damage",
    "preferred_class": "fighter",
    "campaign_type": "combat"
  }
}

Recursos Técnicos

• Cache Inteligente: Cache TTL de 1 hora para minimizar solicitações ao site de origem
• Limitação de Taxa: Atrasos de 1 segundo entre solicitações para respeitar os recursos do servidor
• Tratamento de Erros: Tratamento abrangente de erros para problemas de rede e conteúdo ausente
• TypeScript: Implementação totalmente tipada para melhor experiência de desenvolvimento
• Protocolo MCP: Conformidade total com as especificações do Model Context Protocol
• Testes Abrangentes: Cobertura total de testes para funcionalidade da API Open5e e operações de scraping

Arquitetura

• Integração com API Open5e: Usa Axios para comunicação REST com Open5e
• Processamento de Conteúdo: Tratamento estruturado de dados das respostas JSON do Open5e
• Servidor MCP: Implementação padrão do protocolo MCP com transporte stdio
• Camada de Cache: NodeCache para armazenamento eficiente de conteúdo

Desenvolvimento

Scripts Disponíveis

• npm run build - Compila TypeScript para JavaScript
• npm run dev - Executa em modo de desenvolvimento com recarga automática
• npm start - Executa o servidor compilado
• npm run lint - Executa ESLint
• npm test - Executa testes Jest (inclui testes abrangentes da API Open5e)

Estrutura do Projeto

src/
├── index.ts      # MCP server implementation and tool handlers
├── scraper.ts    # Open5e API integration and data fetching
tsconfig.json     # TypeScript configuration
mcp.json         # MCP client configuration example

Fontes de Dados

Este servidor usa a API REST Open5e para acessar o conteúdo da 5ª Edição de D&D. A implementação:

• Aproveita a API Open5e para dados abrangentes de D&D 5E
• Implementa cache inteligente para minimizar solicitações à API
• Usa limitação de taxa e tratamento de erros apropriados
• Fornece respostas JSON estruturadas da API

Atualizações Recentes

• Migração para Open5e: Migrado de web scraping para API REST Open5e para maior confiabilidade
• Conjunto Abrangente de Ferramentas: Adicionadas mais de 40 ferramentas cobrindo todos os tipos de conteúdo de D&D 5E
• Busca Unificada: Busca inteligente em todo o conteúdo com correspondência difusa
• Ferramentas do Mestre: Montagem de encontros, cálculo de dificuldade e balanceamento de grupo
• Criação de Personagem: Otimização automatizada de personagem e comparação de builds
• Cobertura Total de Testes: Testes abrangentes para toda a funcionalidade da API

Licença

Licença MIT