Swarm种源MCP

![Regression and Safety Tests](https://github.com/datafund/swarm_provenance_MCP/actions/workflows/regression_tests.yml) ![License: MIT](https://opensource.org/licenses/MIT)

⚠️ ALPHA软件-概念验证 此软件位于 阿尔法阶段 应被视为 概念验证。仅用于测试和实验。不建议用于生产。

⚠️ 数据持久性警告 Swarm上的存储 租用仓库 时间有限。默认配置使用非常短的租赁期（大约 1天). 不要指望上传的数据会持续超过租赁期。 邮票过期后，数据将不可用。

⚠️ 测试网通知 链上来源特征的使用 基础Sepolia（测试网） 默认情况下。测试网令牌没有货币价值，测试网状态可能随时重置。不要依赖测试网锚定来保证生产数据的完整性。不提供任何形式的保证。

一种模型上下文协议（MCP）服务器，用于通过集中式FastAPI网关管理Swarm邮票和来源数据存储。使AI代理能够将来源数据上传到去中心化的Swarm网络进行不可变存储，并通过引用进行检索。

概述

此MCP服务器为AI代理提供了与Swarm邮票和来源数据存储交互的工具，包括购买和扩展邮票，将来源数据上传到Swarm进行不可变的去中心化存储，以及通过引用从网络下载数据。它充当了AI代理和 swarm_connect FastAPI网关。

来源和不可变储存

此MCP服务器专为来源数据用例而设计，利用Swarm的去中心化网络提供：

不可变记录：上传后，数据不能更改，确保完整性
去中心化存储：没有单点故障或中央权威
来源元数据：支持具有创建者、时间戳和沿袭信息的结构化来源记录
可验证的真实性：上传数据的加密完整性验证

特性

购买邮票：创建具有可配置持续时间和大小的新邮票
印章状态：获取特定邮票的详细信息
邮票列表：查看所有可用邮票
扩展邮票：延长现有邮票的有效期
数据上传：将数据上传到Swarm网络并进行印章验证
数据下载：通过引用从Swarm网络下载数据
产地储存：使用来源元数据存储数据，用于不可变、可验证的记录
健康监测：检查网关和Swarm网络连接
链诊断 （可选）：检查链上钱包余额和RPC连接以进行来源锚定
关于锚链 （可选）：在链上注册Swarm哈希，以获得不可变的来源记录
转型谱系 （可选）：通过链上状态读取（v2）或事件日志（v1）记录和跟踪数据转换
合并转换 （可选）：记录将多个源哈希合并为一个的N对1合并转换

安装

先决条件

Python 3.10或更高版本（使用 python3 命令）
互联网连接（默认使用公共网关）
可选：自托管 swarm_connect 网关服务（请参阅下面的网关选项）

设置

克隆存储库：

git clone https://github.com/datafund/swarm_provenance_MCP.git
cd swarm_provenance_mcp

创建并激活虚拟环境：

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

安装软件包：

pip install -e .

配置环境变量：

cp .env.example .env
# Edit .env to configure your gateway URL and defaults

码头工人

在没有本地依赖关系的容器中运行MCP服务器。

注册表：预构建图像发布到 GitHub容器注册表 仅-始终使用完整 ghcr.io/ 前缀。它是不可在Docker Hub上使用。

快速开始 （预构建图像）：

docker pull ghcr.io/datafund/swarm-provenance-mcp:latest
docker run -i --rm ghcr.io/datafund/swarm-provenance-mcp

从源代码构建：

docker build -t swarm-provenance-mcp .
docker run -i --rm swarm-provenance-mcp

对于环境变量：

docker run -i --rm \
  -e SWARM_GATEWAY_URL=https://provenance-gateway.datafund.io \
  -e DEFAULT_STAMP_DURATION_HOURS=25 \
  -e DEFAULT_STAMP_SIZE=small \
  swarm-provenance-mcp

