🪐 MCP IPFS Server (storacha.network) 🛰️

🪐 MCP IPFS 服务（storacha.network）🛰️

一个 Node.js 服务，通过 w3 命令行界面（@web3-storage/w3cli）与 storacha.network 平台交互，实现了 Model Context Protocol（MCP）。

该服务通过无缝封装 w3 命令，让语言模型 🤖 和其他 MCP 客户端能够管理 storacha.network 空间、上传／下载数据、管理委托，并执行各种其他任务。

✨ 功能

• 封装 w3 CLI，与 storacha.network 原生集成。
• 提供覆盖多种 w3 功能的 MCP 工具：
  • 🔑 身份验证与 Agent： w3_login、w3_reset、w3_account_ls（用于检查授权）
  • 📦 空间管理： w3_space_ls、w3_space_use、w3_space_info、w3_space_add、w3_space_provision（注意：由于需要交互式提示，必须手动运行 w3_space_create）
  • 💾 数据管理： w3_up、w3_ls、w3_rm
  • 🔗 共享： w3_open（生成 w3s.link URL）
  • 🤝 委托与证明： w3_delegation_create、w3_delegation_ls、w3_delegation_revoke、w3_proof_add、w3_proof_ls
  • 🔐 密钥与令牌： w3_key_create、w3_bridge_generate_tokens
  • ⚙️ 高级存储（w3 can ...）： Blob、CAR、上传、索引、访问声明、Filecoin 信息管理
  • 💳 账户与计费： w3_plan_get、w3_coupon_create、w3_usage_report

🛠️ 前置条件

• Node.js： 版本 22.0.0 或更高（node -v）。
• w3 CLI： 服务会直接执行 w3 命令。请确保已全局安装并配置 @web3-storage/w3cli：

  npm install -g @web3-storage/w3cli
  w3 login <[email protected]>
  # Follow email verification steps
  

• 环境变量： w3_login 工具要求设置 W3_LOGIN_EMAIL 环境变量，其值必须与用于 w3 login 的邮箱相同。

🏗️ 项目结构

代码库组织如下：

src/
├── index.ts          # Main server entry point, MCP setup, request routing
├── schemas.ts        # Zod schemas defining input arguments for each tool
├── tool_handlers.ts  # Implementation logic for each MCP tool
├── utils.ts          # Helper functions (e.g., running w3 commands, parsing JSON)
└── utils/
    └── logger.ts     # Basic logger configuration

🚀 在 MCP 客户端中使用

此服务可与任何兼容 MCP 的客户端搭配使用。你需要配置客户端以连接此服务。

示例：NPX（推荐用于简单的本地使用）

假设已满足 npm 和前置条件。

{
  "mcpServers": {
    "ipfs": {
      "command": "npx",
      "args": ["-y", "mcp-ipfs"],
      "env": {
        "W3_LOGIN_EMAIL": "[email protected]"
      }
    }
  }
}

示例：Docker

请先构建镜像（参见构建部分），或使用预构建镜像 alexbakers/mcp-ipfs。

{
  "mcpServers": {
    "mcp-ipfs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/path/to/your/project",
        "-e",
        "W3_LOGIN_EMAIL",
        "alexbakers/mcp-ipfs"
      ],
      "env": {
        "W3_LOGIN_EMAIL": "[email protected]"
      }
    }
  }
}

📝 路径说明：

多个 w3 命令需要绝对文件系统路径（例如 w3_up、w3_delegation_create --output、w3_proof_add、w3_can_blob_add、w3_can_store_add）。

• NPX： 提供主机上的绝对路径。
• Docker： 提供_容器内_的绝对路径。如果要访问主机上的文件（例如上传文件），必须使用 -v 标志将相关主机目录挂载到容器中（例如 -v /Users/me/project:/Users/me/project），然后在工具参数中使用_容器路径_（例如 /Users/me/project/my_file.txt）。

📦 构建

克隆代码库并安装依赖：

git clone https://github.com/alexbakers/mcp-ipfs.git
cd mcp-ipfs
npm install

构建 TypeScript 代码：

npm run build

之后可以直接运行服务：

# Ensure W3_LOGIN_EMAIL is set in your environment
export W3_LOGIN_EMAIL="[email protected]"
node dist/index.js

或者发布它（如果你有相应权限）：

npm publish

🐳 Docker 构建

构建 Docker 镜像：

# Build locally (replace with your username/repo and desired tag)
docker build -t alexbakers/mcp-ipfs .

📜 许可证

此 MCP 服务采用 MIT 许可证。详情请参阅 LICENSE 文件。