rpg-mcp

Subscribe to real-time events on world or combat topics. Events sent as JSON-RPC notifications.

Unsubscribe from all event topics

Search for available RPG tools by category, capability, or keyword. Use this to discover tools before using them.

Load the full input schema for a specific tool (required before first use). Returns parameter definitions, types, and usage info.

Generate a new procedural RPG world with seed, width, and height parameters. Example: { "seed": "atlas", "width": 50, "height": 50 }

Retrieves the current state of the generated world.

Apply DSL commands to modify the world map. Use find_valid_poi_location first for structure placement. Example: { "worldId": "id", "script": "ADD_STRUCTURE..." }

Returns a high-level overview of the world including biome distribution and statistics.

Returns detailed information about a specific region including its tiles and structures.

Returns the full tile grid for rendering the world map. Includes biome, elevation, region, and river data for visualization.

Previews what a DSL patch script would do without applying it to the world.

Find terrain-valid locations for placing a POI/structure. Returns ranked candidates by suitability.

Batch suggest locations for multiple POI types at once. Returns DSL script for easy application.

Create a combat encounter with positioned combatants and terrain.

📋 WORKFLOW:

1. Generate terrain (obstacles, water, difficult)

2. Add props (buildings, trees, cover)

3. Place party (safe starting positions)

4. Place enemies (tactical positions)

⚠️ CRITICAL VERTICALITY RULES:

• z=0 means "standing on surface at (x,y)" - EVEN ON TOP OF OBSTACLES

• If obstacles exist at (15,3), placing a unit at {x:15,y:3,z:0} = STANDING ON the obstacle

• z>0 = FLYING/LEVITATING only. Creatures without flight condition WILL FALL!

• Do NOT use z values to represent "standing on high ground"

✅ CORRECT: Goblin on rock at (15,3) → position: {x:15, y:3, z:0} ❌ WRONG: Goblin on rock → position: {x:15, y:3, z:25} (will fall!)

🏔️ TERRAIN GENERATION RULES:

• Obstacles should CLUSTER to form hills/mountains/caverns

• Include SLOPES: Adjacent tiles stepping down to ground level

• Isolated cliffs only if intentionally inaccessible

• Water must CONNECT (rivers/streams/pools), never isolated tiles

📐 PATTERN TEMPLATES (USE THESE!):

RIVER VALLEY (cliffs on sides, river in middle): obstacles: ["5,0","5,1","5,2",...,"5,19"] (west cliff), ["13,0","13,1","13,2",...,"13,19"] (east cliff) water: ["8,0","9,0","10,0","8,1","9,1","10,1",...] (3-wide river at x=8,9,10)

CANYON (two parallel walls): obstacles: ["0,5","1,5","2,5",...,"9,5"] (north wall), ["0,15","1,15","2,15",...,"9,15"] (south wall)

Example: { "seed": "battle-1", "terrain": { "obstacles": ["10,5", "11,5", "10,6"], "water": ["5,10", "5,11", "6,11"] }, "participants": [ {"id": "hero-1", "name": "Valeros", "hp": 20, "maxHp": 20, "initiativeBonus": 2, "position": {"x": 15, "y": 15, "z": 0}}, {"id": "goblin-1", "name": "Goblin Archer", "hp": 7, "maxHp": 7, "initiativeBonus": 1, "position": {"x": 10, "y": 5, "z": 0}, "isEnemy": true} ] }

Get the current state of the active combat encounter.

Execute a combat action (attack, heal, move, cast_spell, etc.).

Examples: { "action": "attack", "actorId": "hero-1", "targetId": "goblin-1", "attackBonus": 5, "dc": 12, "damage": 6 }

{ "action": "heal", "actorId": "cleric-1", "targetId": "hero-1", "amount": 8 }

{ "action": "move", "actorId": "hero-1", "targetPosition": { "x": 5, "y": 3 } }

{ "action": "disengage", "actorId": "hero-1" }

{ "action": "cast_spell", "actorId": "wizard-1", "spellName": "Fireball", "targetId": "goblin-1", "slotLevel": 3 }

Advance to the next combatant's turn.

