ChatRPG

D&D 5e MCP Server for AI Dungeon Masters

A Model Context Protocol (MCP) server providing 30+ D&D 5e tools for LLM-powered tabletop gaming. Features real-time combat tracking, character persistence, ASCII art rendering, and a web client interface.

---

Features

• 30+ D&D 5e Tools - Character creation, combat encounters, spell tracking, dice rolling
• ASCII Art Output - Retro-style box drawing for immersive terminal/chat display
• Dual Transport - stdio for Claude Desktop, SSE for web client
• Real-time Sync - WebSocket broadcasting for encounter updates
• Persistent Storage - Characters and encounters saved to AppData
• Web Client - Browser-based interface with typing indicators

---

Quick Start

1. Build & Run

npm install
npm run build

# Run with stdio (for Claude Desktop)
npm start

# Run with SSE (for web client, port 3001)
node dist/index.js --sse

2. Configure Claude Desktop

Add to your Claude Desktop config:

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

{
  "mcpServers": {
    "chatrpg": {
      "command": "node",
      "args": ["C:\\path\\to\\ChatRPG\\dist\\index.js"]
    }
  }
}

3. Web Client

The web client connects to the SSE endpoint:

# Start server with SSE
node dist/index.js --sse

# Open web-client/index.html in browser

---

Available Tools

Character Management

Tool	Description
create_character	Full D&D 5e character creation with auto-calculated stats
get_character	Retrieve by ID/name, supports listing and filtering
update_character	Modify stats with before/after comparison
delete_character	Remove with cascade cleanup, batch support
level_up	Level progression with HP rolls, spell slots
take_rest	Short/long rest with hit dice and recovery
manage_spell_slots	Full/half/third casters, warlock pact magic
roll_check	Skill checks, saves, attacks, initiative

Combat System

Tool	Description
create_encounter	Initialize combat with participants and terrain
get_encounter	Retrieve state with verbosity levels
execute_action	Attack, dash, dodge, disengage, grapple, shove, cast
advance_turn	Turn management with condition ticking
end_encounter	Close with outcome tracking
roll_death_save	D&D 5e death save mechanics
manage_condition	Apply/remove conditions with duration
manage_encounter	Composite operations with state sync
render_battlefield	ASCII tactical map
modify_terrain	Hazards, obstacles, difficult terrain

Magic System

Tool	Description
manage_concentration	Concentration checks and tracking
manage_aura	Spirit Guardians, Paladin auras, etc.
use_scroll	Spell scroll mechanics
synthesize_spell	Improvised magic with Arcana checks

Spatial Mechanics

Tool	Description
measure_distance	Grid-based distance (5e rules)
calculate_aoe	Sphere, cone, line, cube, cylinder
check_line_of_sight	Obstacle detection
check_cover	Half, three-quarters, full cover
place_prop	Interactive battlefield objects
calculate_movement	Pathfinding with terrain

World & Session

Tool	Description
manage_location	Location graph for navigation
move_party	Travel between locations
manage_party	Party composition and roles
manage_inventory	Item management and equipping
manage_notes	Session notes with tagging
get_session_context	Comprehensive state snapshot

Dice

Tool	Description
roll_dice	Standard notation, advantage/disadvantage, batch rolls

---

Project Structure

ChatRPG/
├── src/
│   ├── index.ts           # MCP server (stdio + SSE transports)
│   ├── registry.ts        # Tool registration (30+ tools)
│   ├── types.ts           # Shared Zod schemas
│   ├── fuzzy-enum.ts      # Fuzzy enum matching
│   ├── websocket.ts       # Real-time broadcasting
│   └── modules/
│       ├── ascii-art.ts   # Box drawing, formatting
│       ├── characters.ts  # Character CRUD, leveling
│       ├── combat.ts      # Encounters, conditions, actions
│       ├── data.ts        # Locations, party, inventory, notes
│       ├── dice.ts        # Dice parsing and rolling
│       ├── magic.ts       # Spells, concentration, auras
│       └── spatial.ts     # Distance, AoE, movement
├── web-client/            # Browser-based interface
├── tests/                 # Vitest test suites
├── dist/                  # Compiled output
└── design docs/           # ADRs and documentation

---

Development

Commands

# Development with auto-rebuild
npm run dev

# Type check
npx tsc --noEmit

# Build
npm run build

# Run tests
npm test

# Run tests once
npm test -- --run

Adding a New Tool

1. Define Zod schema in src/modules/[module].ts
2. Write handler function
3. Export schema from module
4. Register in src/registry.ts
5. Add tests in tests/[module]/

Git Workflow

• main - Production-ready, auto-deploys to Railway
• development - Active development branch

---

Data Storage

Character and session data is stored in:

• Windows: %APPDATA%\rpg-lite-mcp\
• macOS/Linux: ~/.config/rpg-lite-mcp/

rpg-lite-mcp/
├── characters/     # Character JSON files
├── encounters/     # Active encounter state
├── locations/      # Location graph
├── party/          # Party composition
└── notes/          # Session notes

---

Example Usage

Ask Claude:

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

Response:

╔═══════════════════════ CHARACTER SHEET ════════════════════════╗
║                             Finn                                ║
║                  PC - Halfling Rogue (Level 5)                  ║
║                                                                 ║
║                   HP: [████████████████] 35/35                  ║
║                                                                 ║
║ ────────────────────────────────────────────────────────────── ║
║                                                                 ║
║ AC         │ Speed        │ Initiative   │ Prof Bonus          ║
║ 15         │ 25 ft        │ +4           │ +3                  ║
╚════════════════════════════════════════════════════════════════╝

Other commands:

• "Roll 4d6 drop lowest for ability scores"
• "Start a combat encounter with 3 goblins"
• "Cast fireball centered at position 5,5"
• "Move the party to the tavern"

---

Deployment

The server is deployed on Railway and auto-deploys from the main branch.

SSE Endpoint: https://chatrpg-production.up.railway.app/

---

Troubleshooting

Server Won't Start

1. Verify build: npm run build
2. Check path in config is absolute
3. Test manually: node dist/index.js

Tool Calls Failing

1. Rebuild: npm run build
2. Run tests: npm test -- --run
3. Check TypeScript: npx tsc --noEmit

Encoding Issues

If ASCII art displays as garbled text (e.g., ââ€â‚¬ instead of ─), ensure:

• Source files are UTF-8 encoded
• Terminal/client supports Unicode
• No double-encoding in transport layer

---

Architecture

MCP Protocol

• Transports: stdio, SSE (Server-Sent Events)
• Format: JSON-RPC 2.0
• Capabilities: Tools (30+)

Design Principles

1. ASCII Art First - All output uses box drawing for terminal aesthetics
2. Zod Validation - Strict input schemas with fuzzy enum matching
3. Stateful Persistence - JSON files in AppData
4. D&D 5e Accurate - SRD-compliant mechanics
5. Real-time Updates - WebSocket broadcasting for encounters

---

Contributing

This project follows TDD:

1. Write failing tests
2. Implement minimal code to pass
3. Refactor

PRs must:

• Include tests
• Pass TypeScript strict mode
• Follow existing patterns

---

License

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

---

Credits

• @modelcontextprotocol/sdk - MCP TypeScript SDK
• Zod - Schema validation
• Vitest - Testing framework
• D&D 5e SRD (System Reference Document)