RandomWeb3MCP - Web3 随机元素生成服务

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

特征

• 可验证性：所有随机数均基于区块链哈希生成，确保公平性和可验证性
• 多样性：支持各种随机数生成场景，从基本随机数到复杂的概率分布
• 可靠性：使用区块链作为熵源，确保随机性质量
• 可用性：提供简单直观的 API 接口，方便集成

安装

快速入门

tico 或 Cursor 中的配置

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

工具清单

生成基本随机数

姓名

基本随机数生成器

功能

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

参数

• 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 字符串，格式为：

应用场景

1. 游戏角色属性生成（力量、敏捷、智力等）
2. 装备属性随机化（攻击、防御、速度等）
3. 生物性状模拟（基因、性状等）
4. 随机场景生成（地形、天气、环境等）

生成分布

姓名

概率分布随机生成器

功能

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

参数

• distribution_type（int）：分布类型：
  • 1 = 均匀分布（参数：[min_value，max_value]）
  • 2 = 正态分布（参数：[平均值，标准差]）
  • 3 = 指数分布（参数：[scale_parameter]）
  • 4 = 二项分布（参数：[试验次数，成功概率]）
• distribution_parameters (List[float]): 分布参数列表
• salt（str，可选）：用于增加随机性的随机数盐值。默认为 ''

返回

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

应用场景

1. 金融市场模拟（收益分布、风险分析）
2. 自然现象模拟（粒子分布、噪声产生）
3. 负载测试（用户行为分布）
4. 统计抽样（实验数据生成）

生成随机事件

姓名

随机事件触发器

功能

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

参数

• event_count (int)：事件总数
• event_probabilities (List[int]): 每个事件的触发概率（0-1000，代表0-100%）
• salt（字符串，可选）：用于增加随机性的随机数盐值。默认为 ''

返回

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

应用场景

1. 游戏随机事件（触发剧情、掉落物品）
2. 概率效果判定（技能触发、连击判定）
3. 风险事件模拟（故障预测、事故事件）
4. 多重条件确定（组合概率事件）

生成随机种子

姓名

随机种子生成器

功能

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

参数

• seed_length（int）：要生成的种子的长度（以字节为单位）
• salt（字符串，可选）：用于增加随机性的随机数盐值。默认为 ''

返回

包含随机种子的 JSON 字符串，格式为：

应用场景

1. 密钥生成（加密密钥、签名种子）
2. 安全令牌（会话标识符、身份验证令牌）
3. 随机数初始化（PRNG种子、模拟初始状态）
4. 唯一标识符生成（UUID 种子、随机标识符）

随机数组

姓名

随机数组洗牌器

功能

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

参数

• input_array（列表）：要打乱的数组，元素可以是任何类型
• salt（字符串，可选）：用于增加随机性的随机数盐值。默认为 ''

返回

包含混洗数组的 JSON 字符串，格式如下：

应用场景

1. 游戏洗牌（扑克牌、麻将牌）
2. 随机排序（问题顺序、播放列表）
3. 随机分组（团队分配、实验分组）
4. 数据混洗（训练数据集、测试用例）

生成坐标

姓名

随机坐标生成器

功能

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

参数

• 维度（int）：坐标维度数（1D、2D、3D 等）
• min_values (List[float])：每个维度的最小值列表
• max_values (List[float])：每个维度的最大值列表
• coordinate_count（int）：要生成的坐标点的数量
• salt（str，可选）：用于增加随机性的随机数盐值。默认为 ''

返回

包含随机坐标的 JSON 字符串，格式为：

应用场景

1. 游戏对象定位（NPC位置、物品分布）
2. 粒子系统（效果生成、粒子分布）
3. 地图生成（地形高度、资源分布）
4. 空间采样（3D建模、空间分析）

生成稀有度

姓名

稀有度随机分配器

功能

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

参数

• item_count：项目数量
• rarity_tiers：稀有度等级数组
• rarity_percentages：每个稀有度等级的概率百分比
• guaranteed_minimums：每个稀有度等级的保证数量（可选）
• salt（str，可选）：用于增加随机性的随机数盐值。默认为 ''

返回

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

应用场景

1. 游戏物品掉落（不同稀有度的装备、物品）
2. 彩票系统（不同概率的奖品）
3. 资源配置（不同稀有度的资源、材料）
4. 随机事件触发（不同概率事件）

应用场景

游戏开发

• 随机物品掉落
• 角色属性生成
• 地图随机生成
• 概率事件触发

财务申请

• 风险模拟
• 投资组合分析
• 市场行为模拟

测试数据

• 随机测试用例生成
• 加载测试数据
• 性能测试样例

科学计算

• 蒙特卡罗模拟
• 粒子系统模拟
• 随机抽样

笔记

1. 所有随机数生成均依赖于信任链的区块链哈希，请确保网络连接正常
2. 加权随机选择器权重值范围是0-1000，代表0-100%的概率
3. 概率分布参数需要根据具体的分布类型提供正确的参数列表
4. 生产环境建议使用salt参数增加随机性

错误处理

服务可能返回错误类型：

常见错误代码：

• INVALID_PARAMS ：参数错误
• NETWORK_ERROR ：网络连接错误
• CHAIN_ERROR ：区块链访问错误
• INTERNAL_ERROR ：内部服务错误

性能考虑

• 每个随机数生成请求都需要访问区块链，可能会有一定的延迟
• 建议缓存经常使用的随机数
• 处理大量并发请求时要注意请求频率

贡献指南

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

1. 代码符合PEP 8规范
2. 添加适当的测试用例
3. 相关文件已更新

执照

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