Random Web3 Mcp

RandomWeb3MCP - Web3 ランダム要素生成サービス

RandomWeb3MCP は、EVM ブロックハッシュに基づくランダム要素生成サービスです。ゲーム、金融、テストなど、さまざまな分野で使用できるランダム要素生成ツールを提供します。

特徴

• 検証可能性：すべての乱数はブロックチェーンのハッシュに基づいて生成され、公平性と検証可能性が確保されます
• 多様性：基本的な乱数から複雑な確率分布まで、さまざまな乱数生成シナリオに対応します
• 信頼性：ブロックチェーンをエントロピーソースとして使用し、乱数の品質を確保します
• 使いやすさ：シンプルで直感的な API インターフェースを提供し、簡単に統合できます

インストール

git clone [email protected]: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"]
    }
  }
}

ツール一覧

generate_basic_random

名前

基本的な乱数ジェネレーター

機能

指定した範囲内のランダムな整数を生成します

パラメーター

• min_value (int, optional)：最小値（含む）。デフォルトは 0 です。
• max_value (int, optional)：最大値（含む）。デフォルトは 1000000 です。
• salt (str, optional)：ランダム性を高めるための乱数ソルト値。デフォルトは '' です

戻り値

乱数の結果を含む JSON 文字列

使用例

1. 抽選システム
2. ゲームの乱数
3. ランダム ID の生成
4. テストデータの生成

generate_random_array

名前

ランダム配列ジェネレーター

機能

指定した長さのランダム配列を生成します

パラメーター

• array_length (int, optional)：配列の長さ。デフォルトは 1 です。
• min_value (int, optional)：最小値。デフォルトは 0 です。
• max_value (int, optional)：最大値。デフォルトは 1000000 です。
• salt (str, optional)：乱数ソルト値。デフォルトは '' です

戻り値

ランダム配列を含む JSON 文字列

使用例

1. 乱数の一括生成
2. ランダムサンプリング
3. テストデータセットの生成
4. ランダムなタスク割り当て

generate_random_weighted

名前

重み付きランダム選択ツール

機能

重みに基づいてオプションをランダムに選択します

パラメーター

• options (List[str])：オプションのリスト
• weights (List[int])：対応する重みのリスト（0-1000）
• salt (str, optional)：乱数ソルト値。デフォルトは '' です

戻り値

選択結果を含む JSON 文字列

使用例

1. 抽選システム（確率の異なる賞品）
2. ランダムドロップ（重み付きアイテムドロップ）
3. タスク割り当て（優先度に基づく）
4. A/B テスト（比率の異なる実験グループ）

generate_random_feature

名前

ランダム特徴割り当てツール

機能

オブジェクトに対してランダムな特徴値のセットを生成します。各特徴値は指定範囲内の値になります。特徴値はビットマップにエンコードされ、各特徴は 8 ビットを占めます

パラメーター

• feature_count (int)：生成する特徴の数
• feature_max_values (List[int])：各特徴の最大値のリスト。長さは feature_count と等しくなければなりません
• salt (str, optional)：ランダム性を高めるための乱数ソルト値。デフォルトは '' です

戻り値

特徴値とビットマップを含む JSON 文字列。形式は次のとおりです：

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

使用例

1. ゲームキャラクターの属性生成（力、敏捷性、知性など）
2. 装備属性のランダム化（攻撃力、防御力、速度など）
3. 生物学的特性のシミュレーション（遺伝子、特性など）
4. ランダムなシーンの生成（地形、天候、環境など）

generate_distribution

名前

確率分布ランダムジェネレーター

機能

指定した確率分布の種類とパラメーターに従って乱数を生成します。一般的なさまざまな確率分布に対応しています。

パラメーター

• distribution_type (int)：分布タイプ：
  • 1 = 一様分布（パラメーター：[min_value, max_value]）
  • 2 = 正規分布（パラメーター：[mean, standard_deviation]）
  • 3 = 指数分布（パラメーター：[scale_parameter]）
  • 4 = 二項分布（パラメーター：[trials, success_probability]）
• distribution_parameters (List[float])：分布パラメーターのリスト
• salt (str, optional)：乱数のランダム性を高めるためのソルト値。デフォルトは '' です。

戻り値

ランダム値と分布情報を含む JSON 文字列。形式は次のとおりです：

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

適用シナリオ

