Walrus MCP

🚀 🦭 Walrus MCP Server

Walrus MCP Server 是为 Walrus 去中心化存储协议打造的 MCP 服务器，它能实现去中心化存储操作，与区块链集成，为开发者提供便捷的工具和良好的开发体验，有效连接 AI 助手和 Walrus 去中心化存储网络。

🚀 快速开始

前提条件

• Node.js >= 18.0.0
• npm >= 8.0.0
• Claude Desktop 或兼容的 MCP 客户端

安装步骤

1. 克隆仓库

git clone https://github.com/MotionEcosystem/walrus-mcp.git
cd walrus-mcp

2. 安装依赖

npm install

3. 构建服务器

npm run build

MCP 设置

将以下内容添加到你的 Claude Desktop 配置中：

{
  "mcpServers": {
    "walrus": {
      "command": "node",
      "args": ["path/to/walrus-mcp/dist/index.js"],
      "env": {
        "WALRUS_AGGREGATOR_URL": "https://aggregator-devnet.walrus.space",
        "WALRUS_PUBLISHER_URL": "https://publisher-devnet.walrus.space"
      }
    }
  }
}

✨ 主要特性

🗄️ 去中心化存储操作

• 在 Walrus 去中心化存储网络中存储数据块。
• 通过数据块 ID 高可用地检索数据块。
• 获取数据块信息，包括大小和认证状态。
• 检查数据块可用性和网络健康状况。

🔗 区块链集成

• 与 Sui 区块链协作管理存储元数据。
• 进行存储周期管理以处理数据块生命周期。
• 通过区块链验证实现可用性证明。
• 进行存储资源管理。

🛠️ 开发者体验

• 提供简单的 MCP 工具，适用于 AI 助手和自动化操作。
• 支持Base64 编码处理二进制数据。
• 支持文件路径直接上传文件。
• 具备全面的错误处理，提供清晰的错误信息。

💻 使用示例

基础用法

// 存储文本数据
await tool_call("store_blob", {
  data: "SGVsbG8sIFdhbHJ1cyE=", // Base64 编码的 "Hello, Walrus!"
  epochs: 10
})

// 存储文件
await tool_call("store_blob", {
  data: "/path/to/file.jpg",
  epochs: 5
})

// 获取数据块内容（Base64 格式）
const blob = await tool_call("get_blob", {
  blobId: "0xabc123..."
})

// 获取数据块元数据
const info = await tool_call("get_blob_info", {
  blobId: "0xabc123..."
})

console.log(info.size, info.certified, info.endEpoch)

// 获取 Walrus 网络健康状态
const status = await resource_read("walrus://status")
console.log(status.epoch, status.networkSize)

// 获取当前客户端配置
const config = await resource_read("walrus://config")
console.log(config.aggregatorUrl, config.publisherUrl)

📦 安装指南

克隆仓库

git clone https://github.com/MotionEcosystem/walrus-mcp.git
cd walrus-mcp

安装依赖

npm install

构建服务器

npm run build

📚 详细文档

环境配置

基于 .env.example 创建 .env 文件：

# 必需：Walrus 网络端点
WALRUS_AGGREGATOR_URL=https://aggregator-devnet.walrus.space
WALRUS_PUBLISHER_URL=https://publisher-devnet.walrus.space

# 可选：自定义系统对象 ID
WALRUS_SYSTEM_OBJECT=0x37c0e4d7b36a2f64d51bba262a1791f844cfd88f19c35b5ca709e1a6991e90dc

# 可选：用于交易签名的钱包
WALRUS_WALLET_PATH=/path/to/your/wallet.json

工具使用示例

存储数据块

// 存储文本数据
await tool_call("store_blob", {
  data: "SGVsbG8sIFdhbHJ1cyE=", // Base64 编码的 "Hello, Walrus!"
  epochs: 10
})

// 存储文件
await tool_call("store_blob", {
  data: "/path/to/file.jpg",
  epochs: 5
})

检索数据块

// 获取数据块内容（Base64 格式）
const blob = await tool_call("get_blob", {
  blobId: "0xabc123..."
})

获取数据块信息

// 获取数据块元数据
const info = await tool_call("get_blob_info", {
  blobId: "0xabc123..."
})

console.log(info.size, info.certified, info.endEpoch)

