random_sample

Instructions

Implementation Reference

• src/random_number_mcp/tools.py:101-119 (handler)

  Core implementation of random_sample: chooses k unique items from population without replacement using random.sample(). Validates inputs via validate_list_not_empty, validate_positive_int, and checks k <= len(population).

  def random_sample(population: list[Any], k: int) -> list[Any]:
      """Choose k unique items from population without replacement.
  
      Args:
          population: List of items to choose from
          k: Number of items to choose
  
      Returns:
          List of k unique chosen items
  
      Raises:
          ValueError: If population is empty, k < 0, or k > len(population)
          TypeError: If k is not an integer
      """
      validate_list_not_empty(population, "population")
      validate_positive_int(k, "k")
      if k > len(population):
          raise ValueError("Sample size k cannot be greater than population size")
      return random.sample(population, k)

• src/random_number_mcp/server.py:83-96 (registration)

  Registers random_sample as an MCP tool via @app.tool() decorator. Defines the public schema with typed parameters (population: list, k: int) and delegates to tools.random_sample().

  @app.tool()
  def random_sample(
      population: list[str | int | float | bool], k: int
  ) -> list[str | int | float | bool]:
      """Choose k unique items from population without replacement.
  
      Args:
          population: List of items to choose from
          k: Number of items to choose
  
      Returns:
          List of k unique chosen items
      """
      return tools.random_sample(population, k)

• src/random_number_mcp/server.py:84-96 (schema)

  Input schema for random_sample: population as list[str|int|float|bool] and k as int. Returns list[str|int|float|bool].

  def random_sample(
      population: list[str | int | float | bool], k: int
  ) -> list[str | int | float | bool]:
      """Choose k unique items from population without replacement.
  
      Args:
          population: List of items to choose from
          k: Number of items to choose
  
      Returns:
          List of k unique chosen items
      """
      return tools.random_sample(population, k)

• src/random_number_mcp/utils.py:12-17 (helper)

  validate_positive_int helper: validates that k is an integer and non-negative, used by random_sample handler.

  def validate_positive_int(value: int, name: str) -> None:
      """Validate that a value is a positive integer."""
      if not isinstance(value, int):
          raise TypeError(f"{name} must be an integer, got {type(value).__name__}")
      if value < 0:
          raise ValueError(f"{name} must be non-negative, got {value}")

• src/random_number_mcp/utils.py:20-23 (helper)

  validate_list_not_empty helper: validates that population list is not empty, used by random_sample handler.

  def validate_list_not_empty(items: list[Any], name: str) -> None:
      """Validate that a list is not empty."""
      if not items:
          raise ValueError(f"{name} cannot be empty")