Skip to main content
Glama
random-web3-mcp
by suxiongye

RandomWeb3MCP - Web3 随机元素生成服务

RandomWeb3MCP 是基于 EVM 区块哈希的随机数生成服务,提供多种随机数生成工具,可用于游戏、金融、测试等领域。

特征

  • 可验证性:所有随机数均基于区块链哈希生成,确保公平性和可验证性

  • 多样性:支持各种随机数生成场景,从基本随机数到复杂的概率分布

  • 可靠性:使用区块链作为熵源,确保随机性质量

  • 可用性:提供简单直观的 API 接口,方便集成

Related MCP server: Random Value MCP Server

安装

git clone git@github.com:suxiongye/random-web3-mcp.git
pip install -e .

快速入门

tico 或 Cursor 中的配置

在 Cursor 设置中添加 random-web3-mcp 服务配置:

{
  "mcpServers": {
    "random-web3-mcp": {
      "command": "uv",
      "args": ["--directory", "local_repo_directory/zxl-mcp-server", "run", "main.py"]
    }
  }
}

工具清单

生成基本随机数

姓名

基本随机数生成器

功能

生成指定范围内的随机整数

参数

  • min_value(int,可选):最小值(含)。默认为 0。

  • max_value(int,可选):最大值(含)。默认为 1000000。

  • salt(字符串,可选):用于增加随机性的随机数盐值。默认为 ''

返回

包含随机数结果的 JSON 字符串

应用场景

  1. 彩票系统

  2. 游戏随机数

  3. 随机 ID 生成

  4. 测试数据生成

生成随机数组

姓名

随机数组生成器

功能

生成指定长度的随机数组

参数

  • array_length (int,可选):数组长度。默认为 1。

  • min_value(int,可选):最小值。默认为 0。

  • max_value(int,可选):最大值。默认为 1000000。

  • salt (str, 可选): 随机数盐值。默认为 ''

返回

包含随机数组的 JSON 字符串

应用场景

  1. 批量随机数生成

  2. 随机抽样

  3. 测试数据集生成

  4. 随机任务分配

生成随机加权

姓名

加权随机选择器

功能

根据权重随机选择一个选项

参数

  • 选项(List [str]):选项列表

  • weights (List[int]): 对应的权重列表(0-1000)

  • salt (str, 可选): 随机数盐值。默认为 ''

返回

包含选择结果的 JSON 字符串

应用场景

  1. 彩票系统(不同概率的奖品)

  2. 随机掉落(加重物品掉落)

  3. 任务分配(基于优先级)

  4. A/B 测试(不同比例的实验组)

生成随机特征

姓名

随机特征分配器

功能

为对象生成一组随机特征值,每个特征值在其指定范围内。特征值被编码成位图,每个特征占用 8 位

参数

  • feature_count(int):要生成的特征数量

  • feature_max_values (List[int]):每个特征的最大值列表,长度必须等于 feature_count

  • salt(str,可选):用于增加随机性的随机数盐值。默认为 ''

返回

包含特征值和位图的 JSON 字符串,格式为:

{
    "requestId": "Generated request ID",
    "features": [List of feature values],
    "featureBitmap": Feature bitmap value
}

应用场景

  1. 游戏角色属性生成(力量、敏捷、智力等)

  2. 装备属性随机化(攻击、防御、速度等)

  3. 生物性状模拟(基因、性状等)

  4. 随机场景生成(地形、天气、环境等)

生成分布

姓名

概率分布随机生成器

功能

根据指定的概率分布类型及参数生成随机数。支持各种常见的概率分布。

参数

  • distribution_type(int):分布类型:

    • 1 = 均匀分布(参数:[min_value,max_value])

    • 2 = 正态分布(参数:[平均值,标准差])

    • 3 = 指数分布(参数:[scale_parameter])

    • 4 = 二项分布(参数:[试验次数,成功概率])

  • distribution_parameters (List[float]): 分布参数列表

  • salt(字符串,可选):用于增加随机性的随机数盐值。默认为 ''

返回

包含随机值及分布信息的JSON字符串,格式为:

{
    "requestId": "Generated request ID",
    "randomValue": Generated random value,
    "distributionMetadata": {
        "distributionType": Distribution type,
        ...Distribution parameters
    }
}

应用场景

  1. 金融市场模拟(收益分布、风险分析)

  2. 自然现象模拟(粒子分布、噪声产生)

  3. 负载测试(用户行为分布)

  4. 统计抽样(实验数据生成)

生成随机事件

姓名

随机事件触发器

功能

根据给定的概率触发一系列事件,每个事件都有独立的触发概率。使用位图记录触发状态,方便处理。

