ChatRPG

Lightweight D&D 5e LLM-as-DM Engine A Model Context Protocol (MCP) server providing 50 core D&D 5e tools for AI Dungeon Masters.

Quick Start

1. Build the Server

2. Test the Server

3. Register with Claude Desktop

Add this configuration to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Important: Replace the path with your actual installation directory!

4. Restart Claude Desktop

The server will auto-start when Claude Desktop launches.

Available Tools (9/50)

Combat Module (4)

• ✅ roll_dice - Standard dice notation with modifiers (2d6+3, 4d6kh3)

• ✅ manage_condition - Apply/remove D&D 5e conditions with duration tracking

• ✅ create_encounter - Initialize combat encounters with participants and terrain

• ✅ execute_action - Execute combat actions (attack, dash, disengage, dodge, grapple, shove) including opportunity attacks

Characters Module (4)

• ✅ create_character - Full D&D 5e character creation with auto-calculated stats

• ✅ get_character - Retrieve character by ID with rich formatting

• ✅ update_character - Update character stats, HP, level, equipment with before/after comparison

• ✅ roll_check - Perform skill checks, saving throws, and ability checks

Spatial Module (1)

• ✅ measure_distance - Grid-based distance calculation (5e rules)

Testing

Current Status: 250/250 tests passing across 12 test files

Project Structure

Development

Watch Mode (Auto-rebuild)

Adding a New Tool

1. Define Schema in src/modules/[module].ts

2. Write Tests in tests/[module]/[tool].test.ts (TDD: Red phase)

3. Implement Handler (Green phase)

4. Register Tool in src/registry.ts

5. Verify with npm test -- --run

Git Workflow

This project acts as a Lite Gitflow repository:

• main: Stable, production-ready code. Only checked-out for release.

• development: Active development branch. All features merged here first.

Architecture

MCP Protocol

• Transport: stdio (standard input/output)

• Format: JSON-RPC 2.0

• Capabilities: Tools only (no resources/prompts yet)

Tool Design Principles

1. Immersive ASCII Art - All responses use box drawing for a retro-game aesthetic

2. Zod Validation - Every tool has strict input schema validation

3. Stateful Persistence - Characters/encounters saved to ./data/

4. D&D 5e Accurate - Proficiency bonuses, hit dice, grid mechanics all SRD-compliant

5. Terminal-First - Monospace-optimized, works in any CLI/chat interface

Example Usage

Once registered with Claude Desktop, you can ask:

"Create a level 5 halfling rogue named Finn with high dexterity"

Claude will call create_character and return:

Try other commands:

• "Roll 2d6+3 for damage"

• "Measure distance from (0,0) to (5,8)"

• "Add the blinded condition to goblin-1 for 3 rounds"

Roadmap

Tier 1: Foundation (In Progress)

• roll_dice

• create_character, get_character, update_character

• manage_condition

• measure_distance

• list_characters

• create_encounter, execute_action(Phases 1-2), apply_damage(merged)

Tier 2: Combat Support

• advance_turn, render_battlefield

• roll_check

• resolve_attack (merged into execute_action)

• roll_death_save

Tier 3: Advanced Features

• Magic system (spell slots, concentration)

• Spatial mechanics (AoE, line of sight, cover)

• Session management (notes, locations, party)

See TOOLS_CHECKLIST.md for full implementation status.

Troubleshooting

Server Won't Start in Claude Desktop

1. Check the path in claude_desktop_config.json is absolute and correct

2. Verify build with npm run build

3. Test manually with node dist/index.js (should print "RPG-Lite MCP Server running on stdio")

4. Check Claude logs (usually in %APPDATA%\Claude\logs on Windows)

Tool Calls Failing

1. Rebuild with npm run build

2. Check test suite with npm test -- --run

3. Verify data directory exists: mkdir -p data/characters

Contributing

This project follows strict TDD protocol:

1. Red: Write failing tests first

2. Green: Implement minimal code to pass

3. Refactor: Clean up and optimize

All PRs must:

• Include tests for new functionality

• Maintain 100% test pass rate

• Pass TypeScript strict mode compilation

• Follow existing code structure

License

Proprietary - See LICENSE for details. Personal, non-commercial use permitted.

Credits

Built with:

• @modelcontextprotocol/sdk - MCP TypeScript SDK

• Zod - Schema validation

• Vitest - Testing framework

• D&D 5e SRD (System Reference Document)

Status: Alpha - 9/50 tools operational | TDD-driven development | 250/250 tests passing