Storacha MCP 스토리지 서버

Storacha 스토리지를 위한 MCP(Model Context Protocol) 서버 구현으로, AI 애플리케이션이 표준화된 인터페이스를 통해 분산 스토리지와 상호 작용할 수 있게 해줍니다.

특징

파일 작업
- Storacha의 분산형 스토리지 네트워크에 파일을 업로드하세요
- Storacha의 HTTP 게이트웨이를 통해 파일 검색
ID 관리
- Storacha 에이전트의 DID 키를 얻으세요
이중 전송 모드
- 실시간 통신을 위한 SSE(Server-Sent Events)를 사용한 HTTP
- 로컬 통합을 위한 Stdio 전송
표준화된 인터페이스
- 도구 검색 및 호출을 위한 MCP 호환 API
- JSON-RPC 메시지 처리
보안
- 베어러 토큰
- CORS 구성
- 입력 검증
- 안전한 오류 처리

미국 사례

문서 저장 및 분석 : Blob 문서를 안전하게 업로드하고 검색합니다.
장기 구조화된 데이터 저장 : 장수명과 접근성을 위해 최적화된 구조화된 데이터 저장을 유지합니다.
에이전트와 시스템 간 데이터 공유 : CID(콘텐츠 식별자)를 사용하여 여러 에이전트와 다양한 시스템에서 데이터를 쉽게 공유하여 분산되고 검증 가능하며 효율적인 데이터 교환을 구현합니다.
애플리케이션 통합 : Model Context Protocol을 통해 Storacha 스토리지 검색을 애플리케이션에 원활하게 통합합니다.
AI 모델 개발 : Storacha에 저장된 외부 데이터 세트에 대한 안정적인 액세스를 제공하여 AI 모델을 지원합니다.
LLM 통합 : 원활한 데이터 액세스를 위해 Storacha Storage에 직접 연결하여 대규모 언어 모델(LLM)을 향상시킵니다.
웹 애플리케이션 백업 : 재해 복구를 위해 웹 애플리케이션의 백업 사본을 안정적으로 저장합니다.
머신 러닝 데이터 세트 : 머신 러닝 워크플로에 사용되는 대규모 데이터 세트를 효율적으로 관리하고 액세스합니다.

설치

저장소를 복제합니다지엑스피1
종속성 설치
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 Inspector는 MCP 서버 테스트 및 디버깅을 위한 시각적 인터페이스를 제공합니다. Storacha MCP 서버를 테스트하려면 다음을 수행하세요.

MCP 검사기 시작

pnpm inspect:stdio

Storacha MCP 서버 시작

pnpm start:stdio

서버에 연결하세요
- 브라우저를 열고 http://localhost:5173/#tools 에서 Inspector UI에 액세스하세요.
- 서버 URL을 입력하세요(예: http://localhost:3001 )
- 검사기는 사용 가능한 도구를 자동으로 검색합니다.
- 인터페이스에서 직접 업로드 및 검색 도구를 테스트할 수 있습니다.

디버깅 팁

연결 문제가 있는지 서버 로그를 확인하세요.
환경 변수가 올바르게 설정되었는지 확인하세요
Inspector 호환성을 위해 서버가 SSE 또는 Stdio 모드로 실행 중인지 확인하세요.

개발

프로젝트 구조

/
├── 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 지원을 방문하거나 이 저장소에서 문제를 열어주세요.