Servidor MCP del sistema de archivos

Servidor Node.js que implementa el Protocolo de Contexto de Modelo (MCP) para operaciones del sistema de archivos con controles de permisos integrales y funcionalidad mejorada.

Características

• Controles de permisos granulares (solo lectura, acceso completo o permisos de operación específicos)

• Operaciones de archivos seguras dentro de directorios permitidos

• Operaciones con archivos:

  • Leer/escribir/modificar archivos

  • Crear/enumerar/eliminar directorios

  • Mover archivos/directorios

  • Buscar archivos por nombre o extensión

  • Obtener metadatos de archivos

• Operaciones de directorio:

  • Vista de árbol de las estructuras de directorios

  • Operaciones recursivas con patrones de exclusión

• Funciones de utilidad:

  • Conversión de XML a JSON

  • Múltiples operaciones de archivo en una sola llamada

  • Edición avanzada de archivos con coincidencia de patrones

• Características de seguridad:

  • Control de enlace simbólico

  • Validación de ruta

  • Operaciones en espacio aislado

Nota : El servidor solo permitirá operaciones dentro de directorios especificados mediante args y de acuerdo con los permisos configurados.

API

Recursos

• file://system : Interfaz de operaciones del sistema de archivos

Herramientas

• leer_archivo

  • Leer el contenido completo de un archivo

  • Entrada: path (cadena)

  • Lee el contenido completo del archivo con codificación UTF-8

• leer_múltiples_archivos

  • Leer varios archivos simultáneamente

  • Entrada: paths (cadena[])

  • Las lecturas fallidas no detendrán toda la operación

• crear_archivo

  • Crear un nuevo archivo con contenido

  • Entradas:

    • path (cadena): Ubicación del archivo

    • content (cadena): contenido del archivo

  • Falla si el archivo ya existe

  • Requiere permiso create

• modificar_archivo

  • Modificar un archivo existente con contenido nuevo

  • Entradas:

    • path (cadena): Ubicación del archivo

    • content (cadena): Nuevo contenido del archivo

  • Falla si el archivo no existe

  • Requiere permiso edit

• archivo_de_edición

  • Realice ediciones selectivas utilizando coincidencia de patrones y formato

  • Características:

    • Coincidencia de contenido basada en líneas y multilíneas

    • Normalización de espacios en blanco con conservación de sangría

    • Múltiples ediciones simultáneas con posicionamiento correcto

    • Detección y conservación del estilo de sangría

    • Salida de diferencias al estilo Git con contexto

    • Vista previa de los cambios con el modo de ejecución en seco

  • Entradas:

    • path (cadena): Archivo a editar

    • edits (matriz): Lista de operaciones de edición

      • oldText (cadena): Texto a buscar (coincidencia exacta)

      • newText (cadena): Texto con el que reemplazar

    • dryRun (booleano): Vista previa de los cambios sin aplicarlos (valor predeterminado: falso)

  • Devuelve una diferencia detallada para ejecuciones en seco; de lo contrario, aplica los cambios.

  • Requiere permiso edit

  • Práctica recomendada: utilice siempre dryRun primero para obtener una vista previa de los cambios

• crear_directorio

  • Crear un nuevo directorio o asegurarse de que exista

  • Entrada: path (cadena)

  • Crea directorios principales si es necesario

  • Tiene éxito silenciosamente si el directorio existe

  • Requiere permiso create

• directorio_de_lista

  • Listar el contenido del directorio con prefijos [FILE] o [DIR]

  • Entrada: path (cadena)

  • Devuelve una lista detallada de archivos y directorios.

• árbol de directorios

  • Obtener una vista de árbol recursiva de la estructura del directorio

  • Entrada: path (cadena)

  • Devuelve la estructura JSON con archivos y directorios

  • Cada entrada incluye nombre, tipo y elementos secundarios (para directorios)

• mover_archivo

  • Mover o renombrar archivos y directorios

  • Entradas:

    • source (cadena): Ruta de origen

    • destination (cadena): Ruta de destino

  • Falla si el destino existe

  • Funciona tanto para archivos como para directorios.

  • Requiere permiso move

• eliminar_archivo

  • Eliminar un archivo

  • Entrada: path (cadena)

  • Falla si el archivo no existe

  • Requiere permiso delete

• eliminar_directorio

  • Eliminar un directorio

  • Entradas:

    • path (cadena): Directorio a eliminar

    • recursive (booleano): si se debe eliminar el contenido (valor predeterminado: falso)

  • Falla si el directorio no está vacío y el recursivo es falso

  • Requiere permiso delete

• archivos de búsqueda

  • Buscar archivos/directorios de forma recursiva

  • Entradas:

    • path (cadena): Directorio de inicio

    • pattern (cadena): Buscar patrón

    • excludePatterns (string[]): Excluye patrones (formato glob compatible)

  • Coincidencia sin distinción entre mayúsculas y minúsculas

  • Devuelve rutas completas a las coincidencias

• buscar_archivos_por_extensión

  • Encuentra todos los archivos con extensión específica

  • Entradas:

    • path (cadena): Directorio de inicio

    • extension (cadena): Extensión del archivo a buscar

    • excludePatterns (string[]): Patrones de exclusión opcionales

  • Coincidencia de extensiones sin distinción entre mayúsculas y minúsculas

  • Devuelve rutas completas a los archivos coincidentes

• obtener_información_del_archivo

  • Obtener metadatos detallados de archivos/directorios

  • Entrada: path (cadena)

  • Devoluciones:

    • Tamaño

    • Tiempo de creación

    • Hora modificada

    • Tiempo de acceso

    • Tipo (archivo/directorio)

    • Permisos