End the current combat encounter.

Load a combat encounter from the database.

Roll a d20 death saving throw for a character at 0 HP. 10+ success, nat 20 regains 1 HP, nat 1 counts as 2 failures.

Execute a lair action at initiative 20 when isLairActionPending is true. Apply environmental effects to targets.

Render an ASCII map of the current combat state showing participant positions, obstacles, and terrain. Returns a text-based grid visualization with:

• A-Z for friendly participants

• 1-9 for enemies

• █ for obstacles

• ░ for difficult terrain

• ☠ for defeated combatants

Example: { "encounterId": "encounter-battle-1-123456", "width": 15, "height": 15 }

Calculate which tiles and participants are affected by an Area of Effect spell or ability. Supports circle (Fireball), cone (Burning Hands), and line (Lightning Bolt) shapes.

Example - Fireball (20ft radius circle): { "encounterId": "encounter-1", "shape": "circle", "origin": { "x": 10, "y": 10 }, "radius": 4 }

Example - Burning Hands (15ft cone): { "encounterId": "encounter-1", "shape": "cone", "origin": { "x": 5, "y": 5 }, "direction": { "x": 1, "y": 0 }, "length": 3, "angle": 90 }

Example - Lightning Bolt (100ft line): { "encounterId": "encounter-1", "shape": "line", "origin": { "x": 0, "y": 5 }, "direction": { "x": 1, "y": 0 }, "length": 20 }

Add, remove, or modify terrain in an active encounter. ALWAYS prefer ranges over tiles arrays for efficiency.

TERRAIN TYPES:

• obstacles: Blocking terrain (walls, rocks, fallen trees)

• difficultTerrain: Half-speed terrain (mud, rubble, underbrush)

• water: Watery terrain (streams, rivers, pools)

INPUT OPTIONS (use ranges for efficiency):

1. ranges: Array of range shortcuts (PREFERRED - saves tokens)

2. tiles: Array of "x,y" strings (only for specific scattered tiles)

RANGE SHORTCUTS (use these!):

LINES:

• "x=N" - vertical line at x=N (full height)

• "x=N:y1:y2" - vertical line segment

• "y=N" - horizontal line at y=N (full width)

• "y=N:x1:x2" - horizontal line segment

• "line:x1,y1,x2,y2" - diagonal/any line from point to point (Bresenham)

• "hline:y:x1:x2" - horizontal line

• "vline:x:y1:y2" - vertical line

• "row:N" / "col:N" - aliases for y=N / x=N

SHAPES:

• "rect:x,y,w,h" - filled rectangle

• "box:x,y,w,h" - hollow rectangle (border only)

• "border:margin" - outer border of grid (margin=0 for edge)

• "fill:x1,y1,x2,y2" - fill between two corners

• "circle:cx,cy,r" - filled circle

• "ring:cx,cy,r" - hollow circle

ALGEBRA (for curves, diagonals):

• "y=x:0:99" - diagonal line (y equals x)

• "y=2*x+5:0:50" - any linear equation

• "y=x/2:0:99" - half-speed diagonal

• "expr:EQUATION:xMin:xMax" - explicit expression format

EXAMPLES:

Maze outer walls (1 call vs 4): { "ranges": ["border:0"], "gridWidth": 100, "gridHeight": 100 }

Complex maze section: { "ranges": ["y=10:0:50", "x=25:10:40", "line:50,50,75,25", "box:60,60,15,15"] }

Diagonal river: { "terrainType": "water", "ranges": ["y=x:0:99"] }

Circular arena: { "ranges": ["ring:50,50,40", "border:0"] }

Place an improvised prop/object on the battlefield during combat.

Props are free-form terrain features with rich description that can be interacted with. Think: ladders, wagons, trees, buildings, towers, cliffs, chandeliers, etc.

⚠️ HEIGHT SEMANTICS (CRITICAL):

• heightFeet describes the PROP'S visual/physical height, NOT entity position

• A 30ft cliff at (5,5) is visually tall

• Entities standing ON such a prop use position (5,5, z=0), NOT z=30!

• The terrain height is implicit in the visualization

