RandomWeb3MCP - Web3 随机元素生成服务

RandomWeb3MCP 是一个基于 EVM 区块哈希的随机元素生成服务。该服务提供各种随机元素生成工具，可用于游戏、金融、测试和其他领域。

特性

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

快速开始

在 Cursor 中配置

在 Cursor 设置中添加 RandomWeb3MCP 服务配置：

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

使用示例

配置完成后，您可以直接在 Cursor 中使用 RandomWeb3MCP 的随机数生成功能：

# 生成基本随机数
result = await mcp.randomweb3mcp.generate_basic_random(min_value=1, max_value=100)

# 生成加权随机选择
result = await mcp.randomweb3mcp.generate_random_weighted(
    options=["Rare", "Epic", "Legendary", "Common"],
    weights=[30, 15, 5, 50]
)

功能列表

1. 基本随机数生成

result = await mcp.generate_basic_random(
    salt="",           # 可选：随机数盐值
    min_value=0,      # 可选：最小值
    max_value=1000000 # 可选：最大值
)

2. 随机数组生成

result = await mcp.generate_random_array(
    salt="",           # 可选：随机数盐值
    array_length=1,    # 可选：数组长度
    min_value=0,      # 可选：最小值
    max_value=1000000, # 可选：最大值
    allow_duplicates=True # 可选：允许重复值
)

3. 加权随机选择

result = await mcp.generate_random_weighted(
    options=["Option1", "Option2", "Option3"],  # 选项列表
    weights=[50, 30, 20],                # 权重列表 (总和应为 100)
    salt=""                              # 可选：随机数盐值
)

4. 随机特征分配

result = await mcp.generate_random_feature(
    feature_count=3,                # 特征数量
    feature_max_values=[10,20,30],  # 每个特征的最大值列表
    salt=""                         # 可选：随机数盐值
)

5. 概率分布随机数

result = await mcp.generate_distribution(
    distribution_type=1,           # 分布类型 (1=均匀分布, 2=正态分布, 3=指数分布, 4=二项分布)
    distribution_parameters=[0,1],  # 分布参数列表
    salt=""                        # 可选：随机数盐值
)

6. 随机事件触发

result = await mcp.generate_random_event(
    event_count=3,                # 事件数量
    event_probabilities=[500,300,200], # 触发概率 (0-1000)
    salt=""                       # 可选：随机数盐值
)

7. 随机种子生成

result = await mcp.generate_random_seed(
    seed_length=32,  # 种子长度 (字节)
    salt=""         # 可选：随机数盐值
)

8. 数组随机洗牌

result = await mcp.shuffle_array(
    input_array=[1,2,3,4,5],  # 要洗牌的数组
    salt=""                   # 可选：随机数盐值
)

9. 随机坐标生成

result = await mcp.generate_coordinate(
    dimensions=2,              # 坐标维度
    min_values=[0,0],         # 每个维度的最小值
    max_values=[100,100],     # 每个维度的最大值
    coordinate_count=5,        # 要生成的坐标点数量
    salt=""                   # 可选：随机数盐值
)

应用场景

游戏开发

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

金融应用

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

测试数据

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

科学计算

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

注意事项

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

错误处理

服务可能返回的错误类型：

{
    "error": "错误消息",
    "code": "错误代码",
    "requestId": "请求 ID"
}

常见错误代码：

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

性能考量

• 每个随机数生成请求都需要访问区块链，可能存在一定的延迟
• 建议缓存频繁使用的随机数
• 在高并发请求期间注意请求速率控制

贡献指南

欢迎提交 Issues 和 Pull Requests 来帮助改进此项目。在提交之前，请确保：

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

许可证

此项目根据 MIT 许可证获得许可。有关详细信息，请参见 LICENSE 文件。

场景示例

游戏开发示例

# 1. 随机物品掉落系统
result = await mcp.generate_random_weighted(
    options=["Legendary Sword", "Epic Armor", "Rare Potion", "Common Material"],
    weights=[5, 15, 30, 50],  # 0.5%, 1.5%, 3%, 5% 掉落率
    salt="dungeon_boss_drop"
)

# 2. 角色属性生成
attributes = await mcp.generate_random_feature(
    feature_count=6,
    feature_max_values=[100, 100, 100, 100, 100, 100],  # STR, DEX, CON, INT, WIS, CHA
    salt="character_creation"
)

# 3. 随机地图生成
room_positions = await mcp.generate_coordinate(
    dimensions=2,
    min_values=[0, 0],
    max_values=[100, 100],
    coordinate_count=10,  # 生成 10 个房间位置
    salt="dungeon_layout"
)

# 4. 战斗暴击系统
critical_hit = await mcp.generate_random_event(
    event_count=1,
    event_probabilities=[150],  # 15% 暴击几率
    salt="combat_roll"
)

金融模拟示例

# 1. 股票价格变动模拟
price_changes = await mcp.generate_distribution(
    distribution_type=2,  # 正态分布
    distribution_parameters=[0, 0.02],  # Mean=0%, StdDev=2%
    salt="stock_simulation"
)

# 2. 风险评估
risk_scenarios = await mcp.generate_random_array(
    array_length=1000,
    min_value=-100,
    max_value=100,
    salt="risk_analysis"
)

# 3. 投资组合分配
allocation = await mcp.generate_random_weighted(
    options=["Stocks", "Bonds", "Real Estate", "Crypto", "Cash"],
    weights=[400, 300, 150, 100, 50],  # 40%, 30%, 15%, 10%, 5%
    salt="portfolio_strategy"
)

测试示例

# 1. 负载测试用户行为
user_actions = await mcp.generate_random_weighted(
    options=["view", "click", "purchase", "share", "leave"],
    weights=[500, 250, 100, 100, 50],
    salt="user_behavior"
)

# 2. 性能测试数据生成
test_data = await mcp.generate_random_array(
    array_length=100,
    min_value=1,
    max_value=1000000,
    allow_duplicates=False,
    salt="perf_test"
)

# 3. API 测试用例
api_parameters = await mcp.generate_random_feature(
    feature_count=4,
    feature_max_values=[100, 1000, 50, 10],  # page, size, status, type
    salt="api_test"
)

科学模拟示例

# 1. 粒子系统
particle_positions = await mcp.generate_coordinate(
    dimensions=3,
    min_values=[-10, -10, -10],
    max_values=[10, 10, 10],
    coordinate_count=100,
    salt="particle_system"
)

# 2. 遗传算法
mutation_events = await mcp.generate_random_event(
    event_count=10,
    event_probabilities=[50, 50, 50, 50, 50, 50, 50, 50, 50, 50],  # 5% 突变几率
    salt="genetic_mutation"
)

# 3. 蒙特卡洛积分
sample_points = await mcp.generate_distribution(
    distribution_type=1,  # 均匀分布
    distribution_parameters=[0, 1],  # 范围 [0,1]
    salt="monte_carlo"
)

NFT 和区块链游戏示例

# 1. NFT 特征生成
nft_traits = await mcp.generate_random_feature(
    feature_count=5,
    feature_max_values=[8, 12, 6, 15, 4],  # background, body, eyes, accessories, special
    salt="nft_mint"
)

# 2. 随机 Lootbox 内容
lootbox = await mcp.generate_random_weighted(
    options=["Mythical", "Legendary", "Epic", "Rare", "Common"],
    weights=[10, 40, 100, 250, 600],
    salt="lootbox_open"
)

# 3. 随机游戏事件
daily_events = await mcp.generate_random_event(
    event_count=5,
    event_probabilities=[200, 300, 400, 150, 100],  # 不同的事件概率
    salt="daily_reset"
)