⚠️ Nota importante: Este proyecto no está pensado para uso en producción. Es un ejercicio didáctico que desarrollé con fines de aprendizaje, para experimentar con modelos LLM locales y explorar la tecnica de Model‑Context‑Protocol (MCP).

Toda la implementación está contenida en un solo archivo Python autocontenido, para facilitar su lectura, comprensión y modificación por parte de quienes están aprendiendo sobre la integración de LLMs locales con MCP y herramientas personalizadas.

FileSystem MCP

FileSystem MCP es un asistente inteligente de línea de comandos para gestionar operaciones del sistema de archivos mediante lenguaje natural, aprovechando el modelo Meta Llama‑3 8B Instruct con capacidades de function calling.

📝 Descripción

Este proyecto implementa un sistema Model‑Context‑Protocol (MCP) que permite:

• Crear, copiar, mover, renombrar y eliminar archivos y directorios.
• Listar contenidos de carpetas y obtener información detallada de archivos.
• Interactuar de forma conversacional, sin tener que recordar comandos del sistema.
• Ejecutar un modelo Llama‑3 localmente, sin depender de servicios en la nube.

🚀 Características destacadas

• Interfaz conversacional en español.
• Sistema de permisos configurable (READ_ONLY, BASIC, STANDARD, ADVANCED, ADMIN).
• Confirmaciones inteligentes para evitar operaciones destructivas.
• UI enriquecida con Rich para formatos de texto, tablas y progreso.
• Function calling optimizado con Llama‑3 Instruct Q4_K_M (8B parámetros).

🖥️ Requisitos del sistema

• Hardware mínimo: GPU con 8 GB de VRAM (recomendado NVIDIA).
• CPU: moderado (multinúcleo recomendado).
• RAM: 16 GB o más.
• Espacio en disco: ~5 GB para el modelo.
• Sistema operativo: Windows, macOS o Linux.
• Python 3.8 o superior.

📦 Instalación

1. Clona o descarga este repositorio:

   git clone https://github.com/Haslick/filesystem-mcp.git
   cd filesystem-mcp
   

2. Asegúrate de tener Python 3.8+ instalado.
3. Ejecuta el script; instalará dependencias automáticamente la primera vez:

   python filesystem_mcp.py
   

   • Se instalarán llama-cpp-python y rich si faltan.
   • Se descargará (o solicitará ruta) el modelo de ~5 GB.

⚙️ Uso

Al ejecutar el script, se te guiará para configurar:

• Directorio base de operaciones.
• Nivel de permisos.
• Confirmaciones de seguridad.

Después de la configuración inicial, ingresa tus peticiones en lenguaje natural:

Tú: Mueve los archivos informe.pdf y datos.csv a la carpeta Backup

Y el asistente procesará la operación.

🎛️ Argumentos de línea de comandos

Puedes pasar opciones al invocar filesystem_mcp.py:

Ejemplo:

python filesystem_mcp.py --base-dir ~/MisProyectos --permission-level ADMIN

🛠️ Comandos especiales

Durante la sesión, usa comandos precedidos por /:

📚 Ejemplos de uso

• Crear directorio:

  Tú: Crea una carpeta llamada Proyectos
  Asistente: ¡Listo! He creado la carpeta 'Proyectos'.
  

• Listar contenido:

  Tú: ¿Qué hay en la carpeta actual?
  Asistente:
    Archivos:
    - informe.txt
    - datos.csv
    Carpetas:
    - Proyectos
  

• Mover varios archivos:

  Tú: Mueve img1.png e img2.png a la carpeta Imágenes
  Detalles: Función: move_multiple_files, Argumentos: {"files": ["img1.png", "img2.png"], "destination": "Imágenes"}
   ¿Confirmar esta operación? [y/n]: y
  Asistente: He movido img1.png y img2.png a 'Imágenes'.
  

💡 Ejecución local del modelo

El modelo Meta-Llama-3‑8B Instruct se ejecuta completamente en tu máquina mediante llama-cpp-python. Esto garantiza:

• Privacidad total de tus datos.
• Baja latencia (no hay llamadas a la nube).
• Optimización Q4-K_M que permite correrlo en 8 GB de VRAM.

Importante: Ajusta n_gpu_layers en CONFIG["MODEL_PARAMS"] según tu GPU.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Para reportar errores o proponer mejoras:

1. Abre un issue en GitHub.
2. Realiza un fork, crea una rama y envía un pull request.

📄 Licencia

Este proyecto está bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.

Desarrollado por Leonardo con ayuda de Claude Sonnet 3.7 thinking mode (Abril 2025).