Docker编写：

docker compose build
docker compose run --rm swarm-provenance-mcp

变量	描述	默认值
`SWARM_GATEWAY_URL`	网关端点URL	`https://provenance-gateway.datafund.io`
`DEFAULT_STAMP_DURATION_HOURS`	默认戳记持续时间（小时）（min 24）	`25`
`DEFAULT_STAMP_SIZE`	默认图章大小： `small`, `medium`，或 `large`	`small`
`PAYMENT_MODE`	网关支付层(`free` =3写入要求/分钟）	`free`

配置

环境变量（设置于 .env 文件）：

SWARM_GATEWAY_URL：swarm_connect FastAPI网关的URL（默认值： https://provenance-gateway.datafund.io)
DEFAULT_STAMP_DURATION_HOURS：默认戳记持续时间（小时），最小24（默认值： 25)
DEFAULT_STAMP_SIZE：默认图章大小-- small, medium，或 large （默认值： small)
PAYMENT_MODE：网关支付层（默认值： free --速率限制为每分钟3个写入请求）

锚链（可选）

CHAIN_ENABLED：启用链上来源锚定（默认值： false)
CHAIN_NAME：区块链网络-- base-sepolia （测试网）， base （主网），或 localhost （本地安全帽，链31337）（默认值： base-sepolia)
PROVENANCE_WALLET_KEY：链交易的私钥（十六进制，带或不带0x前缀）
CHAIN_RPC_URL：自定义RPC终结点（如果未设置，则使用链预设）
CHAIN_RPC_URLS：逗号分隔的回退RPC URL，按以下顺序尝试 CHAIN_RPC_URL
CHAIN_CONTRACT：自定义数据验证合同地址（如果未设置，则使用链预设）
CHAIN_EXPLORER_URL：自定义区块浏览器URL（如果未设置，则使用链预设）
CHAIN_GAS_LIMIT：链式交易的显式气体限制（如果设置，则跳过估计）

启用链后，其他工具可用： chain_balance, chain_health, anchor_hash, verify_hash, get_provenance, record_transform, record_merge_transform, get_provenance_chain, set_storage_ref, lookup_by_storage_ref默认安装中包含区块链依赖项（web3、eth帐户）。只读工具(verify_hash, get_provenance, get_provenance_chain, lookup_by_storage_ref, chain_health)不带钱包钥匙工作；书写工具(anchor_hash, record_transform, record_merge_transform, set_storage_ref)以及 chain_balance 需要 PROVENANCE_WALLET_KEY 有一个资金钱包。

网关选项

公共网关（推荐）

MCP服务器默认使用DataFund托管的公共网关，位于 https://provenance-gateway.datafund.io此网关提供：

高可用性和可靠性
无需设置或维护
直接访问Swarm网络
免费用于开发和测试

自托管网关

您还可以运行自己的网关实例：

自定义配置
私有或隔离环境
本地开发

要使用自托管网关，请执行以下操作：

克隆网关存储库： git clone https://github.com/datafund/swarm_connect
按照该存储库中的设置说明进行操作
更新您的 .env 文件： SWARM_GATEWAY_URL=http://localhost:8000

用法

运行MCP服务器

swarm-provenance-mcp

可用工具

`purchase_stamp`

购买一张新邮票。

参数：

duration_hours （int）：持续时间（小时），最小24（可选，如果未提供，则使用默认值）
size （字符串）：图章大小-- "small", "medium"，或 "large" （可选，如果未提供，则使用默认值）
depth （int）：显式深度覆盖，绕过大小（可选，仅限高级使用）
label （string）：印章的可选标签

例子：

{
  "name": "purchase_stamp",
  "arguments": {
    "duration_hours": 48,
    "size": "small",
    "label": "my-test-stamp"
  }
}

`get_stamp_status`

获取特定邮票的详细信息。

参数：

stamp_id （string）：印章的批次ID

