MCP 服务器

Storacha MCP Storage Server

通过标准化的模型上下文协议接口，使人工智能应用能够与去中心化存储进行交互，从而实现文件上传、检索和身份管理。

README

Storacha MCP 存储服务器

一个用于 Storacha 存储的模型上下文协议 (MCP) 服务器实现，使 AI 应用程序能够通过标准化接口与去中心化存储进行交互。

特性

文件操作
- 将文件上传到 Storacha 的去中心化存储网络
- 通过 Storacha 的 HTTP 网关检索文件
身份管理
- 获取 Storacha 代理的 DID 密钥
双传输模式
- HTTP 与服务器发送事件 (SSE) 用于实时通信
- Stdio 传输用于本地集成
标准化接口
- 符合 MCP 的 API，用于工具发现和调用
- JSON-RPC 消息处理
安全性
- Bearer Token
- CORS 配置
- 输入验证
- 安全的错误处理

使用场景

文档存储与分析: 安全地上传和检索 Blob 文档。
长期结构化数据存储: 维护针对长期性和可访问性优化的结构化数据存储。
代理和系统之间的数据共享: 使用 CIDs (内容标识符) 轻松地跨多个代理和不同的系统共享数据，从而实现去中心化、可验证和高效的数据交换。
应用程序集成: 通过模型上下文协议将 Storacha 存储检索无缝集成到应用程序中。
AI 模型开发: 通过提供对 Storacha 中存储的外部数据集的可靠访问来支持 AI 模型。
LLM 集成: 通过直接连接 Storacha Storage 以实现无缝数据访问来增强大型语言模型 (LLM)。
Web 应用程序备份: 可靠地存储 Web 应用程序的备份副本以进行灾难恢复。
机器学习数据集: 有效地管理和访问机器学习工作流程中使用的大型数据集。

安装

克隆存储库

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

安装依赖项
```
pnpm install
```
创建一个 .env 文件
```
cp .env.example .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=                # 可选：设置此项以要求上传进行身份验证

# 存储客户端配置
PRIVATE_KEY=                        # 必需：授权上传文件的 Storacha 代理私钥
DELEGATION=                         # 可选：base64 编码的授权，授权私钥的代理所有者上传文件。 如果未设置，则必须为每个上传请求提供。
GATEWAY_URL=https://storacha.link   # 可选：用于文件检索的自定义网关 URL（默认：https://storacha.link）

# 文件限制
MAX_FILE_SIZE=104857600             # 可选：最大文件大小，以字节为单位（默认：100MB）

启动服务器

选项 1 - 运行 Stdio 服务器（推荐用于本地服务器通信）

pnpm start:stdio

选项 2 - 运行 SSE 服务器（推荐用于远程服务器通信）

pnpm start:sse

MCP 客户端集成 (stdio 模式)

连接到 MCP 服务器

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// 创建用于通信的传输
const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/index.js'],
  env: {
    ...loadEnvVars(),
    MCP_TRANSPORT_MODE: 'stdio',
  },
});

// 实例化 MCP 客户端
client = new Client(
  {
    name: 'test-client',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// 连接到服务器
await client.connect(transport);

列出工具

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

获取代理的 DID 密钥

// 获取代理的 DID 密钥
const response = await client.callTool({
  name: 'identity',
  arguments: {}, // 发送一个空对象
});
console.log('Agent DID:', JSON.parse(response.content[0].text));
// output:  {"id":"did:key:z6MkjiNpY1QhuULQUkF5thrDbVz2fZwg49zYMg4a7zY1KDr9"}

上传文件

// 将文件上传到 MCP 服务器中委托集中定义的存储空间
const fileBuffer = new Uint8Array([1, 2, 3]);
const base64File = Buffer.from(fileBuffer).toString('base64');
const result = await client.invoke('upload', {
  file: base64File,
  name: 'example.txt',
  type: 'text/plain',
});
// output: {"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"}]}

使用自定义委托上传文件

// 将文件上传到上传请求中委托集中定义的存储空间
const result = await client.invoke('upload', {
  file: base64File,
  name: 'example.txt',
  type: 'text/plain',
  delegation: base64Delegation,
});

阅读分步指南以了解如何使用 CLI 创建委托。

使用 MCP Inspector 进行测试

MCP Inspector 提供了一个可视化界面，用于测试和调试 MCP 服务器。要测试 Storacha MCP 服务器：

启动 MCP Inspector

pnpm inspect:stdio

启动 Storacha MCP 服务器

pnpm start:stdio

连接到您的服务器
- 打开浏览器并访问 Inspector UI，网址为 http://localhost:5173/#tools
- 输入服务器 URL（例如，http://localhost:3001）
- Inspector 将自动发现可用的工具
- 您可以直接从界面测试上传和检索工具

调试技巧

检查服务器日志是否存在连接问题
验证环境变量是否设置正确
确保服务器以 SSE 或 Stdio 模式运行以实现 Inspector 兼容性

开发

项目结构

/
├── src/
│   ├── core/
│   │   ├── server/
│   │   │   ├── index.ts           # 主服务器入口点
│   │   │   ├── config.ts          # 服务器配置
│   │   │   ├── types.ts           # TypeScript 类型定义
│   │   │   ├── tools/             # MCP 工具实现
│   │   │   │   ├── index.ts       # 工具注册
│   │   │   │   ├── upload.ts      # 上传工具
│   │   │   │   ├── retrieve.ts    # 检索工具
│   │   │   │   └── identity.ts    # 身份工具
│   │   │   └── transports/        # 传输实现
│   │   │       ├── sse.ts         # SSE 传输
│   │   │       └── stdio.ts       # Stdio 传输
│   │   └── storage/               # 存储客户端实现
│   │       ├── client.ts          # 存储客户端
│   │       ├── config.ts          # 存储配置
│   │       ├── types.ts           # 存储类型
│   │       └── utils.ts           # 存储实用程序
├── test/
│   ├── core/
│   │   ├── server/
│   │   │   ├── config.test.ts     # 配置测试
│   │   │   ├── index.test.ts      # 服务器测试
│   │   │   ├── tools/             # 工具测试
│   │   │   └── transports/        # 传输测试
│   │   └── storage/               # 存储测试
│   ├── integration/               # 集成测试
│   └── setup.ts                   # 测试设置
├── .env.example                   # 示例环境变量
├── .eslintrc.json                 # ESLint 配置
├── .prettierrc                    # Prettier 配置
├── .husky/                        # Git 钩子
│   └── pre-commit                 # 预提交钩子
├── package.json                   # 项目依赖项和脚本
├── tsconfig.json                  # TypeScript 配置
└── README.md                      # 项目文档

构建

# 安装依赖项
pnpm install

# 构建项目
pnpm build

# 运行测试
pnpm test

贡献

Fork 存储库
创建您的功能分支 (git checkout -b feature/amazing-feature)
提交您的更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开 Pull Request

许可证

MIT 或 Apache 2 License

支持

如需支持，请访问 Storacha Support 或在此存储库中打开一个 issue。