Story SDK MCP Server

Story MCP Hub

このリポジトリは、Story Protocol の Model Context Protocol（MCP）サーバーの中央ハブとして機能します。AI エージェントが Story Protocol のエコシステムとやり取りできるようにする各種 MCP サービスを実行・管理するための統一された環境を提供します。

プロジェクト構成

story-mcp-hub/
├── storyscan-mcp/       # MCP server for blockchain data queries via StoryScan
├── story-sdk-mcp/       # MCP server for Story Protocol SDK interactions
├── utils/               # Shared utilities for MCP servers
├── .venv/               # Python virtual environment
├── pyproject.toml       # Project dependencies and configuration
├── .python-version      # Python version specification
└── README.md            # This file

graph TD
    subgraph "MCP Hub"
        style MCP Hub fill:#F5F5FF,stroke:#9999CC,stroke-width:2px,rx:10,ry:10
        Agent["AI Agent<br>(Claude, IDEs, Tools)"]
        style Agent fill:#E6E6FA,stroke:#9370DB,stroke-width:2px,rx:8,ry:8
    end

    subgraph "StoryScan MCP Server"
        style StoryScan MCP Server fill:#F0F8FF,stroke:#87CEFA,stroke-width:2px,rx:10,ry:10
        StoryscanService["StoryScan Service"]
        style StoryscanService fill:#E6E6FA,stroke:#9370DB,stroke-width:2px,rx:8,ry:8

        subgraph "StoryScan Tools"
            style StoryScan Tools fill:#F0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:10,ry:10
            StoryscanToolset["Blockchain Data<br>get_transactions,<br>get_address_overview,<br>get_token_holdings,<br>get_nft_holdings,<br>get_stats,<br>interpret_transaction"]
            style StoryscanToolset fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
        end
    end

    subgraph "Story SDK MCP Server"
        style Story SDK MCP Server fill:#F5FFFA,stroke:#98FB98,stroke-width:2px,rx:10,ry:10
        StoryService["Story Service"]
        style StoryService fill:#E6E6FA,stroke:#9370DB,stroke-width:2px,rx:8,ry:8

        subgraph "Story SDK Tools"
            style Story SDK Tools fill:#F0FFF0,stroke:#90EE90,stroke-width:2px,rx:10,ry:10
            IPFSTools["IPFS & Metadata<br>upload_image_to_ipfs<br>create_ip_metadata"]
            style IPFSTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
            LicenseTools["License Management<br>get_license_terms,<br>mint_license_tokens,<br>get_license_minting_fee,<br>predict_minting_license_fee"]
            style LicenseTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
            IPTools["IP & NFT Management<br>register, attach_license_terms,<br>mint_and_register_ip_with_terms,<br>create_spg_nft_collection"]
            style IPTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
            TokenTools["Token & Revenue<br>deposit_wip, transfer_wip,<br>pay_royalty_on_behalf,<br>claim_all_revenue,<br>raise_dispute"]
            style TokenTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
        end
    end

    subgraph "External Resources"
        style External Resources fill:#FFF0F5,stroke:#FFB6C1,stroke-width:2px,rx:10,ry:10
        IPFS[(IPFS/Pinata<br>Storage)]
        style IPFS fill:#FFE4E1,stroke:#DB7093,stroke-width:2px,rx:15,ry:15
        Blockchain[(Story Protocol<br>Blockchain)]
        style Blockchain fill:#E0F8E0,stroke:#90EE90,stroke-width:2px,rx:15,ry:15
        StoryScan[(StoryScan/Blockscout<br>API)]
        style StoryScan fill:#E6F3FF,stroke:#87CEFA,stroke-width:2px,rx:15,ry:15
    end

    Agent <--MCP Protocol--> StoryService
    Agent <--MCP Protocol--> StoryscanService
    StoryscanService --> StoryscanToolset
    StoryService --> IPFSTools
    StoryService --> LicenseTools
    StoryService --> IPTools
    StoryService --> TokenTools

    StoryscanToolset <--API Calls--> StoryScan
    IPFSTools <--API Calls--> IPFS
    LicenseTools <--RPC Calls--> Blockchain
    IPTools <--RPC Calls--> Blockchain
    TokenTools <--RPC Calls--> Blockchain