例子：

{
  "name": "get_stamp_status",
  "arguments": {
    "stamp_id": "000de42079daebd58347bb38ce05bdc477701d93651d3bba318a9aee3fbd786a"
  }
}

`list_stamps`

列出所有可用的邮票。

参数： 无

例子：

{
  "name": "list_stamps",
  "arguments": {}
}

`extend_stamp`

延长现有印章的有效期。

参数：

stamp_id （string）：要扩展的印章的批次ID
duration_hours （int）：额外持续时间（小时），至少24小时

例子：

{
  "name": "extend_stamp",
  "arguments": {
    "stamp_id": "000de42079daebd58347bb38ce05bdc477701d93651d3bba318a9aee3fbd786a",
    "duration_hours": 48
  }
}

`upload_data`

将数据上传到Swarm网络并进行戳记验证。

参数：

data （string）：要上传的数据内容（最大4096字节）
stamp_id （string）：用于上传的邮票ID
content_type （string）：内容的MIME类型（可选，默认：“application/json”）

例子：

{
  "name": "upload_data",
  "arguments": {
    "data": "{\"message\": \"Hello Swarm!\"}",
    "stamp_id": "000de42079daebd58347bb38ce05bdc477701d93651d3bba318a9aee3fbd786a",
    "content_type": "application/json"
  }
}

`download_data`

使用参考哈希从Swarm网络下载数据。

参数：

reference （string）：要下载的数据的Swarm引用哈希

例子：

{
  "name": "download_data",
  "arguments": {
    "reference": "a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789a"
  }
}

`check_stamp_health`

对特定印章进行健康检查。返回上传是否可以继续，以及任何错误或警告和可操作的建议。

参数：

stamp_id （string）：要检查的印章的批次ID

例子：

{
  "name": "check_stamp_health",
  "arguments": {
    "stamp_id": "000de42079daebd58347bb38ce05bdc477701d93651d3bba318a9aee3fbd786a"
  }
}

`get_wallet_info`

获取网关节点的钱包地址和BZZ余额。用于检查节点是否有足够的资金。注意：这是一个调试/诊断工具，在未来的版本中可能会被删除。

参数： 无

例子：

{
  "name": "get_wallet_info",
  "arguments": {}
}

`get_notary_info`

检查网关上是否启用了公证签名服务。

参数： 无

例子：

{
  "name": "get_notary_info",
  "arguments": {}
}

`health_check`

检查网关和Swarm网络连接状态。返回自适应状态，包括邮票可用性、 ready 指示上传是否可以继续的标记以及对下一步的建议。

参数： 无

例子：

{
  "name": "health_check",
  "arguments": {}
}

`chain_balance` （可选--必需 `CHAIN_ENABLED=true` 以及区块链依赖关系）

检查用于来源锚定的链上钱包ETH余额。当余额较低时，返回钱包地址、余额、链信息和可操作的资金指导。

参数： 无

例子：

{
  "name": "chain_balance",
  "arguments": {}
}

`chain_health` （可选--必需 `CHAIN_ENABLED=true` 以及区块链依赖关系）

测试链上来源的区块链RPC连接。返回连接状态、链名、链ID、最新块号和RPC响应时间。不需要钱包钥匙。

参数： 无

例子：

{
  "name": "chain_health",
  "arguments": {}
}

`anchor_hash` （可选--必需 `CHAIN_ENABLED=true` 和 `PROVENANCE_WALLET_KEY`)

在区块链上注册Swarm引用哈希，创建一个具有所有者、时间戳和数据类型的不可变来源记录。天然气成本。如果哈希值已经注册，则返回现有记录，没有错误。

参数：

swarm_hash （字符串，必填）：锚定64个字符的十六进制Swarm引用哈希
data_type （字符串）：数据类型/类别（默认值： swarm-provenance，最多64个字符）
owner （string）：注册为所有者的以太坊地址（默认为钱包地址；其他地址需要委托授权）
storage_ref （string）：可选64个字符的十六进制存储引用，用于双向链接。通过以下方式启用反向查找 lookup_by_storage_ref

