dbx-mcp-server

Un servidor MCP para interactuar con archivos y servicios de Dropbox.

GitHubPrueba este MCPPatrocinado

Documentación

dbx-mcp-server

Un servidor de Model Context Protocol (MCP) que proporciona integración con Dropbox, permitiendo que clientes compatibles con MCP interactúen con Dropbox a través de un conjunto de herramientas potentes.

Aviso importante: Este proyecto no está afiliado, respaldado ni patrocinado por Dropbox. Es una integración independiente que funciona con la API pública de Dropbox.

Tabla de Contenidos

Inicio Rápido

  1. Clona el repositorio
  2. Ejecuta npm install para instalar las dependencias
  3. Ejecuta npm run build para compilar el proyecto
  4. Registra una aplicación de Dropbox en Dropbox App Console:
    • Elige la API de "Acceso con ámbito" (Scoped access)
    • Elige el tipo de acceso que tu aplicación necesita
    • Nombra tu aplicación y haz clic en "Crear aplicación"
    • En "Permisos", selecciona los permisos requeridos:
      • files.metadata.read
      • files.content.read
      • files.content.write
      • sharing.write
      • account_info.read
    • Añade http://localhost:3000/callback como tu URI de redirección
    • Anota tu clave de aplicación y secreto de aplicación
  5. Ejecuta el script de configuración: 
    npm run setup
  6. Configura tu cliente MCP para usar el servidor

Instalación

  1. Clona el repositorio

    git clone https://github.com/your-username/dbx-mcp-server.git
cd dbx-mcp-server

  2. Instala las dependencias y compila

    npm install
npm run build

  3. Ejecuta el script de configuración

    npm run setup

  4. Añade a la configuración de MCP

    Añade lo siguiente a tu archivo de configuración de MCP:

    {
  "mcpServers": {
    "dbx": {
      "command": "node",
      "args": ["/path/to/dbx-mcp-server/build/index.js"]
    }
  }
}

Autenticación

El servidor utiliza OAuth 2.0 con PKCE para una autenticación segura con Dropbox.

Variables de Entorno

Requeridas:

  • DROPBOX_APP_KEY: La clave de tu aplicación de Dropbox
  • DROPBOX_APP_SECRET: El secreto de tu aplicación de Dropbox
  • DROPBOX_REDIRECT_URI: URI de redirección OAuth
  • TOKEN_ENCRYPTION_KEY: Clave de 32+ caracteres para el cifrado de tokens

Opcionales:

  • TOKEN_REFRESH_THRESHOLD_MINUTES: Minutos antes de la expiración para renovar el token (predeterminado: 5)
  • MAX_TOKEN_REFRESH_RETRIES: Número máximo de intentos de renovación (predeterminado: 3)
  • TOKEN_REFRESH_RETRY_DELAY_MS: Retraso entre intentos de renovación en ms (predeterminado: 1000)

Herramientas Disponibles

Operaciones de Archivos

  • list_files: Lista archivos en un directorio
  • upload_file: Sube un archivo
  • download_file: Descarga un archivo
  • safe_delete_item: Elimina de forma segura con soporte de papelera de reciclaje
  • create_folder: Crea una nueva carpeta
  • copy_item: Copia un archivo o carpeta
  • move_item: Mueve o renombra un archivo/carpeta

Metadatos y Búsqueda

  • get_file_metadata: Obtiene metadatos de archivo/carpeta
  • search_file_db: Busca archivos y carpetas
  • get_sharing_link: Crea enlaces de uso compartido
  • get_file_content: Obtiene el contenido de un archivo

Operaciones de Cuenta

  • get_account_info: Obtiene información de la cuenta

Ejemplos de Uso

// List files in root directory
await mcp.useTool("dbx-mcp-server", "list_files", { path: "" });

// Upload a file
await mcp.useTool("dbx-mcp-server", "upload_file", {
  path: "/test.txt",
  content: Buffer.from("Hello World").toString("base64"),
});

// Search for files
await mcp.useTool("dbx-mcp-server", "search_file_db", {
  query: "report",
  path: "/Documents",
  max_results: 10,
});

Pruebas

Ejecuta el conjunto de pruebas:

npm test

Las pruebas verifican todas las operaciones, incluyendo autenticación, operaciones de archivos y manejo de errores.

Estructura de Pruebas

El conjunto de pruebas está organizado en varios módulos:

  • Operaciones de Dropbox: Pruebas para operaciones básicas de archivos (subir, descargar, listar, etc.)
  • Operaciones de Cuenta: Pruebas para acceder a la información de la cuenta
  • Búsqueda y Eliminación: Pruebas para la funcionalidad de búsqueda y eliminación segura con soporte de papelera de reciclaje
  • Sistema de Recursos: Pruebas para la integración del sistema de recursos de MCP

Manejo de Datos de Prueba

Las pruebas utilizan nombres de archivos y carpetas generados dinámicamente basados en marcas de tiempo para evitar conflictos. Los datos de prueba se limpian automáticamente después de la ejecución de las pruebas.

Ejecutar Pruebas Específicas

Para ejecutar un archivo de prueba o grupo de pruebas específico:

npm test -- tests/dropbox/search-delete.test.ts  # Run specific test file
npm test -- -t "should search for files"        # Run tests matching description

Solución de Problemas en Pruebas

Si las pruebas fallan con problemas de tiempo o autenticación:

  1. Verifica que las implementaciones simuladas en tests/setup.ts coincidan con tus expectativas de prueba
  2. Asegúrate de que los ayudantes de prueba estén configurados correctamente
  3. Para errores de ámbito de Jest, evita referenciar variables importadas en funciones de fábrica simuladas

Desarrollo

Construido con:

  • TypeScript
  • Model Context Protocol SDK
  • Dropbox SDK v10.34.0
  • Dropbox API v2

Licencia

Licencia MIT

Copyright (c) 2025 MCP Server Contributors

Se concede permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados (el "Software"), para tratar con el Software sin restricción, incluyendo sin limitación los derechos de usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y para permitir a las personas a quienes se les proporcione el Software hacerlo, sujeto a las siguientes condiciones:

El aviso de copyright anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO PERO NO LIMITADO A LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN PROPÓSITO PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE DERECHOS DE AUTOR SERÁN RESPONSABLES DE CUALQUIER RECLAMO, DAÑO U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRO MODO, QUE SURJA DE, FUERA DE O EN CONEXIÓN CON EL SOFTWARE O EL USO U OTROS TRATOS EN EL SOFTWARE.

smithery badge