Storacha MCP 存储服务器

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

特征

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

美国案例

文档存储和分析：安全地上传和检索 Blob 文档。
长期结构化数据存储：维护针对长寿命和可访问性进行优化的结构化数据存储。
代理和系统之间的数据共享：使用**CID（内容标识符）**轻松在多个代理和不同系统之间共享数据，实现分散、可验证和高效的数据交换。
应用程序集成：通过模型上下文协议将 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 Server Configuration MCP_SERVER_PORT=3001 # Optional: The port the server will listen on (default: 3001) MCP_SERVER_HOST=0.0.0.0 # Optional: The host address to bind to (default: 0.0.0.0) MCP_CONNECTION_TIMEOUT=30000 # Optional: The connection timeout in milliseconds (default: 30000) MCP_TRANSPORT_MODE=stdio # Optional: The transport mode to use (stdio or sse) (default: stdio) # Security SHARED_ACCESS_TOKEN= # Optional: Set this to require authentication for uploads # Storage Client Configuration PRIVATE_KEY= # Required: The Storacha Agent private key that is authorized to upload files DELEGATION= # Optional: The base64 encoded delegation that authorizes the Agent owner of the private key to upload files. If not set, MUST be provided for each upload request. GATEWAY_URL=https://storacha.link # Optional: Custom gateway URL for file retrieval (default: https://storacha.link) # File Limits MAX_FILE_SIZE=104857600 # Optional: Maximum file size in bytes (default: 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';

// Create the transport for communication
const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/index.js'],
  env: {
    ...loadEnvVars(),
    MCP_TRANSPORT_MODE: 'stdio',
  },
});

// Instantiate the MCP client
client = new Client(
  {
    name: 'test-client',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// Connect to the server
await client.connect(transport);

列表工具

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

获取代理的 DID 密钥

// Get the agent's DID key
const response = await client.callTool({
  name: 'identity',
  arguments: {}, // Send an empty object
});
console.log('Agent DID:', JSON.parse(response.content[0].text));
// output:  {"id":"did:key:z6MkjiNpY1QhuULQUkF5thrDbVz2fZwg49zYMg4a7zY1KDr9"}

上传文件

// Upload a file to the storage space defined in the delegation set in the MCP Server
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"}]}

使用自定义委托上传文件

// Upload a file to the storage space defined in the delegation set in the upload request
const result = await client.invoke('upload', {
  file: base64File,
  name: 'example.txt',
  type: 'text/plain',
  delegation: base64Delegation,
});

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

使用 MCP Inspector 进行测试

MCP 检查器提供了一个可视化界面，用于测试和调试 MCP 服务器。要测试 Storacha MCP 服务器，请执行以下操作：

启动 MCP 检查器

pnpm inspect:stdio

启动 Storacha MCP 服务器

pnpm start:stdio

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

调试技巧

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

发展

项目结构

/
├── src/
│   ├── core/
│   │   ├── server/
│   │   │   ├── index.ts           # Main server entry point
│   │   │   ├── config.ts          # Server configuration
│   │   │   ├── types.ts           # TypeScript type definitions
│   │   │   ├── tools/             # MCP tools implementation
│   │   │   │   ├── index.ts       # Tool registration
│   │   │   │   ├── upload.ts      # Upload tool
│   │   │   │   ├── retrieve.ts    # Retrieve tool
│   │   │   │   └── identity.ts    # Identity tool
│   │   │   └── transports/        # Transport implementations
│   │   │       ├── sse.ts         # SSE transport
│   │   │       └── stdio.ts       # Stdio transport
│   │   └── storage/               # Storage client implementation
│   │       ├── client.ts          # Storage client
│   │       ├── config.ts          # Storage configuration
│   │       ├── types.ts           # Storage types
│   │       └── utils.ts           # Storage utilities
├── test/
│   ├── core/
│   │   ├── server/
│   │   │   ├── config.test.ts     # Configuration tests
│   │   │   ├── index.test.ts      # Server tests
│   │   │   ├── tools/             # Tool tests
│   │   │   └── transports/        # Transport tests
│   │   └── storage/               # Storage tests
│   ├── integration/               # Integration tests
│   └── setup.ts                   # Test setup
├── .env.example                   # Example environment variables
├── .eslintrc.json                 # ESLint configuration
├── .prettierrc                    # Prettier configuration
├── .husky/                        # Git hooks
│   └── pre-commit                 # Pre-commit hook
├── package.json                   # Project dependencies and scripts
├── tsconfig.json                  # TypeScript configuration
└── README.md                      # Project documentation

建筑

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

贡献

分叉存储库
创建你的功能分支（ git checkout -b feature/amazing-feature ）
提交您的更改（ git commit -m 'Add some amazing feature' ）
推送到分支（ git push origin feature/amazing-feature ）
打开拉取请求

执照

MIT 或 Apache 2 许可证

支持

如需支持，请访问Storacha 支持或在此存储库中打开问题。