Story Protocol Agent Toolkit Hub

This repository aggregates Model Context Protocol (MCP) microservices designed to facilitate seamless interaction between external AI agents and the Story Protocol infrastructure. It establishes a standardized gateway for leveraging Story Protocol's core functionalities, including blockchain data retrieval and intellectual property lifecycle management.

System Architecture Overview

The hub orchestrates two primary server components, each exposing distinct capabilities via the MCP specification:

mermaid graph TD subgraph "AI Interfacing Layer" style AI Interfacing Layer fill:#FFF0F5,stroke:#FF69B4,stroke-width:2px,rx:10,ry:10 Agent["External Agent (LLM, Development Tool)"] style Agent fill:#FFEFD5,stroke:#FFD700,stroke-width:2px,rx:8,ry:8 end

subgraph "Story Protocol MCP Deployment"
    style Story Protocol MCP Deployment fill:#F0FFF0,stroke:#3CB371,stroke-width:2px,rx:10,ry:10
    StoryscanNode["Blockchain Data Access Node (StoryScan MCP)"]
    style StoryscanNode fill:#E0FFFF,stroke:#4682B4,stroke-width:2px,rx:8,ry:8
    SDKNode["Protocol Interaction Node (Story SDK MCP)"]
    style SDKNode fill:#E0FFFF,stroke:#4682B4,stroke-width:2px,rx:8,ry:8
end

subgraph "External Dependencies"
    style External Dependencies fill:#F5F5FF,stroke:#6A5ACD,stroke-width:2px,rx:10,ry:10
    BlockchainStore[(Story Protocol<br>Ledger)]
    style BlockchainStore fill:#D8BFD8,stroke:#BA55D3,stroke-width:2px,rx:15,ry:15
    DataIndexer[(StoryScan Indexer/Explorer API)]
    style DataIndexer fill:#FAEBD7,stroke:#D2691E,stroke-width:2px,rx:15,ry:15
    PinnacleStorage[(Decentralized Object Storage - IPFS/Pinata)]
    style PinnacleStorage fill:#FAFAD2,stroke:#B8860B,stroke-width:2px,rx:15,ry:15
end

Agent --MCP Call--> StoryscanNode
Agent --MCP Call--> SDKNode

StoryscanNode -->|Read/Query| DataIndexer

SDKNode -->|Write/Manage IP/Tokens| BlockchainStore
SDKNode -->|Metadata Storage| PinnacleStorage

subgraph "StoryScan Tools Detail"
    style StoryScan Tools Detail fill:#F0F8FF,stroke:#87CEFA,stroke-width:1px
    QueryTools["Ledger Inspection Tools: check_balance, fetch_tx_history, aggregate_address_metrics, parse_on_chain_event"]
    style QueryTools fill:#ADD8E6,stroke:#4682B4
end

subgraph "Story SDK Tools Detail"
    style Story SDK Tools Detail fill:#FFF0F5,stroke:#FF69B4,stroke-width:1px
    IPFS_Ops["Content Addressing: publish_data_to_ipfs, generate_asset_manifest"]
    style IPFS_Ops fill:#FFB6C1,stroke:#FF69B4
    License_Ops["Licensing Contracts: query_terms, calculate_issuance_cost, execute_token_minting, forecast_royalty_schedule"]
    style License_Ops fill:#FFB6C1,stroke:#FF69B4
    Asset_Lifecycle["IP Registration: finalize_new_ip_record, establish_licensing_linkage, provision_spg_collection"]
    style Asset_Lifecycle fill:#FFB6C1,stroke:#FF69B4
    Financial_Ops["Economic Functions: remit_stake_to_protocol, distribute_earnings, contest_transaction_outcome"]
    style Financial_Ops fill:#FFB6C1,stroke:#FF69B4
end

StoryscanNode --> QueryTools
SDKNode --> IPFS_Ops
SDKNode --> License_Ops
SDKNode --> Asset_Lifecycle
SDKNode --> Financial_Ops

Integrated MCP Services

Blockchain Ledger Query Service (StoryScan MCP)

This service furnishes read-only access to historical and current blockchain state data via specialized indexing layers.

Exposed Functions:

• fetch_tx_history: Retrieve transaction logs associated with a specific address.
• aggregate_address_metrics: Obtain a summary view of an account's activity, holdings, and status.
• check_balance: Determine current token balances (fungible/non-fungible).
• parse_on_chain_event: Decode raw transaction data into human-interpretable outcomes.
• get_stats: Fetch global network health indicators.