🏗️ PROP TYPES:

• cliff: Stacked rocky terrain with slopes

• wall: Stone/brick barriers

• bridge: Spanning structures over gaps

• tree: Vegetation cover

• stairs: Stepped access to elevation

• pit: Below-ground areas (negative Y)

Cover Types (D&D 5e):

• half: +2 AC (waist-high wall, thick furniture)

• three_quarter: +5 AC (arrow slit, portcullis)

• full: Total cover (complete obstruction)

Example - Climbable cliff with slopes adjacent: { "encounterId": "encounter-1", "position": "15,20", "label": "Rocky Cliff", "propType": "structure", "heightFeet": 25, "cover": "half", "climbable": true, "climbDC": 12, "description": "A 25ft rocky outcrop. Adjacent tiles (14,20), (16,20) slope down." }

Calculate the distance between two points or entities on the battlefield. Returns distance in feet (5ft per square, diagonal = 5ft using D&D simplified rules).

Example - Between two coordinates: { "encounterId": "encounter-1", "from": { "type": "position", "value": "10,10" }, "to": { "type": "position", "value": "15,18" } }

Example - Between two entities: { "encounterId": "encounter-1", "from": { "type": "entity", "value": "hero-1" }, "to": { "type": "entity", "value": "goblin-3" } }

Example - From entity to position: { "encounterId": "encounter-1", "from": { "type": "entity", "value": "wizard-1" }, "to": { "type": "position", "value": "25,30" } }

Generate a terrain patch using procedural noise or preset patterns. Much easier than placing individual tiles - LLM describes the area and this tool generates it.

Biome Presets:

• forest: Trees (climbable props), undergrowth (difficult terrain), paths

• cave: Rocky walls (obstacles), stalactites (props), pools (water)

• village: Buildings (obstacle clusters), roads (clear), market stalls (props)

• dungeon: Walls (obstacles), rubble (difficult), traps (hazards)

• swamp: Water, lily pads (props), dead trees, difficult terrain

• battlefield: Barricades, craters (difficult), debris (props)

Density: 0.1 (sparse) to 1.0 (dense)

Example - Generate a forest clearing: { "encounterId": "encounter-1", "biome": "forest", "origin": { "x": 10, "y": 10 }, "width": 20, "height": 20, "density": 0.4, "seed": "goblin-ambush", "clearCenter": true }

Example - Dungeon room: { "encounterId": "encounter-1", "biome": "dungeon", "origin": { "x": 0, "y": 0 }, "width": 15, "height": 12, "density": 0.6, "seed": "throne-room" }

Generate terrain using a pattern template. ONE CALL generates entire layout.

PATTERNS:

• maze: Full procedural maze (corridors & walls) - USE THIS FOR MAZES

• maze_rooms: Maze with open chambers/rooms connected by corridors

• river_valley: Cliff walls on east/west with river in center

• canyon: Parallel walls east-west with pass between

• arena: Circular wall enclosing fighting area

• mountain_pass: Narrowing corridor toward center

MAZE EXAMPLE (100x100 in ONE call): { "encounterId": "enc-1", "pattern": "maze", "origin": { "x": 0, "y": 0 }, "width": 100, "height": 100, "seed": "maze-runner-001" }

MAZE WITH ROOMS: { "pattern": "maze_rooms", "width": 100, "height": 100, "roomCount": 8 }

Create a new world in the database with name, seed, and dimensions. Example: { "name": "New World", "seed": "abc", "width": 50, "height": 50 }

Retrieve a world by ID.

List all worlds.

Update environmental properties (time, weather, lighting, etc.) for a world.

Delete a world by ID.

Create a new character. Only name is required - everything else has sensible defaults.

Character types:

• pc: Player character (default)

• npc: Non-player character (ally or neutral)

• enemy: Hostile creature

• neutral: Non-hostile, non-ally

Class and race can be ANY string - use standard D&D classes/races or create custom ones. Stats can be any positive integer (not limited to 3-18).

Example (minimal - just name): { "name": "Mysterious Stranger" }

