使用说明

项目简介

MCP IPFS Server (mcp-ipfs) 是一个基于 Node.js 开发的 MCP 服务器，它充当语言模型 (LLM) 客户端与 storacha.network (一个基于 IPFS 的去中心化存储平台) 之间的桥梁。该服务器实现了 Model Context Protocol (MCP)，允许 LLM 通过标准化的 JSON-RPC 接口，安全、便捷地访问和管理 storacha.network 上的资源和服务。

主要功能点

资源管理 (Resources): 虽然该仓库没有直接提及“资源”的概念，但它通过 'w3' CLI 工具间接管理 storacha.network 上的存储空间和数据，这些可以被视为 MCP 中的资源。例如，可以列出 (list) 和使用 (use) 存储空间。
工具注册和执行 (Tools): 该服务器的核心功能是注册并执行一系列与 'w3' CLI 命令对应的工具 (Tools)。这些工具覆盖了 storacha.network 的主要功能，例如：
- 身份验证与 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' (密钥生成与桥接令牌)
- 高级存储操作: Blob, CAR, Upload, Index, Access Claim, Filecoin Info 管理等高级功能
- 账户与账单: 'w3_plan_get', 'w3_coupon_create', 'w3_usage_report' (账户和用量查询)
Prompt 模板 (Prompts): 仓库本身没有直接提供 Prompt 模板功能，但作为一个 MCP 服务器，它可以与支持 Prompt 模板的 MCP 客户端协同工作，为 LLM 应用提供上下文数据和功能调用能力。

安装步骤

安装 Node.js 和 npm: 确保你的系统已安装 Node.js (版本 22.0.0 或更高) 和 npm。

安装 w3 CLI: 全局安装 '@web3-storage/w3cli' 命令行工具，并进行配置：

npm install -g @web3-storage/w3cli
w3 login <[email protected]>
# 按照邮件提示完成邮箱验证

设置环境变量: 'w3_login' 工具需要 'W3_LOGIN_EMAIL' 环境变量，请设置为你 'w3 login' 时使用的邮箱地址。

克隆仓库并安装依赖:

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

构建项目:
```
npm run build
```

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令和参数，以下是针对 mcp-ipfs 服务器的配置示例 (JSON 格式)：

1. 使用 NPX 运行 (推荐本地简单使用):

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

'server name': 'ipfs' (服务器名称，客户端用于标识和调用)
'command': 'npx' (启动命令，使用 npx 运行 npm 包)
'args': '["-y", "mcp-ipfs"]' (命令参数，'-y' 自动确认安装包，'mcp-ipfs' 为要运行的 npm 包名)
'env': '{"W3_LOGIN_EMAIL": "[email protected]"}' (环境变量，'W3_LOGIN_EMAIL' 必须设置为你的 storacha.network 账户邮箱)

2. 使用 Docker 运行 (容器化部署):

首先需要构建 Docker 镜像 (或使用预构建镜像 'alexbakers/mcp-ipfs')：

docker build -t alexbakers/mcp-ipfs .

然后配置 MCP 客户端：

{
  "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]"
      }
    }
  }
}

'server name': 'mcp-ipfs'
'command': 'docker' (启动命令，使用 docker 运行容器)
'args': 容器运行参数，包括：
- 'run': 运行容器
- '-i': 保持STDIN开放
- '--rm': 容器退出后自动删除
- '-v /path/to/your/project:/path/to/your/project': 重要: 挂载本地项目目录到容器内，用于 Docker 容器访问宿主机文件 (例如上传文件)。请将 '/path/to/your/project' 替换为你的实际项目路径。
- '-e W3_LOGIN_EMAIL': 设置容器内的环境变量 'W3_LOGIN_EMAIL'
- 'alexbakers/mcp-ipfs': 使用的 Docker 镜像名称
'env': '{"W3_LOGIN_EMAIL": "[email protected]"}' (环境变量，与 NPX 示例相同)

注意：

部分 'w3' 命令 (例如 'w3_up', 'w3_delegation_create', 'w3_proof_add', 'w3_can_blob_add', 'w3_can_store_add') 需要绝对文件系统路径作为参数。
使用 NPX 时, 请提供宿主机的绝对路径。
使用 Docker 时, 请提供容器内部的绝对路径。如果需要访问宿主机文件，务必使用 '-v' 挂载目录，并使用容器内的路径 (例如 '/path/to/your/project/my_file.txt')。

基本使用方法

启动 MCP 服务器: 根据选择的配置 (NPX 或 Docker) 启动 mcp-ipfs 服务器。
配置 MCP 客户端: 在你的 MCP 客户端中，配置连接到 mcp-ipfs 服务器。
调用工具: 通过 MCP 客户端，你可以调用 mcp-ipfs 服务器提供的各种 'w3' 工具，例如：
- 使用 'w3_login' 工具进行身份验证 (首次使用或 Agent 状态丢失时)。
- 使用 'w3_space_ls' 查看可用的存储空间。
- 使用 'w3_up' 上传文件到 storacha.network。
- 使用 'w3_ls' 列出已上传的文件。
- 使用 'w3_open' 获取文件在 'w3s.link' 上的公开访问 URL。
- ... 以及其他 'w3' 工具提供的功能。

请参考 Model Context Protocol (MCP) 规范和 w3 CLI 文档了解更多关于 MCP 协议和 'w3' 工具的详细信息。

关键词