参数

  • event_count (int):事件总数

  • event_probabilities (List[int]): 每个事件的触发概率(0-1000,代表0-100%)

  • salt(str,可选):用于增加随机性的随机数盐值。默认为 ''

返回

包含事件触发结果的JSON字符串,格式为:

{
    "requestId": "Generated request ID",
    "triggeredEvents": Event trigger bitmap,
    "eventResults": [
        {
            "eventId": Event ID,
            "probability": Trigger probability,
            "triggered": Whether triggered,
            "randomValue": Random value
        },
        ...
    ]
}

应用场景

  1. 游戏随机事件(触发剧情、掉落物品)

  2. 概率效果判定(技能触发、连击判定)

  3. 风险事件模拟(故障预测、事故事件)

  4. 多重条件确定(组合概率事件)

生成随机种子

姓名

随机种子生成器

功能

生成高熵随机种子,用于加密或其他需要高质量随机数的场景。使用区块链哈希作为熵源,确保随机性。

参数

  • seed_length(int):要生成的种子的长度(以字节为单位)

  • salt(str,可选):用于增加随机性的随机数盐值。默认为 ''

返回

包含随机种子的 JSON 字符串,格式为:

{
    "requestId": "Generated request ID",
    "randomSeed": "Random seed in hexadecimal format",
    "entropy": Estimated entropy value
}

应用场景

  1. 密钥生成(加密密钥、签名种子)

  2. 安全令牌(会话标识符、身份验证令牌)

  3. 随机数初始化(PRNG种子、模拟初始状态)

  4. 唯一标识符生成(UUID 种子、随机标识符)

随机数组

姓名

随机数组洗牌器

功能

随机打乱输入数组,确保每个元素出现在任意位置的概率均等。使用 Fisher-Yates 打乱算法来确保公平性。

参数

  • input_array(列表):要打乱的数组,元素可以是任何类型

  • salt(字符串,可选):用于增加随机性的随机数盐值。默认为 ''

返回

包含混洗数组的 JSON 字符串,格式如下:

{
    "requestId": "Generated request ID",
    "shuffledArray": [Shuffled array]
}

应用场景

  1. 游戏洗牌(扑克牌、麻将牌)

  2. 随机排序(问题顺序、播放列表)

  3. 随机分组(团队分配、实验分组)

  4. 数据混洗(训练数据集、测试用例)

生成坐标

姓名

随机坐标生成器

功能

在指定维度空间中生成随机坐标点,每个维度都有各自的取值范围。支持任意维度的坐标生成。

参数

  • 维度(int):坐标维度数(1D、2D、3D 等)

  • min_values (List[float]):每个维度的最小值列表

  • max_values (List[float]):每个维度的最大值列表

  • coordinate_count(int):要生成的坐标点的数量

  • salt(字符串,可选):用于增加随机性的随机数盐值。默认为 ''

返回

包含随机坐标的 JSON 字符串,格式为:

{
    "requestId": "Generated request ID",
    "coordinates": [
        [x1, y1, z1, ...],  # First point coordinates
        [x2, y2, z2, ...],  # Second point coordinates
        ...
    ]
}

应用场景

  1. 游戏对象定位(NPC位置、物品分布)

  2. 粒子系统(效果生成、粒子分布)

  3. 地图生成(地形高度、资源分布)

  4. 空间采样(3D建模、空间分析)

生成稀有度

姓名

稀有度随机分配器

功能

在指定维度空间中生成随机坐标点,每个维度都有各自的取值范围。支持任意维度的坐标生成。

参数

  • item_count:项目数量

  • rarity_tiers:稀有度等级数组

  • rarity_percentages:每个稀有度等级的概率百分比

  • guaranteed_minimums:每个稀有度等级的保证数量(可选)

  • salt(字符串,可选):用于增加随机性的随机数盐值。默认为 ''

返回

包含随机稀有度数组的 JSON 字符串,格式如下:

{
    "requestId": "Generated request ID",
    "rarityDistribution": [Rarity allocation result]
}

应用场景

  1. 游戏物品掉落(不同稀有度的装备、物品)

  2. 彩票系统(不同概率的奖品)

  3. 资源配置(不同稀有度的资源、材料)

  4. 随机事件触发(不同概率事件)

应用场景

游戏开发

  • 随机物品掉落

  • 角色属性生成

  • 地图随机生成

  • 概率事件触发

财务申请

  • 风险模拟

  • 投资组合分析

  • 市场行为模拟

测试数据

  • 随机测试用例生成

  • 加载测试数据

  • 性能测试样例

科学计算

  • 蒙特卡罗模拟

  • 粒子系统模拟

  • 随机抽样

笔记

  1. 所有随机数生成均依赖于信任链的区块链哈希,请确保网络连接正常

  2. 加权随机选择器权重值范围是0-1000,代表0-100%的概率

  3. 概率分布参数需要根据具体的分布类型提供正确的参数列表

  4. 生产环境建议使用salt参数增加随机性