例子：

{
  "name": "anchor_hash",
  "arguments": {
    "swarm_hash": "a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789a",
    "data_type": "provenance-metadata"
  }
}

`verify_hash` （可选--必需 `CHAIN_ENABLED=true`)

检查Swarm引用哈希是否在区块链上注册。如果找到，则返回带有基本来源信息（所有者、时间戳、数据类型）的验证状态。只读-不需要汽油或钱包钥匙。

参数：

swarm_hash （字符串，必填）：要验证的64个字符的十六进制Swarm引用哈希

例子：

{
  "name": "verify_hash",
  "arguments": {
    "swarm_hash": "a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789a"
  }
}

`get_provenance` （可选--必需 `CHAIN_ENABLED=true`)

检索Swarm引用哈希的完整链上来源记录。返回所有者、注册时间戳、数据类型、状态、转换和访问者。只读-不需要汽油或钱包钥匙。

参数：

swarm_hash （字符串，必填）：要查找的64个字符的十六进制Swarm引用哈希

例子：

{
  "name": "get_provenance",
  "arguments": {
    "swarm_hash": "a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789a"
  }
}

`record_transform` （可选--必需 `CHAIN_ENABLED=true` 和 `PROVENANCE_WALLET_KEY`)

在链上记录数据转换，将原始数据链接到转换后的版本。创建可验证的血统追踪。原始哈希必须已经锚定。天然气成本。如果相同 (original → new) pair已被记录，返回现有链接而不消耗gas（幂等）。

参数：

original_hash （字符串，必填）：原始数据的64个字符的十六进制Swarm引用（必须已经锚定）
new_hash （字符串，必填）：转换数据的64个字符十六进制Swarm引用
description （string）：转换描述（最多256个字符，例如“匿名PII”）
restrict_original （boolean）：如果为true，则在记录转换后将原始数据状态设置为“受限”（默认值：false）

例子：

{
  "name": "record_transform",
  "arguments": {
    "original_hash": "a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789a",
    "new_hash": "b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab",
    "description": "Filtered for region EU",
    "restrict_original": false
  }
}

`record_merge_transform` （可选--必需 `CHAIN_ENABLED=true` 和 `PROVENANCE_WALLET_KEY`)

在链上记录一个N到1的合并转换，将多个源哈希组合成一个新的哈希。所有源哈希值必须已经锚定。天然气成本。需要v2合约(localhost 或升级部署）。

参数：

source_hashes （字符串数组，必填）：2-50个源Swarm引用哈希值要合并（每个64个字符的十六进制）
new_hash （字符串，必填）：合并结果的64个字符十六进制Swarm引用
description （string）：合并转换的描述（最多256个字符）
new_data_type （string）：合并结果的数据类型（默认值： "merged"，最多64个字符）

例子：

{
  "name": "record_merge_transform",
  "arguments": {
    "source_hashes": [
      "a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789a",
      "b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab"
    ],
    "new_hash": "c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789abc",
    "description": "Merged EU and US datasets",
    "new_data_type": "merged-dataset"
  }
}

`get_provenance_chain` （可选--必需 `CHAIN_ENABLED=true`)

遵循Swarm哈希的转换谱系。在v2合约上，使用状态读取进行快速遍历；在v1合约上，遍历事件日志。显示数据是如何演变的——从原始版本到每个派生版本。只读-不需要汽油或钱包钥匙。

参数：

swarm_hash （字符串，必填）：64个字符的十六进制Swarm引用哈希，用于跟踪沿袭
max_depth （整数）：要遍历的最大深度（默认值：10，范围：1–50）

例子：

{
  "name": "get_provenance_chain",
  "arguments": {
    "swarm_hash": "a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789a",
    "max_depth": 10
  }
}

