D&D MCP Server

Instructions

Implementation Reference

• src/gamemaster_mcp/main.py:773-821 (handler)

  The complete implementation of the 'roll_dice' tool handler, including schema (input parameters with descriptions), registration via @mcp.tool decorator, and the full logic for parsing dice notation, rolling dice (with support for advantage/disadvantage), applying modifiers, and formatting the output.

  @mcp.tool
  def roll_dice(
      dice_notation: Annotated[str, Field(description="Dice notation (e.g., '1d20', '3d6+2')")],
      advantage: Annotated[bool, Field(description="Roll with advantage")] = False,
      disadvantage: Annotated[bool, Field(description="Roll with disadvantage")] = False,
  ) -> str:
      """Roll dice with D&D notation."""
      dice_notation = dice_notation.lower().strip()
  
      # Parse dice notation (e.g., "1d20", "3d6+2", "2d8-1")
      pattern = r'(\d+)d(\d+)([+-]\d+)?'
      match = re.match(pattern, dice_notation)
  
      if not match:
          return f"Invalid dice notation: {dice_notation}"
  
      num_dice = int(match.group(1))
      die_size = int(match.group(2))
      modifier = int(match.group(3)) if match.group(3) else 0
  
      # Roll dice
      if advantage or disadvantage:
          if num_dice != 1 or die_size != 20:
              return "Advantage/disadvantage only applies to single d20 rolls"
  
          roll1 = random.randint(1, 20)
          roll2 = random.randint(1, 20)
  
          if advantage:
              result = max(roll1, roll2)
              roll_text = f"Advantage: {roll1}, {roll2} (taking {result})"
          else:
              result = min(roll1, roll2)
              roll_text = f"Disadvantage: {roll1}, {roll2} (taking {result})"
  
          total = result + modifier
          modifier_text = f" {modifier:+d}" if modifier != 0 else ""
  
          return f"🎲 **{dice_notation}** {roll_text}{modifier_text} = **{total}**"
      else:
          rolls = [random.randint(1, die_size) for _ in range(num_dice)]
          roll_sum = sum(rolls)
          total = roll_sum + modifier
  
          rolls_text = ", ".join(map(str, rolls)) if num_dice > 1 else str(rolls[0])
          modifier_text = f" {modifier:+d}" if modifier != 0 else ""
  
          return f"🎲 **{dice_notation}** [{rolls_text}]{modifier_text} = **{total}**"