A rules-enforced RPG backend that turns any LLM into a game master who can't cheat.
You are the player. The AI is the dungeon master.
You talk to an AI (Claude, GPT, etc.) in natural language. You say things like "I attack the goblin" or "I search the room for traps." The AI narrates what happens and describes the world.
The difference from pure AI storytelling: This engine enforces the rules. When you attack, it actually rolls dice, checks armor class, calculates damage, and updates HP in a real database. The AI can't just decide you hit or miss—the math happens, and both you and the AI see the result.
- Explore procedurally generated worlds with 28+ biome types
- Fight enemies using D&D 5e-style combat (initiative, AC, damage rolls, death saves)
- Cast spells with real slot tracking—if you're out of slots, you can't cast
- Manage inventory with equipment slots, weight, and item properties
- Complete quests with tracked objectives and rewards
- Interact with NPCs who remember your conversations across sessions
- Everything persists—close the game, come back tomorrow, your character is exactly where you left them
- Solo RPG players who want AI-driven adventures with mechanical integrity
- People frustrated with AI RPGs that fall apart when you ask "wait, how much HP do I have?"
- Developers building AI game integrations who need a reference implementation
- Install the MCP server (see Installation below)
- Connect it to Claude Desktop (or any MCP-compatible client)
- Tell the AI: "Let's start a new game. Create a character for me."
- Play naturally—the AI handles narration, the engine handles mechanics
This release consolidates 195 individual tools into 28 action-based tools plus 4 standalone meta/event tools using:
- Action enums - Each tool handles multiple operations via an
actionparameter - Fuzzy matching - Typo-tolerant action matching with suggestions
- Guiding errors - Clear feedback when actions don't match
Before: create_character, get_character, update_character, delete_character, list_characters...
After: character_manage with actions: create, get, update, delete, list, search
| Metric | Before | After | Change |
|---|---|---|---|
| MCP Tools | 195 | 32 | 83.6% reduction |
| Tests | 1,242 | 1,889 | +52% coverage |
| Token overhead | ~50K | ~6-8K | 85% reduction |
Four standalone tools support discovery and real-time events:
| Tool | Purpose |
|---|---|
search_tools |
Search tools by keyword, category, or capability |
load_tool_schema |
Load full parameter schema before first use |
subscribe_to_events |
Subscribe to PubSub event topics (combat, quest, etc.) |
unsubscribe_from_events |
Unsubscribe from event topics |
This engine implements the Event-Driven Agentic AI Architecture:
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ EVENT │
│ │ │
│ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌────────────┐ ┌───────────┐ ┌─────────┐ │
│ │ OBSERVE │ ──▶ │ ORIENT │ ──▶ │ DECIDE │ ──▶ │ ACT │ ──▶ │VALIDATE │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ MCP Read │ │ LLM Brain │ │Orchestrator│ │ MCP Write │ │ Engine │ │
│ │ Tools │ │ Analyze │ │ Plan │ │ Tools │ │ Rules │ │
│ └───────────┘ └───────────┘ └────────────┘ └───────────┘ └────┬────┘ │
│ ▲ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ WORLD STATE │
│ (updates & loops) │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────┘
| Biological System | RPG-MCP Component | Role |
|---|---|---|
| Brain | LLM Agent (external) | Strategic reasoning, planning, interpretation |
| Nervous System | Engine + Orchestrator | Validates intent, enforces constraints, routes actions |
| Reflex Arc | Constraint Validator | Blocks impossible actions before execution |
| Sensory Organs | Observation Tools | getObservation, queryEntities, getWorldSnapshot |
| Muscles | Action Tools | proposeAction, moveEntity, attack, interact |
| Environment | World State + Physics | SQLite-persisted, deterministic, forkable reality |
Key invariant: LLMs propose intentions. The engine validates and executes. LLMs never directly mutate world state.
| Tool | Actions | Description |
|---|---|---|
character_manage |
create, get, update, delete, list, search | Full character CRUD with D&D stat blocks |
party_manage |
create, get, update, delete, add_member, remove_member, set_leader, context | Party management and member operations |
| Tool | Actions | Description |
|---|---|---|
combat_manage |
create, get, end, load, advance, death_save, lair_action, add_participant, remove_participant | Encounter lifecycle and initiative |
combat_action |
attack, cast, move, dash, dodge, disengage, help, ready | Combat actions with full D&D 5e rules |
combat_map |
get_terrain, set_terrain, get_positions, calculate_aoe | Tactical grid and terrain management |
| Tool | Actions | Description |
|---|---|---|
item_manage |
create, get, update, delete, list, search | Item template CRUD |
inventory_manage |
give, remove, transfer, equip, unequip, use | Inventory operations between characters |
corpse_manage |
create, get, list, loot, harvest, advance_decay, cleanup | Death and loot mechanics |
theft_manage |
steal, check_stolen, check_recognition, report | Theft with heat tracking |
| Tool | Actions | Description |
|---|---|---|
world_manage |
generate, get, update, list, delete | Procedural world generation |
world_map |
get_overview, get_region, patch, preview | Map queries and modifications |
spatial_manage |
look, move, generate_room, get_exits, list_rooms | Dungeon navigation and room networks |
| Tool | Actions | Description |
|---|---|---|
quest_manage |
create, get, list, assign, complete, fail, abandon, add_objective, update_objective | Quest lifecycle management |
npc_manage |
get_relationship, update_relationship, record_memory, get_history, interact | NPC memory and social interactions |
aura_manage |
create, list, get_affecting, process, remove, expire | Area effects and buffs/debuffs |
| Tool | Actions | Description |
|---|---|---|
scroll_manage |
use, create, identify, get_dc, get_details | Scroll mechanics |
rest_manage |
long_rest, short_rest | HP and spell slot recovery |
concentration_manage |
check_save, break, get_state, check_duration | Spell concentration tracking |
| Tool | Actions | Description |
|---|---|---|
secret_manage |
create, get, list, update, delete, reveal, check_conditions | DM secrets with reveal conditions |
narrative_manage |
add, search, update, get, delete, get_context | Story notes and session history |
improvisation_manage |
resolve_stunt, apply_effect, get_effects, remove_effect, advance_duration, attempt_synthesis | Rule of Cool and custom effects |
math_manage |
dice_roll, probability, algebra, physics | Dice and calculations |
strategy_manage |
create_nation, get_state, propose_alliance, claim_region | Grand strategy simulation |
turn_manage |
init, get_status, submit_actions, mark_ready, poll_results | Async turn management |
spawn_manage |
spawn_character, spawn_location, spawn_encounter, spawn_preset_location, spawn_tactical | Entity and encounter spawning |
session_manage |
initialize_session, get_context | Session state management |
travel_manage |
travel, loot, rest | Party movement and field actions |
batch_manage |
create_characters, create_npcs, distribute_items, execute_workflow | Bulk operations |
npm install mnehmos.rpg.mcpDownload pre-built binaries from Releases:
# Windows
.\rpg-mcp-win.exe
# macOS (Intel)
chmod +x rpg-mcp-macos && ./rpg-mcp-macos
# macOS (Apple Silicon)
chmod +x rpg-mcp-macos-arm64 && ./rpg-mcp-macos-arm64
# Linux
chmod +x rpg-mcp-linux && ./rpg-mcp-linuxgit clone https://github.com/Mnehmos/rpg-mcp.git
cd rpg-mcp
npm install
npm run build
npm test # 1889 tests should passClaude Desktop / MCP Clients:
{
"mcpServers": {
"rpg-mcp": {
"command": "npx",
"args": ["-y", "mnehmos.rpg.mcp@1.0.2"]
}
}
}Security note: pin an explicit package version in args to avoid unintentionally running a newly published release.
Using Binary:
{
"mcpServers": {
"rpg-mcp": {
"command": "path/to/rpg-mcp-win.exe"
}
}
}- Initiative tracking with advantage/disadvantage
- Spatial combat with grid positioning and collision
- Opportunity attacks with reaction economy
- Death saving throws (D&D 5e rules)
- Damage resistance/vulnerability/immunity
- Legendary creatures with lair actions and legendary resistances
- Encounter presets - Pre-balanced encounters by party level
- 15+ SRD spells (Magic Missile, Fireball, Cure Wounds, etc.)
- Spell slot tracking with class-based progression
- Warlock pact magic with short rest recovery
- Concentration tracking
- Anti-hallucination validation - LLMs cannot cast spells they don't know
- Stolen item tracking with heat levels (burning → cold)
- Witness recording for theft detection
- Fence NPCs with buy rates and heat capacity
- Item recognition - original owners detect their stolen goods
- Relationship tracking (familiarity + disposition)
- Conversation memory with importance levels
- Context injection for LLM prompts
- Interaction history across sessions
- Rule of Cool stunts - "I kick the brazier into the zombies"
- Custom effects - Divine boons, curses, transformations
- Arcane synthesis - Dynamic spell creation with wild surge risk
src/
├── schema/ # Zod schemas: entities, actions, world state
├── engine/
│ ├── combat/ # Encounters, initiative, damage, death saves
│ ├── spatial/ # Grid, collision, movement
│ ├── worldgen/ # Procedural generation (28+ biomes)
│ └── strategy/ # Nation simulation
├── data/
│ ├── creature-presets.ts # 1100+ creature templates
│ ├── encounter-presets.ts # 50+ balanced encounters
│ └── items/ # PHB weapons, armor, magic items
├── storage/
│ ├── migrations.ts # SQLite schema definitions
│ └── repos/ # Repository pattern for persistence
├── server/
│ ├── consolidated/ # 28 action-based tools
│ ├── handlers/ # Extracted handler implementations (combat, spatial)
│ ├── consolidated-registry.ts # Tool registration
│ ├── meta-tools.ts # search_tools, load_tool_schema
│ └── events.ts # PubSub + MCP notification streaming
└── utils/
├── fuzzy-enum.ts # Action matching with typo tolerance
└── schema-shorthand.ts # Token-efficient parsing
tests/ # 1889 tests mirroring src/ structure
docs/ # White paper and LLM spatial guide
-
LLMs propose, never execute The brain suggests; the nervous system validates.
-
All action is tool-mediated No direct world mutation. Every change flows through MCP tools.
-
Validation precedes observation Act → Validate → Observe. The reflex arc pattern.
-
Deterministic outcomes Same inputs → same outputs. Always reproducible.
-
Schema-driven everything Zod validates all data at boundaries. Type safety end-to-end.
-
Anti-hallucination by design LLMs cannot cast spells they don't know or claim damage they didn't roll.
-
Token efficiency 28 consolidated tools with action routing reduce context overhead by 85%.
-
Guiding errors Invalid actions return suggestions, not just failures.
npm test
# 1889 tests passing, 6 skipped
# 85+ test files
# Coverage across all 32 tools (28 consolidated + 4 meta/event)Contributions welcome! Please:
- Fork the repo
- Create a feature branch (
git checkout -b feature/your-feature) - Write tests for new functionality
- Follow existing code style (TypeScript + Zod + tests)
- Submit a pull request
- Full spellcasting system with validation
- Theft and fence economy
- Corpse and loot mechanics
- NPC memory and relationships
- Improvisation engine
- Tool consolidation (195 → 32)
- Fuzzy action matching
- Preset systems (creatures, encounters, locations)
- WebSocket real-time subscriptions
- Dialogue tree system
- Cover mechanics in combat
- Quest chains with prerequisites
ISC — Use freely, attribution appreciated.
- Model Context Protocol Specification
- Quest Keeper AI — Desktop AI dungeon master using this engine
- CLAUDE.md - Development instructions
- docs/WHITE_PAPER.md - Design philosophy and architecture
- docs/LLMSpatialGuide.md - LLM spatial navigation guide
- docs/ADR-005-unified-ownership-architecture.md - Target ownership architecture
- docs/EXECUTION-PRIORITIES-unified-ownership.md - Outcome-based execution priorities
"AI-native autonomic organisms capable of maintaining and improving themselves in complex environments"