aibozo/dnd-mcp

D&D DM Agent MCP Server - Phase 0

A Model Context Protocol (MCP) server for managing D&D 5e game mechanics, character data, and providing DM assistance through structured tools and APIs.

Description

This project implements Phase 0 (Foundational Mechanics) of the D&D DM MCP Server, focusing on basic CRUD operations for character management, dice rolling mechanics, and combat engine fundamentals. The server provides a CLI interface for game masters to manage their campaigns programmatically.

Setup Instructions

Prerequisites

• Python 3.11 or higher
• Poetry for dependency management

Installation

1. Clone the repository
2. Copy .env.example to .env and configure as needed
3. Install dependencies:

   poetry install
   

Running the Server

poetry run python -m src.main

CLI Usage Examples

Character Management

# Create a new character
poetry run python -m src.cli character create --name "Gandalf" --class "Wizard" --level 5

# List all characters
poetry run python -m src.cli character list

# Get character details
poetry run python -m src.cli character get --name "Gandalf"

# Update character
poetry run python -m src.cli character update --name "Gandalf" --level 6

# Delete character
poetry run python -m src.cli character delete --name "Gandalf"

Dice Rolling

# Roll dice
poetry run python -m src.cli roll 1d20+5
poetry run python -m src.cli roll 3d6

Combat Engine

# Start combat session
poetry run python -m src.cli combat start

# Add combatants
poetry run python -m src.cli combat add --name "Gandalf" --initiative 15

# Process turn
poetry run python -m src.cli combat turn

Development

Run tests:

poetry run pytest

License

[License information to be added]