D&D 5E MCP Server

Accede al contenido de Dungeons & Dragons 5ª Edición, incluyendo hechizos, clases y monstruos, a través de la API de Open5e.

GitHub
21
Prueba este MCPPatrocinado

Documentación

D&D 5E MCP Server

Un servidor MCP (Model Context Protocol) que proporciona acceso al contenido de D&D 5ª Edición a través de la API REST de Open5e. Este servidor permite a los asistentes de IA y otros clientes MCP recuperar información completa de D&D 5E, incluyendo conjuros, clases, razas, monstruos y equipo.

Herramientas Disponibles

Búsqueda Universal

  • unified_search - Busca en todos los tipos de contenido de D&D con clasificación inteligente
    • Parámetro query requerido para términos de búsqueda
    • Filtro opcional content_types para contenido específico (conjuros, monstruos, razas, etc.)
    • fuzzy_threshold opcional para sensibilidad de coincidencia
    • Devuelve resultados clasificados en todos los tipos de contenido

Herramientas de Conjuros

  • search_spells - Busca conjuros por nombre u obtiene todos los conjuros
    • Parámetro opcional query para filtrar por nombre de conjuro
    • Devuelve información básica del conjuro (nombre, nivel, escuela, tiempo de lanzamiento, etc.)
  • get_spell_details - Obtén detalles completos sobre un conjuro específico
    • Requiere el parámetro spell_name
    • Devuelve la descripción completa del conjuro, componentes, duración y listas de clases
  • get_spell_by_level - Obtén todos los conjuros de un nivel específico (0-9)
    • Requiere el parámetro level (0 para trucos, 1-9 para niveles de conjuro)
  • get_spells_by_class - Obtén todos los conjuros disponibles para una clase específica
    • Requiere el parámetro class_name (p. ej., "wizard", "cleric", "bard")

Herramientas de Clases

  • search_classes - Obtén una lista de todas las clases disponibles de D&D 5E
    • Devuelve información básica de todas las clases principales
  • get_class_details - Obtén información detallada sobre una clase específica
    • Requiere el parámetro class_name
    • Devuelve dados de golpe, tiradas de salvación, descripción y subclases disponibles

Herramientas de Razas

  • search_races - Obtén una lista de todas las razas disponibles de D&D 5E
    • Devuelve información básica de la raza desde la página de linaje
  • get_race_details - Obtén información detallada sobre una raza específica
    • Requiere el parámetro race_name
    • Devuelve tamaño, velocidad, incrementos de puntuación de habilidad, rasgos y descripción

Herramientas de Monstruos

  • search_monsters - Busca monstruos con opciones de filtrado
    • Parámetro opcional query para nombres de monstruos
    • Filtro opcional challenge_rating
    • Devuelve estadísticas del monstruo e información básica
  • get_monsters_by_cr - Obtén todos los monstruos de un índice de desafío específico
  • get_monsters_by_cr_range - Obtén monstruos dentro de un rango de CR para planificación de encuentros

Herramientas de Equipo

  • search_weapons - Busca armas con filtrado por propiedades
    • Filtros opcionales para armas marciales/de sutileza
  • search_armor - Busca armaduras con filtrado por CA y categoría
  • search_magic_items - Busca objetos mágicos con filtrado por rareza
  • get_magic_item_details - Obtén información detallada de objetos mágicos

Herramientas de Construcción de Personajes

  • search_feats - Busca dotes de personaje
  • get_feat_details - Obtén información detallada de dotes
  • search_backgrounds - Busca trasfondos de personaje
  • get_background_details - Obtén información detallada de trasfondos
  • generate_character_build - Genera construcciones de personaje optimizadas
  • compare_character_builds - Compara múltiples opciones de construcción de personaje
  • get_build_recommendations - Obtén recomendaciones de construcción para la composición del grupo