资源使用示例

检查网络状态

// 获取 Walrus 网络健康状态
const status = await resource_read("walrus://status")
console.log(status.epoch, status.networkSize)

查看配置

// 获取当前客户端配置
const config = await resource_read("walrus://config")
console.log(config.aggregatorUrl, config.publisherUrl)

错误处理

服务器针对常见场景提供了全面的错误处理：

• 数据块未找到：包含数据块 ID 的清晰错误信息。
• 网络问题：提供超时和连接错误详情。
• 无效数据：针对格式错误的输入给出验证错误信息。
• 存储限制：包含周期和容量约束信息。

数据格式支持

支持的输入格式

• Base64 编码字符串：用于二进制数据传输。
• 文件路径：可直接读取文件（相对或绝对路径）。
• 文本内容：自动编码后存储。

输出格式

所有检索到的数据块均以 Base64 编码字符串形式返回，以确保不同数据类型的一致处理。

安全注意事项

⚠️ 重要提示

• 所有存储在 Walrus 中的数据块都是公开且可被发现的。
• 未加密时请勿存储敏感或机密信息。
• 对于私有数据，可考虑使用客户端加密。
• 处理前请验证所有输入。

网络信息

开发网络配置

• 聚合器：https://aggregator-devnet.walrus.space
• 发布者：https://publisher-devnet.walrus.space
• 系统对象：0x37c0e4d7b36a2f64d51bba262a1791f844cfd88f19c35b5ca709e1a6991e90dc

测试网络配置

若要使用测试网络，请更新环境变量：

WALRUS_AGGREGATOR_URL=https://aggregator-testnet.walrus.space
WALRUS_PUBLISHER_URL=https://publisher-testnet.walrus.space

存储经济

周期和定价

• 周期时长：存储承诺的固定时间段。
• 最小存储周期：5 个周期（可配置）。
• 费用计算：基于数据块大小和存储时长。
• 支付方式：通过 Sui 区块链交易处理。

故障排除

常见问题

1. 连接错误
   • 验证网络连接。
   • 检查聚合器/发布者 URL。
   • 确保开发/测试网络端点可访问。
2. 存储失败
   • 检查数据块大小限制。
   • 验证是否有足够的 SUI 代币支付存储费用。
   • 确保周期配置正确。
3. 检索问题
   • 确认数据块 ID 格式和有效性。
   • 检查数据块是否已过期（超过结束周期）。
   • 验证聚合器可用性。

调试模式

启用详细日志记录：

DEBUG=walrus-mcp:* npm run dev

贡献代码

我们欢迎贡献！请按以下步骤操作：

1. 分叉仓库。
2. 创建功能分支。
3. 为新功能添加测试。
4. 更新文档。
5. 提交拉取请求。

路线图

• [ ] 增强数据块管理：支持批量操作和元数据索引。
• [ ] 加密支持：为私有数据提供客户端加密。
• [ ] WebSocket 支持：实现实时数据块状态更新。
• [ ] 命令行工具：提供独立的命令行界面。
• [ ] 性能指标：提供存储和检索分析。
• [ ] 主网支持：集成生产网络。

🔧 技术细节

可用脚本

技术栈

• 运行时环境：Node.js
• 编程语言：TypeScript
• MCP SDK：@modelcontextprotocol/sdk
• HTTP 客户端：Axios
• 验证工具：Zod

架构

Walrus MCP Server 通过模型上下文协议（MCP）在 AI 助手和 Walrus 去中心化存储网络之间搭建桥梁。

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Assistant  │    │  Walrus MCP     │    │ Walrus Network  │
│  (Claude, etc.) │◄──►│     Server      │◄──►│   (DevNet)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │  Sui Blockchain │
                       │   (Metadata)    │
                       └─────────────────┘

组件

• MCP 服务器：处理来自 AI 助手的工具调用和资源请求。
• Walrus 客户端：管理与 Walrus 聚合器和发布者的 HTTP 通信。
• 聚合器：提供数据块检索功能。
• 发布者：处理数据块存储操作。
• Sui 集成：管理存储元数据和周期。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🤝 支持

• 文档：Walrus 官方文档
• 社区：Motion Labs Discord
• 问题反馈：GitHub Issues
• 邮箱：hello@motionecosystem.com