How piplabs/story-mcp-hub works
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).