Swarm MCP服务器
免责声明： 此实现仅是概念验证，不应在生产中使用。
模型上下文协议（MCP）服务器实现，使用以太坊Swarm的Bee API存储和检索数据。
概述
该服务器实现了模型上下文协议（MCP），这是一种用于将AI系统与外部工具和数据源连接的标准协议。Swarm MCP服务器提供上传和下载文本数据的工具，使用Bee API将这些数据存储在Swarm去中心化存储网络上。
特性
- 将文本数据上传到Swarm。
- 从Swarm下载文本数据。
- 将文件和文件夹上传到Swarm。
- 从Swarm下载文件和文件夹。
- 更新Swarm提要上的数据。
- 从Swarm提要中读取最新数据。
- 创建邮票批次以供存储。
- 买一批邮票。
- 列出邮票批次。
- 延长邮票批次的存储和持续时间。
配置选项
| 选项 | 类型 | 必填 | 描述 |
|---|---|---|---|
BEE_API_URL | 字符串 | 可选的 （除非使用您自己的节点） | Bee API端点的URL。如果省略，将使用默认的Swarm网关： https://api.gateway.ethswarm.org示例： http://localhost:1633. |
BEE_FEED_PK | 字符串 | 可选的 （没有它就无法更新提要） | 要使用的Swarm提要的私钥。如果没有提供，Swarm Feed功能将被禁用。 |
AUTO_ASSIGN_STAMP | 布尔值 | 可选的 | 如果没有提供邮票，是否自动分配邮票。默认值为：true。设置为false可禁用自动戳记分配。 |
DEFERRED_UPLOAD_SIZE_THRESHOLD_MB | 编号 | 可选的 | 延迟上传的大小阈值（MB）。大于此大小的文件将异步上传。默认值为：5（MB）。 |
MCP工具
服务器提供以下MCP工具：
create_postage_stamp
根据邮票的大小（以兆字节为单位）和持续时间购买邮票。
参数：
size：存储大小（MB）。这些其他大小单位转换为MB：1字节=0.000001 MB，1 KB=0.001 MB，1GB=1000MB。duration：数据应存储的持续时间。邮票批次的生存时间，例如1d-1天、1w-1周、1个月-1个月。label：（可选）设置邮票批次的标签。
示例提示：
Create new stamp with 4 days, 10 megabytes.get_postage_stamp
根据批次id获取特定的邮票批次。
参数：
postageBatchId：请求的邮票批次的id。
示例提示：
Give me the details for batch 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa.list_postage_stamps
列出可用的邮票批次。
参数：
leastUsed：（可选）一个布尔值，用于告诉邮票批次是否排序为最少使用。limit：（可选）Limit是退回邮票批次的最大数量。minUsage：（可选）仅列出至少具有此使用百分比的邮票批次。maxUsage：（可选）仅列出最多具有此使用百分比的邮票批次。
示例提示：
List my stamps.extend_postage_stamp
增加邮票批次的持续时间（相对于当前持续时间）或大小（以兆字节为单位）。
参数：
postageBatchId：执行扩展的邮票批次的id。size：（可选）存储大小，单位为MB（MB）。这些其他大小单位转换为MB：1字节=0.000001 MB，1 KB=0.001 MB，1GB=1000MB。duration：（可选）数据应存储的持续时间。邮票批次的生存时间，例如1d-1天、1w-1周、1个月-1个月。
示例提示：
Extend 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa to 5 days.upload_data
将文本数据上传到Swarm。
参数：
data：要上载的任意字符串。redundancyLevel：（可选）容错冗余级别：0-无，1-中等，2-强，3-疯狂，4-偏执（值越高，容错性越好，但会增加存储开销）。可选，如果没有请求，则值为0。postageBatchId：（可选）用于执行上传的邮票批次ID（如果提供）。
示例提示：
Upload data to Swarm: Hello World!.download_data
从Swarm内容地址哈希中下载不可变数据。
参数：
reference：Swarm引用哈希。
示例提示：
Download data from Swarm: 76d133e2798d2b15db55b6c3de01303acd86e43998eab372e25c5a2115bf3f0b.update_feed
用新数据更新给定主题的提要。
参数：
data：要上载的任意字符串。memoryTopic：如果提供，将最新数据上传到包含此主题的提要中。它是内存的标签，以后可以用来检索数据，而不是其内容哈希。如果不是十六进制字符串，它将被散列以创建提要主题。postageBatchId：（可选）用于执行上传的邮票批次ID（如果提供）。
示例提示：
Update the Swarm feed of Topic1 with: Message1 using postage batch id 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa.read_feed
从给定主题的提要中检索最新数据。
参数：
memoryTopic：Feed主题。owner：（可选）访问外部存储器或提要时，必须设置所有者的以太坊地址。.
示例提示：
Read the Swarm feed of Topic1.upload_file
将文件上传到Swarm。
参数：
data：base64编码的文件内容或文件路径。isPath：数据参数是否为路径。redundancyLevel：（可选）容错冗余级别（值越高，容错性越好，但会增加存储开销）。0-无，1-中等，2-强壮，3-疯狂，4-偏执。postageBatchId：（可选）用于执行上传的邮票批次ID（如果提供）。
示例提示：
Upload to Swarm the file: uploads/file.txt.upload_folder
将文件夹上传到Swarm。
参数：
folderPath：要上载的文件夹的路径。redundancyLevel：（可选）容错冗余级别（值越高，容错性越好，但会增加存储开销）。0-无，1-中等，2-强壮，3-疯狂，4-偏执。postageBatchId：（可选）用于执行上传的邮票批次ID（如果提供）。
示例提示：
Upload to Swarm folder: /home/conversational-agent-client/uploads.download_files
下载文件夹，从Swarm引用文件并保存到引用文件路径或返回引用文件列表。
参数：
reference：Swarm引用哈希。filePath：（可选）保存下载内容的可选文件路径。如果没有提供清单中的文件列表，将返回。
示例提示：
Download from Swarm the file with reference ba35af06601ddf5ac3d71ee33da0db7537215a914fd6a5414b5597bb3d618bdb to folder downloads.query_upload_progress
查询由返回的标签ID标识的特定上传会话的上传进度。
参数：
tagId：swarm上传文件和swarm上传文件夹工具返回的标签ID，用于跟踪上传进度。
示例提示：
Query Swarm for upload tag with id: 1.设置
先决条件
- 已安装Node.js 18+
- npm
- 正在运行的Bee节点或对公共Bee网关的访问
- 有效的邮资批次ID（用于生产）
安装
- 克隆此存储库
- 安装依赖项：
npm ci配置
服务器配置位于 src/config.ts:
您可以自定义：
- Bee API终点：设置为任何Swarm Bee节点或网关
- 邮资批次ID：上传数据到Swarm时需要（默认ID是测试的占位符）
根据您的环境需要修改这些值。
在本地运行服务器
您可以在本地以两种不同的模式运行服务器： stdio 或 web.
标准（默认）
这是与管理自己子流程的MCP客户端直接集成的标准模式。
开发（热重新加载）：
npm run dev开发（无建筑）：
npm run serve生产： 首先，构建项目：
npm run build然后，运行服务器：
npm start
# or
npm run start:stdioWeb服务器（HTTP+SSE）
这将服务器作为web服务在端口3000上运行，具有HTTP和SSE的端点。
开发（无建筑）：
npm run serve:web生产： 首先，构建项目：
npm run build然后，运行服务器：
npm run start:web码头工人
该项目包括一个Dockerfile，用于将Swarm MCP服务器作为容器化服务运行，同时使用HTTP和SSE传输。
Dockerfile：为在端口3000上运行的服务器构建单个映像。
构建Docker镜像
要构建Docker镜像，请从项目根运行以下命令：
docker build -t swarm-mcp .运行Docker容器
要运行服务器，请使用 docker run 命令。集装箱露出端口 3000 适用于HTTP和SSE。
docker run --name swarm-mcp -p 3000:3000 swarm-mcp使用环境变量进行配置
要配置服务器，请使用以下命令将环境变量传递给容器 -e 旗帜。这是连接到自己的Bee节点或使用Swarm Feeds等功能所必需的。
docker run -p 3000:3000 \
-e BEE_API_URL="http://localhost:1633" \
-e BEE_FEED_PK="your_private_key_here" \
swarm-mcp使用cURL进行测试
您可以通过发送 tools/list 请求使用 curl.
HTTP服务器
此命令要求服务器列出所有可用工具，并期望得到一个JSON响应。
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1
}'_注：_ text/event-stream HTTP服务器甚至需要在accept标头中返回JSON响应。
成功的响应将是一个包含服务器工具列表的JSON对象。
SSE服务器
与SSE服务器交互是一个两步过程。首先，您建立连接以获得 sessionId，然后使用该ID发送消息。
步骤1：打开SSE连接
在终端中运行以下命令。它将连接到服务器并等待事件。服务器将发回 sessionId 下一步您将需要它。
# In Terminal 1
curl -N -H "Accept:text/event-stream" http://localhost:3000/sse输出将包含会话ID，例如： id: ""
第二步：发送消息
在第二个终端中，使用 sessionId 从步骤1开始发送请求。替换 `` 使用实际ID。
# In Terminal 2
curl -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}' \
"http://localhost:3000/message?sessionId="响应将出现在终端1中。
与MCP客户端一起使用
服务器支持两种连接方式：
1.Web连接（Docker）
在Docker中运行服务器时，它作为具有HTTP和SSE端点的web服务运行。要连接MCP客户端，您必须使用支持通过URL连接到远程服务器的客户端。
- HTTP服务器URL:
http://localhost:3000/mcp - SSE服务器URL:
http://localhost:3000/sse
在客户端的设置中，添加一个新的远程/自定义连接器并提供相应的URL。
_关于支持功能的说明_：需要直接访问本地文件系统的功能在web模式下不可用。这包括使用本地路径进行上传（例如。， upload_folder 或 upload_file 随着 isPath: true)并直接下载到文件（例如。， download_folder 随着 filePath).仅当在中运行服务器时才支持这些功能 stdio 模式。
2.标准连接（本地）
对于本地开发或管理自己的服务器子流程的客户端，您可以直接在 stdio 模式。
有关如何为stdio配置MCP客户端的详细说明，请参阅 Swarm MCP客户端设置指南.
要在此模式下运行服务器，请参阅 标准（默认） 上面的部分。