mcp_server/README.md

D&D Campaign Manager MCP Server

A Model Context Protocol (MCP) server providing D&D 5e tools for AI agents and LLMs.

🎲 What This MCP Server Provides

This MCP server extends LLM capabilities with specialized D&D 5e tools for:

• Character validation and rules compliance
• Encounter difficulty calculation
• XP award computation
• Multiclass requirement checking
• NPC stat block generation
• Ability modifier calculations

🚀 Quick Start

Installation

# Install FastMCP
pip install fastmcp

# Run the MCP server
python3 mcp_server/dnd_mcp_server.py

Usage with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "dnd-campaign-manager": {
      "command": "python3",
      "args": [
        "/path/to/dungeon-smasher-pro/mcp_server/dnd_mcp_server.py"
      ]
    }
  }
}

📚 Available Tools

validate_character

Validates D&D 5e character builds for rules compliance.

Parameters:

• character_class (string): Character class (e.g., "fighter")
• level (int): Character level (1-20)
• ability_scores (dict): Ability scores (e.g., {"strength": 16, "dexterity": 14, ...})
• multiclass (list, optional): List of multiclass names

Example:

validate_character(
    character_class="fighter",
    level=5,
    ability_scores={"strength": 16, "dexterity": 14, "constitution": 15, "intelligence": 10, "wisdom": 12, "charisma": 8}
)

Returns:

{
  "valid": true,
  "errors": [],
  "warnings": ["Low charisma (8) for fighter - recommend 13+"],
  "hp_estimate": 49,
  "hit_die": "d10",
  "constitution_modifier": 2
}

calculate_encounter_cr

Calculates encounter difficulty using D&D 5e rules.

Parameters:

• party_levels (list): Party member levels (e.g., [5, 5, 4, 6])
• monster_crs (list): Monster challenge ratings (e.g., [2, 2, 0.5])
• difficulty_target (string): Target difficulty ("easy", "medium", "hard", "deadly")

Example:

calculate_encounter_cr(
    party_levels=[5, 5, 4, 6],
    monster_crs=[2, 2, 0.5],
    difficulty_target="medium"
)

Returns:

{
  "difficulty": "hard",
  "adjusted_xp": 2100,
  "raw_xp": 1050,
  "multiplier": 2.0,
  "thresholds": {"easy": 1000, "medium": 2000, "hard": 3000, "deadly": 4400},
  "target_met": false,
  "recommendations": [],
  "party_size": 4,
  "monster_count": 3
}

calculate_xp_award

Calculates XP rewards for defeated monsters.

Parameters:

• party_size (int): Number of players
• monster_crs (list): CRs of defeated monsters

Example:

calculate_xp_award(party_size=4, monster_crs=[2, 2, 0.5])

Returns:

{
  "total_xp": 1150,
  "xp_per_player": 287,
  "party_size": 4,
  "monsters_defeated": 3
}

validate_multiclass

Checks multiclass requirements.

Parameters:

• current_class (string): Current primary class
• target_class (string): Class to multiclass into
• ability_scores (dict): Character ability scores

Example:

validate_multiclass(
    current_class="fighter",
    target_class="wizard",
    ability_scores={"intelligence": 14, "strength": 16, ...}
)

Returns:

{
  "valid": true,
  "requirements_met": true,
  "required": {"intelligence": 13},
  "missing": [],
  "can_multiclass": true
}

generate_npc_stats

Generates balanced NPC stat blocks.

Parameters:

• npc_name (string): NPC name
• character_class (string): NPC class
• level (int): NPC level
• role (string): Combat role ("tank", "damage", "support", "standard")

Example:

generate_npc_stats(
    npc_name="Guard Captain",
    character_class="fighter",
    level=5,
    role="tank"
)

Returns:

{
  "name": "Guard Captain",
  "class": "fighter",
  "level": 5,
  "role": "tank",
  "hp": 49,
  "hp_formula": "5d10 + 10",
  "ac": 18,
  "ability_scores": {"strength": 16, "dexterity": 12, "constitution": 16, ...},
  "proficiency_bonus": 3,
  "primary_ability": "strength",
  "hit_die": "d10"
}

get_ability_modifier

Calculates ability modifier from ability score.

Parameters:

• ability_score (int): Ability score (1-30)

Example:

get_ability_modifier(16)

Returns: 3

get_cr_for_solo_monster

Recommends CR for solo monster encounters.

Parameters:

• party_level (int): Average party level
• party_size (int): Number of party members
• difficulty (string): Desired difficulty

Example:

get_cr_for_solo_monster(party_level=5, party_size=4, difficulty="hard")

Returns:

{
  "recommended_cr": 7.0,
  "target_xp": 3000,
  "actual_xp": 2900,
  "party_level": 5,
  "party_size": 4,
  "difficulty": "hard"
}

🏗️ Architecture

mcp_server/
├── __init__.py              # Package initialization
├── dnd_mcp_server.py       # Main MCP server with tools
├── mcp_config.json         # MCP configuration
└── README.md               # Documentation

🎯 Use Cases

For DMs

• Validate player character builds during session 0
• Balance encounters on-the-fly
• Generate quick NPC stats for improvised encounters
• Calculate XP rewards accurately

For AI Agents

• Autonomous character creation with rules compliance
• Intelligent encounter design
• Campaign balance analysis
• NPC generation for story development

For Developers

• Integrate D&D rules into LLM applications
• Build D&D assistants and tools
• Create automated campaign managers
• Develop character builders with validation

📊 Example Integration

# Example: AI agent using MCP tools to balance an encounter

# 1. Validate party
for character in party:
    validation = validate_character(
        character_class=character.class,
        level=character.level,
        ability_scores=character.abilities
    )
    if not validation["valid"]:
        print(f"Error: {validation['errors']}")

# 2. Design encounter
party_levels = [char.level for char in party]
encounter = calculate_encounter_cr(
    party_levels=party_levels,
    monster_crs=[2, 2, 1, 0.5],
    difficulty_target="medium"
)

# 3. Adjust if needed
if encounter["difficulty"] != "medium":
    print(f"Encounter is {encounter['difficulty']}, adjusting...")
    # AI can now reason about how to adjust

# 4. Calculate rewards
xp = calculate_xp_award(
    party_size=len(party),
    monster_crs=[2, 2, 1, 0.5]
)
print(f"Party earns {xp['xp_per_player']} XP each")

🔧 Development

Adding New Tools

1. Add tool function with @mcp.tool() decorator
2. Document parameters and return values
3. Add to tool list in __main__
4. Update this README

Testing

# Test individual tools
python3 -c "from mcp_server.dnd_mcp_server import *; print(validate_character('fighter', 5, {'strength': 16, 'dexterity': 14, 'constitution': 15, 'intelligence': 10, 'wisdom': 12, 'charisma': 8}))"

📝 License

MIT License - See main project LICENSE

🤝 Contributing

Contributions welcome! Please:

1. Follow D&D 5e SRD rules
2. Add tests for new tools
3. Update documentation
4. Ensure backward compatibility

🎲 D&D 5e SRD Compliance

This MCP server implements rules from the D&D 5e System Reference Document (SRD). All content is from open game content under the OGL 1.0a.

🔗 Links

• FastMCP Documentation
• Model Context Protocol
• D&D 5e SRD