1. 金融市場のシミュレーション（リターン分布、リスク分析）
2. 自然現象のシミュレーション（粒子分布、ノイズ生成）
3. 負荷テスト（ユーザー行動の分布）
4. 統計的サンプリング（実験データの生成）

generate_random_event

名前

ランダムイベントトリガー

機能

指定された確率に基づいて一連のイベントをトリガーします。各イベントには独立したトリガー確率があります。トリガー状態をビットマップに記録するため、簡単に処理できます。

パラメーター

• event_count (int)：イベントの総数
• event_probabilities (List[int])：各イベントのトリガー確率（0～1000、0～100％を表します）
• salt (str, optional)：乱数のランダム性を高めるためのソルト値。デフォルトは '' です。

戻り値

イベントのトリガー結果を含む 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. 複数条件の判定（複合確率イベント）

generate_random_seed

名前

ランダムシードジェネレーター

機能

暗号化や高品質な乱数が必要なその他のシナリオ向けに、高エントロピーのランダムシードを生成します。エントロピー源としてブロックチェーンのハッシュを使用し、ランダム性を確保します。

パラメーター

• seed_length (int)：生成するシードの長さ（バイト単位）
• salt (str, optional)：乱数のランダム性を高めるためのソルト値。デフォルトは '' です。

戻り値

ランダムシードを含む JSON 文字列。形式は次のとおりです：

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

適用シナリオ

1. キー生成（暗号化キー、署名シード）
2. セキュリティトークン（セッション識別子、認証トークン）
3. 乱数の初期化（PRNG シード、シミュレーションの初期状態）
4. 一意の識別子の生成（UUID シード、ランダム識別子）

shuffle_array

名前

ランダム配列シャッフラー

機能

入力配列をランダムにシャッフルします。各要素がどの位置にも等しい確率で現れるようにします。公平性を確保するため、Fisher-Yates シャッフルアルゴリズムを使用します。

パラメーター

• input_array (List)：シャッフルする配列。要素には任意の型を指定できます
• salt (str, optional)：乱数のランダム性を高めるためのソルト値。デフォルトは '' です。

戻り値

シャッフルされた配列を含む JSON 文字列。形式は次のとおりです：

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

適用シナリオ

1. ゲームでのシャッフル（トランプ、麻雀牌）
2. ランダムな順序付け（質問の順序、プレイリスト）
3. ランダムなグループ分け（チーム割り当て、実験グループ分け）
4. データのシャッフル（トレーニングデータセット、テストケース）

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
        ...
    ]
}

アプリケーションシナリオ

1. ゲームオブジェクトの配置（NPC の位置、アイテムの分布）
2. パーティクルシステム（エフェクトの生成、パーティクルの分布）
3. マップ生成（地形の高度、リソースの分布）
4. 空間サンプリング（3D モデリング、空間分析）

generate_rarity

名前

レアリティのランダム割り当て

機能

指定された次元空間内でランダムな座標点を生成します。各次元には独自の値の範囲があります。任意の数の次元で座標を生成できます。

パラメーター

• item_count：アイテム数
• rarity_tiers：レアリティレベルの配列
• rarity_percentages：各レアリティレベルの確率（パーセンテージ）
• guaranteed_minimums：各レアリティレベルの保証数量（任意）
• salt (str, optional)：ランダム性を高めるための乱数ソルト値です。デフォルトは '' です

戻り値

ランダムなレアリティ配列を含む JSON 文字列です。形式は次のとおりです：

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

アプリケーションシナリオ

1. ゲームアイテムのドロップ（レアリティの異なる装備、アイテム）
2. 抽選システム（当選確率の異なる賞品）
3. リソース割り当て（レアリティの異なるリソース、素材）
4. ランダムイベントの発生（確率の異なるイベント）

アプリケーションシナリオ

ゲーム開発

• ランダムなアイテムドロップ
• キャラクター属性の生成
• マップのランダム生成
• 確率イベントの発生

金融アプリケーション

• リスクシミュレーション
• 投資ポートフォリオ分析
• 市場行動のシミュレーション

テストデータ

• ランダムなテストケースの生成
• 負荷テストデータ
• パフォーマンステスト用サンプル

科学計算

• モンテカルロシミュレーション
• パーティクルシステムのシミュレーション
• ランダムサンプリング

注意事項

1. すべての乱数生成は Trust Chain のブロックチェーンハッシュに依存するため、ネットワークが正常に接続されていることを確認してください
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 を使用しています。詳細は LICENSE ファイルを参照してください。