Servidor del sistema de archivos MCP

Un potente servidor de Protocolo de Contexto de Modelo (MCP) para operaciones de sistemas de archivos, optimizado para la interacción inteligente con archivos y sistemas de archivos de gran tamaño. Proporciona acceso seguro a archivos y directorios con gestión inteligente del contexto para maximizar la eficiencia al trabajar con grandes volúmenes de datos.

¿Por qué MCP-Filesystem?

• Gestión inteligente del contexto : trabaje de manera eficiente con archivos y sistemas de archivos grandes

  • Lectura parcial para centrarse solo en el contenido relevante

  • Control de contexto preciso para encontrar exactamente lo que necesita

  • Resultados de búsqueda eficientes en tokens con paginación

  • Operaciones con múltiples archivos para reducir la sobrecarga de solicitudes

• Operaciones de archivos inteligentes :

  • Lectura orientada a líneas con ventanas de contexto configurables

  • Edición avanzada con verificación de contenido para evitar conflictos

  • Capacidades de búsqueda de grano fino que superan el grep estándar

  • Referencias de línea relativas para una manipulación precisa de archivos

Características principales

• Acceso seguro a archivos : solo permite operaciones dentro de directorios explícitamente permitidos

• Operaciones integrales : conjunto completo de capacidades del sistema de archivos

  • Operaciones estándar (leer, escribir, enumerar, mover, eliminar)

  • Operaciones mejoradas (visualización de árboles, búsqueda de duplicados, etc.)

  • Búsqueda avanzada con integración de grep (usa ripgrep cuando está disponible)

    • Control de contexto (como las opciones -A/-B/-C de grep)

    • Paginación de resultados para conjuntos de resultados grandes

  • Operaciones dirigidas a líneas con verificación de contenido y números de línea relativos

• Rendimiento optimizado :

  • Maneja eficientemente archivos y directorios grandes

  • Integración de Ripgrep para búsquedas ultrarrápidas

  • Operaciones dirigidas a líneas para evitar cargar archivos completos

• Pruebas integrales : más de 75 pruebas con un enfoque basado en el comportamiento

• Multiplataforma : funciona en Windows, macOS y Linux

Guía de inicio rápido

1. Clonar y configurar

Primero, instala uv si aún no lo has hecho:

Luego clona el repositorio e instala las dependencias:

2. Obtener rutas absolutas

Necesitará rutas absolutas tanto para la ubicación del repositorio como para cualquier directorio al que desee acceder:

3. Configurar Claude Desktop

Abra el archivo de configuración de Claude Desktop:

• En macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

• En Windows: %APPDATA%/Claude/claude_desktop_config.json

Agregue la siguiente configuración (sustituya sus rutas actuales):

Importante : Todas las rutas deben ser absolutas (rutas completas desde el directorio raíz). Use realpath o pwd para asegurarse de tener las rutas absolutas correctas.

4. Reinicie Claude Desktop

Después de guardar su configuración, reinicie Claude Desktop para que los cambios surtan efecto.

Instalación

Uso

Ver registros del servidor

Puede supervisar los registros del servidor desde Claude Desktop con:

Esto es particularmente útil para depurar problemas o ver exactamente lo que Claude está solicitando.

Ejecución del servidor

Ejecute el servidor con acceso a directorios específicos:

Opciones

• --transport o -t : Protocolo de transporte (stdio o sse, predeterminado: stdio)

• --port o -p : Puerto para transporte SSE (predeterminado: 8000)

• --debug o -d : Habilitar el registro de depuración

• --version o -v : Mostrar información de la versión

Uso con MCP Inspector

Para realizar pruebas y depuraciones interactivas con el Inspector MCP:

Este servidor se ha desarrollado con el SDK de FastMCP para una mejor adaptación a las mejores prácticas actuales de MCP. Utiliza un sistema eficiente de almacenamiento en caché de componentes y un patrón de decorador directo.

