# Dice Roller MCP Server

A Model Context Protocol (MCP) server that provides dice rolling, coin flipping,
and full DnD/tabletop RPG mechanics for AI assistants.

## Purpose

This MCP server gives Claude (or any MCP-compatible AI) the ability to roll dice,
flip coins, and run tabletop RPG mechanics in real-time with true randomness.

## Features

- `flip_coin` - Flip one or more coins, get Heads/Tails results
- `roll_dice` - Roll using standard NdM+K notation (e.g. 2d6, 1d20+5, 4d8-2)
- `roll_advantage` - Roll with advantage (2x, take higher) for DnD 5e
- `roll_disadvantage` - Roll with disadvantage (2x, take lower) for DnD 5e
- `roll_stats` - Generate a full DnD character stat block (4d6 drop lowest x6)
- `roll_initiative` - Roll initiative (1d20 + modifier) for DnD combat
- `roll_custom` - Roll any count/sides/modifier combo with an optional label
- `roll_percentile` - Roll a percentile die (d100)
- `roll_drop_lowest` - Roll NdM and drop the lowest result

## Prerequisites

- Docker Desktop with MCP Toolkit enabled
- Docker MCP CLI plugin (`docker mcp` command)

## Installation

See INSTALLATION section at the bottom of this file, or follow the numbered steps
provided when you received these files.

## Usage Examples

In Claude Desktop, you can ask:
- "Roll a d20 with +5 modifier"
- "Flip 3 coins"
- "Roll 2d6+3 for damage"
- "Roll my DnD character stats"
- "Roll initiative with +2 dex"
- "Roll with advantage on a d20"
- "Roll 4d6 drop lowest for strength"
- "Roll a percentile die"
- "Roll 3d8 for my fireball damage, label it Fireball"

## Architecture

    Claude Desktop -> MCP Gateway -> Dice Roller MCP Server (Docker)

No external API or secrets needed. Pure Python random module.

## Development

### Local Testing

    # Run directly (no Docker needed for testing)
    python dice_roller_server.py

    # Test MCP protocol
    echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python dice_roller_server.py

### Adding New Tools

1. Add an async function to dice_roller_server.py
2. Decorate with @mcp.tool()
3. Single-line docstring only
4. All params default to empty string ""
5. Return a formatted string
6. Add tool name to custom.yaml catalog
7. Rebuild Docker image: docker build -t dice-roller-mcp-server .

## Troubleshooting

- Tools not appearing? Verify Docker image built, check catalog/registry files, restart Claude Desktop.
- Gateway panic? Ensure all docstrings are single-line only.
- Wrong results? All randomness uses Python's secrets-seeded random — it's fair!

## Security

- No API keys required
- Running as non-root user in Docker
- No network access needed

## License

MIT License