故事-mcp-中心

Name: 故事-mcp-中心
Author: piplabs

作者：piplabs16 星标更新：2025-10-17

安装使用来源：spider==github.com

项目介绍

技术文档摘要

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 Agent<br>(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<br>get_transactions,<br>get_address_overview,<br>get_token_holdings,<br>get_nft_holdings,<br>get_stats,<br>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<br>upload_image_to_ipfs<br>create_ip_metadata"]
            style IPFSTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
            LicenseTools["License Management<br>get_license_terms,<br>mint_license_tokens,<br>get_license_minting_fee,<br>predict_minting_license_fee"]
            style LicenseTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
            IPTools["IP & NFT Management<br>register, attach_license_terms,<br>mint_and_register_ip_with_terms,<br>create_spg_nft_collection"]
            style IPTools fill:#E0FFFF,stroke:#5F9EA0,stroke-width:2px,rx:8,ry:8
            TokenTools["Token & Revenue<br>deposit_wip, transfer_wip,<br>pay_royalty_on_behalf,<br>claim_all_revenue,<br>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<br>Storage)]
        style IPFS fill:#FFE4E1,stroke:#DB7093,stroke-width:2px,rx:15,ry:15
        Blockchain[(Story Protocol<br>Blockchain)]
        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 Protocol--> StoryService
    Agent <--MCP Protocol--> StoryscanService
    StoryscanService --> StoryscanToolset
    StoryService --> IPFSTools
    StoryService --> LicenseTools
    StoryService --> IPTools
    StoryService --> TokenTools

    StoryscanToolset <--API Calls--> StoryScan
    IPFSTools <--API Calls--> IPFS
    LicenseTools <--RPC Calls--> Blockchain
    IPTools <--RPC Calls--> Blockchain
    TokenTools <--RPC Calls--> Blockchain

MCP服务器

StoryScan MCP服务器

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

工具：

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交互的工具。

工具：

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、许可证条款和数量的铸造许可证费用

IP资产管理工具：

register: 注册NFT为IP，创建相应的IP记录
attach_license_terms: 将许可证条款附加到IP资产
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: 代表付款方IP资产支付接收方IP资产的版税（自动批准代币）
claim_all_revenue: 声明祖先IP的所有子IP的全部收入，可选自动转移

争议工具：

raise_dispute: 对IP资产提出争议（自动批准WIP债券代币）

代币管理工具：

deposit_wip: 将IP包装成WIP并存入钱包
transfer_wip: 转移WIP代币给接收者
get_erc20_token_balance: 获取账户任何ERC20代币的余额
mint_test_erc20_tokens: 如果合约具有公共铸造/水龙头功能，则铸造测试ERC20代币

安装

先决条件

Python 3.12+
UV包管理器

安装步骤

安装UV包管理器并设置环境：

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

克隆此仓库：

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

使用UV安装依赖项：

uv sync

设置每个服务器的环境变量：

对于StoryScan MCP：

cd storyscan-mcp
cp .env.example .env
# 编辑.env以包含您的StoryScan API端点

对于Story SDK MCP：

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

运行服务器

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服务器

转到Cursor设置 > 功能 > MCP
点击+ 添加新MCP服务器按钮
填写表单：
- 在类型下选择传输方式
- 在名称字段中输入服务器的昵称
- 根据传输方式输入运行命令或服务器URL
- 我们将使用uv命令运行服务器，因此确保包含--directory标志和服务器路径（例如：uv --directory ~/path/to/story-mcp-hub/storyscan-mcp run server.py）

截图 2025-03-10 下午2:50:48

项目特定的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代理会自动使用MCP设置页面上列出的任何相关MCP工具。要有意提示工具使用，只需告诉代理使用该工具，可以按名称或描述引用。

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

Claude Desktop

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

在Claude Desktop中添加MCP服务器

打开Claude Desktop配置文件：

code ~/Library/Application\ Support/Claude/claude_desktop_config.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"
      ]
    }
  }
}

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

截图 2025-03-10 下午2:57:24

示例查询：使用storyscan检查0x95A13F457C76d10A40D7e8497eD4F40c53F4d04b的余额

开发

要向中心添加新的MCP服务器：

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

测试

运行测试

该项目包含一个测试运行脚本（run_tests.py），负责环境设置和测试执行。要运行测试：

安装测试依赖项：

uv sync --extra test

运行所有测试：

uv run python run_tests.py

运行特定测试类别：

# 只运行单元测试
uv run python run_tests.py -t tests/unit/

# 只运行集成测试
uv run python run_tests.py -t tests/integration/

# 以详细输出运行
uv run python run_tests.py -v

运行单独的测试文件：

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

获取可用选项的帮助：

uv run python run_tests.py --help

测试环境设置

测试使用一个包含模拟凭证的.env.test文件。此文件由测试运行器自动加载。

要设置您的测试环境：

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

cp .env.test.example .env.test

编辑.env.test文件以包含您的测试凭证：

# 例如，更新区块链交互的私钥
nano .env.test  # 或使用您喜欢的文本编辑器

有关测试的更多详细信息，请参阅测试指南。

故障排除

如果您遇到问题：

验证每个服务器的环境变量是否正确设置
检查对外部API（如StoryScan、IPFS等）的网络连接
确保您使用的是正确的Python版本（3.12+）
检查所有依赖项是否已使用uv sync安装

许可证

MIT许可证