Servidor MCP del sistema de archivos

Un potente servidor de gestión de sistemas de archivos desarrollado con FastMCP que proporciona un conjunto completo de herramientas para operaciones con archivos y directorios. Este servidor permite realizar diversas operaciones con el sistema de archivos mediante una API estructurada, lo que lo hace ideal para la automatización y la integración con otros sistemas.

Soporte de plataforma

El servidor está diseñado para funcionar en diferentes sistemas operativos, pero con distintos niveles de funcionalidad:

Ventanas

• Soporte completo de funciones
• Listado de unidades
• Acceso a carpetas especiales
• Manejo de rutas específicas de Windows
• Información detallada del sistema

macOS/Linux

• Operaciones básicas con archivos
• Operaciones de directorio
• Búsqueda de archivos y metadatos
• Información básica del sistema
• Nota: Algunas funciones específicas de Windows no están disponibles

Implementación futura

Compatibilidad planificada con macOS

• Manejo de rutas nativo para macOS
• Recuperación de información del sistema específica de macOS
• Integración con las funciones del sistema de archivos macOS
• Compatibilidad con atributos de archivos específicos de macOS
• Implementación de utilidades específicas de macOS (similares a windows_utils.py)

Soporte planificado para Linux

• Manejo de rutas nativo para Linux
• Recuperación de información del sistema específico de Linux
• Integración con las características del sistema de archivos de Linux
• Compatibilidad con permisos y atributos de archivos de Linux
• Implementación de utilidades específicas de Linux

Mejoras multiplataforma

• Sistema unificado de gestión de rutas
• Detección de unidades independiente de la plataforma
• API de información del sistema consistente
• Atributos de archivos estandarizados en todas las plataformas
• Monitoreo de eventos del sistema de archivos multiplataforma
• Sistema universal de recopilación de archivos

Cronología

• Fase 1: Mejoras básicas de compatibilidad multiplataforma
• Fase 2: Implementaciones de funciones específicas de la plataforma
• Fase 3: Funciones multiplataforma avanzadas
• Fase 4: Optimizaciones y mejoras de rendimiento

Características

Operaciones con archivos

• Copiar archivos con soporte de respaldo
• Mueva archivos con soporte de respaldo
• Eliminar archivos con comprobaciones de seguridad
• Leer el contenido del archivo
• Escribir el contenido del archivo
• Obtener información del archivo (tamaño, hora de creación, hora de modificación)
• Buscar archivos por patrón de nombre
• Crear colecciones de archivos para organizar archivos relacionados

Operaciones de directorio

• Listar el contenido del directorio
• Crear directorios
• Eliminar directorios
• Listar directorios de forma recursiva (estructura tipo árbol)
• Buscar directorios por patrón de nombre

Información del sistema

• Obtener información del sistema (SO, CPU, memoria, uso del disco)
• Obtener información del disco (espacio total, espacio utilizado, espacio libre)
• Obtener información del directorio (cantidad de archivos, tamaño total)

Estructura del proyecto

Almacenamiento de colecciones

Las colecciones se pueden almacenar en cualquier directorio especificado por el usuario. Si no se especifica una ubicación de almacenamiento, se almacenarán en una ubicación predeterminada dentro del directorio data/collections del proyecto.

Ejemplo de uso:

Dependencias

Dependencias requeridas

• FastMCP
• Pydantic
• pywin32 (solo Windows)
• WMI (solo Windows)

Para instalar dependencias:

Configuración

1. Clonar el repositorio:

2. Crear y activar un entorno virtual:

3. Instalar dependencias:

Uso

Para obtener instrucciones detalladas de configuración de MCP en diferentes entornos de desarrollo (Claude, Cursor, Windsurf), visite: Guía de configuración de MCP

Integración con Claude

Para integrar el servidor MCP del sistema de archivos con Claude, agregue lo siguiente a su archivo claude_desktop_config.json :

Encontrar su ruta en Python

Para encontrar la ruta ejecutable de Python, utilice el siguiente comando:

Ventanas (PowerShell):

Windows (Símbolo del sistema/Terminal):

Linux/macOS (Terminal):

Reemplace /absolute/path/to/python con la salida del comando apropiado anterior.

Ejemplo de configuración

Para Windows, su configuración podría verse así:

Para macOS/Linux:

Después de agregar la configuración:

1. Guarde el archivo claude_desktop_config.json
2. Reiniciar Claude
3. Ahora puedes usar las herramientas del sistema de archivos pidiéndole a Claude que realice operaciones con archivos

Herramientas disponibles

Operaciones con archivos

• copy_file : Copiar un archivo con copia de seguridad opcional
• move_file : Mover un archivo con copia de seguridad opcional
• delete_file : elimina un archivo con comprobaciones de seguridad
• read_file : Leer el contenido del archivo
• write_file : Escribe el contenido en un archivo
• get_file_info : Obtener información detallada del archivo
• search_files : Buscar archivos por patrón de nombre
• create_collection : Crea una colección de archivos

Operaciones de directorio

• list_directory : Lista el contenido del directorio
• create_directory : Crea un nuevo directorio
• delete_directory : Eliminar un directorio
• list_directory_recursively : muestra la estructura del directorio en formato de árbol
• search_directories : Buscar directorios por patrón de nombre

Información del sistema

• get_system_info : Obtener información del sistema
• get_disk_info : Obtener información de uso del disco
• get_directory_info : Obtener estadísticas del directorio

Problemas conocidos

Las siguientes funciones actualmente están experimentando problemas y es posible que no funcionen como se espera:

1. Función de eliminación de archivos
   • La función delete_file puede no eliminar archivos correctamente en algunos casos
   • Se recomienda a los usuarios verificar la eliminación de archivos manualmente o utilizar métodos alternativos cuando sea crítico.
   • El problema está bajo investigación y se solucionará en una futura actualización.
2. Función de lista de unidades
   • Es posible que la función list_drives no detecte o muestre correctamente todas las unidades disponibles
   • Es posible que algunas unidades falten en la lista o muestren información incorrecta
   • Esta es una limitación conocida y se abordará en futuras actualizaciones.
3. Limitaciones específicas de la plataforma
   • Las funciones específicas de Windows no están disponibles en macOS/Linux
   • El manejo de algunas rutas puede variar entre plataformas.
   • La recuperación de información del sistema varía según la plataforma

Manejo de errores

El servidor incluye un manejo integral de errores para:

• Rutas de archivo no válidas
• Archivo/directorio no encontrado
• Problemas de permisos
• Limitaciones de espacio en disco
• Operaciones no válidas
• Errores específicos de la plataforma

Seguridad

• Todas las operaciones de archivo incluyen validación de ruta
• Los archivos de respaldo se crean antes de las operaciones destructivas
• El acceso a la información del sistema está restringido a operaciones seguras
• Las operaciones de archivo se realizan con un manejo de errores adecuado

Contribuyendo

1. Bifurcar el repositorio
2. Crear una rama de características
3. Confirme sus cambios
4. Empujar hacia la rama
5. Crear una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Expresiones de gratitud

• Creado con FastMCP
• Utiliza Pydantic para la validación de datos
• Inspirado en las herramientas modernas de gestión de sistemas de archivos