# Dice Roller MCP Server

A Model Context Protocol (MCP) server that flips coins and rolls dice, including standard dice notation and D&D mechanics.

## Purpose

This MCP server gives Claude a simple, dependency-free way to generate random results for tabletop games, D&D sessions, or any "let's leave it to chance" moment.

## Features

### Current Implementation
- **`flip_coin`** - Flip one or more coins and get Heads/Tails results
- **`roll_dice`** - Roll dice using standard notation (e.g. `d20`, `2d6+3`, `4d6-1`)
- **`roll_advantage`** - Roll 2d20 and keep the higher, D&D advantage mechanic
- **`roll_disadvantage`** - Roll 2d20 and keep the lower, D&D disadvantage mechanic
- **`roll_ability_scores`** - Generate D&D ability scores (4d6, drop lowest) for one or more stats

## Prerequisites

- Docker Desktop with MCP Toolkit enabled
- Docker MCP CLI plugin (`docker mcp` command)
- No API keys or external services required — this server is fully self-contained

## Installation

See the step-by-step instructions provided alongside these files.

## Usage Examples

In Claude Desktop, you can ask:
- "Flip a coin"
- "Flip 5 coins"
- "Roll 2d6+3"
- "Roll a d20"
- "Roll with advantage, +5 modifier"
- "Roll with disadvantage"
- "Roll me a set of D&D ability scores"
- "Generate 6 ability scores for a new character"

## Architecture

```
Claude Desktop → MCP Gateway → Dice Roller MCP Server (local, no external calls)
```

## Development

### Local Testing

```bash
# Run directly
python dice_server.py

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

### Adding New Tools

1. Add the function to `dice_server.py`
2. Decorate with `@mcp.tool()`
3. Use a single-line docstring and string parameter defaults (`param: str = ""`)
4. Update the catalog entry with the new tool name
5. Rebuild the Docker image

## Troubleshooting

### Tools Not Appearing
- Verify the Docker image built successfully
- Check catalog and registry files
- Ensure Claude Desktop config includes the custom catalog
- Restart Claude Desktop

### Unexpected Errors
- Check container logs with `docker logs <container_name>`
- Confirm dice notation matches the expected format, e.g. `NdM`, `NdM+K`, or `NdM-K`

## Security Considerations

- No API keys or secrets are used by this server
- Running as a non-root user inside the container
- No external network calls are made

## License

MIT License