dice-mcp-server: Instructions file for Claude Code

CLAUDE.md - Dice Roller MCP Server

Implementation Overview

This is a self-contained MCP server with no external API dependencies — everything runs on Python's built-in random module. It exposes 5 tools for coin flips, standard dice notation, and D&D-specific roll mechanics.

Server Details

• Server name: dice
• File: dice_server.py
• Transport: stdio
• External dependencies: none beyond mcp[cli]

Tools

Tool	Parameters	Description
flip_coin	times: str = "1"	Flips 1+ coins, returns Heads/Tails and a summary if more than one
roll_dice	notation: str = "1d20"	Parses NdM, NdM+K, NdM-K notation and returns individual rolls + total
roll_advantage	modifier: str = "0"	Rolls 2d20, keeps the higher, applies modifier
roll_disadvantage	modifier: str = "0"	Rolls 2d20, keeps the lower, applies modifier
roll_ability_scores	count: str = "6"	Rolls 4d6 drop-lowest per score, for count scores

Design Decisions

• No typing imports, single-line docstrings, string-only params: follows the gateway compatibility rules to avoid panics in Claude Desktop.
• Dice notation parsing via regex: parse_dice_notation() uses re.fullmatch(r"(\d*)d(\d+)([+-]\d+)?", ...) to support the common NdM+K shorthand DMs and players use at the table.
• Sane limits: capped at 100 dice per roll, 1000 sides per die, and 100 coin flips per call, to avoid pathological inputs (e.g. someone requesting a million-sided die).
• Every tool returns a formatted string with emoji markers (🪙 🎲 📊 ✅ ❌) for quick visual scanning, per the output formatting conventions.
• roll_ability_scores shows its work: displays each individual d6 roll and which die was dropped, so results are auditable/transparent for tabletop use.

Adding a New Tool

1. Add a new async def function decorated with @mcp.tool().
2. Keep the docstring to a single line — multi-line docstrings break the gateway.
3. Use param: str = "" defaults, never None or typed defaults.
4. Validate input with .strip() checks, not truthiness checks.
5. Wrap logic in try/except and return a ❌ Error: ... string on failure.
6. Rebuild the Docker image and update the custom catalog's tools: list.