`set_storage_ref` （可选--必需 `CHAIN_ENABLED=true` 和 `PROVENANCE_WALLET_KEY`)

将Swarm存储引用附加到现有的链上记录。设置一次：第一次写入后不能更改。仅限所有者。有用之后 record_transform 以链接转换后的数据的Swarm存储位置。

参数：

data_hash （字符串，必填）：现有链上记录的64个字符的十六进制数据哈希
storage_ref （字符串，必填）：链接的64个字符十六进制存储引用（例如Swarm引用）

例子：

{
  "name": "set_storage_ref",
  "arguments": {
    "data_hash": "a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789a",
    "storage_ref": "b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab"
  }
}

`lookup_by_storage_ref` （可选--必需 `CHAIN_ENABLED=true`)

反向查找：通过Swarm存储引用查找链上来源记录。返回链接的数据哈希值和完整的来源记录（如果找到）。只读-不需要汽油或钱包钥匙。

参数：

storage_ref （字符串，必填）：要查找的64个字符的十六进制存储引用

例子：

{
  "name": "lookup_by_storage_ref",
  "arguments": {
    "storage_ref": "b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab"
  }
}

响应格式

所有工具响应都包含结构化元数据，以帮助代理高效地链接操作：

成功响应

每个成功的响应都会附加工作流提示：

_next:         # The logical next tool to call
_related: ,        # Other relevant tools

提示是上下文相关的，例如， list_stamps 建议 _next: upload_data 当存在可用邮票时，但是 _next: purchase_stamp 当没有可用时。

错误响应

错误响应包括结构化恢复信息：

retryable: true|false            # Whether retrying the same call may succeed
_next:            # Tool to call for recovery

可重试：true --瞬态错误（超时、速率限制、502/503/504）。请稍候，然后重试。
可重试：false --永久性错误（验证失败、未知工具）。修复输入并尝试不同的方法。

适应性健康检查

这 health_check 工具返回其他字段：

ready: true|false                # Whether the system is ready for uploads
_recommendations:                # Actionable suggestions (only when issues exist)
  - No stamps found — purchase one before uploading
_companion_servers:              # Related servers in the ecosystem
  - swarm_connect gateway:  (connected|unreachable)
  - fds-id MCP: optional (identity/signing for provenance chain anchoring)

MCP提示

服务器提供工作流提示，代理可以通过以下方式调用 prompts/list 和 prompts/get。这些为常见任务提供了分步说明：

提示	描述	参数
`provenance-upload`	将数据上传到Swarm：健康检查、印章选择、上传、验证	`data` （必填）， `content_type` （可选）
`provenance-verify`	通过引用下载并验证现有数据	`reference` （必填）
`stamp-management`	审查印章库存，诊断问题，建议行动	无
`provenance-chain-workflow`	端到端的链上来源：存储、锚定和可选地记录转换	`data` （必填）， `transform_description` （可选）

MCP资源

服务器公开代理可以通过以下方式加载的按需知识资源 resources/list 和 resources/read:

资源URI	MIME类型	描述
`provenance://skills`	`text/markdown`	来源技能指南——概念、关键规则、工作流程、图表和错误恢复

码头工人

建筑

docker build -t swarm-provenance-mcp .

要标记特定版本，请执行以下操作：

docker build --build-arg VERSION=0.1.0 -t swarm-provenance-mcp:0.1.0 .

跑步

服务器通过stdio通信（无端口）。通过 -i 对于交互式stdin：

docker run -i --rm swarm-provenance-mcp

通过环境变量配置网关URL和其他设置：

docker run -i --rm \
  -e SWARM_GATEWAY_URL=https://provenance-gateway.datafund.io \
  -e DEFAULT_STAMP_SIZE=medium \
  swarm-provenance-mcp

