// EXECUTIVE_SUMMARY
This is a sophisticated multi-server MCP (Model Context Protocol) architecture designed to enable AI-powered D&D 5e gameplay. The system consists of two complementary servers that handle game state persistence and combat mechanics, with a custom Roo Code mode configuration for AI dungeon master functionality.
🚀 Key Innovation
The system bridges the gap between LLM AI assistants and traditional tabletop RPG mechanics, providing persistent state management and authentic D&D 5e rule implementation while maintaining narrative flexibility.
// ARCHITECTURE_OVERVIEW
Server Structure
rpg-mcp-servers/ ├── game-state-server/ # Persistent character & world state │ ├── src/ │ │ ├── index.ts # Main MCP server implementation │ │ ├── db.ts # SQLite database management │ │ ├── monsters.ts # Monster/NPC templates │ │ └── enhanced-db-schema.sql │ └── dist/ # Compiled JavaScript ├── combat-engine-server/ # Real-time combat mechanics │ ├── src/ │ │ ├── index.ts # Main combat server │ │ ├── dice.ts # Dice rolling utilities │ │ ├── spatial-engine.ts # 3D battlefield system │ │ └── action-types.ts # Action economy definitions │ └── dist/ # Compiled JavaScript └── dungeon-master-mode.json # Roo Code AI mode configuration
Technology Stack
- Language: TypeScript (compiled to JavaScript)
- Protocol: Model Context Protocol (MCP) via @modelcontextprotocol/sdk
- Database: SQLite (for game-state-server)
- Communication: stdio transport layer
- Deployment: Node.js runtime
// GAME_STATE_SERVER_ANALYSIS
Core Responsibilities
The game-state-server is the persistence layer of the system, handling:
- Character Management - Full D&D 5e character sheets
- Inventory System - Item tracking with quantities and equipped states
- World State - Location, NPCs, events, environmental data
- NPC Management - Monsters and allies with stat blocks
- Encounter Management - Combat sessions with turn tracking
- Story Progress - Checkpoint system for narrative continuity
- Quest System - Quest tracking with objectives and rewards
- Spell Management - Spellbooks, spell slots, and casting
- Stronghold Management - Base building, facilities, hirelings, businesses
- Batch Operations - Efficient multi-entity updates
Character System
Full D&D 5e Implementation
Complete character data including:
- All six ability scores (STR, DEX, CON, INT, WIS, CHA)
- Automatic ability modifier calculation
- Proficiency bonus scaling with level
- Initiative and saving throw calculations
- Skill proficiency tracking
- Features and abilities storage
Inventory Management
Comprehensive item tracking with:
- Multiple items per addition (batch support)
- Quantity tracking
- Equipped/unequipped status
- Item properties (JSON storage)
- Item types and categorization
World State System
Innovative Merge Strategy
The system supports both overwrite and append operations, preventing accidental data loss during incremental world updates.
Stronghold System
Advanced base building features including:
- Stronghold creation and leveling
- Defense and prosperity tracking
- Facility construction (military, economic, magical, etc.)
- Hireling management with loyalty tracking
- Economic system with businesses and weekly income
- Random event system (opportunities, disasters, quests)
// COMBAT_ENGINE_SERVER_ANALYSIS
Core Responsibilities
The combat-engine-server is the mechanics engine, handling:
- Dice Rolling - All D&D dice mechanics
- Spatial Combat - 3D battlefield with terrain
- Line of Sight - Vision and cover calculations
- Movement - Speed-based movement with opportunity attacks
- Action Economy - Actions, reactions, legendary actions
- Area Effects - Spell geometry and targeting
- Tactical Analysis - AI-friendly battlefield descriptions
- Combat Logging - Action history tracking
- Batch Operations - Multiple rolls and actions
Advanced Dice System
roll_dice({ notation: "1d20+5" }) // Standard roll
roll_dice({ notation: "2d20kh1+5" }) // Advantage (keep highest)
roll_dice({ notation: "2d20kl1+5" }) // Disadvantage (keep lowest)
roll_dice({ notation: "3d6" }) // Multiple dice
roll_dice({ notation: "8d6" }) // Fireball damage
3D Spatial Engine
Beyond Grid-Based Combat
The system features a full 3D battlefield with:
- Elevation (Z-axis) tracking
- Height advantage calculations
- Terrain features (walls, pillars, stairs, pits, etc.)
- Line of sight with 3D raycasting
- Cover mechanics (half, three-quarters, total)
- Movement validation with obstacle detection
Area Effect System
Sophisticated spell geometry supporting:
- Sphere: Radius-based (Fireball)
- Cube: Side length (Thunderwave)
- Cone: Directional spread (Burning Hands)
- Line: Directional beam (Lightning Bolt)
- Cylinder: Vertical area (Flame Strike)
Tactical Intelligence
Human-readable battlefield descriptions for AI decision-making, including:
- Enemy positions and distances
- Cover availability
- Height advantages
- Flanking detection
- Movement options
- Optimal tactical positions
// DUNGEON_MASTER_MODE_CONFIGURATION
The dungeon-master-mode.json file configures a custom Roo Code mode that:
- Provides the AI with context about available MCP tools
- Establishes the AI's role as a D&D Dungeon Master
- Defines workflow patterns for game management
- Sets narrative and mechanical guidelines
Game Flow Rules
Before Describing Actions:
- Check character stats
- Use combat engine for ALL dice rolls
- Track HP, inventory, and progress
- Create immersive descriptions
- Give players meaningful choices
- Balance challenge with fun
Narrative Style Guidelines
The system emphasizes:
- Vivid, sensory language
- Atmosphere appropriate to scene
- Distinct NPC personalities
- Dynamic reactions to player choices
- Consistency with world state
// SYSTEM_INTEGRATION
Cross-Server Operations
Many gameplay actions require coordinating both servers. For example, a combat encounter requires:
Starting Combat Workflow
- Game State: Create encounter and add participants
- Combat Engine: Initialize battlefield and place creatures
- Combat Engine: Generate tactical view
- Both Servers: Coordinate turn-by-turn actions
// ADVANCED_FEATURES
Comprehensive Spell System
- Class-based spell slot calculation
- Spell preparation mechanics
- Upcasting support
- Cantrips (unlimited use)
- Spell save DC and attack bonus calculation
- Concentration tracking (potential)
Quest System
Multi-layer quest tracking with:
- Quest creation and assignment
- Objective tracking
- Progress updates
- Rewards management (gold, XP, items)
- Status tracking (active, completed, failed)
Combat Log System
Persistent action history for:
- Session recap
- Dispute resolution
- Learning combat tactics
- Debugging mechanics
// BEST_PRACTICES_&_PATTERNS
1. State Management
Always preserve existing data using append operations instead of overwrite when updating world state incrementally.
2. Batch Operations
Use batch operations for efficiency when dealing with multiple entities.
3. Combat Flow
Proper turn structure: Start turn → Take actions → Consume action economy → End turn → Next turn
4. Spatial Combat Setup
Initialize battlefield before placing creatures, then check tactics.
5. Spell Casting
Check spell availability and slots before casting.
// USE_CASES_&_EXAMPLES
Use Case 1: Solo Adventure Session
Complete workflow from character creation through combat encounters with full mechanical support.
Use Case 2: Party Management
Support for multiple characters with shared or individual world states.
Use Case 3: Stronghold Campaign
Domain-level play with base building, economic management, and NPC hiring.
Use Case 4: Spell Combat
Full spellcasting mechanics including spell slot management, area effects, and saving throws.
// STRENGTHS_&_INNOVATIONS
Key Innovations
- First system to bridge LLM AI assistants and traditional tabletop RPG mechanics
- Comprehensive 3D spatial combat beyond traditional 2D grids
- Sophisticated stronghold management for high-level play
- Rich ASCII visualization for text-based environments
- Intelligent world state merging to prevent data loss
- Batch operations for performance at scale
// LIMITATIONS_&_CONSIDERATIONS
Current Limitations
- ASCII visualization only (no graphical battle maps)
- Manual stat management required
- Limited automation for conditions and duration tracking
- Single-character world state (not ideal for shared parties)
- No character sheet import from other platforms
- Performance at extreme scale untested (100+ creatures)
Mitigations
Many limitations have workarounds or can be addressed through future enhancements.
// FUTURE_ENHANCEMENT_OPPORTUNITIES
High Priority
- Condition System with automatic effect application
- Concentration Tracking for spells
- Rest System (short and long rests)
- Character Import from D&D Beyond and other platforms
Medium Priority
- Advanced Terrain (difficult terrain, hazards)
- Stealth System
- Mounted Combat
- Vehicle Combat
Low Priority
- Weather System
- Reputation System
// COMPARISON_TO_ALTERNATIVES
vs. D&D Beyond
| Feature | Quest Keeper AI | D&D Beyond |
|---|---|---|
| AI Integration | ✅ Native | ❌ None |
| 3D Spatial Combat | ✅ Yes | ❌ No |
| Stronghold Management | ✅ Yes | ❌ No |
| Cost | ✅ Free & Open Source | 💰 Subscription |
| Visual Polish | ⚠️ Text-based | ✅ High |
vs. Roll20
| Feature | Quest Keeper AI | Roll20 |
|---|---|---|
| AI Dungeon Master | ✅ Yes | ❌ No |
| Full API Access | ✅ Yes | ⚠️ Limited |
| Visual Maps | ❌ ASCII only | ✅ Full graphics |
| Persistent World State | ✅ Database | ⚠️ Campaign files |
Key Differentiators
- Only system with native LLM integration AND full D&D 5e rules
- Most comprehensive spell management
- Unique stronghold system
- Best-in-class tactical combat for AI
- Completely free and open source
// CONCLUSION
Summary
The Quest Keeper AI system represents a sophisticated marriage of traditional tabletop RPG mechanics and modern AI assistant capabilities.
Technical Achievement
- ~10,150 lines of TypeScript
- 100+ MCP tools across both servers
- 15+ database tables with relational integrity
- 3D spatial engine with line-of-sight calculations
- Complete D&D 5e rule implementation
Innovation
First-of-its-Kind: To our knowledge, this is the only system that combines full D&D 5e mechanical accuracy, MCP protocol for AI integration, 3D spatial combat, stronghold management, comprehensive spell system, and persistent state management—all in a free, open-source package designed specifically for LLM-powered gameplay.
Perfect For
- Solo D&D campaigns with AI DM
- Learning D&D mechanics
- Rapid prototyping encounters
- Text-based gameplay
- Integration with other AI tools
- Custom campaign management
Final Assessment
A groundbreaking proof-of-concept that demonstrates the viability of AI-powered D&D gameplay with full mechanical fidelity. The system successfully bridges the gap between narrative AI flexibility and crunchy D&D rules, opening new possibilities for tabletop RPG experiences.