MCP Rand

Instructions

Implementation Reference

• src/handlers/roll-dice.handler.ts:80-102 (handler)

  The main handler function that executes the roll_dice tool, parsing arguments, rolling dice, and returning results as JSON.

  export const rollDiceHandler = async (
    request: CallToolRequest
  ): Promise<CallToolResult> => {
    const args = request.params.arguments as { dice: string[] };
    
    if (!args.dice || args.dice.length === 0) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Must specify at least one die to roll'
      );
    }
  
    const results = args.dice.map(dice => rollDiceSet(dice));
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(results, null, 2)
        }
      ]
    };
  };

• src/handlers/roll-dice.handler.ts:13-30 (schema)

  Tool specification including name, description, and input schema for validating roll_dice parameters.

  export const toolSpec = {
    name: 'roll_dice',
    description: 'Roll a set of dice using standard dice notation (e.g., "2d6" for two six-sided dice, "3d6+5" for three six-sided dice plus 5)',
    inputSchema: {
      type: 'object' as const,
      properties: {
        dice: {
          type: 'array',
          items: {
            type: 'string',
            description: 'Dice notation (e.g., "2d6", "1d20", "4d4")'
          },
          description: 'Array of dice to roll'
        }
      },
      required: ['dice']
    }
  };

• src/index.ts:24-24 (registration)

  Registers the roll_dice tool handler in the main server registry.

  registry.register('tools/call', 'roll_dice', rollDiceHandler as Handler);

• src/handlers/roll-dice.handler.ts:66-78 (helper)

  Helper function that rolls a single set of dice, computes rolls and total.

  function rollDiceSet(notation: string): DiceRoll {
    const { count, sides, modifier } = parseDiceNotation(notation);
    const rolls = Array.from({ length: count }, () => rollDie(sides));
    const rollTotal = rolls.reduce((a, b) => a + b, 0);
    const total = rollTotal + modifier;
  
    return {
      dice: notation,
      rolls,
      modifier,
      total
    };
  }

• src/handlers/roll-dice.handler.ts:32-60 (helper)

  Helper function to parse dice notation like '2d6+5' into count, sides, and modifier.

  function parseDiceNotation(notation: string): { count: number; sides: number; modifier: number } {
    const match = notation.toLowerCase().match(/^(\d+)d(\d+)([+-]\d+)?$/);
    if (!match) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid dice notation'
      );
    }
  
    const count = parseInt(match[1]);
    const sides = parseInt(match[2]);
    const modifier = match[3] ? parseInt(match[3]) : 0; // If no modifier, default to 0
  
    if (count <= 0) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Number of dice must be positive'
      );
    }
  
    if (sides <= 0) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Die size must be positive'
      );
    }
  
    return { count, sides, modifier };
  }