D&D MCP Server

Un servidor para gestionar campañas de Dungeons & Dragons, que almacena todos los datos en archivos JSON locales.

Documentación

Gamemaster MCP 🐉

Un servidor integral de Model Context Protocol MCP para gestionar campañas de Dungeons & Dragons asistidas por IA, construido con FastMCP 2.9.0+

Gamemaster MCP 🐉 aspira a ser el Dungeon Master definitivo asistido por IA para DnD 5e, proporcionando:

Para Grupos: Un kit de herramientas integral para ayudar al usuario a dirigir campañas de manera más efectiva
Para Jugadores en Solitario: Una experiencia virtual completa de DnD que facilita el juego en solitario inmersivo
Para Creadores de Mundos: Potentes herramientas para ayudar a crear mundos de juego ricos e interconectados

Construido sobre FastMCP, el servidor proporciona modelos de datos estructurados y herramientas inteligentes para gestionar todos los aspectos de una campaña de D&D, permitiendo la interacción en lenguaje natural a través de clientes MCP.

🚧 En construcción 🚧

✨ Características

🌍 Gestión de Campañas

La base de tu mundo de D&D. Cada campaña contiene:

Metadatos principales: Nombre, descripción, ambientación, nombre del DM
Personajes: Todos los personajes jugadores y sus fichas
PNJs: Cada personaje no jugador en tu mundo
Ubicaciones: Ciudades, mazmorras y puntos de interés
Misiones: Historias activas y completadas
Estado del juego: Sesión actual, ubicación del grupo, condiciones del mundo

Todos los datos se guardan automáticamente y se pueden compartir entre sesiones.

Crea y gestiona múltiples campañas
Cambia entre campañas sin problemas
Registra metadatos de campaña (nombre, descripción, DM, ambientación)

📑 Gestión de Personajes

Fichas de personaje completas de D&D 5e con:

Atributos principales: Puntuaciones de habilidad con modificadores calculados automáticamente
Estadísticas de combate: PG, CA, tiradas de salvación, resistencias
Inventario: Equipo con seguimiento de peso y valor
Lanzamiento de conjuros: Conjuros preparados, espacios y CD
Progresión: Subidas de nivel con desbloqueo automático de características

Los personajes evolucionan mientras juegas: reciben daño, obtienen objetos y suben de nivel.

Fichas de personaje completas con estadísticas de D&D 5e
Puntuaciones de habilidad con cálculo automático de modificadores
Puntos de golpe, clase de armadura y estadísticas de combate
Gestión de inventario y equipo
Soporte para lanzamiento de conjuros

🧝 Gestión de PNJs

Dale vida a tu mundo con PNJs ricos que incluyen:

Descripciones: Apariencia, personalidad, notas de voz
Relaciones: Conexiones con otros personajes/facciones
Ubicaciones: Dónde viven y frecuentan
Secretos: Motivaciones y conocimientos ocultos
Estadísticas: Referencia rápida para combate si es necesario

Los PNJs se pueden vincular a misiones y ubicaciones para facilitar la referencia.

Crea y registra personajes no jugadores
Gestiona relaciones y ubicaciones
Almacena descripciones y notas

🗺️ Construcción de Ubicaciones/Mundos

Crea ambientaciones inmersivas con:

Descripciones detalladas: Detalles sensoriales y mapas
Características notables: Lugares emblemáticos, secretos, peligros
Conexiones: Áreas vinculadas para rutas de viaje
Habitantes: PNJs y monstruos presentes
Lore: Historia local y leyendas

Las ubicaciones se actualizan a medida que el grupo explora, añadiendo áreas descubiertas y condiciones cambiantes.

Crea ubicaciones detalladas (ciudades, mazmorras, etc.)
Registra poblaciones, gobiernos y características notables
Conecta ubicaciones y gestiona la geografía

💎 Gestión de Misiones

Registra arcos argumentales y misiones con:

Objetivos: Pasos claros para completar
Seguimiento de estado: Activa/Completada/Fallida
Otorgantes y recompensas: PNJs conectados y premios
Sensibilidad temporal: Plazos opcionales
Caminos ramificados: Resoluciones alternativas

El progreso de las misiones actualiza automáticamente el Estado del Juego y el Registro de Aventuras.

Crea misiones con objetivos y recompensas
Registra el estado y la finalización de misiones
Vincula misiones a PNJs y ubicaciones

⚔️ Gestión de Combate

Registra y dirige encuentros de combate dinámicos con:

Orden de iniciativa: Clasificación automática con anulación manual
Seguimiento de turnos: Resaltado del actor actual y recordatorios de turno
Gestión de condiciones: Efectos de estado con seguimiento de duración
Daño/Curación: Aplicar con cálculo automático de PG
Estadísticas de enemigos: Referencia rápida para monstruos/PNJs

