# piplabs/story-mcp-hub architecture

> Architecture diagram of the GitHub repository piplabs/story-mcp-hub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/piplabs/story-mcp-hub
- Repository: https://github.com/piplabs/story-mcp-hub

## Overview

##### Project Overview and Type
- The project is a central hub for running multiple Model Context Protocol (MCP) servers that facilitate interactions between AI agents (like Claude, IDEs, tools) and Story Protocol’s ecosystem.
- There are two primary MCP servers:
- The StoryScan MCP Server for querying blockchain data.
- The Story SDK MCP Server for interacting with Story Protocol’s SDK.
- Shared utilities in the "utils" directory support both servers.

##### Analyzing the File Structure
- Top-level directories include:
- story-sdk-mcp: Contains the server entry point (server.py), service implementations (story_service.py), environment example configuration, and a README.
- storyscan-mcp: Similarly structured for blockchain-related queries, with its own server.py, service file, and environment variables.
- utils: This directory provides common functionality such as address resolution, gas utilities, and contract addresses.
- A centralized pyproject.toml at the root manages project dependencies and configuration.
- Notice the existence of UV package manager lock files (uv.lock and story-sdk-mcp/uv.lock, etc.) which may indicate deployment specifics.

##### Key Components
- MCP Hub (central coordinating element) with an “AI Agent” representing external clients.
- Two distinct server groups as sub-components:
- StoryScan MCP Server which consists of:
◦ The StoryScan Service (implemented in storyscan_service.py).
◦ StoryScan Tools (e.g., functions such as check_balance, get_address_overview, etc.).
- Story SDK MCP Server which consists of:
◦ The Story Service (implemented in story_service.py).
◦ Story SDK Tools (e.g., IPFS Tools like upload_image_to_ipfs and create_ip_metadata, along with IP Management Tools).
- Shared utilities (from the utils directory) that support lower-level operations across the servers.
- External resources:
- IPFS/Pinata for storage.
- Story Protocol Blockchain for interacting with the blockchain.
- StoryScan/Blockscout API endpoint for blockchain data queries.

##### Design Principles and Architectural Patterns
- Clear separation of concerns: the StoryScan server and the Story SDK server do not mix functionality but communicate with external services and the central hub in defined ways.
- Shared utilities as supporting modules that are used across MCP servers.

##### Elements to Add
- Clear labels for each component:
- “MCP Hub”, “AI Agent”, “StoryScan MCP Server”, “Story SDK MCP Server”, “Shared Utilities”, and “External Resources.”

##### Putting It All Together
- Drill down into two parallel branches representing the StoryScan and Story SDK servers.
- Internal components of the servers (service implementations and the toolsets).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    AI_Agent["AI Agent"]:::hub
    MCP_Hub["MCP Hub"]:::hub
    Shared_Utils["Shared Utilities"]:::utility

    %% External Resources
    subgraph "External Resources"
        IPFS["IPFS/Pinata"]:::external
        Blockchain["Story Protocol Blockchain"]:::external
        StoryScan_API["StoryScan API Endpoint"]:::external
    end

    %% MCP Hub Interaction
    AI_Agent <--> MCP_Hub

    %% StoryScan MCP Server Subgraph
    subgraph "StoryScan MCP Server"
        StoryScan_Server["StoryScan MCP Server"]:::server
        StoryScan_Service["StoryScan Service"]:::service
        StoryScan_Tools["StoryScan Tools"]:::tools
        StoryScan_Server --> StoryScan_Service
        StoryScan_Server --> StoryScan_Tools
    end

    %% Story SDK MCP Server Subgraph
    subgraph "Story SDK MCP Server"
        StorySDK_Server["Story SDK MCP Server"]:::server
        Story_Service["Story Service"]:::service
        Story_SDK_Tools["Story SDK Tools"]:::tools
        StorySDK_Server --> Story_Service
        StorySDK_Server --> Story_SDK_Tools
    end

    %% MCP Hub connects to both Servers
    MCP_Hub --> StoryScan_Server
    MCP_Hub --> StorySDK_Server

    %% Shared Utilities used by both servers (dotted arrow represents dependency)
    StoryScan_Server -.-> Shared_Utils
    StorySDK_Server -.-> Shared_Utils

    %% External Interactions for StoryScan server
    StoryScan_Tools -->|"calls"| StoryScan_API

    %% External Interactions for Story SDK server
    Story_SDK_Tools -->|"uploads to"| IPFS
    Story_SDK_Tools -->|"queries"| Blockchain

    %% Click Events
    click StoryScan_Server "https://github.com/piplabs/story-mcp-hub/blob/main/storyscan-mcp/server.py"
    click StoryScan_Service "https://github.com/piplabs/story-mcp-hub/blob/main/storyscan-mcp/services/storyscan_service.py"
    click StorySDK_Server "https://github.com/piplabs/story-mcp-hub/blob/main/story-sdk-mcp/server.py"
    click Story_Service "https://github.com/piplabs/story-mcp-hub/blob/main/story-sdk-mcp/services/story_service.py"
    click Shared_Utils "https://github.com/piplabs/story-mcp-hub/tree/main/utils/"

    %% Styles
    classDef hub fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef server fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef service fill:#FFECB3,stroke:#F57C00,stroke-width:2px;
    classDef tools fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef utility fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
```