Herramientas de Dungeon Master

  • build_encounter - Construye encuentros equilibrados para el grupo especificado
    • Requiere party_size, party_level y difficulty
    • Filtros opcionales para entorno, tipos de monstruos, rango de CR
    • Devuelve un encuentro equilibrado con cálculos de XP
  • calculate_encounter_difficulty - Calcula la dificultad de encuentros personalizados
    • Requiere información del grupo y lista de monstruos con cantidades
    • Devuelve la calificación de dificultad del encuentro y el desglose de XP

Herramientas de Reglas y Referencia

  • search_conditions - Busca condiciones de estado y efectos
  • get_condition_details - Obtén información detallada de condiciones
  • get_all_conditions - Obtén todas las condiciones para referencia rápida
  • search_sections - Busca secciones de reglas para consultas rápidas de reglas
  • get_section_details - Obtén información detallada de secciones de reglas
  • search_spell_lists - Busca listas de conjuros por clase
  • get_spell_list_details - Obtén listas de conjuros detalladas para clases específicas

Instalación

  1. Clona este repositorio:

    git clone <repository-url>
cd dnd-mcp

  2. Instala las dependencias:

    npm install

  3. Compila el proyecto:

    npm run build

Uso

Ejecutando el Servidor

npm start

Modo de Desarrollo

npm run dev

Configuración del Cliente MCP

Añade a tu configuración de cliente MCP (p. ej., mcp.json):

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

Ejemplo de Uso de Herramientas MCP

El servidor implementa el Model Context Protocol, exponiendo herramientas que pueden ser llamadas por clientes MCP. Aquí hay algunos ejemplos de llamadas a herramientas:

Búsqueda Universal

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

Construir Encuentro

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

Generar Construcción de Personaje

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

Características Técnicas

  • Caché Inteligente: Caché TTL de 1 hora para minimizar solicitudes al sitio web fuente
  • Limitación de Velocidad: Retrasos de 1 segundo entre solicitudes para respetar los recursos del servidor
  • Manejo de Errores: Manejo integral de errores para problemas de red y contenido faltante
  • TypeScript: Implementación completamente tipada para una mejor experiencia de desarrollo
  • Protocolo MCP: Cumplimiento total con las especificaciones del Model Context Protocol
  • Pruebas Integrales: Cobertura completa de pruebas para la funcionalidad de la API de Open5e y operaciones de scraping

Arquitectura

  • Integración con la API de Open5e: Usa Axios para la comunicación REST API con Open5e
  • Procesamiento de Contenido: Manejo de datos estructurados de respuestas JSON de Open5e
  • Servidor MCP: Implementación estándar del protocolo MCP con transporte stdio
  • Capa de Caché: NodeCache para almacenamiento eficiente de contenido

Desarrollo

Scripts Disponibles

  • npm run build - Compila TypeScript a JavaScript
  • npm run dev - Ejecuta en modo de desarrollo con recarga en caliente
  • npm start - Ejecuta el servidor compilado
  • npm run lint - Ejecuta ESLint
  • npm test - Ejecuta pruebas de Jest (incluye pruebas integrales de la API de Open5e)

Estructura del Proyecto

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

Fuentes de Datos

Este servidor utiliza la API REST de Open5e para acceder al contenido de D&D 5ª Edición. La implementación:

  • Aprovecha la API de Open5e para datos completos de D&D 5E
  • Implementa caché inteligente para minimizar solicitudes a la API
  • Usa limitación de velocidad y manejo de errores apropiados
  • Proporciona respuestas JSON estructuradas desde la API

Actualizaciones Recientes

  • Migración a Open5e: Migrado de web scraping a la API REST de Open5e para mayor fiabilidad
  • Suite Integral de Herramientas: Se añadieron más de 40 herramientas que cubren todos los tipos de contenido de D&D 5E
  • Búsqueda Unificada: Búsqueda inteligente en todo el contenido con coincidencia difusa
  • Herramientas de DM: Construcción de encuentros, cálculo de dificultad y equilibrio del grupo
  • Construcción de Personajes: Optimización automatizada de personajes y comparación de construcciones
  • Cobertura Completa de Pruebas: Pruebas integrales para toda la funcionalidad de la API

Licencia

Licencia MIT