Walrus Mcp

Walrus Mcp

开发 TypeScript

🚀 🦭 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
  1. 安装依赖
npm install
  1. 构建服务器
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 支持：实现实时数据块状态更新。
  • [ ] 命令行工具：提供独立的命令行界面。
  • [ ] 性能指标：提供存储和检索分析。
  • [ ] 主网支持：集成生产网络。

🔧 技术细节

可用脚本

脚本 描述
npm run dev 启动开发服务器
npm run build 构建生产版本
npm run start 启动生产服务器
npm run lint 运行 ESLint
npm run type-check 运行 TypeScript 类型检查
npm run format 使用 Prettier 格式化代码

技术栈

架构

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 文件。

🤝 支持

Built with 🦭 for the decentralized future
默认排序 时间排序

0 个评论

« 上一篇
S3 Mcp Server
下一篇 »
Hmk_box Mcp Server
  • 0 关注
  • 0 收藏，24 浏览
  • system 提出于 2025-10-05 06:57

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »