Tavily Web Search MCP Server

Instructions

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)