Story MCP Hub

本仓库作为 Story Protocol 的模型上下文协议 (MCP) 服务器的中心枢纽。它提供了一个统一的环境，用于运行和管理各种 MCP 服务，这些服务使 AI 代理能够与 Story Protocol 的生态系统进行交互。

项目结构

story-mcp-hub/
├── storyscan-mcp/       # 用于通过 StoryScan 查询区块链数据的 MCP 服务器
├── story-sdk-mcp/       # 用于 Story Protocol SDK 交互的 MCP 服务器
├── utils/               # MCP 服务器的共享实用程序
├── .venv/               # Python 虚拟环境
├── pyproject.toml       # 项目依赖和配置
├── .python-version      # Python 版本规范
└── README.md            # 本文件

graph TD
    subgraph "MCP Hub"
        style MCP Hub fill:#F5F5FF,stroke:#9999CC,stroke-width:2px,rx:10,ry:10
        Agent["AI 代理<br>(Claude, IDEs, 工具)"]
        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 服务"]
        style StoryscanService fill:#E6E6FA,stroke:#9370DB,stroke-width:2px,rx:8,ry:8

        subgraph "StoryScan 工具"
            style StoryScan Tools fill:#F0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:10,ry:10
            StoryscanToolset["余额 & 统计<br>check_balance,<br>get_address_overview,<br>get_transactions,<br>interpret_transaction,<br>get_token_holdings,<br>get_nft_holdings,<br>get_stats"]
            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 服务"]
        style StoryService fill:#E6E6FA,stroke:#9370DB,stroke-width:2px,rx:8,ry:8

        subgraph "Story SDK 工具"
            style Story SDK Tools fill:#F0FFF0,stroke:#90EE90,stroke-width:2px,rx:10,ry:10
            IPFSTools["IPFS 工具<br>upload_image_to_ipfs<br>create_ip_metadata"]
            style IPFSTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
            IPTools["IP 管理工具<br>mint_and_register_ip_with_terms<br>get_license_terms,<br>mint_license_tokens,<br>send_ip,<br>create_spg_nft_collection"]
            style IPTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
        end
    end

    subgraph "外部资源"
        style External Resources fill:#FFF0F5,stroke:#FFB6C1,stroke-width:2px,rx:10,ry:10
        IPFS[(IPFS/Pinata<br>存储)]
        style IPFS fill:#FFE4E1,stroke:#DB7093,stroke-width:2px,rx:15,ry:15
        Blockchain[(Story Protocol<br>区块链)]
        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 协议--> StoryService
    Agent <--MCP 协议--> StoryscanService
    StoryscanService --> StoryscanToolset
    StoryService --> IPFSTools
    StoryService --> IPTools

    StoryscanToolset <--API 调用--> StoryScan
    IPFSTools <--API 调用--> IPFS
    IPTools <--RPC 调用--> Blockchain

MCP 服务器

StoryScan MCP 服务器

提供用于查询区块链数据的工具，包括地址余额、交易和区块链统计信息。

工具：

• check_balance: 检查地址的余额
• 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 交互的工具。

工具：

• get_license_terms: 检索特定 ID 的许可条款
• mint_license_tokens: 为特定 IP 和许可条款铸造许可代币
• send_ip: 使用原生代币转移将 IP 代币发送到指定地址
• upload_image_to_ipfs: 将图像上传到 IPFS 并返回 URI
• create_ip_metadata: 为特定图像 URI 创建 NFT 元数据
• mint_and_register_ip_with_terms: 铸造并注册带有条款的 IP

设置

前提条件

• Python 3.12+
• UV 包管理器

安装

1. 安装 UV 包管理器并安装 env：

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
# 使用您的 StoryScan API 端点编辑 .env

对于 Story SDK MCP：

cd story-sdk-mcp
cp .env.example .env
# 使用您的钱包私钥、RPC 提供程序 URL 等编辑 .env

运行服务器

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 实现了一个 MCP 客户端，该客户端支持任意数量的 MCP 服务器，具有 stdio 和 sse 传输。

在 Cursor 中添加 MCP 服务器

1. 转到 Cursor 设置 > 功能 > MCP
2. 单击 + 添加新的 MCP 服务器 按钮
3. 填写表格：
   • 在 类型 下选择传输
   • 在 名称 字段中输入服务器的昵称
   • 根据传输方式，输入要运行的命令或服务器的 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 设置页面上的 可用工具 下列出的任何 MCP 工具是相关的，它将自动使用它们。 要有意提示工具的使用，只需告诉代理使用该工具，通过名称或描述来引用它。

当 Agent 想要使用 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"
      ],
      // 添加服务器的环境变量
      "env": {
        "STORY_API_KEY": "your_story_api_key_here",
        "STORYSCAN_API_ENDPOINT": "your_story_api_endpoint_here"
      }
    },
    "story-sdk-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "~/path/to/story-mcp-hub/story-sdk-mcp",
        "run",
        "server.py"
      ],
      // 添加服务器的环境变量
      "env": {
        "WALLET_PRIVATE_KEY": "your_private_key_here",
        "RPC_PROVIDER_URL": "your_rpc_provider_url_here",
        "PINATA_JWT": "your_pinata_jwt_here"
      }
    }
  }
}

3. 保存文件并重新启动 Claude Desktop 以使更改生效。

示例查询：use storyscan to check balance of 0x95A13F457C76d10A40D7e8497eD4F40c53F4d04b

开发

要向 hub 添加新的 MCP 服务器：

1. 为您的服务器创建一个新目录
2. 在您的服务器中实现 MCP 协议
3. 将任何必要的依赖项添加到根 pyproject.toml
4. 使用有关您的服务器的信息更新此 README

故障排除

如果您遇到问题：

1. 验证是否为每个服务器正确设置了环境变量
2. 检查与外部 API（StoryScan、IPFS 等）的网络连接
3. 确保您使用的是正确的 Python 版本 (3.12+)
4. 检查是否使用 uv sync 安装了所有依赖项

许可证

MIT 许可证