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

Combat System

Magic System

Spatial Mechanics

World & Session

Dice

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)