• obtener_permisos

  • Obtener los permisos actuales del servidor

  • No se requiere entrada

  • Devoluciones:

    • Banderas de permisos (solo lectura, acceso completo, crear, editar, mover, eliminar)

    • Estado de seguimiento del enlace simbólico

    • Número de directorios permitidos

• lista_de_directorios_permitidos

  • Enumere todos los directorios a los que el servidor tiene permiso de acceder

  • No se requiere entrada

  • Devuelve una matriz de rutas de directorio permitidas

• xml_a_json

  • Convertir archivo XML a formato JSON

  • Entradas:

    • xmlPath (cadena): archivo XML de origen

    • jsonPath (cadena): archivo JSON de destino

    • options (objeto): configuraciones opcionales

      • ignoreAttributes (booleano): omite atributos XML (valor predeterminado: falso)

      • preserveOrder (booleano): Mantener el orden de la propiedad (valor predeterminado: verdadero)

      • format (booleano): JSON de impresión bonita (predeterminado: verdadero)

      • indentSize (número): sangría JSON (predeterminado: 2)

  • Requiere permiso read para el archivo XML

  • Requiere permiso para create o edit archivos JSON

• cadena xml_a_json

  • Convertir archivo XML a cadena JSON

  • Entradas:

    • xmlPath (cadena): archivo XML de origen

    • options (objeto): configuraciones opcionales

      • ignoreAttributes (booleano): omite atributos XML (valor predeterminado: falso)

      • preserveOrder (booleano): Mantener el orden de la propiedad (valor predeterminado: verdadero)

  • Requiere permiso read para el archivo XML

  • Devuelve la representación de cadena JSON

• consulta_xml

  • Consultar archivo XML mediante expresiones XPath

  • Entradas:

    • path (cadena): Ruta al archivo XML

    • query (cadena, opcional): consulta XPath a ejecutar

    • structureOnly (booleano, opcional): Devuelve solo la estructura de la etiqueta

    • maxBytes (número, opcional): Máximo de bytes a leer (predeterminado: 1 MB)

    • includeAttributes (booleano, opcional): incluye información del atributo (valor predeterminado: verdadero)

  • Ejemplos de XPath:

    • Obtener todos los elementos: //tagname

    • Obtener elementos con atributo específico: //tagname[@attr="value"]

    • Obtener el contenido del texto: //tagname/text()

  • Uso eficiente de la memoria para archivos XML grandes

  • Devuelve la representación JSON de los resultados o la estructura de la consulta.

• estructura_xml

  • Analizar la estructura XML sin leer el archivo completo

  • Entradas:

    • path (cadena): Ruta al archivo XML

    • depth (número, opcional): Qué tan profundo analizar (predeterminado: 2)

    • includeAttributes (booleano, opcional): incluye análisis de atributos

    • maxBytes (número, opcional): Máximo de bytes a leer (predeterminado: 1 MB)

  • Devuelve información estadística sobre elementos, atributos y estructura.

  • Útil para comprender archivos XML grandes antes de realizar un análisis detallado

Permisos y seguridad

El servidor implementa un modelo de seguridad integral con controles de permisos granulares:

Control de acceso al directorio

• Las operaciones están estrictamente limitadas a los directorios especificados durante el inicio a través de args

• Todas las operaciones (incluidos los destinos de enlaces simbólicos) deben permanecer dentro de los directorios permitidos

• La validación de ruta garantiza que no se pueda atravesar ningún directorio ni acceder a él fuera de las rutas permitidas

Banderas de permiso

• --readonly : Aplica el modo de solo lectura, anulando todos los demás indicadores de permisos

• --full-access : Habilita todas las operaciones (crear, editar, mover, eliminar)

• Banderas de permisos individuales (requieren habilitación explícita a menos que se configure --full-access):

  • --allow-create : Permitir la creación de nuevos archivos y directorios

  • --allow-edit : Permitir la modificación de archivos existentes

  • --allow-move : Permitir mover/renombrar archivos y directorios

  • --allow-delete : Permitir la eliminación de archivos y directorios

Comportamiento predeterminado : Si no se especifican indicadores de permiso, el servidor se ejecuta en modo de solo lectura. Para habilitar cualquier operación de escritura, debe usar los indicadores --full-access o --allow-* .

Manejo de enlaces simbólicos

• De forma predeterminada, se siguen los enlaces simbólicos (tanto el enlace como el destino deben estar en directorios permitidos)

• --no-follow-symlinks : Deshabilita el seguimiento de enlaces simbólicos (las operaciones actúan sobre el enlace en sí)

Uso con Claude Desktop y Cursor

Agregue la configuración adecuada a claude_desktop_config.json (para Claude Desktop) o .cursor/mcp.json (para Cursor):

Configuración del cursor

En .cursor/mcp.json :

Configuración de Docker

Para Claude Desktop con Docker:

Configuración NPX

Para Claude Desktop o Cursor con NPX:

Ejemplos de banderas de permiso

Puede configurar el servidor con varias combinaciones de permisos:

Nota: --readonly tiene prioridad sobre todos los demás indicadores de permisos, y --full-access habilita todas las operaciones a menos que se especifique --readonly .

Múltiples directorios y permisos

Al especificar varios directorios, los indicadores de permiso se aplican globalmente a todos los directorios:

Si necesita diferentes niveles de permisos para distintos directorios, cree múltiples configuraciones de servidor:

Ejemplos de línea de comandos

1. Acceso de solo lectura:

2. Acceso completo:

3. Permisos específicos:

4. No hay ningún enlace simbólico a continuación:

Construir

Compilación de Docker:

Licencia

Este servidor MCP cuenta con la licencia MIT. Esto significa que puede usar, modificar y distribuir el software libremente, sujeto a los términos y condiciones de la licencia MIT. Para más detalles, consulte el archivo de LICENCIA en el repositorio del proyecto.