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