Claude桌面与Docker

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "swarm-provenance": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "swarm-provenance-mcp"]
    }
  }
}

建筑

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Agents     │◄──►│  MCP Server     │◄──►│ swarm_connect   │
│                 │    │                 │    │   Gateway       │
│ • Claude        │    │ • Tool handlers │    │                 │
│ • Other LLMs    │    │ • Gateway client│    │ • Purchase API  │
│ • Custom agents │    │ • Chain client  │    │ • Status API    │
└─────────────────┘    │ • Error handling│    │ • Extension API │
                       └────────┬────────┘    └─────────┬───────┘
                                │                       │
                       ┌────────▼────────┐    ┌─────────▼───────┐
                       │  Base Sepolia   │    │  Swarm Network  │
                       │  (DataProv.     │    │   (Bee Node)    │
                       │   Contract)     │    └─────────────────┘
                       └─────────────────┘

组件

MCP服务器：通过模型上下文协议公开工具
网关客户端：用于与swarm_connect通信的HTTP客户端
连锁客户 （可选）：通过Base Sepolia上的DataProvenance智能合约进行链上来源
配置：基于环境的设置管理
错误处理：全面的错误处理和记录

Claude桌面集成

安装说明

安装克劳德桌面：从下载 claude.ai

克隆并设置此存储库:

# Clone the repository
git clone https://github.com/datafund/swarm_provenance_MCP.git

# Navigate to the project directory
cd swarm_provenance_mcp

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package in development mode
pip install -e .

# Configure environment variables
cp .env.example .env
# Edit .env file if you need to customize gateway URL or defaults

配置MCP服务器：添加到Claude Desktop的配置文件中：

macOS/Linux (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "swarm-provenance": {
      "command": "/path/to/swarm_provenance_mcp/venv/bin/python",
      "args": ["-m", "swarm_provenance_mcp.server"],
      "cwd": "/path/to/swarm_provenance_mcp"
    }
  }
}

视窗 (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "swarm-provenance": {
      "command": "C:\\path\\to\\swarm_provenance_mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "swarm_provenance_mcp.server"],
      "cwd": "C:\\path\\to\\swarm_provenance_mcp"
    }
  }
}

*注：更换 /path/to/swarm_provenance_mcp 使用克隆存储库的实际路径。*

替代方案（如果安装了软件包）：您可以使用 "command": "swarm-provenance-mcp" 而是在跑步之后 pip install -e .

具有链上来源

要启用区块链锚定，请添加 "env" 块到配置。您可以使用它来代替（或与） .env 文件：

{
  "mcpServers": {
    "swarm-provenance": {
      "command": "/path/to/swarm_provenance_mcp/venv/bin/python",
      "args": ["-m", "swarm_provenance_mcp.server"],
      "cwd": "/path/to/swarm_provenance_mcp",
      "env": {
        "CHAIN_ENABLED": "true",
        "PROVENANCE_WALLET_KEY": "0x...your_private_key_here..."
      }
    }
  }
}

只读链工具(verify_hash, get_provenance, get_provenance_chain, lookup_by_storage_ref, chain_health)工作没有 PROVENANCE_WALLET_KEY.编写工具(anchor_hash, record_transform, record_merge_transform, set_storage_ref)以及 chain_balance 需要资金钱包——请参阅锚链了解详情。

基于Docker

使用Docker实现零安装体验——不需要Python、venv或pip：

{
  "mcpServers": {
    "swarm-provenance": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SWARM_GATEWAY_URL=https://provenance-gateway.datafund.io",
        "ghcr.io/datafund/swarm-provenance-mcp"
      ]
    }
  }
}

要使用Docker启用链锚定，请添加chain env vars：

{
  "mcpServers": {
    "swarm-provenance": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SWARM_GATEWAY_URL=https://provenance-gateway.datafund.io",
        "-e", "CHAIN_ENABLED=true",
        "-e", "PROVENANCE_WALLET_KEY=0x...your_private_key_here...",
        "ghcr.io/datafund/swarm-provenance-mcp"
      ]
    }
  }
}