Integración de escritorio de Claude

Edite el archivo de configuración de Claude Desktop para integrar MCP-Filesystem:

Ubicación del archivo de configuración:

• En macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

• En Windows: %APPDATA%/Claude/claude_desktop_config.json

Para permitir el acceso a directorios específicos, agréguelos como argumentos adicionales:

Nota: El indicador --directory es importante, ya que indica a uv dónde encontrar el repositorio que contiene run_server.py. Reemplace /path/to/mcp-filesystem/repo con la ruta real donde clonó el repositorio en su sistema.

Desarrollo

Ejecución de pruebas

Estilo y calidad del código

Herramientas disponibles

Operaciones básicas con archivos

• read_file : Lee el contenido completo de un archivo

• read_multiple_files : Leer varios archivos simultáneamente

• write_file : Crea un nuevo archivo o sobrescribe un archivo existente

• create_directory : Crea un nuevo directorio o asegúrate de que exista un directorio

• list_directory : Obtenga una lista detallada de archivos y directorios

• move_file : Mover o renombrar archivos y directorios

• get_file_info : recupera metadatos detallados sobre un archivo o directorio

• list_allowed_directories : enumera los directorios a los que el servidor tiene permiso de acceso

Operaciones dirigidas a la línea

• read_file_lines : lee rangos de líneas específicos con parámetros de desplazamiento/límite

• edit_file_at_line : Realice ediciones precisas con verificación de contenido y números de línea relativos

  • Soporte para verificación de contenido para evitar editar contenido obsoleto

  • Números de línea relativos para facilitar la edición regional

  • Múltiples acciones de edición (reemplazar, insertar antes, insertar después, eliminar)

• head_file : Lee las primeras N líneas de un archivo de texto

• tail_file : lee las últimas N líneas de un archivo de texto

Búsqueda avanzada

• grep_files : busca patrones en archivos con opciones potentes

  • Integración de Ripgrep para mejorar el rendimiento (con respaldo de Python)

  • Control de contexto de grano fino (como las opciones -A/-B/-C de grep)

  • Paginación de resultados para resultados de búsqueda grandes

  • Compatibilidad con expresiones regulares con distinción entre mayúsculas y minúsculas y opciones de palabras completas

• search_files : Busca archivos que coincidan con patrones de búsqueda de contenido

• directory_tree : Obtener una vista de árbol recursiva de archivos y directorios

Análisis e informes

• calculate_directory_size : Calcula el tamaño total de un directorio

• find_duplicate_files : Encuentra archivos duplicados comparando el contenido

• compare_files : Compara dos archivos de texto y muestra las diferencias

• find_large_files : busca archivos más grandes que un tamaño especificado

• find_empty_directories : Encuentra directorios vacíos

Ejemplos de uso

Leyendo líneas de archivo

Búsqueda de contenido con Grep

Edición orientada a líneas

Encontrar archivos duplicados

Flujo de trabajo eficiente para archivos y sistemas de archivos grandes

MCP-Filesystem está diseñado para la interacción inteligente con archivos grandes y sistemas de archivos complejos:

1. Descubrimiento de contexto inteligente

   • Utilice grep_files para encontrar exactamente lo que necesita con un control de contexto preciso

   • El control detallado sobre las líneas de contexto antes y después de las coincidencias evita el desperdicio de tokens

   • Paginar grandes conjuntos de resultados de manera eficiente sin sobrecargar los límites de tokens

   • La integración de Ripgrep maneja sistemas de archivos masivos con millones de archivos y líneas

2. Lectura dirigida

   • Examine solo las secciones relevantes con read_file_lines usando offset/limit

   • Indexación basada en cero con parámetros de desplazamiento/límite simples para una recuperación precisa de contenido

   • Controle exactamente cuántas líneas leer para maximizar la eficiencia del token

   • Leer varios archivos simultáneamente para reducir los viajes de ida y vuelta