MCP サーバー

StoryScan MCP サーバー

アドレスの残高、トランザクション、ブロックチェーンの統計情報など、ブロックチェーンデータを照会するツールを提供します。

ツール：

• get_transactions：アドレスの最近のトランザクションを取得します
• get_stats：現在のブロックチェーン統計情報を取得します
• get_address_overview：残高、トークン情報、ブロックチェーン上のアクティビティを含む、アドレスの包括的な概要を取得します
• get_token_holdings：詳細なトークン情報と残高を含む、アドレスが保有するすべての ERC-20 トークンを取得します
• get_nft_holdings：コレクション情報と個々のトークンのメタデータを含む、アドレスが保有するすべての NFT を取得します
• interpret_transaction：ブロックチェーン上のトランザクションを人間が読みやすい形式で解釈します

Story SDK MCP サーバー

Story Protocol の Python SDK を操作するツールを提供します。

ツール：

IPFS とメタデータのツール（PINATA_JWT が必要）：

• upload_image_to_ipfs：Pinata API を使用して画像を IPFS にアップロードし、URI を返します
• create_ip_metadata：NFT と IP の両方のメタデータを作成し、IPFS にアップロードします

ライセンス管理ツール：

• get_license_terms：指定した ID のライセンス条件を取得します
• get_license_minting_fee：指定したライセンス条件 ID のミント手数料を取得します
• get_license_revenue_share：指定したライセンス条件 ID の商業収益の分配率を取得します
• mint_license_tokens：指定した IP とライセンス条件のライセンストークンをミントします（WIP トークンを自動承認します）
• predict_minting_license_fee：指定した IP、ライセンス条件、数量に対するライセンスのミント手数料を事前計算します

IP アセット管理ツール：

• register：NFT を IP として登録し、対応する IP レコードを作成します
• attach_license_terms：IP アセットにライセンス条件を適用します
• mint_and_register_ip_with_terms：ライセンス条件付きで IP をミントし、登録します

NFT コレクションツール：

• create_spg_nft_collection：IP アセットのミントと登録に使用できる、新しい SPG NFT コレクションを作成します
• get_spg_nft_minting_token：SPG NFT コントラクトで必要なミント手数料を取得します

収益とロイヤリティのツール：

• pay_royalty_on_behalf：支払元 IP アセットに代わって受取先 IP アセットにロイヤリティを支払います（トークンを自動承認します）
• claim_all_revenue：オプションの自動送金を使用して、祖先 IP の子 IP からすべての収益を請求します

紛争ツール：

• raise_dispute：IP アセットに対する紛争を申し立てます（WIP の保証金トークンを自動承認します）

トークン管理ツール：

• deposit_wip：IP を WIP にラップし、ウォレットに入金します
• transfer_wip：WIP トークンを受取人に送金します
• get_erc20_token_balance：アカウントが保有する任意の ERC20 トークンの残高を取得します
• mint_test_erc20_tokens：コントラクトにパブリックなミント／ファウセット関数がある場合、テスト用 ERC20 トークンをミントします

セットアップ

前提条件

• Python 3.12+
• UV パッケージマネージャー

インストール

1. UV パッケージマネージャーをインストールし、環境をセットアップします：

curl -LsSf https://astral.sh/uv/install.sh | sh

2. このリポジトリをクローンします：

git clone https://github.com/piplabs/story-mcp-hub.git
cd story-mcp-hub

3. UV を使用して依存関係をインストールします：

uv sync

4. 各サーバーの環境変数を設定します：

StoryScan MCP の場合：

cd storyscan-mcp
cp .env.example .env
# Edit .env with your StoryScan API endpoint

Story SDK MCP の場合：

cd story-sdk-mcp
cp .env.example .env
# Edit .env with your wallet private key, RPC provider URL, etc.

サーバーの実行

StoryScan MCP サーバーインスペクター

cd storyscan-mcp
uv run mcp dev server.py

Story SDK MCP サーバー

cd story-sdk-mcp
uv run mcp dev server.py

MCP クライアントでの使用

以下の手順に従って、MCP サーバーをさまざまな MCP 対応クライアントに接続します。