Docker桌面MCP工具包：如果您使用支持MCP Toolkit的Docker Desktop，则可以从Docker MCP目录中自动发现服务器。

重新启动克劳德桌面 并验证连接。

入门指南

设置后，在Claude Desktop中尝试以下提示以验证一切正常：

检查连接：

“在Swarm网关上运行健康检查”

预期：状态显示 healthy、网关URL和响应时间。如果启用了链，您还将看到RPC连接和钱包余额信息。

列表邮票：

“列出所有可用的Swarm邮票”

预期：一份带有批次ID的邮票列表，或一条尚未存在邮票的消息（建议购买一枚）。

完整的上传工作流程：

“将文本‘Hello Swarm！’上传到Swarm网络”

Claude将完成以下步骤：购买邮票，等待其传播，上传数据，并返回Swarm引用哈希。

在链上验证（如果链已启用）：

“将上传的哈希锚定在链上并进行验证”

Claude将在区块链上注册哈希值并确认来源记录。

故障排除设置

如果Claude Desktop未显示Swarm工具：

检查配置文件路径是否适合您的操作系统
验证 command 路径指向venv中的Python可执行文件
检查克劳德桌面日志： 帮助>显示日志 （查找MCP连接错误）
手动测试：运行 swarm-provenance-mcp 在您的终端中，它应该无错误地启动并等待MCP输入

发展

测试

# Install development dependencies
pip install -e .[dev]

# Run tests
pytest

# Run with coverage
pytest --cov=swarm_provenance_mcp

Docker测试

需要Docker守护进程正在运行：

# Run all Docker tests (builds image, tests MCP protocol, tool calls)
pytest tests/test_docker.py -v -m docker

# Verify manually
docker build -t swarm-provenance-mcp .
docker run -i --rm swarm-provenance-mcp                           # starts, waits for MCP input
docker run -i --rm -e SWARM_GATEWAY_URL=https://provenance-gateway.datafund.io swarm-provenance-mcp  # env override

代码质量

# Format code
black swarm_provenance_mcp/

# Lint code
ruff check swarm_provenance_mcp/

依赖项

核心依赖关系:

- mcp>=1.0.0：模型上下文协议框架 - requests>=2.31.0：用于网关通信的HTTP客户端 - pydantic>=2.0.0：数据验证和设置 - python-dotenv>=1.0.0：环境配置 - web3>=6.0.0：用于链上来源的以太坊区块链交互 - eth-account>=0.10.0：用于链锚的钱包和交易签名

发展依赖性:

- pytest：测试框架 - pytest-asyncio：异步测试支持 - pytest-mock：模拟实用程序 - black：代码格式 - ruff：林婷

与AI代理集成

此MCP服务器旨在与支持模型上下文协议的AI代理协同工作。代理商可以使用提供的工具：

管理邮票库存：根据需要购买和扩展邮票
监控使用情况：检查印章状态和使用情况
优化成本：列出邮票，找到最适合任务的邮票
存储来源数据：将带有来源元数据的数据上传到不可变的去中心化存储
验证数据完整性：从Swarm网络检索和验证不可变记录
数据生命周期管理：处理从创建到验证的完整来源工作流
跟踪数据沿袭：记录转换并跟踪导出数据的完整来源链
自动化工作流程：将印章管理和数据存储集成到更大的人工智能工作流程中

故障排除

常见问题

