roll_dice
Roll dice using D&D-style notation like 2d20k1 to generate random numbers for games, simulations, or decision-making.
Instructions
Roll dice with D&D-style notation (e.g., 2d20k1).
Args: notation: Dice notation (e.g., "2d20k1" = roll 2d20, keep highest 1) num_rolls: Number of times to roll (default 1)
Returns: Formatted dice roll results
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notation | Yes | ||
| num_rolls | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- server.py:61-79 (handler)MCP tool handler for 'roll_dice': decorated with @mcp.tool(), instantiates DiceRoller and returns string result. This is the primary entrypoint for the tool.
@mcp.tool() def roll_dice(notation: str, num_rolls: int = 1) -> str: """ Roll dice with D&D-style notation (e.g., 2d20k1). Args: notation: Dice notation (e.g., "2d20k1" = roll 2d20, keep highest 1) num_rolls: Number of times to roll (default 1) Returns: Formatted dice roll results """ try: roller = DiceRoller(notation, num_rolls) return str(roller) except ValueError as e: return f"Invalid dice notation: {str(e)}" except Exception as e: return f"Error rolling dice: {str(e)}" - dice_roller.py:4-47 (helper)DiceRoller class providing the core dice rolling logic: parses D&D notation, generates random rolls, handles keeping highest dice, and formats output strings used by the handler.
class DiceRoller: def __init__(self, notation, num_rolls=1): self.notation = notation self.num_rolls = num_rolls self.dice_pattern = re.compile(r"(\d+)d(\d+)(k(\d+))?") def roll_dice(self): match = self.dice_pattern.match(self.notation) if not match: raise ValueError("Invalid dice notation") num_dice = int(match.group(1)) dice_sides = int(match.group(2)) keep = int(match.group(4)) if match.group(4) else num_dice rolls = [random.randint(1, dice_sides) for _ in range(num_dice)] rolls.sort(reverse=True) kept_rolls = rolls[:keep] return rolls, kept_rolls def roll_multiple(self): """Roll the dice multiple times according to num_rolls""" results = [] for _ in range(self.num_rolls): rolls, kept_rolls = self.roll_dice() results.append({ "rolls": rolls, "kept": kept_rolls, "total": sum(kept_rolls) }) return results def __str__(self): if self.num_rolls == 1: rolls, kept_rolls = self.roll_dice() return f"ROLLS: {', '.join(map(str, rolls))} -> RETURNS: {sum(kept_rolls)}" else: results = self.roll_multiple() result_strs = [] for i, result in enumerate(results, 1): result_strs.append(f"Roll {i}: ROLLS: {', '.join(map(str, result['rolls']))} -> RETURNS: {result['total']}") return "\n".join(result_strs) - server.py:93-93 (registration)Startup print confirming roll_dice tool registration.
print(" ✅ roll_dice (D&D dice roller)") - server_old.py:19-23 (helper)Legacy version of the roll_dice handler in server_old.py.
def roll_dice(notation: str, num_rolls: int = 1) -> str: """Roll the dice with the given notation""" roller = DiceRoller(notation, num_rolls) return str(roller)