错误处理

服务可能返回错误类型:

{
    "error": "Error message",
    "code": "Error code",
    "requestId": "Request ID"
}

常见错误代码:

  • INVALID_PARAMS :参数错误

  • NETWORK_ERROR :网络连接错误

  • CHAIN_ERROR :区块链访问错误

  • INTERNAL_ERROR :内部服务错误

性能考虑

  • 每个随机数生成请求都需要访问区块链,可能会有一定的延迟

  • 建议缓存经常使用的随机数

  • 处理大量并发请求时要注意请求频率

贡献指南

欢迎提交 Issue 和 Pull Request 来帮助改进本项目。提交前请确保:

  1. 代码符合PEP 8规范

  2. 添加适当的测试用例

  3. 相关文件已更新

执照

本项目使用 MIT 许可证。详情请参阅LICENSE文件。

Available Tools

10 tools
generate_basic_randomA

Basic Random Number Generator

Generate a random integer within the specified range

Args:
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".
    min_value (int, optional): Minimum value (inclusive). Defaults to 0.
    max_value (int, optional): Maximum value (inclusive). Defaults to 1000000.

Returns:
    str: JSON string containing the random number result

Application Scenarios:
1. Lottery systems
2. Game random numbers
3. Random ID generation
4. Test data generation

Inputs: max_value, min_value, salt.

generate_coordinateA

Random Coordinate Generator

Generate random coordinate points in a specified dimensional space, each dimension has its own value range.
Supports coordinate generation in any number of dimensions.

Args:
    dimensions (int): Number of coordinate dimensions (1D, 2D, 3D, etc.)
    min_values (List[float]): List of minimum values for each dimension
    max_values (List[float]): List of maximum values for each dimension
    coordinate_count (int): Number of coordinate points to generate
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing random coordinates, formatted as:
    {
        "requestId": "Generated request ID",
        "coordinates": [
            [x1, y1, z1, ...],  # First point coordinates
            [x2, y2, z2, ...],  # Second point coordinates
            ...
        ]
    }

Application Scenarios:
1. Game object positioning (NPC locations, item distribution)
2. Particle systems (effect generation, particle distribution)
3. Map generation (terrain height, resource distribution)
4. Spatial sampling (3D modeling, spatial analysis)

Inputs: coordinate_count (required), dimensions (required), max_values (required), min_values (required), +1 more.

generate_distributionA

Probability Distribution Random Generator

Generate random numbers according to specified probability distribution type and parameters.
Supports various common probability distributions.

Args:
    distribution_type (int): Distribution type:
        1 = Uniform distribution (parameters: [min_value, max_value])
        2 = Normal distribution (parameters: [mean, standard_deviation])
        3 = Exponential distribution (parameters: [scale_parameter])
        4 = Binomial distribution (parameters: [trials, success_probability])
    distribution_parameters (List[float]): Distribution parameter list
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing random value and distribution information, formatted as:
    {
        "requestId": "Generated request ID",
        "randomValue": Generated random value,
        "distributionMetadata": {
            "distributionType": Distribution type,
            ...Distribution parameters
        }
    }

Application Scenarios:
1. Financial market simulation (return distribution, risk analysis)
2. Natural phenomena simulation (particle distribution, noise generation)
3. Load testing (user behavior distribution)
4. Statistical sampling (experimental data generation)

Inputs: distribution_parameters (required), distribution_type (required), salt.

generate_random_arrayA

Random Array Generator

Generate a random array of specified length

Args:
    salt (str, optional): Random number salt value. Defaults to "".
    array_length (int, optional): Array length. Defaults to 1.
    min_value (int, optional): Minimum value. Defaults to 0.
    max_value (int, optional): Maximum value. Defaults to 1000000.
    allow_duplicates (bool, optional): Allow duplicate values. Defaults to True.

Returns:
    str: JSON string containing the random array

Application Scenarios:
1. Batch random number generation
2. Random sampling
3. Test dataset generation
4. Random task assignment

Inputs: allow_duplicates, array_length, max_value, min_value, +1 more.

generate_random_eventA

Random Event Trigger

Trigger a series of events based on given probabilities, each event has an independent trigger probability.
Uses bitmap to record trigger status for easy processing.

Args:
    event_count (int): Total number of events
    event_probabilities (List[int]): Trigger probability for each event (0-1000, representing 0-100%)
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing event trigger results, formatted as:
    {
        "requestId": "Generated request ID",
        "triggeredEvents": Event trigger bitmap,
        "eventResults": [
            {
                "eventId": Event ID,
                "probability": Trigger probability,
                "triggered": Whether triggered,
                "randomValue": Random value
            },
            ...
        ]
    }

