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

```bash
# 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`):

```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:**
```python
validate_character(
    character_class="fighter",
    level=5,
    ability_scores={"strength": 16, "dexterity": 14, "constitution": 15, "intelligence": 10, "wisdom": 12, "charisma": 8}
)
```

**Returns:**
```json
{
  "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:**
```python
calculate_encounter_cr(
    party_levels=[5, 5, 4, 6],
    monster_crs=[2, 2, 0.5],
    difficulty_target="medium"
)
```

**Returns:**
```json
{
  "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:**
```python
calculate_xp_award(party_size=4, monster_crs=[2, 2, 0.5])
```

**Returns:**
```json
{
  "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:**
```python
validate_multiclass(
    current_class="fighter",
    target_class="wizard",
    ability_scores={"intelligence": 14, "strength": 16, ...}
)
```

**Returns:**
```json
{
  "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:**
```python
generate_npc_stats(
    npc_name="Guard Captain",
    character_class="fighter",
    level=5,
    role="tank"
)
```

**Returns:**
```json
{
  "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:**
```python
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:**
```python
get_cr_for_solo_monster(party_level=5, party_size=4, difficulty="hard")
```

**Returns:**
```json
{
  "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

```python
# 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

```bash
# 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](https://github.com/anthropics/anthropic-tools)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [D&D 5e SRD](https://dnd.wizards.com/resources/systems-reference-document)