使用说明

项目简介

Storacha MCP存储服务器是一个实现了 Model Context Protocol (MCP) 的服务器，它允许AI应用通过标准化的接口与 Storacha 去中心化存储网络进行交互。该服务器提供文件上传、检索和身份管理等核心功能，旨在简化LLM应用与去中心化存储的集成。

主要功能点

文件操作:
- 上传文件到 Storacha 去中心化存储网络。
- 通过 Storacha HTTP 网关检索文件。
身份管理:
- 获取 Storacha Agent 的 DID 密钥。
双传输模式:
- HTTP SSE (Server-Sent Events) 模式，用于远程通信。
- Stdio 模式，用于本地集成。
标准化接口:
- 遵循 MCP 协议的 API，用于工具发现和调用。
- JSON-RPC 消息处理。
安全性:
- Bearer Token 认证
- CORS 配置
- 输入验证
- 安全的错误处理

安装步骤

克隆仓库

git clone https://github.com/storacha/mcp-storage-server.git
cd mcp-storage-server

安装依赖
```
pnpm install
```

创建 '.env' 配置文件

cp .env.example .env

配置服务器 修改 '.env' 文件，根据需要配置以下环境变量：

# MCP 服务器配置
MCP_SERVER_PORT=3001                # (可选) 服务器监听端口，默认为 3001
MCP_SERVER_HOST=0.0.0.0             # (可选) 服务器绑定地址，默认为 0.0.0.0
MCP_CONNECTION_TIMEOUT=30000        # (可选) 连接超时时间，单位毫秒，默认为 30000
MCP_TRANSPORT_MODE=stdio            # (可选) 传输模式，可选 stdio 或 sse，默认为 stdio

# 安全配置
SHARED_ACCESS_TOKEN=                # (可选) 设置后上传文件需要 Bearer Token 认证

# 存储客户端配置
PRIVATE_KEY=                        # (必填) Storacha Agent 私钥，用于文件上传授权
DELEGATION=                         # (可选) Base64 编码的 Delegation，授权 Agent 所有者上传文件。如未设置，则每次上传请求必须提供。
GATEWAY_URL=https://storacha.link   # (可选) 自定义文件检索网关 URL，默认为 https://storacha.link

启动服务器

Stdio 模式 (推荐本地通信):
```
pnpm start:stdio
```
SSE 模式 (推荐远程通信):
```
pnpm start:sse
```

服务器配置 (MCP客户端)

MCP 客户端需要配置以下信息以连接到 Storacha MCP 服务器。以下是 Stdio 模式的配置示例：

{
  "serverName": "storacha-mcp-server",
  "command": "node",
  "args": [
    "dist/index.js"
  ],
  "env": {
    "MCP_TRANSPORT_MODE": "stdio",
    "PRIVATE_KEY": "<Your_Storacha_Agent_Private_Key>",
    "DELEGATION": "<Your_Storacha_Delegation>"
  }
}

配置参数说明:

'serverName': 服务器名称，可以自定义。
'command': 启动 MCP 服务器的命令，这里是 'node'。
'args': 命令参数，指向服务器入口文件 'dist/index.js'。
'env': 环境变量配置，需要设置 'MCP_TRANSPORT_MODE' 为 'stdio'，并配置 Storacha Agent 的 'PRIVATE_KEY' 和 'DELEGATION'。

注意: 如果使用 SSE 模式，MCP 客户端需要配置服务器的 SSE 端点 URL，而不是启动命令。具体配置方式请参考 MCP 客户端 SDK 的文档。

基本使用方法

列出工具: 客户端连接服务器后，可以调用 'listTools' 方法列出服务器提供的工具，例如：

const response = await client.listTools();
console.log(response.tools.map(tool => tool.name));
// 输出: ['identity', 'retrieve', 'upload']

获取 Agent DID: 调用 'identity' 工具获取 Storacha Agent 的 DID 密钥：

const response = await client.callTool({
  name: 'identity',
  arguments: {}
});
console.log('Agent DID:', JSON.parse(response.content[0].text));
// 输出:  {"id":"did:key:z6MkjiNpY1QhuULQUkF5thrDbVz2fZwg49zYMg4a7zY1KDr9"}

上传文件: 调用 'upload' 工具上传文件，文件内容需要 Base64 编码：

const fileBuffer = new Uint8Array([1, 2, 3]);
const base64File = Buffer.from(fileBuffer).toString('base64');
const result = await client.callTool({
  name: 'upload',
  arguments: {
    file: base64File,
    name: 'example.txt',
    type: 'text/plain',
  }
});
console.log(result);
// 输出: {"content":[{"type":"text","text":"{\"root\":\"bafk...123\",\"rootURL\":\"https://storacha.link/ipfs/bafk...123\",\"files\":[{\"name\":\"test.txt\",\"type\":\"text/plain\",\"url\":\"https://storacha.link/ipfs/bafk...123/test.txt\"}]}"}]}

检索文件: 调用 'retrieve' 工具检索文件，需要提供文件的 root CID：

const retrieveResponse = await client.callTool({
  name: 'retrieve',
  arguments: {
    root: 'bafy...', // 替换为实际的 root CID
  },
});
console.log(retrieveResponse);
// 输出文件内容 (Base64 编码) 和类型

关键词