Los datos de combate fluyen hacia:

Fichas de personaje (PG, condiciones)
Estado del juego (encuentro actual)
Registro de aventuras (eventos de combate)
Seguimiento de iniciativa
Flujo de combate por turnos
Planificación de encuentros de combate

⏰ Gestión de Sesiones

Organiza tus sesiones de juego con:

Notas de sesión: Eventos y decisiones clave
Seguimiento de asistencia: Qué jugadores estuvieron presentes
Recompensas de XP: Registro de progresión de personajes
Distribución de botín: Tesoro encontrado y reclamado
Fecha del juego: Registro del paso del tiempo en el mundo

Los datos de sesión actualizan:

Fichas de personaje (XP, objetos)
Estado del juego (número de sesión actual)
Registro de aventuras (resumen de sesión)
Notas y resúmenes de sesión
Registro de experiencia y tesoro
Asistencia de personajes

🏕️ Registro de Aventuras

La historia viva de tu campaña:

Tipos de eventos: Combate, interpretación, exploración, etc.
Vista de línea de tiempo: Progresión cronológica de la historia
Búsqueda: Encuentra momentos clave rápidamente
Etiquetas e importancia: Resalta puntos principales de la trama
Vinculación de sesiones: Conecta eventos con sesiones de juego

El registro se conecta con:

Misiones (actualizaciones de progreso)
Ubicaciones (dónde ocurrieron los eventos)
PNJs (quién estuvo involucrado)
Registro integral de eventos
Categorizado por tipo de evento (combate, interpretación, exploración, etc.)
Buscable y filtrable
Clasificaciones de importancia

🎮 Seguimiento del Estado del Juego

La instantánea actual de tu mundo:

Estado del grupo: Ubicación, recursos, condiciones
Misiones activas: Objetivos y progreso actuales
Condiciones del mundo: Clima, clima político
Seguimiento del tiempo: Fecha y hora en el juego
Estado del combate: Detalles del encuentro actual

El Estado del Juego conecta todos los demás modelos:

Actualizaciones de las acciones de los personajes
Impulsa la simulación del mundo
Informa las decisiones del DM de IA
Ubicación y sesión actuales
Nivel y fondos del grupo
Estado del combate
Seguimiento de la fecha en el juego

🎲 Herramientas de Utilidad

Tiradas de dados con ventaja/desventaja
Cálculos de puntos de experiencia
Soporte de mecánicas de D&D 5e

💾 Instalación

Requisitos previos

Python 3.12+
uv (disponible en el PATH de tu sistema)

Instalación para usuarios

Clona el repositorio:

git clone https://github.com/study-flamingo/gamemaster-mcp.git
cd gamemaster-mcp

Crea un entorno virtual e instala las dependencias:
```
uv venv
uv pip install .
```

🏁 Ejecutar el servidor

Desde la línea de comandos

Para ejecutar el servidor directamente, primero activa el entorno virtual:

# On macOS/Linux
source .venv/bin/activate

# On Windows
.venv\Scripts\activate

Luego, ejecuta el ejecutable:

gamemaster-mcp

Alternativamente, usa uv para ejecutar el script sin activar el entorno:

uv run gamemaster-mcp

Con un cliente MCP (por ejemplo, Claude Desktop)

Configura tu cliente MCP para usar uv para ejecutar el servidor. Solo necesitas proporcionar la ruta a tu carpeta de proyecto como directorio de trabajo.

{
  "mcpServers": {
    "gamemaster-mcp": {
      "command": "uv",
      "args": [
        "run",
        "gamemaster-mcp"
      ],
      "cwd": "C:\\path\\to\\your\\gamemaster-mcp"
    }
  }
}

Nota: Reemplaza C:\\path\\to\\your\\gamemaster-mcp con la ruta absoluta al directorio del proyecto.

🎛️ Recomendación de Prompt del Sistema

Para un rendimiento óptimo, usa un prompt del sistema que prepare al LLM para actuar como un asistente experto de Dungeon Master. Este prompt debe guiar al modelo para comprender el contexto de la gestión de campañas de D&D y aprovechar las herramientas proporcionadas de manera efectiva.

📜 Ejemplo de Prompt del Sistema

You are a master Dungeon Master (DM) or a Dungeon Master's Assistant, powered by the Gamemaster MCP server. Your primary role is to help users manage all aspects of their Dungeons & Dragons campaigns using a rich set of specialized tools. You are a stateful entity, always operating on a single, currently active campaign.

**Core Principles:**