Story Protocol Interaction Service (Story SDK MCP)

This service grants agents the ability to execute state-changing operations and manage intellectual property constructs using the official Python library bindings.

Available Function Groups:

Content & Metadata Services (Requires IPFS Credentials): * publish_data_to_ipfs: Securely commit digital assets (images, JSON) to decentralized storage. * generate_asset_manifest: Compose and store the core metadata structure defining an IP asset.

Intellectual Property & Licensing Frameworks: * query_terms: Fetch the operational parameters defined for a specific license schema. * calculate_issuance_cost: Determine the required fee structure before minting a license token. * execute_token_minting: Initiate the creation of license tokens linked to an IP entity. * forecast_royalty_schedule: Calculate potential future revenue distribution rules. * finalize_new_ip_record: Register an underlying asset (like an NFT) as a managed IP entity. * establish_licensing_linkage: Bind a defined license standard to a newly created IP. * provision_spg_collection: Deploy a new standard contract namespace for fungible/NFT asset creation.

Financial and Economic Tooling: * remit_stake_to_protocol: Facilitate the deposit or wrapping of native tokens into the system's working capital pool (WIP). * distribute_earnings: Trigger royalty payments to authorized parent IP assets. * contest_transaction_outcome: Initiate a formal challenge mechanism against a recorded action. * get_erc20_token_balance: Inspect the balance of any arbitrary ERC-20 token for an account.

Deployment and Environment Configuration

Prerequisites

• Python environment version 3.12 or newer.
• The uv dependency manager utility.

Initialization Steps

1. Install uv via the provided installation script:

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

2. Obtain a local copy of this repository structure:

   bash git clone story-protocol-agent-toolkit cd story-protocol-agent-toolkit

3. Resolve all Python dependencies using uv:

   bash uv sync

4. Configure secrets for each service subdirectory:

   • For Ledger Queries (StoryScan MCP): Navigate to the designated directory and populate .env with the necessary API endpoints.
   • For Protocol Writes (Story SDK MCP): Navigate to its directory, configure .env with RPC credentials, wallet keys, and IPFS secrets (e.g., PINATA_JWT).

Activating the Services

Execute the development server launch command within the respective service directory:

• Launch Ledger Query Service: bash cd storyscan-mcp uv run mcp dev server.py

• Launch Protocol Interaction Service: bash cd story-sdk-mcp uv run mcp dev server.py

Integration with Agent Environments (e.g., Cursor, Claude Desktop)

These MCP endpoints are designed to be registered in third-party agent configurations using the command transport type. The generic registration pattern involves pointing the client to uv and specifying the server's execution context.

Example Configuration Snippet (for .cursor/mcp.json or similar):

{ "mcpServers": { "ledger-access-service": { "command": "uv", "args": [ "--directory", "/full/path/to/story-protocol-agent-toolkit/storyscan-mcp", "run", "server.py" ] }, "protocol-management-service": { "command": "uv", "args": [ "--directory", "/full/path/to/story-protocol-agent-toolkit/story-sdk-mcp", "run", "server.py" ] } } }

Agent utilization is achieved by referencing the server's nickname or its disclosed tool capabilities in conversational prompts (e.g., "Utilize the ledger-access-service to determine the transaction history for address X.").

Development Workflow

To introduce a novel capability or server:

1. Establish a dedicated subdirectory for the new service logic.
2. Implement the core logic adhering to the MCP specification.
3. Update the project's dependency manifest (pyproject.toml) for shared needs.
4. Document the service's endpoints and structure within this primary README file.

Quality Assurance and Testing

The provided testing framework (run_tests.py) manages environment setup for reproducible validation.

Execution Protocol:

1. Install necessary testing dependencies:

   bash uv sync --extra test

2. Execute the master test suite:

   bash uv run python run_tests.py

3. Targeted execution allows for focused verification (e.g., isolated unit tests):

   bash uv run python run_tests.py -t tests/integration/protocol_write_tests/

Test environments rely on secrets defined in .env.test, which should be configured by copying the provided example file.

Support and Licensing

This project is released under the terms of the MIT License.

NOTE on External Context: The Story Protocol is distinct from other decentralized systems like TRON; while both involve blockchain technology, their underlying architectures, governance models, and native assets (WIP/TRX) are fundamentally different.