RandomWeb3MCP - Web3 随机元素生成服务 RandomWeb3MCP 是一个基于 EVM 区块哈希的随机元素生成服务。该服务提供了多种随机元素生成工具，可用于游戏、金融、测试等领域。 特性 可验证性：所有随机数都是基于区块链哈希生成的，确保了公平性和可验证性 多样性：支持各种随机数生成场景，从基本的随机数到复杂的概率分布 可靠性：使用区块链作为熵源，确保随机性的质量 易用性：提供简单直观的 API 接口，便于集成 安装 git clone git@git.woa.com:zhixinlian/zxl-mcp-server.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"] \} \} \} 工具列表 generate_basic_random 名称 基础随机数生成器 功能 生成指定范围内的随机整数 参数 min_value (int, 可选): 最小值（包含）。默认为 0。 max_value (int, 可选): 最大值（包含）。默认为 1000000。 salt (str, 可选): 用于增加随机性的随机数盐值。默认为空字符串。 返回 包含随机数结果的 JSON 字符串 应用场景 抽奖系统 游戏随机数 随机 ID 生成 测试数据生成 generate_random_array 名称 随机数组生成器 功能 生成指定长度的随机数组 参数 array_length (int, 可选): 数组长度。默认为 1。 min_value (int, 可选): 最小值。默认为 0。 max_value (int, 可选): 最大值。默认为 1000000。 salt (str, 可选): 随机数盐值。默认为空字符串。 返回 包含随机数组的 JSON 字符串 应用场景 批量随机数生成 随机抽样 测试数据集生成 随机任务分配 generate_random_weighted 名称 加权随机选择器 功能 根据权重随机选择一个选项 参数 options (List[str]): 选项列表 weights (List[int]): 对应的权重列表（0-1000） salt (str, 可选): 随机数盐值。默认为空字符串。 返回 包含选择结果的 JSON 字符串 应用场景 抽奖系统（不同概率的奖品） 随机掉落（加权物品掉落） 任务分配（基于优先级） A/B 测试（具有不同比例的实验组） generate_random_feature 名称 随机特征分配器 功能 为对象生成一组随机特征值，每个特征值都在其指定范围内。特征值被编码成位图，每个特征占用 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 \} 应用场景 游戏角色属性生成（力量、敏捷、智力等） 装备属性随机化（攻击、防御、速度等） 生物特征模拟（基因、性状等） 随机场景生成（地形、天气、环境等） generate_distribution 名称 概率分布随机生成器 功能 根据指定的概率分布类型和参数生成随机数。支持多种常见概率分布。 参数 distribution_type (int): 分布类型： 1 = 均匀分布（参数：[最小值, 最大值]） 2 = 正态分布（参数：[均值, 标准差]） 3 = 指数分布（参数：[尺度参数]） 4 = 二项分布（参数：[试验次数, 成功概率]） distribution_parameters (List[float]): 分布参数列表 salt (str, 可选): 用于增加随机性的随机数盐值。默认为'' 返回 包含随机值和分布信息的JSON字符串，格式如下： \{ "requestId": "Generated request ID", "randomValue": Generated random value, "distributionMetadata": \{ "distributionType": Distribution type, ...Distribution parameters \} \} 应用场景 金融市场模拟（收益分布、风险分析） 自然现象模拟（粒子分布、噪声生成） 负载测试（用户行为分布） 统计抽样（实验数据生成） generate_random_event 名称 随机事件触发 功能 基于给定的概率触发一系列事件，每个事件都有独立的触发概率。使用位图记录触发状态以便于处理。 参数 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 \}, ... ] \} 应用场景 游戏随机事件（触发剧情、掉落物品） 概率效果判定（技能触发、连击判定） 风险事件模拟（故障预测、事故事件） 多条件判定（组合概率事件） generate_random_seed 名称 随机种子生成器 功能 为加密或其他需要高质量随机数的场景生成高熵随机种子。使用区块链哈希作为熵源以确保随机性。 参数 seed_length (int): 要生成的种子长度（以字节为单位） salt (str, 可选): 用于增加随机性的随机数盐值。默认为'' 返回 包含随机种子的 JSON 字符串，格式如下： \{ "requestId": "Generated request ID", "randomSeed": "Random seed in hexadecimal format", "entropy": Estimated entropy value \} 应用场景 密钥生成（加密密钥、签名种子） 安全令牌（会话标识符、认证令牌） 随机数初始化（PRNG 种子、模拟初始状态） 唯一标识符生成（UUID 种子、随机标识符） shuffle_array 名称 随机数组打乱器 功能 随机打乱输入数组，确保每个元素出现在任何位置的概率相等。使用 Fisher-Yates 打乱算法以确保公平性。 参数 input_array (List): 要被打乱的数组，元素可以是任何类型 salt (str, optional): 用于增加随机性的随机数盐值，默认为 '' 返回 包含打乱后数组的 JSON 字符串，格式如下： \{ "requestId": "Generated request ID", "shuffledArray": [Shuffled array] \} 应用场景 游戏洗牌（扑克牌、麻将牌） 随机排序（问题顺序、播放列表） 随机组队（团队分配、实验分组） 数据打乱（训练数据集、测试案例） generate_coordinate 名称 随机坐标生成器 功能 在指定维度空间中生成随机坐标点，每个维度都有自己的值范围。支持任意维度的坐标生成。 参数 dimensions (int): 坐标维度数量（1D、2D、3D 等） min_values (List[float]): 每个维度的最小值列表 max_values (List[float]): 每个维度的最大值列表 coordinate_count (int): 要生成的坐标点数量 salt (str, optional): 用于增加随机性的随机数盐值，默认为 '' 返回 包含随机坐标的 JSON 字符串，格式如下： \{ "requestId": "Generated request ID", "coordinates": [ [x1, y1, z1, ...], # First point coordinates [x2, y2, z2, ...], # Second point coordinates ... ] \} 应用场景 游戏对象定位（NPC 位置、物品分布） 粒子系统（效果生成、粒子分布） 地图生成（地形高度、资源分布） 空间采样（3D 建模、空间分析） generate_rarity 名称 稀有度随机分配器 功能 在指定维度空间中生成随机坐标点，每个维度都有自己的值范围。支持任意维度的坐标生成。 参数 item_count: 项目数量 rarity_tiers: 稀有度等级数组 rarity_percentages: 每个稀有度等级的概率百分比 guaranteed_minimums: 每个稀有度等级的保证数量（可选） salt (str, optional): 用于增加随机性的随机数盐值，默认为 '' 返回 包含随机稀有度数组的 JSON 字符串，格式如下： \{ "requestId": "Generated request ID", "rarityDistribution": [Rarity allocation result] \} 应用场景 游戏掉落物（不同稀有度的装备、物品） 抽奖系统（不同概率的奖品） 资源分配（不同稀有度的资源、材料） 随机事件触发（不同概率的事件） 应用场景 游戏开发 随机物品掉落 角色属性生成 地图随机生成 概率事件触发 金融应用 风险模拟 投资组合分析 市场行为模拟 测试数据 随机测试用例生成 负载测试数据 性能测试样本 科学计算 蒙特卡洛模拟 粒子系统模拟 随机抽样 注意事项 所有随机数生成依赖于 Trust Chain 的区块链哈希，请确保网络连接正常 加权随机选择器的权重值范围是0-1000，代表0-100%的概率 概率分布参数需要根据特定的分布类型提供正确的参数列表 建议在生产环境中使用盐参数以增加随机性 错误处理 服务可能返回的错误类型： \{ "error": "Error message", "code": "Error code", "requestId": "Request ID" \} 常见的错误代码： INVALID_PARAMS: 参数错误 NETWORK_ERROR: 网络连接错误 CHAIN_ERROR: 区块链访问错误 INTERNAL_ERROR: 内部服务错误 性能考虑 每次随机数生成请求都需要访问区块链，可能会有一定的延迟 建议缓存常用的随机数 在处理大量并发请求时请注意请求频率 贡献指南 欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。在提交之前，请确保： 代码符合 PEP 8 规范 添加了适当的测试用例 更新相关文档 许可证 本项目使用 MIT 许可证。详见 LICENSE 文件。