# CLAUDE.md — Dice Roller MCP Server
## What This Server Does
Provides true random dice rolling and coin flipping tools via MCP protocol.
No external APIs. No secrets needed. Pure Python randomness.
## Tools Available
| Tool | Description | Example Input |
|--------------------|------------------------------------------------------|--------------------------------------|
| flip_coin | Flip N coins | times="3" |
| roll_dice | NdM+K notation roller | notation="2d6+3" |
| roll_advantage | 2x roll, take higher (DnD 5e) | sides="20" modifier="3" |
| roll_disadvantage | 2x roll, take lower (DnD 5e) | sides="20" modifier="0" |
| roll_stats | Full 6-stat DnD block (4d6 drop lowest) | (no params) |
| roll_initiative | 1d20 + modifier for initiative | modifier="2" |
| roll_custom | Fully custom count/sides/modifier/label | count="3" sides="8" modifier="2" |
| roll_percentile | d100 roll | (no params) |
| roll_drop_lowest | NdM drop lowest die | count="4" sides="6" |
## Code Rules (CRITICAL)
- All tool docstrings are SINGLE LINE — multi-line causes gateway panic errors
- All params default to empty string `""` — never None
- All tools return strings — never None or other types
- Check `.strip()` before using string params
- Convert string params to int/float inside the tool function
## Dice Notation Supported
Format: `NdM`, `NdM+K`, `NdM-K`
- N = number of dice (default 1)
- M = number of sides
- K = modifier (positive or negative)
- Examples: `d6`, `2d6`, `1d20+5`, `4d8-2`, `3d10+0`
## Docker Build
docker build -t dice-roller-mcp-server .
docker run -i --rm dice-roller-mcp-server
## Catalog Entry (custom.yaml snippet)
dice-roller:
description: "Roll dice, flip coins, and handle DnD tabletop mechanics"
title: "Dice Roller"
type: server
dateAdded: "2026-02-19T00:00:00Z"
image: dice-roller-mcp-server:latest
ref: ""
tools:
- name: flip_coin
- name: roll_dice
- name: roll_advantage
- name: roll_disadvantage
- name: roll_stats
- name: roll_initiative
- name: roll_custom
- name: roll_percentile
- name: roll_drop_lowest
## Extending
To add a new die mechanic:
1. Add `async def new_tool(param: str = "") -> str:` to dice_roller_server.py
2. Use `@mcp.tool()` decorator
3. Single-line docstring
4. Return a formatted string
5. Add tool name to custom.yaml
6. Rebuild image
