星战科技xingzhan.cloud
返回市场
群集-mcp

群集-mcp

作者：ethersphere4 星标更新：2025-09-27
安装使用来源：spider==github.com

项目介绍

Swarm MCP Server

免责声明： 此实现仅作为概念验证，不应在生产环境中使用。

这是一个使用Ethereum Swarm的Bee API来存储和检索数据的模型上下文协议（MCP）服务器实现。

概述

此服务器实现了模型上下文协议（MCP），这是一种标准协议，用于连接AI系统与外部工具和数据源。Swarm MCP服务器提供了上传和下载文本数据的工具，并通过Bee API将这些数据存储在Swarm去中心化存储网络上。

特性

  • 通过MCP协议将文本数据上传到Swarm
  • 通过MCP协议从Swarm下载文本数据
  • 使用stdio传输的标准MCP服务器接口
  • 可配置的Bee API端点和邮票批次ID

MCP工具

服务器提供以下MCP工具：

upload_text

将文本数据上传到Swarm网络。

参数：

  • data: 要上传的字符串数据
  • redundancyLevel: （可选）容错冗余级别（0-4，默认值：0）
    • 0: 无
    • 1: 中等
    • 2: 强
    • 3: 极高
    • 4: 过度谨慎
  • memoryTopic: （可选）如果提供，则将数据上传到具有该主题的Swarm Feed（需要在配置中提供BEE_FEED_PK）

返回：

  • reference: 上传的数据或Feed的Swarm参考哈希
  • url: 通过Bee API访问数据的URL
  • message: 状态消息
  • topicString, topic, feedUrl: （如果使用memoryTopic）Feed详情

download_text

从Swarm网络检索文本数据。当已知数据为文本格式时应使用此方法。

参数：

  • reference: Swarm参考哈希或Feed主题
  • isMemoryTopic: （可选，布尔值）设置为true以从Swarm Feed中检索
  • owner: （可选）Feed所有者的Ethereum地址

返回：

  • 检索到的文本数据

upload_file

将文件上传到Swarm网络。

参数：

  • data: 基64编码的文件内容或文件路径
  • isPath: （可选）数据参数是否为文件路径（默认值：false）
  • redundancyLevel: （可选）容错冗余级别（0-4，默认值：0）

返回：

  • reference: 上传文件的Swarm参考哈希
  • url: 通过Bee API访问文件的URL
  • message: 状态消息

upload_folder

将文件夹上传到Swarm网络。

参数：

  • folderPath: 要上传的文件夹路径
  • redundancyLevel: （可选）容错冗余级别（0-4，默认值：0）

返回：

  • reference: 上传文件夹的Swarm参考哈希
  • url: 通过Bee API访问文件夹的URL
  • message: 状态消息

download_folder

根据Swarm参考下载文件夹、文件或二进制数据。如果没有假设数据类型，应优先使用此工具。

参数：

  • reference: Swarm参考哈希
  • filePath: （可选）保存下载内容的文件路径（仅在stdio模式下可用）

返回：

  • 如果未提供filePath：清单中的文件列表
  • 如果提供了filePath：内容保存到指定位置

设置

先决条件

  • 安装Node.js 18+
  • npm
  • 运行中的Bee节点或对公共Bee网关的访问
  • 有效的邮票批次ID（用于生产用途）

安装

  1. 克隆此仓库
  2. 安装依赖项：
npm ci

配置

服务器配置位于src/config.ts：

您可以自定义：

  • Bee API端点：设置为任何Swarm Bee节点或网关
  • 邮票批次ID：上传数据到Swarm所需（默认ID是测试用占位符）

根据您的环境需求修改这些值。

在本地运行服务器

您可以在两种不同模式下本地运行服务器：stdio或web。

Stdio（默认）

这是直接集成MCP客户端的标准模式，这些客户端管理自己的子进程。

开发（带热重载）：

npm run dev

开发（不构建）：

npm run serve

生产： 首先，构建项目：

npm run build

然后，运行服务器：

npm start
# 或
npm run start:stdio

Web服务器（HTTP + SSE）

此模式下，服务器作为Web服务在3000端口运行，具有HTTP和SSE端点。

开发（不构建）：

npm run serve:web

生产： 首先，构建项目：

npm run build

然后，运行服务器：

npm run start:web

Docker

此项目包括一个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_BATCH_ID="your_batch_id_here" \
  -e BEE_FEED_PK="your_private_key_here" \
  swarm-mcp

使用cURL进行测试

您可以通过发送tools/list请求来测试服务器是否正确运行。

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
}'

注意： 即使返回JSON响应，HTTP服务器也需要在接受头中包含text/event-stream。

成功响应将是一个包含服务器工具列表的JSON对象。

SSE服务器

与SSE服务器交互是一个两步过程。首先，您建立连接以获取sessionId，然后使用该ID发送消息。

步骤1：打开SSE连接

在终端中运行以下命令。它将连接到服务器并等待事件。服务器会返回一个sessionId，您将在下一步中使用它。

# 在终端1
curl -N -H "Accept:text/event-stream" http://localhost:3000/sse

输出将包含会话ID，例如： id: "<your-session-id>"

步骤2：发送消息

在第二个终端中，使用步骤1中的sessionId发送请求。将<your-session-id>替换为实际ID。

# 在终端2
curl -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}' \
"http://localhost:3000/message?sessionId=<your-session-id>"

响应将出现在终端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客户端以使用stdio的详细说明，请参阅Swarm MCP客户端设置指南。

要在这种模式下运行服务器，请参见上述**Stdio（默认）**部分中的命令。