Servidor de almacenamiento Storacha MCP

Una implementación de servidor de Protocolo de contexto de modelo (MCP) para el almacenamiento Storacha, que permite que las aplicaciones de IA interactúen con el almacenamiento descentralizado a través de una interfaz estandarizada.

Características

Operaciones con archivos
- Sube archivos a la red de almacenamiento descentralizada de Storacha
- Recuperar archivos a través de la puerta de enlace HTTP de Storacha
Gestión de identidad
- Obtenga la clave DID del agente de Storacha
Modos de transporte duales
- HTTP con eventos enviados por el servidor (SSE) para comunicación en tiempo real
- Transporte de Stdio para integraciones locales
Interfaz estandarizada
- API compatible con MCP para el descubrimiento e invocación de herramientas
- Manejo de mensajes JSON-RPC
Seguridad
- Token al portador
- Configuración de CORS
- Validación de entrada
- Manejo seguro de errores

Casos en Estados Unidos

Almacenamiento y análisis de documentos : cargue y recupere documentos Blob de forma segura.
Almacenamiento de datos estructurados a largo plazo : mantenga el almacenamiento de datos estructurados optimizado para la longevidad y la accesibilidad.
Intercambio de datos entre agentes y sistemas : comparta datos fácilmente entre múltiples agentes y diversos sistemas utilizando CID (identificadores de contenido) , lo que permite un intercambio de datos descentralizado, verificable y eficiente.
Integración de aplicaciones : integre sin problemas la recuperación de almacenamiento de Storacha en las aplicaciones a través del Protocolo de contexto de modelo.
Desarrollo de modelos de IA : apoye los modelos de IA proporcionando acceso confiable a conjuntos de datos externos almacenados en Storacha.
Integración LLM : mejore los modelos de lenguaje grandes (LLM) conectándose directamente con Storacha Storage para obtener un acceso perfecto a los datos.
Copias de seguridad de aplicaciones web : almacene de forma confiable copias de seguridad de aplicaciones web para recuperación ante desastres.
Conjuntos de datos de aprendizaje automático : administre y acceda de manera eficiente a grandes conjuntos de datos utilizados en flujos de trabajo de aprendizaje automático.

Instalación

Clonar el repositorio
git clone https://github.com/storacha/mcp-storage-server.git cd mcp-storage-server
Instalar dependencias
pnpm install
Crear un archivo .env
cp .env.example .env
Configure el servidor utilizando las siguientes variables de entorno
# 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)

Iniciando el servidor

Opción 1: Ejecutar el servidor Stdio (recomendado para la comunicación con el servidor local)

pnpm start:stdio

Opción 2: Ejecutar el servidor SSE (recomendado para la comunicación con servidores remotos)

pnpm start:sse

Integración de cliente MCP (modo stdio)

Conectarse al servidor 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);

Herramientas de lista

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

Obtenga la clave DID del agente

// 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"}

Subir un archivo

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

Subir un archivo usando una delegación personalizada

// 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,
});

Lea la guía paso a paso para aprender a crear una delegación usando la CLI.

Pruebas con MCP Inspector

El Inspector MCP proporciona una interfaz visual para probar y depurar servidores MCP. Para probar el servidor MCP de Storacha:

Iniciar el Inspector MCP

pnpm inspect:stdio

Inicie el servidor Storacha MCP

pnpm start:stdio

Conéctese a su servidor
- Abra el navegador y acceda a la interfaz de usuario del Inspector en http://localhost:5173/#tools
- Introduzca la URL del servidor (por ejemplo, http://localhost:3001 )
- El Inspector descubrirá automáticamente las herramientas disponibles
- Puede probar las herramientas de carga y recuperación directamente desde la interfaz

Consejos de depuración

Verifique los registros del servidor para detectar problemas de conexión
Verificar que las variables de entorno estén configuradas correctamente
Asegúrese de que el servidor se esté ejecutando en modo SSE o Stdio para la compatibilidad con Inspector

Desarrollo

Estructura del proyecto

/
├── 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

Edificio

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

Contribuyendo

Bifurcar el repositorio
Crea tu rama de funciones ( git checkout -b feature/amazing-feature )
Confirme sus cambios ( git commit -m 'Add some amazing feature' )
Empujar a la rama ( git push origin feature/amazing-feature )
Abrir una solicitud de extracción

Licencia

Licencia MIT o Apache 2

Apoyo

Para obtener ayuda, visite el Soporte de Storacha o abra un problema en este repositorio.