连接错误：确保swarm_connect网关正在运行且可访问
身份验证错误：检查网关是否不需要身份验证
印章ID无效：验证邮票ID是否为Swarm网络中的有效批次ID
超时错误：如果操作时间过长，请增加超时值
链：“钱包密钥未配置”：设置 PROVENANCE_WALLET_KEY 在 .env 用于写入操作(anchor_hash, record_transform, set_storage_ref).只读工具没有它也能工作。
链：“资金不足”：使用测试网ETH（Base Sepolia水龙头）为您的钱包充值，或将ETH桥接到Base主网。跑 chain_balance 以供指导。
链：“已注册”：哈希值已经锚定在链上。使用 get_provenance 查看现有记录。
链：“转换已记录”：The (original → new) 链上已存在链接。无气体消耗——使用 get_provenance_chain 以验证血统。
链：“来源太少/太多”: record_merge_transform 需要2-50个源哈希。调整 source_hashes 阵列相应。

日志记录

服务器记录重要事件和错误。要增加日志记录的详细程度：

import logging
logging.getLogger("swarm_provenance_mcp").setLevel(logging.DEBUG)

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

swarm provenance MCP

快速接入

详细介绍

Swarm种源MCP

概述

来源和不可变储存

特性

安装

先决条件

设置

码头工人

配置

锚链（可选）

网关选项

公共网关（推荐）

自托管网关

用法

运行MCP服务器

可用工具

purchase_stamp

get_stamp_status

list_stamps

extend_stamp

upload_data

download_data

check_stamp_health

get_wallet_info

get_notary_info

health_check

chain_balance *（可选--必需 CHAIN_ENABLED=true 以及区块链依赖关系）*

chain_health *（可选--必需 CHAIN_ENABLED=true 以及区块链依赖关系）*

anchor_hash *（可选--必需 CHAIN_ENABLED=true 和 PROVENANCE_WALLET_KEY)*

verify_hash *（可选--必需 CHAIN_ENABLED=true)*

get_provenance *（可选--必需 CHAIN_ENABLED=true)*

record_transform *（可选--必需 CHAIN_ENABLED=true 和 PROVENANCE_WALLET_KEY)*

record_merge_transform *（可选--必需 CHAIN_ENABLED=true 和 PROVENANCE_WALLET_KEY)*

get_provenance_chain *（可选--必需 CHAIN_ENABLED=true)*

set_storage_ref *（可选--必需 CHAIN_ENABLED=true 和 PROVENANCE_WALLET_KEY)*

lookup_by_storage_ref *（可选--必需 CHAIN_ENABLED=true)*

响应格式

成功响应

错误响应

适应性健康检查

MCP提示

MCP资源

码头工人

建筑

跑步

Claude桌面与Docker

建筑

组件

Claude桌面集成

安装说明

具有链上来源

基于Docker

入门指南

故障排除设置

发展

测试

Docker测试

代码质量

依赖项

与AI代理集成

故障排除

常见问题

日志记录

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`purchase_stamp`

`get_stamp_status`

`list_stamps`

`extend_stamp`

`upload_data`

`download_data`

`check_stamp_health`

`get_wallet_info`

`get_notary_info`

`health_check`

`chain_balance` （可选--必需 `CHAIN_ENABLED=true` 以及区块链依赖关系）

`chain_health` （可选--必需 `CHAIN_ENABLED=true` 以及区块链依赖关系）

`anchor_hash` （可选--必需 `CHAIN_ENABLED=true` 和 `PROVENANCE_WALLET_KEY`)

`verify_hash` （可选--必需 `CHAIN_ENABLED=true`)

`get_provenance` （可选--必需 `CHAIN_ENABLED=true`)

`record_transform` （可选--必需 `CHAIN_ENABLED=true` 和 `PROVENANCE_WALLET_KEY`)

`record_merge_transform` （可选--必需 `CHAIN_ENABLED=true` 和 `PROVENANCE_WALLET_KEY`)

`get_provenance_chain` （可选--必需 `CHAIN_ENABLED=true`)

`set_storage_ref` （可选--必需 `CHAIN_ENABLED=true` 和 `PROVENANCE_WALLET_KEY`)

`lookup_by_storage_ref` （可选--必需 `CHAIN_ENABLED=true`)