MCP File Organizer — demo para el artículo del blog técnico "MCP in Practice"

Una demo que ilustra MCP mediante el caso de uso "Asistente de organización de archivos con IA": un servidor MCP que expone 2 herramientas de gestión de archivos (list_files, move_file — sin read_file; el servidor nunca lee el contenido de los archivos, solo el nombre, la extensión y la fecha de modificación), y un cliente/agente MCP que usa Gemini (a través de @google/genai, con soporte MCP integrado mediante mcpToTool) para decidir qué herramienta llamar según la solicitud en lenguaje natural del usuario. folder es cualquier ruta absoluta de la máquina (no se limita a storage/inbox de la demo — puede apuntar a una carpeta real como Downloads), y los resultados siempre van a parar a <folder>/organized/<extension>/<year>/<month>/<day>/. El conjunto de datos de la demo son 500 archivos simulados acumulados durante 365 días, reorganizados por extensión y luego por año/mes/día de la última modificación.

Configuración

npm install

Related MCP server: Organizer MCP Server

Generación de datos simulados

npm run generate-mock   # generates 500 mock files into storage/inbox, with mtimes spread across the last 365 days

Vuelve a ejecutar este comando en cualquier momento para generar un conjunto de datos nuevo.

Ejecución del agente real (requiere una clave de API de Gemini)

client/client.ts es el agente real: expone el cliente MCP a Gemini mediante mcpToTool, lo que permite que Gemini decida por sí mismo qué herramienta llamar y con qué argumentos (llamada automática a funciones), sin reglas codificadas. Lee la clave de GEMINI_API_KEY, o GOOGLE_API_KEY, o API_KEY (en ese orden de prioridad); lee el modelo de MODEL si el valor empieza por gemini-; de lo contrario, recurre al valor predeterminado gemini-2.5-flash.

# PowerShell
$env:GEMINI_API_KEY = "AIza..."
npm run agent

# bash
export GEMINI_API_KEY="AIza..."
npm run agent

Estas variables también se pueden definir en un archivo .env en el directorio del proyecto; npm run agent carga .env automáticamente si existe (usando la opción --env-file-if-exists de Node).

Para probarlo en una carpeta real en lugar de storage/inbox, pasa una ruta absoluta como argumento, p. ej. npm run agent -- "C:\Users\you\Downloads".

Seguridad al usar datos reales

server.ts ya protege contra varios casos antes de tocar el sistema de archivos:

• folder debe ser una ruta absoluta: una ruta relativa se rechaza de inmediato, nunca se resuelve en silencio contra el directorio de trabajo del proceso del servidor.

• name debe ser un nombre de archivo simple (sin /, \ ni ..): bloquea el acceso fuera de folder.

• to_folder se resuelve y luego se vuelve a comprobar para garantizar que permanezca dentro de <folder>/organized/: bloquea el acceso fuera mediante ...

• move_file se niega si el destino ya existe (nunca sobrescribe en silencio); pasa dry_run: true para previsualizar lo que se movería sin tocar archivos reales.

• Define la variable de entorno ALLOWED_ROOTS (una lista de rutas absolutas, delimitadas por ; en Windows o : en Unix, siguiendo path.delimiter) para restringir folder solo a esas raíces. Si no está definida, la demo conserva su comportamiento original: acepta cualquier carpeta absoluta, lo cual está bien para fines de demostración, pero ALLOWED_ROOTS debería definirse al apuntar a datos reales.

Estructura

server/server.ts               MCP Server: list_files, move_file — folder is any absolute path, never reads file contents
client/generate-mock-inbox.ts  Generates 500 mock files into storage/inbox
client/client.ts               MCP Client + Agent, using Gemini via @google/genai
storage/                       Generated by running generate-mock, not committed to the repo