MCP Rand

Instructions

Implementation Reference

• src/handlers/draw-cards.handler.ts:102-160 (handler)

  The main handler function that executes the draw_cards tool: parses arguments, manages deck state, shuffles and draws cards, returns JSON result.

  export const drawCardsHandler = async (
    request: CallToolRequest
  ): Promise<CallToolResult> => {
    const args = request.params.arguments as { count: number; deckState?: string };
    
    if (args.count <= 0) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Must draw at least one card'
      );
    }
  
    // Validate and process deck state if provided
    let availableCards: Card[];
    if (args.deckState) {
      // Validate base64 format
      if (!/^[A-Za-z0-9+/]+=*$/.test(args.deckState)) {
        throw new McpError(
          ErrorCode.InvalidParams,
          'Invalid deck state: must be base64 encoded'
        );
      }
      availableCards = getAvailableCardsFromState(args.deckState);
    } else {
      availableCards = createDeck();
    }
  
    if (args.count > availableCards.length) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Cannot draw ${args.count} cards from deck with ${availableCards.length} cards remaining`
      );
    }
  
    // Shuffle the available cards
    const shuffledCards = shuffleArray(availableCards);
    
    // Draw the requested number of cards
    const drawnCards = shuffledCards.slice(0, args.count);
    
    // Calculate remaining cards and get their state
    const remainingCards = shuffledCards.slice(args.count);
    const newDeckState = getDeckStateFromCards(remainingCards);
  
    const result = {
      drawnCards,
      remainingCount: remainingCards.length,
      deckState: newDeckState
    };
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2)
        }
      ]
    };
  };

• src/handlers/draw-cards.handler.ts:11-28 (schema)

  Tool specification defining name, description, and input schema for the draw_cards tool.

  export const toolSpec = {
    name: 'draw_cards',
    description: 'Draw cards from a standard deck of playing cards',
    inputSchema: {
      type: 'object' as const,
      properties: {
        count: {
          type: 'number',
          description: 'Number of cards to draw',
        },
        deckState: {
          type: 'string',
          description: 'Optional base64 encoded string representing the current deck state',
        }
      },
      required: ['count']
    }
  };

• src/index.ts:17-26 (registration)

  Registers all tool handlers including draw_cards with the HandlerRegistry in the main server setup.

  async function registerHandlers(registry: HandlerRegistry): Promise<void> {
    registry.register('tools/list', 'list', ListToolsHandler as Handler);
    registry.register('tools/call', 'generate_uuid', generateUuidHandler as Handler);
    registry.register('tools/call', 'generate_random_number', generateRandomNumberHandler as Handler);
    registry.register('tools/call', 'generate_gaussian', generateGaussianHandler as Handler);
    registry.register('tools/call', 'generate_string', generateStringHandler as Handler);
    registry.register('tools/call', 'generate_password', generatePasswordHandler as Handler);
    registry.register('tools/call', 'roll_dice', rollDiceHandler as Handler);
    registry.register('tools/call', 'draw_cards', drawCardsHandler as Handler);
  }

• src/handlers/draw-cards.handler.ts:33-41 (helper)

  Helper function to create a full standard deck of 52 cards.

  function createDeck(): Card[] {
    const deck: Card[] = [];
    for (const suit of SUITS) {
      for (const value of VALUES) {
        deck.push({ suit, value });
      }
    }
    return deck;
  }

• src/handlers/draw-cards.handler.ts:43-50 (helper)

  Fisher-Yates shuffle implementation for randomizing the deck.

  function shuffleArray<T>(array: T[]): T[] {
    const shuffled = [...array];
    for (let i = shuffled.length - 1; i > 0; i--) {
      const j = Math.floor(Math.random() * (i + 1));
      [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
    }
    return shuffled;
  }