Complete tabletop RPG game engine via MCP - D&D 5e combat, procedural worldgen, NPC memory, 28 consolidated tools
npm install mnehmos.rpg.mcpaction parameter
create_character, get_character, update_character, delete_character, list_characters...
character_manage with actions: create, get, update, delete, list, search
search_tools | Search tools by keyword, category, or capability |
load_tool_schema | Load full parameter schema before first use |
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ EVENT │
│ │ │
│ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌────────────┐ ┌───────────┐ ┌─────────┐ │
│ │ OBSERVE │ ──▶ │ ORIENT │ ──▶ │ DECIDE │ ──▶ │ ACT │ ──▶ │VALIDATE │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ MCP Read │ │ LLM Brain │ │Orchestrator│ │ MCP Write │ │ Engine │ │
│ │ Tools │ │ Analyze │ │ Plan │ │ Tools │ │ Rules │ │
│ └───────────┘ └───────────┘ └────────────┘ └───────────┘ └────┬────┘ │
│ ▲ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ WORLD STATE │
│ (updates & loops) │
│ │
└─────────────────────────────────────────────────────────────────────────────────────────┘
`
$3
| 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.
---
Consolidated Tools Reference (28 Tools)
$3
| 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 |
$3
| 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 |
$3
| 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 |
$3
| 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 |
$3
| 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 |
$3
| 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 |
$3
| 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 |
---
Installation
$3
`bash
npm install mnehmos.rpg.mcp
`
$3
Download pre-built binaries from Releases:
`bash
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-linux
`
$3
`bash
git clone https://github.com/Mnehmos/rpg-mcp.git
cd rpg-mcp
npm install
npm run build
npm test # 2080+ tests should pass
`
$3
Claude Desktop / MCP Clients:
`json
{
"mcpServers": {
"rpg-mcp": {
"command": "npx",
"args": ["-y", "mnehmos.rpg.mcp@1.0.2"]
}
}
}
`Security note: pin an explicit package version in
to avoid unintentionally running a newly published release.Using Binary:
`json
{
"mcpServers": {
"rpg-mcp": {
"command": "path/to/rpg-mcp-win.exe"
}
}
}
`
---
Core Systems
$3
- 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
$3
- 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
$3
- 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
$3
- Relationship tracking (familiarity + disposition)
- Conversation memory with importance levels
- Context injection for LLM prompts
- Interaction history across sessions
$3
- 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
`
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
│ ├── consolidated-registry.ts # Tool registration
│ └── meta-tools.ts # search_tools, load_tool_schema
└── utils/
├── fuzzy-enum.ts # Action matching with typo tolerance
└── schema-shorthand.ts # Token-efficient parsing
tests/ # 2080+ tests mirroring src/ structure
docs/ # White paper and LLM spatial guide
`
---
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. Deterministic outcomes
Same inputs → same outputs. Always reproducible.
5. Schema-driven everything
Zod validates all data at boundaries. Type safety end-to-end.
6. Anti-hallucination by design
LLMs cannot cast spells they don't know or claim damage they didn't roll.
7. Token efficiency
28 consolidated tools with action routing reduce context overhead by 85%.
8. Guiding errors
Invalid actions return suggestions, not just failures.
---
Test Coverage
`bash
npm test
2080+ tests passing
85+ test files
Coverage across all 28 consolidated tools
`
---
Contributing
Contributions welcome! Please:
1. Fork the repo
2. Create a feature branch (git checkout -b feature/your-feature`)
"AI-native autonomic organisms capable of maintaining and improving themselves in complex environments"