D&D MCP Server

# Gamemaster MCP 🐉 A comprehensive [Model Context Protocol MCP](https://www.github.com/modelcontextprotocol) server for managing AI-assisted Dungeons & Dragons campaigns, built with **FastMCP 2.9.0+** **Gamemaster MCP 🐉** aims to be the ultimate AI-assisted Dungeon Master for DnD 5e, providing: - **For Groups**: A comprehensive toolkit to help the user run campaigns more effectively - **For Solo Players**: A complete virtual DnD experience that facilitates immersive solo play - **For Worldbuilders**: Powerful tools to assist in creating rich, interconnected game worlds Built on FastMCP, the server provides structured data models and intelligent tools to manage all aspects of a D&D campaign while enabling natural language interaction through MCP clients. **🚧 Under construction 🚧** ## ✨ Features ### 🌍 Campaign Management The foundation of your D&D world. Each campaign contains: - **Core Metadata**: Name, description, setting, DM name - **Characters**: All player characters and their sheets - **NPCs**: Every non-player character in your world - **Locations**: Cities, dungeons, and points of interest - **Quests**: Active and completed storylines - **Game State**: Current session, party location, world conditions All data is automatically saved and can be shared between sessions. - Create and manage multiple campaigns - Switch between campaigns seamlessly - Track campaign metadata (name, description, DM, setting) ### 📑 Character Management Complete D&D 5e character sheets with: - **Core Attributes**: Ability scores with auto-calculated modifiers - **Combat Stats**: HP, AC, saving throws, resistances - **Inventory**: Equipment with weight and value tracking - **Spellcasting**: Prepared spells, slots, and DCs - **Progression**: Level ups with automatic feature unlocks Characters evolve as you play - taking damage, gaining items, and leveling up. - Complete character sheets with D&D 5e stats - Ability scores with automatic modifier calculation - Hit points, armor class, and combat stats - Inventory and equipment management - Spellcasting support ### 🧝 NPC Management Bring your world to life with rich NPCs featuring: - **Descriptions**: Appearance, personality, voice notes - **Relationships**: Connections to other characters/factions - **Locations**: Where they live and frequent - **Secrets**: Hidden motivations and knowledge - **Stats**: Quick reference for combat if needed NPCs can be linked to quests and locations for easy reference. - Create and track non-player characters - Manage relationships and locations - Store descriptions and notes ### 🗺️ Location/World Building Create immersive settings with: - **Detailed Descriptions**: Sensory details and maps - **Notable Features**: Landmarks, secrets, hazards - **Connections**: Linked areas for travel routes - **Inhabitants**: NPCs and monsters present - **Lore**: Local history and legends Locations update as the party explores - adding discovered areas and changing conditions. - Create detailed locations (cities, dungeons, etc.) - Track populations, governments, and notable features - Connect locations and manage geography ### 💎 Quest Management Track story arcs and missions with: - **Objectives**: Clear steps to completion - **Status Tracking**: Active/Completed/Failed - **Givers & Rewards**: Connected NPCs and prizes - **Time Sensitivity**: Optional deadlines - **Branching Paths**: Alternate resolutions Quest progress automatically updates the Game State and Adventure Log. - Create quests with objectives and rewards - Track quest status and completion - Link quests to NPCs and locations ### ⚔️ Combat Management Track and run dynamic combat encounters with: - **Initiative Order**: Automatic sorting with manual override - **Turn Tracking**: Current actor highlight and turn reminders - **Condition Management**: Status effects with duration tracking - **Damage/Healing**: Apply with automatic HP calculation - **Enemy Stats**: Quick reference for monsters/NPCs Combat data flows to: - Character sheets (HP, conditions) - Game State (current encounter) - Adventure Log (combat events) - Initiative tracking - Turn-based combat flow - Combat encounter planning ### ⏰ Session Management Organize your game sessions with: - **Session Notes**: Key events and decisions - **Attendance Tracking**: Which players were present - **XP Awards**: Track character progression - **Loot Distribution**: Treasure found and claimed - **Game Date**: Track in-world time passage Session data updates: - Character sheets (XP, items) - Game State (current session #) - Adventure Log (session summary) - Session notes and summaries - Experience and treasure tracking - Character attendance ### 🏕️ Adventure Log Your campaign's living history: - **Event Types**: Combat, Roleplay, Exploration, etc. - **Timeline View**: Chronological story progression - **Searchable**: Find key moments quickly - **Tags & Importance**: Highlight major plot points - **Session Linking**: Connect events to game sessions The log connects to: - Quests (progress updates) - Locations (where events occurred) - NPCs (who was involved) - Comprehensive event logging - Categorized by event type (combat, roleplay, exploration, etc.) - Searchable and filterable - Importance ratings ### 🎮 Game State Tracking The current snapshot of your world: - **Party Status**: Location, resources, conditions - **Active Quests**: Current objectives and progress - **World Conditions**: Weather, political climate - **Time Tracking**: In-game date and time - **Combat Status**: Current encounter details The Game State connects all other models: - Updates from character actions - Drives world simulation - Informs AI DM decisions - Current location and session - Party level and funds - Combat status - In-game date tracking ### 🎲 Utility Tools - Dice rolling with advantage/disadvantage - Experience point calculations - D&D 5e mechanics support ## 💾 Installation ### Prerequisites - Python 3.12+ - `uv` (available in your system's PATH) ### User Installation 1. **Clone the repository:** ```bash git clone https://github.com/study-flamingo/gamemaster-mcp.git cd gamemaster-mcp ``` 2. **Create a virtual environment and install dependencies:** ```bash uv venv uv pip install . ``` ## 🏁 Running the Server ### From the Command Line To run the server directly, first activate the virtual environment: ```bash # On macOS/Linux source .venv/bin/activate # On Windows .venv\Scripts\activate ``` Then, run the executable: ```bash gamemaster-mcp ``` Alternatively, use `uv` to run the script without activating the environment: ```bash uv run gamemaster-mcp ``` ### With an MCP Client (e.g., Claude Desktop) Configure your MCP client to use `uv` to run the server. You only need to provide the path to your project folder as the working directory. ```json { "mcpServers": { "gamemaster-mcp": { "command": "uv", "args": [ "run", "gamemaster-mcp" ], "cwd": "C:\\path\\to\\your\\gamemaster-mcp" } } } ``` *Note: Replace `C:\\path\\to\\your\\gamemaster-mcp` with the absolute path to the project directory.* ## 🎛️ System Prompt Recommendation For optimal performance, use a system prompt that primes the LLM to act as a knowledgeable Dungeon Master's assistant. This prompt should guide the model to understand the context of D&D campaign management and leverage the provided tools effectively. ### 📜 Example System Prompt ```markdown 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." ``` ## Available Tools (25+ FastMCP Tools) ### Campaign Management - `create_campaign` - Create a new campaign - `get_campaign_info` - Get current campaign information - `list_campaigns` - List all available campaigns - `load_campaign` - Switch to a different campaign ### Character Management - `create_character` - Create a new player character - `get_character` - Get character sheet details - `update_character` - Update a character's properties (name, stats, HP, etc.). - `bulk_update_characters` - Update multiple characters at once (e.g., apply damage to all). - `add_item_to_character` - Add items to inventory - `list_characters` - List all characters ### NPC Management - `create_npc` - Create a new NPC - `get_npc` - Get NPC details - `list_npcs` - List all NPCs ### Location Management - `create_location` - Create a new location - `get_location` - Get location details - `list_locations` - List all locations ### Quest Management - `create_quest` - Create a new quest - `update_quest` - Update quest status or objectives - `list_quests` - List quests (optionally filtered by status) ### Game State Management - `update_game_state` - Update current game state - `get_game_state` - Get current game state ### Combat Management - `start_combat` - Initialize combat with initiative order - `end_combat` - End combat encounter - `next_turn` - Advance to next participant's turn ### Session Management - `add_session_note` - Add session notes and summary - `get_sessions` - Get all session notes ### Adventure Log - `add_event` - Add event to adventure log - `get_events` - Get events (with filtering and search) ### Utility Tools - `roll_dice` - Roll dice with D&D notation (e.g., "1d20", "3d6+2") - `calculate_experience` - Calculate XP distribution for encounters ## 💽 Data Structure The Gamemaster MCP server organizes all campaign data around a central `Campaign` model, which acts as the primary container for the entire game world. This design ensures a cohesive and interconnected data structure, allowing for easy management and interaction with various game elements. The system is built around a hierarchical data structure with the `Campaign` model at its core. All other models relate to the active campaign, as shown below: ```mermaid 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 ``` Here's how the core data models in `src/gamemaster_mcp/models.py` interact: - **`Campaign`**: The foundational model. It encapsulates all campaign-specific data, including: - **`characters`**: A dictionary of `Character` models, representing player characters. Each `Character` is a complex model composed of `CharacterClass`, `Race`, `AbilityScore` (for core stats), `Item` (for inventory and equipment), and `Spell` (for known spells). - **`npcs`**: A dictionary of `NPC` models, representing non-player characters. NPCs can be linked to `Location` models. - **`locations`**: A dictionary of `Location` models, defining places within the campaign world. Locations can list associated NPCs and connections to other locations. - **`quests`**: A dictionary of `Quest` models, tracking ongoing and completed missions. Quests can reference NPCs as givers. - **`encounters`**: A dictionary of `CombatEncounter` models, detailing planned or active combat scenarios. Encounters can be tied to specific locations. - **`sessions`**: A list of `SessionNote` models, providing summaries and details for each game session played within the campaign. - **`game_state`**: A single `GameState` model, which captures the dynamic, real-time conditions of the campaign, such as the current location, active quests, and party funds. This model is crucial for understanding the immediate context of the game. - **`GameState`**: While part of the `Campaign`, `GameState` plays a pivotal role in reflecting the current state of the world. It influences and is influenced by other models: - `current_location` can point to a `Location` model. - `active_quests` references `Quest` titles. - Changes in `Character` status (e.g., `hit_points_current`) or `Quest` status (`active`, `completed`) directly impact the `GameState`. - **`AdventureEvent`**: This model is used to log significant occurrences throughout the campaign. While not directly nested within `Campaign` (it's stored globally), `AdventureEvent` instances often reference elements from the `Campaign`'s data, such as `characters_involved` and `location`. This provides a historical log for understanding past events and narrative progression. ## 🖥️ Development ### Development Workflow If you want to contribute to the project, the setup is slightly different. 1. **Follow steps from the User Installation** to clone the repo and set up the virtual environment. 2. **Install in editable mode with development dependencies:** ```bash uv pip install -e .[dev] ``` This installs the project in a way that your code changes are immediately reflected without needing to reinstall. It also installs tools for testing and linting. ### Running Tests To run the test suite, use the following command: ```bash uv run pytest ``` ## 📜 License MIT License