RPG-MCP: Agentic Embodied Simulation Kernel

A rules-enforced RPG backend that turns any LLM into a game master who can't cheat.

What Is This? (Start Here)

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.

What can you actually do?

• 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

Who is this for?

• 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

How do I play?

1. Install the MCP server (see Installation below)

2. Connect it to Claude Desktop (or any MCP-compatible client)

3. Tell the AI: "Let's start a new game. Create a character for me."

4. Play naturally—the AI handles narration, the engine handles mechanics

For Developers

RPG-MCP is a world kernel—the physics, constraints, persistence, and deterministic execution layer that allows LLM agents to inhabit a simulated reality with real bodies, real limits, and real consequences.

What's New (December 2025)

Latest Release

• 145+ MCP Tools - Complete RPG mechanics coverage with new composite tools

• 800+ Passing Tests - Comprehensive test coverage across all systems

• Composite Tools (TIER 1) - Reduce token overhead by 80-95% for common workflows

• Preset Systems - 1100+ creature presets, 50+ encounter presets, 30+ location presets

• Schema Shorthand (TIER 2) - Token-efficient position/stats parsing

• Batch Repository Methods - Optimized for world generation workflows

• Location Presets - Tavern, dungeon, temple, market presets with full population

• Encounter Presets - Level-scaled encounters (goblin ambush, undead crypt, dragon's lair)

Core Systems

• Full Spellcasting System - 15+ SRD spells, class progression, slot tracking

• Theft & Fence System - Heat decay, witness tracking, black market economy

• Corpse & Loot System - Decay states, harvestable resources, loot tables

• NPC Memory System - Relationship tracking, conversation history, context injection

• Improvisation Engine - Rule of Cool stunts, custom effects, arcane synthesis

• Legendary Creatures - Lair actions, legendary resistances, boss mechanics

• Death Saving Throws - Full D&D 5e rules with stabilization

• Spatial Navigation - Room networks, terrain-aware POI placement

• Narrative Memory Layer - Session notes, plot threads, NPC voices, foreshadowing

• Currency System - Gold/silver/copper with auto-conversion

Architecture Philosophy

This engine implements the Event-Driven Agentic AI Architecture:

The Embodiment Model

Key invariant: LLMs propose intentions. The engine validates and executes. LLMs never directly mutate world state.

Features

Core Systems

Multi-tenant & Multi-world

• Isolated projects (projectId) and parallel worlds (worldId)

• Fork worlds for branching timelines or "what-if" simulations

Embodied Entities

• Position, velocity, orientation in 3D space

• Stats, inventories, status effects, controller links

• Sensory radius, line-of-sight, perception limits

Intent-Based Actions

• Agents submit intentions: MOVE_TO, ATTACK, CAST_SPELL, INTERACT

• Engine validates against physics, rules, and constraints

• Invalid actions rejected with structured feedback

Deterministic Physics

• Collision detection, projectile trajectories, movement costs

• Reproducible world steps—same inputs always yield same outputs

• Full audit trail: snapshots, event logs, action history

Combat & Encounters

• 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

Magic System

• 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

• Rest mechanics restore spell slots and HP

Theft & Economy

• 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

• Heat decay over time

Corpse & Loot

• Corpse creation on creature death

• Loot tables with guaranteed and random drops

• Harvestable resources (pelts, fangs, etc.)

• Decay system (fresh → decaying → skeletal → gone)

NPC Memory

• Relationship tracking (familiarity + disposition)

• Conversation memory with importance levels

• Context injection for LLM prompts

• Interaction history across sessions

Improvisation Engine

• 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

Project Structure

Installation

Option 1: Standalone Binaries (Recommended)

Download the pre-built binary for your platform from the Releases page:

Windows:

macOS (Intel):

macOS (Apple Silicon - M1/M2/M3/M4):

Linux:

The binaries are self-contained and include all dependencies. No Node.js installation needed.

Option 2: From Source

To build binaries yourself:

MCP Client Configuration

To use with an MCP-compatible client (Claude Desktop, etc.), add to your client's configuration:

Using Binary:

Using Source:

MCP Tools Reference (135 Tools)

World Management (12 tools)

POI Location Tools (2 tools)

Character Management (5 tools)

Inventory & Items (15 tools)

Combat & Encounters (7 tools)

Spellcasting (integrated with combat)

Rest System (2 tools)

Theft & Fence System (10 tools)

Corpse & Loot System (14 tools)

NPC Memory System (7 tools)

Improvisation System (8 tools)

Quest System (8 tools)

Secrets System (9 tools)

Party System (17 tools)

Spatial Navigation (4 tools)

Math & Dice (5 tools)

Grand Strategy (11 tools)

Use Cases

Tabletop RPG Backend Run D&D, Pathfinder, or custom systems with AI dungeon masters and NPCs that have real bodies and spatial reasoning.

Multi-Agent Simulation Test agent coordination, emergent behavior, or adversarial scenarios in a controlled, reproducible environment.

Embodied AI Research Study how LLMs behave when constrained by physics, resources, and perception limits—not just text.

Game Development Use as a headless game server with deterministic state, replay capability, and clean API boundaries.

Training Data Generation Fork worlds, run thousands of parallel scenarios, collect structured action/outcome pairs.

Design Principles

1. LLMs propose, never execute The brain suggests; the nervous system validates.

2. All action is tool-mediated No direct world mutation. Every change flows through MCP tools.

3. Validation precedes observation Act → Validate → Observe. The reflex arc pattern.

4. Events trigger tasks JIT execution. No polling, no stale state.

5. Deterministic outcomes Same inputs → same outputs. Always reproducible.

6. Schema-driven everything Zod validates all data at boundaries. Type safety end-to-end.

7. Anti-hallucination by design LLMs cannot cast spells they don't know or claim damage they didn't roll.

8. Token efficiency Composite tools and schema shorthand reduce LLM context overhead.

Test Coverage

Key test areas:

• Combat encounters and HP persistence

• Spellcasting validation (anti-hallucination)

• Inventory integrity and exploit prevention

• Theft/fence mechanics with heat decay

• Corpse/loot system with decay states

• NPC memory and relationship tracking

• Improvisation system (stunts, effects, synthesis)

• Composite tool workflows

• Preset system expansion and validation

Contributing

Contributions welcome! Please:

1. Fork the repo

2. Create a feature branch (git checkout -b feature/your-feature)

3. Write tests for new functionality

4. Follow existing code style (TypeScript + Zod + tests)

5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

Roadmap

• Full spellcasting system with validation

• Theft and fence economy

• Corpse and loot mechanics

• NPC memory and relationships

• Improvisation engine

• Composite tools (TIER 1)

• Preset systems (creatures, encounters, locations)

• Narrative memory layer

• WebSocket real-time subscriptions

• Dialogue tree system

• Cover mechanics in combat

• Quest chains with prerequisites

• Visual debugger / world inspector UI

License

ISC — Use freely, attribution appreciated.

Related

• Model Context Protocol Specification

• Quest Keeper AI — Desktop AI dungeon master using this engine

Documentation

• CLAUDE.md - Development instructions

• docs/WHITE_PAPER.md - Design philosophy and architecture

• docs/LLMSpatialGuide.md - LLM spatial navigation guide