D&D 5.5 Character Generator

A comprehensive D&D 5.5 character generator with homebrew content support.

Built with React, TypeScript, Express, and Vite as an npm workspaces monorepo.

Architecture

dnd-character-generator/
├── backend/          # Express API server (port 3001)
├── frontend/         # Vite + React SPA (port 3000)
├── shared/           # Shared TypeScript types, constants, utils
├── docker-compose.yml
├── Dockerfile        # Single container: nginx (frontend) + supervisord (backend)
├── docker-nginx.conf
└── docker-supervisord.conf

• Production: Single Docker container. Nginx serves the built frontend; supervisord manages Nginx + the Express backend.
• Development: npm run dev starts both backend (ts-node-dev) and frontend (Vite dev server) concurrently. Vite proxies /api to localhost:3001.

Quick Start

npm install          # installs all workspaces (backend, frontend, shared)
npm run dev          # starts backend + frontend concurrently

• Frontend: http://localhost:3000
• Backend: http://localhost:3001

Testing

# Backend (Jest)
cd backend && npm test

# Frontend (Vitest)
cd frontend && npm test

Deployment

docker compose up -d --build

Environment is configured via docker-supervisord.conf (production) or backend/.env (development).

Find your default login with Owner permissions with this command: sudo docker compose exec dndgen-test cat /var/log/backend.log | grep -A4 "DEFAULT OWNER ACCOUNT"

!! This will appear only once so save it !!

API

All routes are under /api. See backend/src/routes/ for the full route tree. Key groups:

• /api/dnd/* — Proxy to D&D 5.5 API (now using MCP server by default)
• /api/mcp/* — MCP server integration endpoints
• /api/homebrew/* — Custom homebrew CRUD
• /api/characters/* — Character management
• /api/combined/* — Merged official + homebrew data
• /api/parties/* / /api/party/inventory/* — Party management
• /api/settings — App settings
• /api/auth/* — Login, register, OAuth
• /api/users/* / /api/roles/* — User and role administration

MCP Integration (Issue #4)

The D&D Character Generator now includes a Model Context Protocol (MCP) server integration that enables:

• Parallel querying of multiple D&D data sources simultaneously
• Source redundancy with automatic fallback to alternative APIs
• Unified data access through a single architecture
• Performance optimization through caching and parallel requests

Key Features:

• ✅ Multiple Source Support: Queries dnd5eapi.co, open5e.com, and legacy APIs in parallel
• ✅ Automatic Fallback: Transparently falls back to direct API calls if MCP fails
• ✅ Source Priority: Prioritizes official WotC data over community sources
• ✅ Caching: Dual-layer caching (MCP server + backend) for optimal performance
• ✅ Source Attribution: All data includes _source field for transparency
• ✅ 100% Backward Compatible: Existing /api/dnd/* endpoints work unchanged

MCP Endpoints:

• GET /api/mcp/config — Get MCP configuration and server endpoint
• GET /api/mcp/status — Check MCP service status
• GET /api/mcp/sources — List all configured D&D data sources
• GET /api/mcp/sources/health — Check health of D&D data sources
• POST /api/mcp/cache/clear — Clear MCP server cache

Configuration:

MCP can be configured through environment variables:

# Enable/disable MCP
MCP_DATA_ENABLED=true

# Fallback to direct API if MCP fails
MCP_FALLBACK_TO_DIRECT=true

# MCP-specific caching
MCP_CACHE_ENABLED=true
MCP_CACHE_TTL=3600

In Docker, the MCP server is automatically included and configured in docker-compose.yml.