1.  **Campaign-Centric:** All data—characters, NPCs, quests, locations—is stored within a single, active `Campaign`. Always be aware of the current campaign context. If a user's request seems to reference a different campaign, use the `list_campaigns` and `load_campaign` tools to switch context.
2.  **Structured Data:** You are working with structured data models (`Character`, `NPC`, `Quest`, `Location`, etc.). When creating or updating these entities, strive to populate them with as much detail as possible. If a user is vague, ask for specifics (e.g., "What is the character's class and race? What are their ability scores?").
3.  **Proactive Assistance:** Don't just execute single commands. Fulfill complex user requests by chaining tools together. For example, to "add a new character to the party," you should use `create_character`, then perhaps `add_item_to_character` to give them starting gear.
4.  **Information Gathering:** Before acting, use `list_` and `get_` tools to understand the current state. For instance, before adding a quest, you might `list_npcs` to see who could be the quest giver.
5.  **State Management:** Use the `get_game_state` and `update_game_state` tools to keep track of the party's current location, in-game date, and combat status.
6.  **Be a Storyteller:** While your primary function is data management, frame your responses in the context of a D&D game. You are not just a database; you are the keeper of the campaign's world.

**Interactive Session Zero:**

When a user wants to start a new campaign, initiate an interactive "Session Zero." Guide them through the setup process step-by-step, asking questions and using tools to build the world collaboratively. Use the following framework as a *loose* framework: it is more important to follow the user's prompting. However, be sure to establish the necessary parameters for each tool call.

1.  **Establish the Campaign:**
    *   **You:** "Welcome to the world of adventure! What shall we name our new campaign?" (Wait for user input)
    *   **You:** "Excellent! And what is the central theme or description of 'Campaign Name'?" (Wait for user input)
    *   *Then, use `create_campaign` with the gathered information.*

2.  **Build the Party:**
    *   **You:** "Now, let's assemble our heroes. How many players will be in the party?"
    *   *For each player, engage in a dialogue to create their character:*
    *   **You:** "Let's create the first character. What is their name, race, and class?"
    *   **You:** "Great. What are their ability scores (Strength, Dexterity, etc.)?"
    *   *Use `create_character` after gathering the core details for each hero.*

3.  **Flesh out the World:**
    *   **You:** "Where does our story begin? Describe the starting town or location."
    *   *Use `create_location`.*
    *   **You:** "Who is the first person the party meets? Let's create an NPC."
    *   *Use `create_npc`.*

4.  **Launch the Adventure:**
    *   **You:** "With our world set up, what is the first challenge or quest the party will face?"
    *   *Use `create_quest`.*
    *   **You:** "Session Zero is complete! I've logged the start of your first session. Are you ready to begin?"
    *   *Use `add_session_note`.*

Your goal is to be an indispensable partner to the Dungeon Master, co-creating the campaign's foundation so they can focus on telling a great story.

**In-Play Campaign Guidance:**

Once the campaign is underway, your focus shifts to dynamic management and narrative support:

1.  **Dynamic World:** Respond to player actions and tool outputs by dynamically updating the `GameState`, `NPC` statuses, `Location` details, and `Quest` progress.
2.  **Event Logging:** Every significant interaction, combat round, roleplaying encounter, or quest milestone should be logged using `add_event` to maintain a comprehensive `AdventureLog`.
3.  **Proactive DM Support:** Anticipate the DM's needs. If a character takes damage, suggest `update_character_hp`. If they enter a new area, offer `get_location` details.
4.  **Narrative Cohesion:** Maintain narrative consistency. Reference past events from the `AdventureLog` or `SessionNotes` to enrich descriptions and ensure continuity.
5.  **Challenge and Consequence:** When players attempt actions, consider the potential outcomes and use appropriate tools to reflect success, failure, or partial success, including updating character stats or game state.
6.  **Tool-Driven Responses:** Frame your narrative responses around the successful execution of tools. For example, instead of "The character's HP is now 15," say "You successfully heal [Character Name], their hit points now stand at 15."

Herramientas Disponibles (más de 25 herramientas FastMCP)

Gestión de Campañas

create_campaign - Crear una nueva campaña
get_campaign_info - Obtener información de la campaña actual
list_campaigns - Listar todas las campañas disponibles
load_campaign - Cambiar a una campaña diferente

Gestión de Personajes

create_character - Crear un nuevo personaje jugador
get_character - Obtener detalles de la ficha del personaje
update_character - Actualizar las propiedades de un personaje (nombre, estadísticas, PG, etc.)
bulk_update_characters - Actualizar múltiples personajes a la vez (por ejemplo, aplicar daño a todos)
add_item_to_character - Añadir objetos al inventario
list_characters - Listar todos los personajes

Gestión de PNJs

create_npc - Crear un nuevo PNJ
get_npc - Obtener detalles del PNJ
list_npcs - Listar todos los PNJs

Gestión de Ubicaciones

create_location - Crear una nueva ubicación
get_location - Obtener detalles de la ubicación
list_locations - Listar todas las ubicaciones

Gestión de Misiones

