Story SDK MCP Server

故事MCP中心

该存储库是Story Protocol的模型上下文协议（MCP）服务器的中心枢纽。它为运行和管理各种MCP服务提供了一个统一的环境，使AI代理能够与Story Protocol的生态系统进行交互。

项目结构

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
(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
get_transactions,
get_address_overview,
get_token_holdings,
get_nft_holdings,
get_stats,
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
upload_image_to_ipfs
create_ip_metadata"]
            style IPFSTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
            LicenseTools["License Management
get_license_terms,
mint_license_tokens,
get_license_minting_fee,
predict_minting_license_fee"]
            style LicenseTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
            IPTools["IP & NFT Management
register, attach_license_terms,
mint_and_register_ip_with_terms,
create_spg_nft_collection"]
            style IPTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
            TokenTools["Token & Revenue
deposit_wip, transfer_wip,
pay_royalty_on_behalf,
claim_all_revenue,
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
Storage)]
        style IPFS fill:#FFE4E1,stroke:#DB7093,stroke-width:2px,rx:15,ry:15
        Blockchain[(Story Protocol
Blockchain)]
        style Blockchain fill:#E0F8E0,stroke:#90EE90,stroke-width:2px,rx:15,ry:15
        StoryScan[(StoryScan/Blockscout
API)]
        style StoryScan fill:#E6F3FF,stroke:#87CEFA,stroke-width:2px,rx:15,ry:15
    end

    Agent  StoryService
    Agent  StoryscanService
    StoryscanService --> StoryscanToolset
    StoryService --> IPFSTools
    StoryService --> LicenseTools
    StoryService --> IPTools
    StoryService --> TokenTools

    StoryscanToolset  StoryScan
    IPFSTools  IPFS
    LicenseTools  Blockchain
    IPTools  Blockchain
    TokenTools  Blockchain

MCP服务器

StoryScan MCP服务器

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

工具：

• get_transactions：获取地址的最近交易记录
• get_stats：获取当前区块链统计数据
• get_address_overview：全面了解地址，包括余额、代币信息和区块链活动
• get_token_holdings：获取一个地址的所有ERC-20代币持有量，包括详细的代币信息和余额
• get_nft_holdings：获取地址的所有NFT持有量，包括收集信息和单个令牌元数据
• interpret_transaction：获得区块链交易的人类可读解释

故事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的铸造许可费、许可条款和金额

知识产权资产管理工具：

• register：将NFT注册为IP，创建相应的IP记录
• attach_license_terms：将许可条款附加到知识产权资产
• mint_and_register_ip_with_terms：创建并注册带有条款的IP

NFT收集工具：

• create_spg_nft_collection：创建一个新的SPG NFT集合，可用于铸造和注册IP资产
• get_spg_nft_minting_token：获得SPG俱乐部NFT合同要求的铸币费

收入和特许权使用费工具：

• pay_royalty_on_behalf：代表支付方知识产权资产向接收方知识产权资产支付特许权使用费（自动批准代币）
• claim_all_revenue：通过可选的自动转账从祖先IP的子IP中提取所有收入

争议工具：

• raise_dispute：对知识产权资产提出争议（自动批准WIP债券代币）

令牌管理工具：

• deposit_wip：将IP打包到WIP并存入钱包
• transfer_wip：将WIP令牌转移给收件人
• get_erc20_token_balance：获取账户中任何ERC20代币的余额
• mint_test_erc20_tokens：如果合约具有公共薄荷/水龙头功能，则测试ERC20代币

设置

先决条件

• Python 3.12+
• UV包管理器

安装

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

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

1. 克隆此存储库：

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

1. 使用UV安装依赖项：

uv sync

1. 为每台服务器设置环境变量：

对于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

故事SDK MCP服务器

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

与MCP客户端一起使用

按照以下说明将MCP服务器连接到各种MCP兼容客户端。

光标

Cursor实现了一个MCP客户端，该客户端支持任意数量的MCP服务器 stdio 和 sse 运输。

在游标中添加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配置

您可以使用配置特定于项目的MCP服务器 .cursor/mcp.json。文件遵循以下格式：

{
  "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"
      ]
    }
  }
}

在游标中使用MCP工具

Composer Agent将自动使用以下列出的任何MCP工具 Available Tools 在MCP设置页面上，如果它确定它们是相关的。要有意提示工具的使用，只需告诉代理使用该工具，通过名称或描述来引用它。

当代理想要使用MCP工具时，它将显示一条消息，要求您批准。

克劳德桌面

Claude Desktop可以通过编辑其配置文件来配置为使用MCP服务器。

在Claude Desktop中添加MCP服务器

1. 打开Claude Desktop配置文件：

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

1. 添加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"
      ]
    }
  }
}

1. 保存文件并重新启动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

1. 运行所有测试：

uv run python run_tests.py

1. 运行特定测试类别：

# 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

1. 运行单个测试文件：

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

1. 获取有关可用选项的帮助：

uv run python run_tests.py --help

测试环境设置

测试使用a .env.test 使用模拟凭据进行测试的文件。此文件由测试运行器自动加载。

要设置测试环境，请执行以下操作：

1. 复制示例文件以创建自己的 .env.test:

cp .env.test.example .env.test

1. 编辑 .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许可证