Cursor

Cursor は、stdio と sse の両方のトランスポートを使用して任意の数の MCP サーバーをサポートする MCP クライアントを実装しています。

Cursor で MCP サーバーを追加する

1. Cursor Settings > Features > MCP に移動します
2. + Add New MCP Server ボタンをクリックします
3. フォームに入力します：
   • Type でトランスポートを選択します
   • Name フィールドにサーバーのニックネームを入力します
   • トランスポートに応じて、実行するコマンドまたはサーバーの URL を入力します
   • サーバーの実行には uv コマンドを使用するため、サーバーへのパスを指定した --directory フラグを必ず含めてください（例：uv --directory ~/path/to/story-mcp-hub/storyscan-mcp run server.py）

プロジェクト固有の MCP 設定

.cursor/mcp.json を使って、プロジェクト固有の MCP サーバーを設定できます。このファイルは次の形式に従います：

{
  "mcpServers": {
    "storyscan-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "~/path/to/story-mcp-hub/storyscan-mcp",
        "run",
        "server.py"
      ]
    },
    "story-sdk-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "~/path/to/story-mcp-hub/story-sdk-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

Cursor で MCP ツールを使用する

Composer Agent は、MCP 設定ページの Available Tools に表示されている MCP ツールのうち、関連性があると判断したものを自動的に使用します。意図的にツールを使用させるには、ツール名または説明を指定して、そのツールを使うようエージェントに伝えてください。

エージェントが MCP ツールを使用しようとすると、承認を求めるメッセージが表示されます。

Claude Desktop

Claude Desktop は、設定ファイルを編集することで MCP サーバーを使用するように設定できます。

Claude Desktop で MCP サーバーを追加する

1. Claude Desktop の設定ファイルを開きます：

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. MCP サーバーの設定を追加します：

{
  "mcpServers": {
    "storyscan-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "~/path/to/story-mcp-hub/storyscan-mcp",
        "run",
        "server.py"
      ]
    },
    "story-sdk-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "~/path/to/story-mcp-hub/story-sdk-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

3. ファイルを保存し、Claude Desktop を再起動して変更を反映します。

クエリの例：use storyscan to check balance of 0x95A13F457C76d10A40D7e8497eD4F40c53F4d04b

開発

ハブに新しい MCP サーバーを追加するには：

1. サーバー用の新しいディレクトリを作成します
2. サーバーで MCP プロトコルを実装します
3. 必要な依存関係をルートの pyproject.toml に追加します
4. この README を更新して、サーバーに関する情報を記載します

テスト

テストの実行

このプロジェクトには、環境設定とテストの実行を処理するテストランナースクリプト（run_tests.py）が含まれています。テストを実行するには：

1. テストの依存関係をインストールします：

uv sync --extra test

2. すべてのテストを実行します：

uv run python run_tests.py

3. 特定のテストカテゴリを実行します：

# Run unit tests only
uv run python run_tests.py -t tests/unit/

# Run integration tests only
uv run python run_tests.py -t tests/integration/

# Run with verbose output
uv run python run_tests.py -v

4. 個別のテストファイルを実行します：

uv run python run_tests.py -t tests/unit/story_sdk_mcp/test_story_service.py

5. 使用可能なオプションについてヘルプを表示します：

uv run python run_tests.py --help

テスト環境の設定

テストでは、テスト用のモック認証情報を含む .env.test ファイルを使用します。このファイルはテストランナーによって自動的に読み込まれます。

テスト環境を設定するには：

1. サンプルファイルをコピーして、独自の .env.test を作成します：

cp .env.test.example .env.test

2. .env.test ファイルを編集し、テスト用の認証情報を記載します：

# For example, update the private key for blockchain interactions
nano .env.test  # or use your preferred text editor

テストについて詳しくは、テストガイドを参照してください。

トラブルシューティング

問題が発生した場合：

1. 各サーバーの環境変数が正しく設定されていることを確認します
2. 外部 API（StoryScan、IPFS など）へのネットワーク接続を確認します
3. 正しい Python バージョン（3.12 以降）を使用していることを確認します
4. uv sync ですべての依存関係がインストールされていることを確認します

ライセンス

MIT ライセンス