create_quest - Crear una nueva misión
update_quest - Actualizar el estado u objetivos de la misión
list_quests - Listar misiones (opcionalmente filtradas por estado)

Gestión del Estado del Juego

update_game_state - Actualizar el estado actual del juego
get_game_state - Obtener el estado actual del juego

Gestión de Combate

start_combat - Inicializar combate con orden de iniciativa
end_combat - Finalizar encuentro de combate
next_turn - Avanzar al turno del siguiente participante

Gestión de Sesiones

add_session_note - Añadir notas y resumen de sesión
get_sessions - Obtener todas las notas de sesión

Registro de Aventuras

add_event - Añadir evento al registro de aventuras
get_events - Obtener eventos (con filtrado y búsqueda)

Herramientas de Utilidad

roll_dice - Tirar dados con notación de D&D (por ejemplo, "1d20", "3d6+2")
calculate_experience - Calcular distribución de XP para encuentros

💽 Estructura de Datos

El servidor Gamemaster MCP organiza todos los datos de la campaña alrededor de un modelo central Campaign, que actúa como el contenedor principal de todo el mundo del juego. Este diseño garantiza una estructura de datos cohesiva e interconectada, permitiendo una gestión e interacción fáciles con varios elementos del juego.

El sistema está construido alrededor de una estructura de datos jerárquica con el modelo Campaign en su núcleo. Todos los demás modelos se relacionan con la campaña activa, como se muestra a continuación:

graph TD
    A[Campaign] --> B[GameState]
    A --> C[Character]
    A --> D[NPC]
    A --> E[Location]
    A --> F[Quest]
    A --> G[CombatEncounter]
    A --> H[SessionNote]
    B --> I[AdventureEvent]
    
    C --> J[Item]
    C --> K[Spell]
    C --> L[AbilityScore]
    C --> M[CharacterClass]
    C --> N[Race]
    
    style A fill:#f9f,stroke:#333,stroke-width:4px

Así es como interactúan los modelos de datos principales en src/gamemaster_mcp/models.py:

Campaign: El modelo fundamental. Encapsula todos los datos específicos de la campaña, incluyendo:
- characters: Un diccionario de modelos Character, que representan personajes jugadores. Cada Character es un modelo complejo compuesto por CharacterClass, Race, AbilityScore (para estadísticas principales), Item (para inventario y equipo) y Spell (para conjuros conocidos).
- npcs: Un diccionario de modelos NPC, que representan personajes no jugadores. Los PNJs se pueden vincular a modelos Location.
- locations: Un diccionario de modelos Location, que definen lugares dentro del mundo de la campaña. Las ubicaciones pueden listar PNJs asociados y conexiones con otras ubicaciones.
- quests: Un diccionario de modelos Quest, que registran misiones en curso y completadas. Las misiones pueden referenciar PNJs como otorgantes.
- encounters: Un diccionario de modelos CombatEncounter, que detallan escenarios de combate planificados o activos. Los encuentros se pueden vincular a ubicaciones específicas.
- sessions: Una lista de modelos SessionNote, que proporcionan resúmenes y detalles de cada sesión de juego jugada dentro de la campaña.
- game_state: Un único modelo GameState, que captura las condiciones dinámicas y en tiempo real de la campaña, como la ubicación actual, las misiones activas y los fondos del grupo. Este modelo es crucial para comprender el contexto inmediato del juego.
GameState: Aunque es parte de Campaign, GameState juega un papel fundamental al reflejar el estado actual del mundo. Influye y es influenciado por otros modelos:
- current_location puede apuntar a un modelo Location.
- active_quests referencia títulos de Quest.
- Los cambios en el estado de Character (por ejemplo, hit_points_current) o el estado de Quest (active, completed) impactan directamente en GameState.
AdventureEvent: Este modelo se utiliza para registrar ocurrencias significativas a lo largo de la campaña. Aunque no está anidado directamente dentro de Campaign (se almacena globalmente), las instancias de AdventureEvent a menudo referencian elementos de los datos de Campaign, como characters_involved y location. Esto proporciona un registro histórico para comprender eventos pasados y la progresión narrativa.

🖥️ Desarrollo

Flujo de Trabajo de Desarrollo

Si quieres contribuir al proyecto, la configuración es ligeramente diferente.

Sigue los pasos de la Instalación de Usuario para clonar el repositorio y configurar el entorno virtual.
Instala en modo editable con dependencias de desarrollo:
```
uv pip install -e .[dev]
```
Esto instala el proyecto de manera que tus cambios de código se reflejen inmediatamente sin necesidad de reinstalar. También instala herramientas para pruebas y linting.

Ejecutar Pruebas

Para ejecutar el conjunto de pruebas, usa el siguiente comando:

uv run pytest

📜 Licencia

Licencia MIT