Application Scenarios:
1. Game random events (trigger plot, drop items)
2. Probability effect determination (skill trigger, combo determination)
3. Risk event simulation (fault prediction, accident events)
4. Multiple condition determination (combined probability events)

Inputs: event_count (required), event_probabilities (required), salt.

generate_random_featureA

Random Feature Allocator

Generate a set of random feature values for objects, each feature value within its specified range.
Feature values are encoded into a bitmap, with each feature occupying 8 bits.

Args:
    feature_count (int): Number of features to generate
    feature_max_values (List[int]): List of maximum values for each feature, length must equal feature_count
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing feature values and bitmap, formatted as:
    {
        "requestId": "Generated request ID",
        "features": [List of feature values],
        "featureBitmap": Feature bitmap value
    }

Application Scenarios:
1. Game character attribute generation (strength, agility, intelligence, etc.)
2. Equipment attribute randomization (attack, defense, speed, etc.)
3. Biological trait simulation (genes, traits, etc.)
4. Random scene generation (terrain, weather, environment, etc.)

Inputs: feature_count (required), feature_max_values (required), salt.

generate_random_seedA

Random Seed Generator

Generate high-entropy random seed for encryption or other scenarios requiring high-quality random numbers.
Uses blockchain hash as entropy source to ensure randomness.

Args:
    seed_length (int): Length of seed to generate (in bytes)
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing random seed, formatted as:
    {
        "requestId": "Generated request ID",
        "randomSeed": "Random seed in hexadecimal format",
        "entropy": Estimated entropy value
    }

Application Scenarios:
1. Key generation (encryption keys, signature seeds)
2. Security tokens (session identifiers, authentication tokens)
3. Random number initialization (PRNG seeds, simulation initial states)
4. Unique identifier generation (UUID seeds, random identifiers)

Inputs: seed_length (required), salt.

generate_random_weightedA

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)

Inputs: options (required), weights (required), salt.

generate_rarityC

Rarity Distributor Args: item_count: Number of items rarity_tiers: Array of rarity tiers rarity_percentages: Probability percentage for each rarity tier guaranteed_minimums: Minimum guaranteed count for each rarity tier (optional) salt: Additional entropy source

Inputs: item_count (required), rarity_percentages (required), rarity_tiers (required), guaranteed_minimums, +1 more.

shuffle_arrayA

Random Array Shuffler

Randomly shuffle the input array, ensuring each element has an equal probability of appearing in any position.
Uses Fisher-Yates shuffle algorithm to ensure fairness.

Args:
    input_array (List): Array to be shuffled, elements can be of any type
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing the shuffled array, formatted as:
    {
        "requestId": "Generated request ID",
        "shuffledArray": [Shuffled array]
    }

Application Scenarios:
1. Game shuffling (playing cards, mahjong tiles)
2. Random ordering (question order, playlist)
3. Random grouping (team assignment, experiment grouping)
4. Data shuffling (training dataset, test cases)

Inputs: input_array (required), salt.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 10 tools

    Disambiguation3/5

    The tools have overlapping purposes in random generation, with multiple tools generating random numbers or arrays (e.g., generate_basic_random, generate_random_array, generate_distribution). However, descriptions clarify distinctions like coordinate generation, distribution types, or weighted selection, helping agents differentiate between them. Some ambiguity remains, such as between generate_random_array and shuffle_array for array manipulation.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with a clear 'generate_' or 'shuffle_' prefix, making them predictable and readable. The naming convention is uniform across all tools, with no mixing of styles or deviations, which aids in easy identification and usage.

    Tool Count4/5

    With 10 tools, the count is reasonable for a random generation server, covering various aspects like basic numbers, coordinates, distributions, and shuffling. It's slightly heavy but well-scoped, as each tool addresses a specific niche in random generation without being excessive for the domain.

    Completeness4/5

    The toolset covers a broad range of random generation scenarios, including numbers, arrays, distributions, events, and seeds, with no obvious gaps for core functionalities. Minor gaps might include lack of tools for random string generation or more advanced statistical distributions, but the existing set supports most common use cases effectively.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Production-ready MCP server that provides LLMs with essential random generation abilities, including random integers, floats, choices, shuffling, and cryptographically secure tokens.
      7
      156 PyPI
      50
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Generates random integers within a specified range and random alphanumeric strings of specified length through MCP protocol integration.
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An encrypted and secure random number generation server that complies with the MCP protocol, suitable for AI applications, LLMS, and other systems that require high-quality random numbers.
      7
      2
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      MCP server providing true randomness capabilities to Claude, enabling cryptographically secure random number generation for games, decision-making, sampling, simulations, and any operation requiring genuine randomness.
      13
      2
      MIT