dbx-mcp-server

Un servidor de Protocolo de Contexto de Modelo (MCP) que provee integración con Dropbox, permitiendo a clientes compatibles con MCP interactuar con Dropbox a través de un conjunto de poderosas herramientas.

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

Tabla de contenidos

• Inicio rápido
• Instalación
• Autenticación
• Herramientas disponibles
• Configuración
• Ejemplos de uso
• Pruebas
• Desarrollo
• Licencia

Inicio rápido

1. Clonar 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 "Scoped access
   • Elige el tipo de acceso que necesita tu aplicación
   • Asigna un nombre a tu aplicación y haz clic en "Crear aplicación"
   • En "Permisos", selecciona los permisos necesarios
     • files.metadata.read
     • files.content.read
     • archivos.contenido.escribir
     • compartir.escribir
     • account_info.read
   • Añada http://localhost:3000/callback como URI de redirección
   • Anote la clave y el secreto de su aplicación
5. Ejecute el script de instalación:

   npm run setup

6. Configure su cliente MCP para utilizar el servidor

Instalación

1. Clone 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. Ejecutar el script de instalación

   npm run setup

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

   Añada lo siguiente a su archivo de configuración 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 la autenticación segura con Dropbox.

Variables de entorno

Obligatorias:

• 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 de OAuth
• TOKEN_ENCRYPTION_KEY: Clave de más de 32 caracteres para el cifrado de tokens

Opcional:

• TOKEN_REFRESH_THRESHOLD_MINUTES: Minutos antes de la caducidad para actualizar el token (por defecto: 5)
• MAX_TOKEN_REFRESH_RETRIES: Número máximo de intentos de actualización (por defecto: 3)
• TOKEN_REFRESH_RETRY_DELAY_MS: retardo entre intentos de actualización en ms (por defecto: 1000)

Herramientas disponibles

Operaciones con archivos

• list_files: Lista los archivos de un directorio
• subir_archivo: Subir un fichero
• descargar_archivo: Descargar un archivo
• safe_delete_item: Eliminar de forma segura con soporte de papelera de reciclaje
• create_folder: Crear una nueva carpeta
• copy_item: Copiar un archivo o carpeta
• mover_elemento: Mover o renombrar un archivo/carpeta

Metadatos y búsqueda

• get_file_metadata: Obtener metadatos de archivo/carpeta
• search_file_db: Buscar archivos y carpetas
• get_sharing_link: Crear enlaces compartidos
• get_file_content: Obtener contenido de archivos

Operaciones de cuenta

• get_account_info: Obtener información de la cuenta

Ejemplos de uso

// Listar ficheros en el directorio raíz await mcp.useTool("dbx-mcp-server", "list_files", { path: "" }); // Subir un fichero await mcp.useTool("dbx-mcp-server", "upload_file", { path: "/prueba.txt", contenido: Buffer.from("Hola Mundo").toString("base64"), }); // Buscar archivos await mcp.useTool("dbx-mcp-server", "search_file_db", { query: "informe", ruta: "/Documentos", max_results: 10, })

Pruebas

Ejecute el conjunto de pruebas:

npm test

Las pruebas verifican todas las operaciones, incluida la autenticación, las operaciones con archivos y la gestión de errores.

Estructura de las 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 decuenta: Pruebas de acceso a la información de la cuenta
• Búsqueda y eliminación: Pruebas de funcionalidad de búsqueda y borrado seguro con soporte de papelera de reciclaje
• Sistema de recursos: Pruebas de integración del sistema de recursos MCP

Manejo de los datos de prueba

Las pruebas utilizan nombres de archivos y carpetas generados dinámicamente a partir de marcas de tiempo para evitar conflictos. Los datos de las pruebas se limpian automáticamente tras su ejecución.

Ejecución de pruebas específicas

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

npm test -- tests/dropbox/search-delete.test.ts # Ejecutar archivo de prueba específico npm test -- -t "debe buscar archivos" # Ejecutar pruebas que coincidan con la descripción

Resolución de problemas

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

1. Compruebe que las implementaciones simuladas en tests/setup.ts coinciden con sus expectativas de prueba
2. Asegúrese de que los ayudantes de prueba están correctamente configurados
3. Para los errores de ámbito de Jest, evite hacer referencia a variables importadas en funciones de fábrica simuladas

Desarrollo

Construido con:

• TypeScript
• SDK de protocolo de contexto de modelo
• SDK de Dropbox v10.34.0
• API de Dropbox v2

Licencia

Licencia MIT

Copyright (c) 2025 Colaboradores del servidor MCP

Por el presente documento 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 comerciar con el Software sin restricciones, incluidos, entre otros, los derechos de uso, copia, modificación, fusión, publicación, distribución, sublicencia y/o venta de copias del Software, y para permitir que las personas a las que se proporcione el Software lo hagan, con sujeción 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 SUMINISTRA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUIDAS, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN DETERMINADO Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O LOS TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE NINGUNA RECLAMACIÓN, DAÑO U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN CONTRACTUAL, EXTRACONTRACTUAL O DE OTRO TIPO, QUE SURJA DE, O ESTÉ RELACIONADA CON EL SOFTWARE O EL USO U OTRAS OPERACIONES CON EL SOFTWARE.