3. Edición precisa

   • Realice ediciones específicas con edit_file_at_line con verificación de contenido

   • Verifique que el contenido no haya cambiado antes de editarlo para evitar conflictos.

   • Utilice números de línea relativos para la edición regional en archivos complejos

   • Múltiples acciones de edición en una sola operación para cambios complejos

   • Capacidad de ejecución en seco para obtener una vista previa de los cambios antes de aplicarlos

4. Análisis avanzado

   • Utilice herramientas especializadas como find_duplicate_files y compare_files

   • Genere árboles de directorios con directory_tree para una navegación rápida

   • Identifique áreas problemáticas con find_large_files y find_empty_directories

Este flujo de trabajo es especialmente valioso para herramientas basadas en IA que necesitan trabajar con archivos y sistemas de archivos de gran tamaño. Por ejemplo, Claude y otros asistentes de IA avanzados pueden aprovechar estas capacidades para navegar eficientemente por bases de código, analizar archivos de registro o trabajar con grandes conjuntos de datos de texto, manteniendo la eficiencia de los tokens.

Ventajas sobre los servidores MCP del sistema de archivos estándar

A diferencia de los servidores MCP de sistemas de archivos básicos, MCP-Filesystem ofrece:

1. Eficiencia del token

   • Las operaciones inteligentes dirigidas a líneas evitan cargar archivos completos en contexto

   • Los controles de paginación para resultados grandes evitan el desbordamiento de contexto

   • Grep preciso con controles de contexto (no solo búsquedas en archivos completos)

   • La lectura de múltiples archivos reduce las solicitudes de ida y vuelta

2. Edición inteligente

   • Verificación de contenido para evitar conflictos de edición

   • Ediciones orientadas a líneas que no requieren el archivo completo

   • Compatibilidad con números de línea relativos para una edición regional más sencilla

   • Capacidad de ejecución en seco para obtener una vista previa de los cambios antes de aplicarlos

3. Búsqueda avanzada

   • Integración de Ripgrep para un rendimiento masivo del sistema de archivos

   • Resultados según el contexto (no solo coincidencias)

   • Control detallado sobre lo que se devuelve

   • Búsqueda de archivos basada en patrones con soporte de exclusión

4. Utilidades adicionales

   • Comparación y deduplicación de archivos

   • Cálculo y análisis del tamaño del directorio

   • Identificación de directorio vacío

   • Visualización de directorios basada en árboles

5. Enfoque de seguridad

   • Validación de ruta robusta y sandboxing

   • Protección contra ataques de cruce de ruta

   • Validación y seguridad de enlaces simbólicos

   • Informe detallado de errores sin exposición sensible

Problemas y limitaciones conocidos

• Resolución de rutas : Utilice siempre rutas absolutas para obtener resultados más consistentes. Las rutas relativas podrían interpretarse en relación con el directorio de trabajo del servidor, en lugar de los directorios permitidos.

• Rendimiento : en el caso de directorios grandes, operaciones como find_duplicate_files o búsqueda recursiva pueden tardar un tiempo considerable en completarse.

• Manejo de permisos : El servidor opera con los mismos permisos que el usuario que lo ejecuta. Asegúrese de que el servidor tenga los permisos adecuados para los directorios a los que necesita acceder.

Seguridad

El servidor aplica una validación de ruta estricta para evitar el acceso fuera de los directorios permitidos:

• Sólo permite operaciones dentro de directorios explícitamente permitidos

• Proporciona protección contra ataques de cruce de ruta

• Valida los enlaces simbólicos para garantizar que no apunten fuera de los directorios permitidos

• Devuelve mensajes de error significativos sin exponer información confidencial

Consideraciones de rendimiento

Para obtener el mejor rendimiento con la funcionalidad grep:

• Instalar ripgrep ( rg )

• El servidor utiliza automáticamente ripgrep si está disponible, con una alternativa de Python

Licencia

Licencia MIT