shutil-mcp

Un servidor MCP que proporciona utilidades de shell asíncronas usando aioshutil.

Este proyecto ofrece un conjunto de herramientas de sistema de archivos diseñadas para agentes de IA, que devuelven salida JSON estructurada en lugar de texto sin formato. Esto permite un consumo más preciso y directo de los datos del sistema de archivos por parte de los modelos de IA.

Características

• Operaciones asíncronas: Aprovecha aioshutil y ejecutores de hilos para tareas de sistema de archivos no bloqueantes.

• Salida JSON: Todas las herramientas devuelven JSON minimizado, optimizado para agentes de IA.

• Soporte de jail: Restringe el acceso al sistema de archivos a un árbol de directorios específico por seguridad.

• Verificación e integridad: mv y cp verifican los datos de destino antes de desvincular o finalizar, evitando la pérdida de datos en fallos parciales.

• Mutaciones reversibles y deshacer: chmod y chown devuelven los modos y la propiedad anteriores para facilitar deshacer/rehacer inmediato, con reversión automática en caso de fallo.

• Eliminación suave y recuperación: rm admite eliminación suave con trash=True y una herramienta restore correspondiente.

• Protección contra zip-slip: unpack_archive valida todas las rutas de los miembros del archivo contra ataques de traversal de directorios / zip-slip.

• Metadatos detallados: Herramientas como ls y stat proporcionan información completa (tamaño, mtime, modo, propietario, etc.).

• Soporte de transporte HTTP: Incluye soporte integrado para transportes HTTP SSE y Streamable.

Related MCP server: File Manager MCP Server

Herramientas disponibles

• ls: Lista el contenido del directorio con metadatos detallados.

• cp: Copia archivos o directorios recursivamente con verificación.

• mv: Mueve/renombra archivos o directorios con verificación segura antes de la eliminación.

• rm: Elimina archivos o directorios (admite eliminación suave con trash=True).

• restore: Restaura archivos o directorios desde la papelera.

• chmod: Cambia los permisos de archivos/directorios con reversión y modo anterior.

• chown: Cambia la propiedad de archivos/directorios con reversión y propietario anterior.

• disk_usage: Obtiene estadísticas de uso de disco para una ruta.

• which: Encuentra la ruta a un ejecutable.

• cat: Lee el contenido de un archivo, opcionalmente limitado a un rango de líneas específico.

• glob: Encuentra archivos que coincidan con patrones glob.

• grep: Busca en el contenido de archivos usando patrones regex.

• tree: Obtiene un árbol de directorios recursivo como JSON anidado.

• make_archive: Crea archivos comprimidos (zip, tar, etc.) con protecciones de sobrescritura.

• unpack_archive: Descomprime archivos de forma segura con protección contra zip-slip.

• get_archive_formats: Lista los formatos de archivo comprimido admitidos.

Instalación

pip install shutil-mcp

Uso

Ejecutar con transporte stdio

shutil-mcp --transport stdio

Ejecutar con restricción de jail

shutil-mcp --transport stdio --jail /path/to/projects

Ejecutar como servidor SSE

shutil-mcp --transport sse --jail /path/to/projects --port 8000

Desarrollo

Consulta DEVELOPMENT.md para instrucciones detalladas de desarrollo.

Licencia

MIT