random-web3-mcp

Instructions

Randomly select an option based on weights

Args:
    options (List[str]): List of options
    weights (List[int]): Corresponding weight list (0-1000)
    salt (str, optional): Random number salt value. Defaults to "".

Returns:
    str: JSON string containing the selection result

Application Scenarios:
1. Lottery systems (prizes with different probabilities)
2. Random drops (weighted item drops)
3. Task assignment (based on priority)
4. A/B testing (experiment groups with different ratios)

Implementation Reference

• main.py:92-112 (handler)

  The handler function for the MCP tool 'generate_random_weighted', decorated with @mcp.tool() for registration. It receives input parameters and delegates execution to the weighted_random_selector helper in utils.py, returning the result as a string.

  @mcp.tool()
  async def generate_random_weighted(options: List[str], weights: List[int], salt: str = "") -> str:
      """Weighted Random Selector
      
      Randomly select an option based on weights
      
      Args:
          options (List[str]): List of options
          weights (List[int]): Corresponding weight list (0-1000)
          salt (str, optional): Random number salt value. Defaults to "".
      
      Returns:
          str: JSON string containing the selection result
      
      Application Scenarios:
      1. Lottery systems (prizes with different probabilities)
      2. Random drops (weighted item drops)
      3. Task assignment (based on priority)
      4. A/B testing (experiment groups with different ratios)
      """
      return await weighted_random_selector(options, weights, salt)

• utils.py:268-306 (helper)

  The core helper function implementing the weighted random selection logic. It derives a seed from blockchain block hashes and salt, normalizes weights, and uses numpy.random.choice to select an option probabilistically.

  async def weighted_random_selector(options: List[str], weights: List[int], salt: str = "") -> Dict:
      """
      Weighted random selector
      
      Randomly select an option based on weights
      
      Args:
          options: List of options to choose from
          weights: List of weights for each option (0-1000)
          salt: Optional salt value for additional randomness
          
      Returns:
          Dict containing selected option and selection metadata
      """
      if len(options) != len(weights):
          raise ValueError("Options and weights must have the same length")
      random_num = await get_random_str()
      if not random_num:
          return {"error": "Failed to get random number"}
          
      request_id = generate_request_id(random_num)
      seed = _derive_seed(request_id, salt)
      
      np.random.seed(seed)
      # Normalize weights
      weights_array = np.array(weights, dtype=float)
      weights_normalized = weights_array / np.sum(weights_array)
      
      # Select based on weights
      selection_index = np.random.choice(len(options), p=weights_normalized)
      selected_option = options[selection_index]
          
      result = {
          "requestId": request_id,
          "selectedOption": selected_option,
          "selectionIndex": int(selection_index)
      }
          
      return result