# mcp-dropbox

[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/release/python-3130/)
[![License: Non-Commercial](https://img.shields.io/badge/License-Non--Commercial-red.svg)](LICENSE)
[![FastMCP](https://img.shields.io/badge/FastMCP-Supported-brightgreen.svg)](https://gofastmcp.com/)

<div align="center">
  <img src="mcp_dropbox.png" alt="MCP Dropbox Logo" width="300" />
</div>
<br>

Servidor **MCP (Model Context Protocol)** construido con [FastMCP](https://gofastmcp.com/) para recibir documentos desde un agente (por ejemplo, un agente de OpenAI) y guardarlos en dropbox. El proyecto está pensado como un Remote MCP Server: simple, mantenible y escalable.

## Descripción

Este MCP expone herramientas (tools) que un agente puede invocar de forma remota.

### Tools de Dropbox disponibles

| Tool                        | Descripción                                                                    | Parámetros                                                                                                                             |
| --------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `create_folder`           | Crea una carpeta en Dropbox (idempotente: si ya existe, no falla).              | `path: str`, `folder_name: str`                                                                                                     |
| `folder_exists`           | Verifica si una carpeta existe en una ruta dada.                                | `path: str`, `folder_name: str`                                                                                                     |
| `delete_folder`           | Borra el contenido (subcarpetas) de un directorio.                              | `directory_path: str`                                                                                                                 |
| `create_shared_link_file` | Crea o recupera un enlace público para un archivo o carpeta.                   | `path: str`, `expires_days: Optional[int]`, `password: Optional[str]`, `access_level: str`, `folder_settings: Optional[dict]` |
| `upload_file`             | Sube un archivo local a Dropbox (con soporte de sesiones para archivos >150MB). | `path_local_file: str`, `remote_file_upload: str`                                                                                   |
| `list_directories`        | Lista las subcarpetas de una ruta (no recursivo).                               | `path: str`                                                                                                                           |
| `list_files`              | Lista los archivos de una ruta (no recursivo).                                  | `path: str`                                                                                                                           |
| `upload_file_binario`     | Recibe un archivo en base64, lo guarda en `HD_DESCARGAS/` y lo sube a Dropbox en segundo plano (vía `process_upload.py`). | `nombre_archivo: str`, `contenido_base64: str`, `dropbox_path: str` |

`upload_file_binario` acepta dos variables de entorno opcionales para lanzar el subproceso: `_APP_PATH_` (raíz del proyecto; por defecto se detecta automáticamente) y `_PYTHON_APP_` (intérprete de Python; por defecto el mismo que ejecuta el servidor).

Cada tool documenta sus parámetros y valores de retorno en su propio docstring; para verlos vía CLI:

```bash
uv run fastmcp list http://127.0.0.1:8000/mcp --auth mi-token-secreto-dropbox --input-schema
```

## Requisitos

- Python 3.13+
- [uv](https://docs.astral.sh/uv/)

## Instalación de uv

### macOS / Linux

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Windows

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Verifica la instalación con:

```bash
uv --version
```

## Crear el entorno virtual

```bash
uv venv
```

Activar el entorno:

- macOS / Linux: `source .venv/bin/activate`
- Windows: `.venv\Scripts\activate`

## Instalar dependencias (pyproject.toml)

Con el entorno virtual activo, instala las dependencias declaradas en `pyproject.toml`:

```bash
uv sync
```

## Autenticación

El servidor exige un token Bearer para todas las peticiones. El token válido se define mediante la variable de entorno `MCP_AUTH_TOKEN` (no se hardcodea en el código) `MCP_AUTH_TOKEN` es el token con los permisos nesesario en dropbox.

Para levantar el servidor con autenticación activada:

```bash
MCP_AUTH_TOKEN=mi-token-secreto-dropbox uv run python3 main.py
```

Variables opcionales:

- `MCP_HOST` (por defecto `0.0.0.0`)
- `MCP_PORT` (por defecto `8000`)
- `MCP_ALLOWED_HOSTS`: dominios permitidos en el header `Host` (separados por coma). Necesario cuando expones el servidor a través de un túnel (ngrok, cloudflared) o dominio propio; de lo contrario el servidor responde `421 Misdirected Request`, ya que por seguridad solo acepta `localhost`/`127.0.0.1` por defecto. Ejemplo: `MCP_ALLOWED_HOSTS=*.ngrok-free.app` o `MCP_ALLOWED_HOSTS=mi-tunel.ngrok-free.app`

Cualquier cliente (incluido el agente) debe enviar el header:

```text
Authorization: Bearer mi-token-secreto-dropbox
```

## Ejecutar el servidor

```bash
MCP_AUTH_TOKEN=mi-token-secreto-dropbox uv run python3 main.py
```

Esto levanta el servidor en `http://0.0.0.0:8000/mcp` (o el `MCP_PORT` que definas).

Según cómo quieras dejarlo corriendo:

1. **Primer plano (para probar)**: el comando de arriba tal cual; se detiene con `Ctrl+C`.
2. **En segundo plano**: agrega `&` al final, o usa `nohup ... &` para que sobreviva si cierras la terminal.
3. **Como servicio persistente** (recomendado si un agente debe conectarse en todo momento): usa algo que lo mantenga vivo y lo reinicie si falla, por ejemplo un `launchd` plist en macOS, o Docker/systemd en un servidor Linux.
4. **Accesible desde internet**: como corre en `0.0.0.0`, localmente solo es alcanzable en tu red. Para exponerlo a un agente remoto (por ejemplo un agente de OpenAI) necesitas un túnel (`ngrok`, `cloudflared`) mientras pruebas, o desplegarlo en un servidor/VPS con IP pública para producción.

## Ver la documentación de las tools disponibles

El endpoint `/mcp` no es una API REST navegable (no muestra una página de documentación en el navegador): es un endpoint JSON-RPC que espera peticiones `POST` con headers específicos. Además, si accedes usando `http://0.0.0.0:8000/mcp` verás el error **"Misdirected Request" (421)**, ya que `0.0.0.0` solo indica en qué interfaces escucha el servidor, no es una dirección válida para conectarte: usa `http://127.0.0.1:8000/mcp` o `http://localhost:8000/mcp` en su lugar.

Para listar las tools disponibles y su esquema, usa la CLI de FastMCP:

```bash
uv run fastmcp list http://127.0.0.1:8000/mcp --auth mi-token-secreto-dropbox --input-schema
```

### Inspector visual (MCP Inspector)

Para explorar y probar las tools desde una interfaz web interactiva, usa el MCP Inspector (requiere Node.js/npx instalado). No necesitas tener el servidor corriendo por separado: el propio comando lo levanta.

```bash
MCP_AUTH_TOKEN=mi-token-secreto-dropbox uv run fastmcp dev inspector main.py
```

Esto abre automáticamente el navegador en una URL tipo `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=...`, donde puedes ver las tools disponibles, sus esquemas y ejecutarlas manualmente con distintos parámetros.

## Despliegue en Producción (Ubuntu 24.04)

Para entornos de producción (por ejemplo, en un VPS con Ubuntu 24.04 y un dominio como `mcp.dominio.com`), se incluye un archivo de configuración de systemd (`mcp-dropbox.service`).

1. **Sube tu código al servidor**, por ejemplo a `/var/www/mcp_dropbox`.
2. **Asegúrate de instalar `uv`** en el servidor y ejecuta `uv sync` en la carpeta del proyecto.
3. **Configura el token (Archivo `.env`):**
   Crea un archivo `.env` en la ruta de tu proyecto para mantener seguro el token:

   ```bash
   sudo nano /var/www/mcp_dropbox/.env
   ```

   Agrega la siguiente línea:

   ```env
   MCP_AUTH_TOKEN=aqui-tu-token-super-seguro-dropbox
   ```

4. **Instala y habilita el servicio de systemd:**
   Asegúrate de que las rutas y el usuario en `mcp-dropbox.service` coincidan con tu servidor, luego ejecuta:

   ```bash
   sudo cp /var/www/mcp_dropbox/mcp-dropbox.service /etc/systemd/system/mcp-dropbox.service
   sudo systemctl daemon-reload
   sudo systemctl enable mcp-dropbox
   sudo systemctl start mcp-dropbox
   ```

5. **Verifica el estado del servicio:**

   ```bash
   sudo systemctl status mcp-dropbox
   ```

*Nota: Necesitarás configurar un proxy inverso (como Nginx o Caddy) en el servidor para redirigir el tráfico de tu dominio (`mcp.dominio.com`) en los puertos 80/443 hacia el servicio interno en `http://127.0.0.1:8000`.*

## Licencia

Este proyecto se distribuye bajo una licencia de uso No Comercial. Permite su uso libre para fines personales, académicos o de investigación, pero prohíbe cualquier uso comercial o corporativo sin autorización previa. Ver [LICENSE](LICENSE) para más detalles.