Example (full): { "name": "Valeros", "class": "Fighter", "race": "Human", "hp": 20, "maxHp": 20, "ac": 18, "level": 1, "stats": { "str": 16, "dex": 14, "con": 14, "int": 10, "wis": 12, "cha": 10 }, "characterType": "pc" }

Example (custom class/race): { "name": "Whiskers", "class": "Chronomancer", "race": "Mousefolk", "stats": { "str": 6, "dex": 18, "con": 10, "int": 16, "wis": 14, "cha": 12 } }

Retrieve a character by ID.

Update character properties. All fields except id are optional.

For conditions, you can pass an array to SET all conditions (replacing existing), or use addConditions/removeConditions for granular control.

List all characters, optionally filtered by type (pc, npc, enemy, neutral).

Delete a character by ID.

Add experience points to a character. Checks for level-up thresholds.

Get level progression details including XP needed for next level.

Increment character level and optionally update stats like HP.

Create a typed narrative note (plot thread, canonical moment, NPC voice, foreshadowing, or session log). Used to build long-term narrative memory.

Search and filter narrative notes by type, status, tags, or text content. Returns matching notes for context building.

Update an existing narrative note. Common use: marking a plot_thread as resolved.

Retrieve a single narrative note by ID.

Delete a narrative note. Use sparingly - prefer archiving via status update.

Retrieve aggregated narrative context for LLM prompt injection. Returns active plot threads, recent canonical moments, NPC voices, and pending foreshadowing.

Create a new party (adventuring group).

Example: { "name": "The Fellowship", "description": "Nine companions on a quest to destroy the One Ring", "worldId": "middle-earth-id", "initialMembers": [ { "characterId": "gandalf-id", "role": "leader" }, { "characterId": "frodo-id", "role": "member" } ] }

Get a party with all member details, leader, and active character info.

List all parties, optionally filtered by status or world.

Update party properties (name, description, location, formation, status).

Delete a party. Members become unassigned (not deleted).

Add a character to a party with role (leader, member, companion, hireling, prisoner, mount).

Remove a character from a party.

Update a party member's role, position, or notes.

Set the party leader. The character must already be a member.

Set the active character (player's POV). The character must already be a member.

Get all members of a party with their character details.

Get party context for LLM prompts. Verbosity: minimal (~150 tokens), standard (~400), or detailed (~800).

Get characters not assigned to any party. Useful for adding members.

Move a party to world map coordinates or POI. Updates location name and optional POI reference.

Get the current position of a party on the world map.

Get all parties within a certain distance of a coordinate (useful for finding nearby groups).

Define a new type of item (e.g., "Iron Sword").

Add an item to a character's inventory.

Remove an item from a character's inventory.

Equip an item in a specific slot.

Unequip an item.

List all items in a character's inventory.

Get details of a specific item by ID.

List all item templates in the database.

Search for items by name, type, or value range.

Update an existing item template.

Delete an item template from the database.

Transfer an item from one character to another.

Use a consumable item (removes it from inventory and applies effects).

Get detailed inventory with full item info, sorted by equipped/type/name.

Define a new quest in the world.

Get a single quest by ID with full details.

List all quests, optionally filtered by world.

Assign a quest to a character.

Update progress on a quest objective.

Mark an objective as fully completed.

Mark a quest as completed and grant rewards.

Get the quest log for a character.

Roll dice using standard notation. Supports: basic rolls (2d6+3), drop lowest (4d6dl1), drop highest (4d6dh1), keep lowest (2d20kl1), keep highest (2d20kh1), advantage/disadvantage, and exploding dice (2d6!).

Calculate probabilities for dice rolls, including distributions and expected values.

Solve algebraic equations.

Simplify algebraic expressions.

Calculate projectile motion trajectory.

Create a new nation in the world.

Get the world state from the perspective of a specific nation (applies Fog of War for Grand Strategy).

Get private state for a specific nation (LLM only).

Propose an alliance to another nation.

Assert a territorial claim on a region.

Process a full turn cycle (economy, conflicts, etc.).

Initialize turn management for a world (call once per world)

Check current turn state and which nations are ready

Submit actions for this turn (batched)

Signal that your nation is done planning for this turn