Vulcan File Ops

Servidor MCP que otorga a Claude Desktop y otros clientes MCP de escritorio capacidades de sistema de archivos: leer, escribir, editar y gestionar archivos como asistentes de codificación de IA.

GitHub
9

Documentación

Servidor MCP de Vulcan File Ops

TypeScript MCP Registry MCP Dev MCP Server MCP Server with Tools standard-readme compliant License: MIT MseeP.ai Security Assessment Badge

Seguro • Controlado por el Usuario • Servidor de Operaciones de Archivos de Alto Rendimiento

Transforma tus asistentes de IA de escritorio en poderosos compañeros de desarrollo. Vulcan File Ops cierra la brecha entre la IA conversacional (Claude Desktop, ChatGPT Desktop, etc.) y tu sistema de archivos local, desbloqueando las mismas capacidades de manipulación de archivos que se encuentran en IDE potenciados por IA como Cursor y extensiones de VS Code como Cline. Escribe código, refactoriza proyectos, gestiona documentación y realiza operaciones complejas de archivos—igualando el poder de los asistentes de codificación con IA dedicados. Con controles de seguridad de nivel empresarial, registro dinámico de directorios y filtrado inteligente de herramientas, mantienes un control total mientras tu asistente de IA se encarga del trabajo pesado.

Tabla de Contenidos

Antecedentes

Protocolo de Contexto de Modelo

El Protocolo de Contexto de Modelo (MCP) permite a los asistentes de IA acceder de forma segura a recursos y servicios externos. Este servidor implementa MCP para operaciones del sistema de archivos, permitiendo que los agentes de IA lean, escriban y gestionen archivos dentro de límites de directorio controlados.

Características Clave

Esta implementación mejorada proporciona:

  • Acceso Dinámico a Directorios: Registro de directorios en tiempo de ejecución mediante comandos conversacionales
  • Soporte de Documentos: Lectura/escritura de PDF, DOCX, PPTX, XLSX, ODT con conversión de HTML a documento
  • Operaciones por Lotes: Leer, escribir, editar, copiar, mover o renombrar múltiples archivos concurrentemente
  • Edición Avanzada de Archivos: Modificaciones basadas en patrones con coincidencia flexible y vista previa de diferencias
  • Modos de Lectura Flexibles: Archivo completo, inicio/final, o rangos arbitrarios de líneas
  • Soporte de Visión de Imágenes: Adjuntar imágenes para análisis y descripción por IA
  • Filtrado de Directorios: Excluir carpetas no deseadas (node_modules, dist, .git) de los listados, ya que la herramienta list_directory puede inflar la salida del servidor si se incluyen este tipo de carpetas, normalmente ignoradas por git
  • Activación Selectiva de Herramientas: Habilitar solo herramientas específicas o categorías de herramientas
  • Alto Rendimiento: Algoritmos de búsqueda optimizados con detección inteligente de recursión
  • Controles de Seguridad: Validación de rutas, restricciones de acceso y aprobación de comandos de shell
  • Control Local: Instalación completamente local sin dependencias externas

Modelo de Acceso a Directorios

Este servidor soporta múltiples enfoques flexibles para el acceso a directorios:

  1. Acceso Preconfigurado: Usa --approved-folders para especificar directorios al iniciar el servidor para acceso inmediato
  2. Registro en Tiempo de Ejecución: Los usuarios pueden instruir a los agentes de IA para registrar directorios durante la conversación mediante la herramienta register_directory. Por defecto, se te pide confirmar cada nuevo directorio a través de tu cliente MCP (ver Política de Registro en Tiempo de Ejecución)
  3. Protocolo de Raíces MCP: Las aplicaciones cliente pueden proporcionar directorios de trabajo dinámicamente
  4. Permisos Flexibles: Combina múltiples enfoques—comienza con carpetas aprobadas, agrega más en tiempo de ejecución
  5. Límites Seguros: Todas las operaciones se validan contra los directorios registrados independientemente del método de acceso

Instalación

Este servidor requiere Node.js y puede instalarse globalmente, localmente, o ejecutarse directamente con npx. La mayoría de los usuarios deberían usar npx para ejecución instantánea sin instalación.

Inicio Rápido (Recomendado para la Mayoría de Usuarios)

Ejecuta directamente sin instalación:

npx @n0zer0d4y/vulcan-file-ops --help

Para desarrolladores que quieran contribuir o modificar el código, ver Ejecución desde Repositorio Local a continuación.

Instalación Global

Instala globalmente para acceso en todo el sistema:

npm install -g @n0zer0d4y/vulcan-file-ops

Instalación Local

Instala en un proyecto específico:

npm install @n0zer0d4y/vulcan-file-ops

Requisitos Previos

Node.js (versión 20.19 o superior, o 22.12 o superior) debe estar instalado en tu sistema. Esto proporciona npm y npx, que son necesarios para ejecutar este paquete.

  • Descargar Node.js: https://nodejs.org/
  • Verificar instalación: Ejecuta node --version y npm --version

Dependencias

El servidor no tiene dependencias de servicios externos y opera completamente de forma local. Todos los paquetes necesarios se descargan automáticamente al usar npx.

Uso

Este servidor puede usarse directamente con npx (recomendado) o instalarse globalmente/localmente. El enfoque con npx no requiere instalación y siempre usa la versión más reciente.

Configuración Básica

Agrega a la configuración de tu cliente MCP.

Para clientes basados en JSON como Claude Desktop y Cursor, usa su formato JSON mcpServers. Para Codex, usa C:\Users\<username>\.codex\config.toml y el formato de tabla TOML mcp_servers que se muestra a continuación.

Opción 1: Usando npx (Recomendado - Sin Instalación Requerida)

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": ["-y", "@n0zer0d4y/vulcan-file-ops"]
    }
  }
}

Codex (config.toml)

[mcp_servers.vulcan_file_ops]
command = "npx"
args = ["-y", "@n0zer0d4y/vulcan-file-ops"]
enabled = true
startup_timeout_sec = 120.0

Opción 2: Usando Instalación Global

Después de ejecutar npm install -g @n0zer0d4y/vulcan-file-ops:

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "vulcan-file-ops"
    }
  }
}

Opción 3: Usando Instalación Local

Después de ejecutar npm install @n0zer0d4y/vulcan-file-ops en tu proyecto:

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "./node_modules/.bin/vulcan-file-ops"
    }
  }
}

Opción 4: Ejecución desde Repositorio Local (Para Desarrolladores)

Si has clonado este repositorio y quieres ejecutar desde el código fuente:

git clone https://github.com/n0zer0d4y/vulcan-file-ops.git
cd vulcan-file-ops
npm install
npm run build

Luego configura tu cliente MCP:

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "node",
      "args": [
        "/absolute/path/to/vulcan-file-ops/dist/cli.js",
        "--approved-folders",
        "/path/to/your/allowed/directories"
      ]
    }
  }
}

Codex (config.toml)

[mcp_servers.vulcan_file_ops]
command = "node"
args = [
  'C:\absolute\path\to\vulcan-file-ops\dist\cli.js',
  "--approved-folders",
  'C:\path\to\your\allowed\directories'
]
cwd = 'C:\absolute\path\to\vulcan-file-ops'
enabled = true
startup_timeout_sec = 120.0

Nota: Para ejecución desde repositorio local, prefiere node dist/cli.js con una ruta absoluta. Esto funciona de manera confiable en Codex y evita ambigüedad en PATH.

Configuración Avanzada

Carpetas Aprobadas

Preconfigura directorios específicos para acceso inmediato al iniciar el servidor:

macOS/Linux (npx):

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "-y",
        "@n0zer0d4y/vulcan-file-ops",
        "--approved-folders",
        "/Users/username/projects",
        "/Users/username/documents"
      ]
    }
  }
}

Windows (npx):

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "-y",
        "@n0zer0d4y/vulcan-file-ops",
        "--approved-folders",
        "C:/Users/username/projects",
        "C:/Users/username/documents"
      ]
    }
  }
}

Alternativa: Ejecución desde Repositorio Local

Para usuarios que ejecutan desde un repositorio clonado (después de npm run build):

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "vulcan-file-ops",
      "args": [
        "--approved-folders",
        "/Users/username/projects",
        "/Users/username/documents"
      ]
    }
  }
}

Codex con Carpetas Aprobadas (config.toml)

[mcp_servers.vulcan_file_ops]
command = "node"
args = [
  'C:\absolute\path\to\vulcan-file-ops\dist\cli.js',
  "--approved-folders",
  'C:\Users\username\projects',
  'C:\Users\username\documents'
]
cwd = 'C:\absolute\path\to\vulcan-file-ops'
enabled = true
startup_timeout_sec = 120.0

Nota sobre Formato de Ruta:

  • Windows: Incluye la letra de unidad (ej., C:/, D:/). Usa barras diagonales en JSON para evitar escapar barras invertidas.
  • macOS/Linux: Comienza con / para rutas absolutas, o usa ~ para el directorio de inicio.

Beneficios:

  • Acceso Instantáneo: Los directorios se validan y están listos inmediatamente cuando el servidor se inicia
  • Seguridad: Solo los directorios especificados son accesibles (a menos que se use el protocolo de Raíces MCP)
  • Conveniencia: No es necesario registrar directorios manualmente mediante conversación
  • Visibilidad para IA: Los directorios aprobados se incrustan dinámicamente en las descripciones de las herramientas register_directory y list_allowed_directories, asegurando que los asistentes de IA puedan ver qué directorios están preaprobados y evitar intentos de registro redundantes

Cómo Ven los Asistentes de IA las Carpetas Aprobadas:

Cuando configuras --approved-folders, el servidor inyecta dinámicamente esta información en las descripciones de las herramientas para register_directory y list_allowed_directories. Esto asegura:

  • ✅ Los asistentes de IA pueden ver qué directorios ya son accesibles
  • ✅ La IA sabe NO volver a registrar directorios preaprobados o sus subdirectorios
  • ✅ Visibilidad clara sin requerir que la IA llame a list_allowed_directories primero
  • ✅ Funciona de manera confiable en todos los clientes MCP (incluyendo Cursor, Claude Desktop, etc.)

Ejemplo de lo que la IA ve en la descripción de la herramienta:

PRE-APPROVED DIRECTORIES (already accessible, DO NOT register these):
  - C:\Users\username\projects
  - C:\Users\username\documents

IMPORTANT: These directories and their subdirectories are ALREADY accessible
to all filesystem tools. Do NOT use register_directory for these paths.

Notas:

  • Las rutas deben ser absolutas: Windows requiere letra de unidad (C:/path), Unix/Mac comienza con / o ~
  • Lista de directorios separada por comas (sin espacios a menos que sean parte de la ruta)
  • Los directorios se validan al inicio; el servidor saldrá si alguna ruta es inválida
  • Funciona junto con la herramienta register_directory en tiempo de ejecución para acceso adicional
  • El protocolo de Raíces MCP (si lo usa el cliente) reemplazará las carpetas aprobadas con las raíces del espacio de trabajo

Filtrado de Directorios

Excluye carpetas específicas de los listados de directorios:

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--ignored-folders",
        "node_modules,dist,.git,.next"
      ]
    }
  }
}

Selección de Herramientas

Habilita solo categorías específicas de herramientas:

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--enabled-tool-categories",
        "read,filesystem"
      ]
    }
  }
}

O habilita herramientas individuales:

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--enabled-tools",
        "read_file,list_directory,grep_files"
      ]
    }
  }
}

Comandos de Shell

execute_shell solo ejecuta comandos cuyo comando raíz esté aprobado:

  • --approved-commands npm,node,git — lista de permitidos separada por comas de comandos raíz. Cada comando en una cadena (;, &&, ||, |) debe estar aprobado.
  • --allow-dangerous-commands rm — comandos aprobados que también pueden ejecutarse cuando coinciden con un patrón peligroso (por ejemplo rm -rf, del /s, Remove-Item -Recurse, sudo). Sin esta bandera, tales comandos siempre están bloqueados; la IA no puede anularlo.
  • --commands-env-file <path> — lee APPROVED_COMMANDS de un archivo con formato .env. Solo se usa esa clave y no se agrega nada al entorno del servidor. --approved-commands tiene prioridad.

Cambiado en 1.3.0: el servidor ya no lee un archivo .env desde su directorio de trabajo. Usa --approved-commands o --commands-env-file. No uses --env-file: Node.js reserva esa bandera y aplicaría el archivo al propio proceso del servidor.

Nota: execute_shell no es una zona de pruebas. Un intérprete aprobado o una herramienta de ejecución de código (node, python, bash, npm, git, find -exec, ...) puede hacer cualquier cosa que tu cuenta de usuario pueda hacer. Solo aprueba comandos con los que te sientas cómodo dejando que la IA ejecute.

Política de Registro en Tiempo de Ejecución

--runtime-registration <confirm|allow|deny> controla la herramienta register_directory:

  • confirm (predeterminado) — se te pide aprobar cada nuevo directorio a través del mensaje de confirmación de tu cliente MCP (elicitation MCP). Si el cliente no soporta mensajes de confirmación, el registro se rechaza; agrega la carpeta con --approved-folders en su lugar, o usa allow.
  • allow — los directorios se registran sin un mensaje (el comportamiento antes de 1.3.0).
  • deny — el registro en tiempo de ejecución está deshabilitado; solo --approved-folders y las Raíces MCP otorgan acceso.

Las raíces del sistema de archivos (como C:\ o /) y tu propio directorio de inicio solo pueden registrarse con allow.

Configuración Combinada

Todas las opciones de configuración se pueden combinar:

Ejemplo Windows (npx):

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--approved-folders",
        "C:/Users/username/projects",
        "C:/Users/username/documents",
        "--ignored-folders",
        "node_modules,dist,.git",
        "--approved-commands",
        "npm,node,git,ls,pwd,cat,echo",
        "--enabled-tool-categories",
        "read,filesystem,shell",
        "--enabled-tools",
        "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell"
      ]
    }
  }
}

Ejemplo macOS/Linux (npx):

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--approved-folders",
        "/Users/username/projects",
        "/Users/username/documents",
        "--ignored-folders",
        "node_modules,dist,.git",
        "--approved-commands",
        "npm,node,git,ls,pwd,cat,echo",
        "--enabled-tool-categories",
        "read,filesystem,shell",
        "--enabled-tools",
        "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell"
      ]
    }
  }
}

Alternativa: Ejecución desde Repositorio Local

Para usuarios que ejecutan desde un repositorio clonado (después de npm run build):

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "vulcan-file-ops",
      "args": [
        "--approved-folders",
        "/Users/username/projects",
        "/Users/username/documents",
        "--ignored-folders",
        "node_modules,dist,.git",
        "--approved-commands",
        "npm,node,git,ls,pwd,cat,echo",
        "--enabled-tool-categories",
        "read,filesystem,shell",
        "--enabled-tools",
        "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell"
      ]
    }
  }
}

Registro de Directorios

Para acceder a un directorio específico, instruye al agente de IA:

"Please register the directory C:\path\to\your\folder for access, then list its contents."

La IA usará la herramienta register_directory para obtener acceso, luego realizará operaciones dentro de ese directorio. Con la política predeterminada --runtime-registration confirm, tu cliente MCP te pedirá aprobar el directorio primero.

API

Herramientas Disponibles por Categorías

Operaciones de Lectura

read_file

Lee el contenido de archivos con modos flexibles (completo, inicio, final, rango)

Nota: Esta herramienta está limitada a operaciones de un solo archivo. RECOMENDADO: Usa read_multiple_files en su lugar, que admite operaciones de archivos individuales y por lotes para mayor flexibilidad.

Entrada:

  • path (cadena): Ruta del archivo
  • mode (cadena, opcional): Modo de lectura
    • full - Lee el archivo completo (predeterminado)
    • head - Lee las primeras N líneas
    • tail - Lee las últimas N líneas
    • range - Lee un rango arbitrario de líneas (p. ej., líneas 50-100)
  • lines (número, opcional): Número de líneas para el modo inicio/final
  • startLine (número, opcional): Línea de inicio para el modo rango
  • endLine (número, opcional): Línea de fin para el modo rango

Salida: Contenido del archivo como texto. Admite archivos de texto y documentos (PDF, DOCX, PPTX, XLSX, ODT, ODP, ODS)

attach_image

Adjunta imágenes para análisis de visión por IA

Entrada:

  • path (cadena | cadena[]): Ruta al archivo de imagen, o matriz de rutas para adjuntar múltiples imágenes a la vez

Salida: Contenido de la imagen en formato MCP para procesamiento por modelos de visión. Admite PNG, JPEG, GIF y WebP (los formatos que aceptan los modelos de visión). Los archivos SVG se devuelven como su texto de marcado; BMP no es compatible (convertir a PNG)

read_multiple_files

Lee múltiples archivos por lotes de forma concurrente

Entrada:

  • files (matriz): Lista de objetos de archivo con ruta y configuraciones de modo opcionales

Salida: Contenido de todos los archivos. Las lecturas fallidas no detienen la operación

Operaciones de Escritura

write_file

Crea o reemplaza el contenido de un archivo

Nota: Esta herramienta está limitada a operaciones de un solo archivo. RECOMENDADO: Usa write_multiple_files en su lugar, que admite operaciones de archivos individuales y por lotes para mayor flexibilidad.

Creación automática de directorios:

  • Si el directorio padre del archivo de destino no existe pero está dentro de tus carpetas aprobadas configuradas, el servidor creará automáticamente la estructura de directorios requerida antes de escribir el archivo
  • Si la ruta está fuera de las carpetas aprobadas, la operación falla con un error claro y no se crean directorios

Entrada:

  • path (cadena): Ruta del archivo
  • content (cadena): Contenido del archivo (texto o HTML para conversión a PDF/DOCX)

Salida: Confirmación de éxito. Admite conversión de HTML a PDF/DOCX con formato enriquecido

write_multiple_files

Crea o reemplaza múltiples archivos de forma concurrente

Creación automática de directorios:

  • Para cada archivo solicitado, si el directorio padre no existe pero está dentro de tus carpetas aprobadas configuradas, el servidor creará automáticamente la estructura de directorios requerida antes de escribir
  • Las rutas fuera de las carpetas aprobadas se rechazan durante la validación y no se crean directorios; la operación falla con una lista detallada de rutas inválidas

Entrada:

  • files (matriz): Lista de objetos de archivo con ruta y contenido

Salida: Estado para cada archivo. Las escrituras fallidas no detienen otros archivos

edit_file

Aplica modificaciones precisas a archivos de texto y código con coincidencia inteligente. Admite operaciones de un solo archivo y de múltiples archivos.

Entrada de un solo archivo (modo: 'single'):

  • mode (cadena, opcional): Establecer a "single" (predeterminado si se omite para compatibilidad hacia atrás)
  • path (cadena): Ruta del archivo
  • edits (matriz): Lista de operaciones de edición, cada una contiene:
    • oldText (cadena): Texto a buscar (incluye 3-5 líneas de contexto)
    • newText (cadena): Texto con el que reemplazar
    • instruction (cadena, opcional): Descripción de lo que hace esta edición
    • expectedOccurrences (número, opcional): Recuento esperado de coincidencias (predeterminado: 1)
  • matchingStrategy (cadena, opcional): Estrategia de coincidencia
    • exact - Coincidencia carácter por carácter (más rápida, más segura)
    • flexible - Coincidencia insensible a espacios en blanco, preserva la indentación
    • fuzzy - Coincidencia regex basada en tokens (más permisiva)
    • auto - Intentar exacta → flexible → difusa (predeterminado)
  • dryRun (booleano, opcional): Vista previa de cambios sin escribir (predeterminado: false)
  • failOnAmbiguous (booleano, opcional): Fallar cuando las coincidencias son ambiguas (predeterminado: true)

Entrada de múltiples archivos (modo: 'multiple'):

  • mode (cadena): Establecer a "multiple"
  • files (matriz): Matriz de solicitudes de edición de archivos (máx. 50), cada una contiene:
    • path (cadena): Ruta del archivo
    • edits (matriz): Lista de operaciones de edición para este archivo (misma estructura que arriba)
    • matchingStrategy (cadena, opcional): Estrategia de coincidencia por archivo
    • dryRun (booleano, opcional): Modo de prueba en seco por archivo
    • failOnAmbiguous (booleano, opcional): Manejo de ambigüedad por archivo
  • failFast (booleano, opcional): Detener en el primer fallo con reversión (true, predeterminado) o continuar (false)

Características:

  • Procesamiento concurrente para operaciones de múltiples archivos
  • Operaciones atómicas con reversión automática en caso de fallo (cuando failFast: true)
  • Preservación de finales de línea multiplataforma
  • Salida detallada de diferencias con estadísticas

Salida: Diferencias detalladas con estadísticas. Para operaciones de múltiples archivos, incluye resultados por archivo y estadísticas resumidas con información de reversión para operaciones atómicas.

Importante: Usa caracteres de nueva línea reales en oldText/newText, NO secuencias de escape como \n.

Operaciones del Sistema de Archivos

make_directory

Crea directorios individuales o múltiples (como Unix mkdir -p)

Entrada:

  • paths (cadena | matriz): Ruta única o matriz de rutas

Salida: Confirmación de éxito. Crea directorios padre recursivamente, idempotente

list_directory

Lista el contenido del directorio con múltiples formatos de salida

Entrada:

  • path (cadena): Ruta del directorio
  • format (cadena, opcional): Formato de salida
    • simple - Listado básico [DIR]/[ARCHIVO] (predeterminado)
    • detailed - Con tamaños, marcas de tiempo y estadísticas
    • tree - Vista de árbol de texto jerárquica
    • json - Datos estructurados con metadatos completos
  • sortBy (cadena, opcional): Orden de clasificación
    • name - Alfabético (predeterminado)
    • size - Más grande primero
  • excludePatterns (matriz, opcional): Patrones glob para excluir (p. ej., ['*.log', 'temp*'])

Salida: Listado del directorio en el formato especificado con metadatos

move_file

Reubica o renombra archivos y directorios

Nota: Esta herramienta está limitada a operaciones de un solo archivo. RECOMENDADO: Usa file_operations en su lugar, que admite operaciones de mover, copiar y renombrar para archivos individuales y por lotes con mayor flexibilidad.

Entrada:

  • source (cadena): Ruta de origen
  • destination (cadena): Ruta de destino

Salida: Confirmación de éxito

file_operations

Operaciones de archivos por lotes (mover, copiar, renombrar)

Entrada:

  • operation (cadena): Tipo de operación
    • move - Reubicar archivos
    • copy - Duplicar archivos
    • rename - Renombrar archivos
  • files (matriz): Lista de pares origen-destino
  • onConflict (cadena, opcional): Resolución de conflictos
    • skip - Omitir archivos existentes
    • overwrite - Reemplazar archivos existentes
    • error - Fallar en conflictos (predeterminado)

Salida: Estado para cada operación. Máximo 100 archivos por operación

delete_files

Elimina archivos y directorios individuales o múltiples

Entrada:

  • paths (matriz): Lista de rutas a eliminar
  • recursive (booleano, opcional): Habilitar eliminación recursiva
  • force (booleano, opcional): Forzar eliminación de archivos de solo lectura

Salida: Estado para cada eliminación. No recursivo por defecto por seguridad

get_file_info

Recupera metadatos de archivos y directorios

Entrada:

  • path (cadena): Ruta del archivo o directorio

Salida: Tamaño, marcas de tiempo, permisos e información de tipo

register_directory

Habilita acceso en tiempo de ejecución a nuevos directorios

Entrada:

  • path (cadena): Ruta del directorio a registrar

Salida: Confirmación de éxito. El directorio se vuelve accesible para operaciones. Se registra la ruta real del directorio (enlaces simbólicos resueltos). Sujeto a --runtime-registration (predeterminado: confirmación del usuario a través del cliente MCP).

list_allowed_directories

Muestra las rutas de directorios actualmente accesibles

Entrada: Ninguna

Salida: Lista de todos los directorios permitidos

Operaciones de Búsqueda

glob_files

Encuentra archivos usando coincidencia de patrones glob

Entrada:

  • path (cadena): Directorio a buscar
  • pattern (cadena): Patrón glob (p. ej., **/*.ts)
  • excludePatterns (matriz, opcional): Patrones a excluir

Salida: Lista de rutas de archivos coincidentes. Los patrones están limitados a 1,000 caracteres.

grep_files

Busca patrones de texto dentro de archivos

Entrada:

  • pattern (cadena): Patrón regex a buscar
  • path (cadena, opcional): Directorio a buscar
  • -i (booleano, opcional): Insensible a mayúsculas/minúsculas
  • -A/-B/-C (número, opcional): Líneas de contexto antes/después de las coincidencias
  • type (cadena, opcional): Filtro de tipo de archivo (js, py, ts, etc.)
  • output_mode (cadena, opcional): Formato de salida
    • content - Líneas coincidentes con números de línea (predeterminado)
    • files_with_matches - Solo rutas de archivos
    • count - Recuentos de coincidencias por archivo
  • head_limit (número, opcional): Limitar resultados

Salida: Líneas coincidentes con contexto, rutas de archivos o recuentos de coincidencias

La coincidencia regex se ejecuta en un hilo de trabajo con un presupuesto de tiempo (5 s por archivo, 30 s por búsqueda), por lo que un patrón patológico falla con un error de tiempo de espera en lugar de congelar el servidor. Los patrones están limitados a 1,000 caracteres.

Operaciones de Shell

execute_shell

Ejecuta comandos de shell con controles de seguridad

Entrada:

  • command (cadena): Comando de shell a ejecutar
  • description (cadena, opcional): Propósito del comando
  • workdir (cadena, opcional): Directorio de trabajo (debe estar dentro de los directorios permitidos). Si no se proporciona, se usa process.cwd() y se valida
  • timeout (número, opcional): Tiempo de espera en milisegundos (predeterminado: 30000)
  • requiresApproval (booleano, opcional): Obsoleto e ignorado (se mantiene por compatibilidad)

Salida: Código de salida, stdout, stderr y metadatos de ejecución

Seguridad:

  • Al menos un directorio aprobado debe estar configurado antes de ejecutar comandos de shell
  • El directorio de trabajo (ya sea explícito o process.cwd() predeterminado) siempre se valida contra los directorios permitidos
  • Cada comando en una cadena (;, &&, ||, |) debe estar en --approved-commands
  • Los operandos de archivos y directorios (argumentos, valores de opciones como --out=... y objetivos de redirección) se validan contra los directorios permitidos después de resolver enlaces simbólicos y uniones; los operandos con variables que no se pueden resolver se rechazan
  • Los comandos deben ser de una sola línea. No permitidos: nuevas líneas, sustitución de comandos, comillas invertidas, un & solitario, agrupación ( )/{ } o bloques de script, heredocs y comillas escapadas (\", \')
  • Los comandos que coinciden con patrones peligrosos se bloquean a menos que el operador los permita con --allow-dangerous-commands
  • execute_shell no es un sandbox: los intérpretes aprobados y las herramientas de ejecución de código aún pueden hacer cualquier cosa que tu cuenta pueda hacer

Ejemplos de Edición de Múltiples Archivos

Refactorización por lotes en múltiples archivos:

{
  files: [
    {
      path: "src/utils.ts",
      edits: [{
        instruction: "Update deprecated function call",
        oldText: "oldApi.getData()",
        newText: "newApi.fetchData()"
      }]
    },
    {
      path: "src/components/Button.tsx",
      edits: [{
        instruction: "Update component prop",
        oldText: "onClick={oldHandler}",
        newText: "onClick={newHandler}"
      }]
    },
    {
      path: "src/hooks/useData.ts",
      edits: [{
        instruction: "Update hook implementation",
        oldText: "const data = oldApi.getData()",
        newText: "const data = newApi.fetchData()"
      }]
    }
  ],
  failFast: true  // Atomic operation - rollback all if any fails
}

Configuración por archivo:

{
  files: [
    {
      path: "config.json",
      edits: [{
        oldText: '"version": "1.0.0"',
        newText: '"version": "1.1.0"'
      }],
      matchingStrategy: "exact"  // JSON needs exact matches
    },
    {
      path: "src/app.py",
      edits: [{
        oldText: "def old_function():",
        newText: "def new_function():"
      }],
      matchingStrategy: "flexible"  // Python indentation may vary
    },
    {
      path: "README.md",
      edits: [{
        oldText: "## Old Section",
        newText: "## New Section"
      }],
      matchingStrategy: "auto"  // Let AI decide best strategy
    }
  ],
  failFast: false  // Continue even if some files fail
}

Para ejemplos de uso detallados, consulta Guía de Uso de Herramientas

Seguridad

Este servidor MCP implementa controles de seguridad para proteger contra vulnerabilidades comunes del sistema de archivos, basados en patrones CVE conocidos. Para reportar una vulnerabilidad, siga SECURITY.md (reporte privado; no abra un issue público).

Protegido Contra

Path Traversal y Bypass de Directorios (CWE-22)

  • Patrón Protegido: CVE-2025-54794 / CVE-2025-53110
  • Mitigación: La validación de ruta canónica con requisitos de separadores de ruta previene ataques de colisión de prefijos
  • Implementación: Utiliza isPathWithinAllowedDirectories() que requiere rutas de subdirectorio reales (no solo coincidencias de prefijo)
  • Ejemplo: Bloquea /path/to/allowed_evil cuando /path/to/allowed está aprobado

Inyección de Comandos (CWE-78)

  • Patrón Protegido: CVE-2025-54795
  • Mitigación: Los comandos se analizan con un parser conservador y consciente de comillas; solo se acepta una gramática pequeña que bash y PowerShell interpretan de la misma manera, y cada comando en una cadena debe ser aprobado
  • Implementación: Rechaza nuevas líneas y caracteres de control, sustitución de comandos, backticks, comillas escapadas, un & solitario, bloques de agrupación/scripts y heredocs; los patrones peligrosos se bloquean a menos que el operador los permita (--allow-dangerous-commands)
  • Ejemplo: echo "\"; malicious_cmd; echo \"" y comandos separados por nuevas líneas son rechazados

Bypass de Directorio en Comandos Shell (CWE-22)

  • Patrón Protegido: Bypass de restricción de ruta a través de rutas en comandos shell
  • Mitigación: Cada operando de archivo (argumentos, valores de opciones como --out=..., objetivos de redirección, objetivos de cd) se valida contra directorios permitidos después de resolver symlinks y junctions
  • Implementación: Los operandos se verifican léxicamente, después de realpath, y con resolución física (symlinks seguidos antes de .., como lo hace un kernel POSIX); los operandos relativos se verifican contra cada directorio donde un cd podría dejar el comando; variables no resolubles y rutas de proveedor de PowerShell (env:, HKLM:, ...) son rechazadas
  • Ejemplo: Bloquea cat /etc/passwd, type C:\Windows\System32\drivers\etc\hosts, echo x >C:\outside\file y cat link/secret (donde link apunta fuera) cuando los objetivos están fuera de los directorios aprobados
  • Alcance: execute_shell no es un sandbox. Un intérprete aprobado o una herramienta de ejecución de código aún puede hacer cualquier cosa que su cuenta pueda hacer, así que apruebe comandos con moderación

Ataques de Symlink (CWE-59 / CWE-61)

  • Patrón Protegido: CVE-2025-53109
  • Mitigación: Todas las rutas se resuelven a través de realpath() antes de la validación para seguir symlinks a los objetivos reales
  • Implementación: Los objetivos de symlink deben estar dentro de directorios permitidos; valida directorios padre para nuevos archivos
  • Ejemplo: Bloquea symlinks que apuntan a /etc/passwd incluso si el symlink está en un directorio permitido

Directory Traversal

  • Mitigación: Normalización estricta de rutas y validación solo contra directorios aprobados
  • Implementación: Rechaza intentos de traversal ../; valida directorios padre antes de la creación de archivos
  • Ejemplo: Bloquea acceso a /unauthorized/path independientemente de los intentos de traversal

Controles de Seguridad

Validación de Rutas

  • Resolución de Ruta Canónica: Todas las rutas se normalizan y resuelven antes de la validación
  • Requisito de Separador: Los subdirectorios deben incluir separadores de ruta (previene colisión de prefijos)
  • Resolución Realpath: Los symlinks se resuelven a objetivos reales antes de las verificaciones de acceso
  • Validación de Directorio Padre: La creación de nuevos archivos valida que el directorio padre esté dentro del alcance permitido

Ejecución de Comandos

  • Lista Blanca de Comandos: Solo se ejecutan los comandos listados en --approved-commands; todo lo demás se bloquea
  • Detección de Patrones: Bloquea patrones peligrosos (destructivos, escalada de privilegios, ejecución de red) a menos que el operador permita el comando con --allow-dangerous-commands
  • Análisis Estructural: Rechaza sustitución de comandos, backticks, nuevas líneas, agrupación y otras construcciones que podrían ocultar comandos de la validación
  • Extracción de Comando Raíz: Analiza todos los comandos en operaciones encadenadas para aprobación
  • Validación de Operandos de Ruta: Valida todos los operandos de archivos/directorios, incluidos los objetivos de redirección, contra directorios permitidos con resolución de symlinks

Controles de Acceso

  • Lista Blanca de Directorios: Las operaciones se restringen a directorios explícitamente aprobados
  • Registro en Tiempo de Ejecución: Los directorios adicionales requieren registro a través de register_directory, que pide al usuario confirmar por defecto (--runtime-registration)
  • Límites de Recursos: Las lecturas de texto de archivos completos están limitadas a 10 MB, attach_image a 10 MB por imagen y 20 MB por llamada, y los documentos Office/ODF se verifican para bombas zip antes de analizarlos
  • Validación Atómica: Las rutas se validan antes de que comience cualquier operación de archivos
  • Seguridad Multiplataforma: Manejo adecuado de diferencias de rutas Windows/Unix y rutas UNC

Mejores Prácticas de Seguridad

  1. Minimizar Directorios Aprobados: Solo apruebe directorios que requieran acceso de IA
  2. Usar Filtrado de Directorios: Excluya carpetas sensibles (por ejemplo, .git, node_modules) de los listados
  3. Limitar Acceso a Herramientas: Habilite solo las herramientas necesarias a través de --enabled-tools o --enabled-tool-categories
  4. Aprobación de Comandos: Apruebe solo los comandos que necesite a través de --approved-commands; evite shells e intérpretes (bash, sh, powershell, node, python, eval), que pueden ejecutar código arbitrario
  5. Monitorear Operaciones: Revise los registros del cliente MCP para intentos de acceso inesperados
  6. Actualizaciones Regulares: Mantenga el servidor actualizado para recibir parches de seguridad

Auditoría de Seguridad

Este servidor ha sido auditado exhaustivamente contra vulnerabilidades conocidas y hallazgos de análisis estático:

Estado de Protección CVE:

  • ✅ CVE-2025-54794 (Bypass de Restricción de Ruta) - CORREGIDO
  • ✅ CVE-2025-54795 (Inyección de Comandos) - PROTEGIDO (variantes de comillas escapadas y nuevas líneas cerradas en 1.3.0)
  • ✅ CVE-2025-53109 (Ataques de Symlink) - PROTEGIDO (brechas de make_directory y execute_shell cerradas en 1.3.0)
  • ✅ CVE-2025-53110 (Bypass de Contención de Directorios) - PROTEGIDO
  • ✅ Bypass de Directorio en Ejecución Shell - CORREGIDO en 1.3.0. La corrección de noviembre de 2024 fue incompleta: rutas con prefijo de barra, redirecciones adjuntas y rutas con symlinks aún podían escapar

Últimas Auditorías de Seguridad:

  • 📋 Lanzamiento de endurecimiento de seguridad 1.3.0 - Octubre 2026

    • Alcance: Auditoría independiente del issue #3 de GitHub más un escaneo de Snyk Open Source / Snyk Code / contenedor y revisión manual
    • Corregido: encadenamiento de comandos con nuevas líneas más allá de la lista blanca, brechas de validación de rutas shell (rutas con barra, redirecciones, symlinks), comandos peligrosos autoaprobados, escape de symlink make_directory, registro de directorios iniciado por IA sin consentimiento, carga de .env desde el directorio de trabajo, manejo de imágenes PDF que podría bloquear el servidor o buscar URLs remotas, uso de recursos regex/lectura/descompresión sin límites, desreferenciación de symlinks en copias de directorios
    • Dependencias: actualizadas con una cuarentena de lanzamiento de 14 días; todos los paquetes pasan npm audit signatures
    • Ver CHANGELOG.md para detalles

  • 📋 Informe de Auditoría de Vulnerabilidades Snyk - Noviembre 2025

    • Estado: 5/6 hallazgos de Snyk validados como falsos positivos, 1 hallazgo corregido
    • Nivel de Riesgo: BAJO - Protección integral de path traversal verificada
    • Análisis Estático: Tasa de falsos positivos de Snyk del 83% debido a validación personalizada no reconocida
    • Cobertura de Pruebas: Más de 2000 líneas de pruebas de seguridad validan todas las medidas de protección

  • 📋 Auditoría Manual CVE - Noviembre 2025

    • Estado: Vulnerabilidad crítica make_directory identificada y corregida
    • Enfoque: Análisis de patrones CVE-2025-54794/54795 y estrategias de mitigación
    • Fecha: 4 de noviembre de 2025 (Investigación Manual de CVE)

  • 📋 Auditoría de Bypass de Directorio en Comandos Shell - Noviembre 2025

    • Estado: Parcialmente corregido en noviembre de 2024; completado en 1.3.0 (octubre de 2026)
    • Problema: Los comandos shell anteriormente podían acceder a archivos fuera de los directorios aprobados a través de rutas absolutas
    • Severidad: ALTA (CVSS ~7.5) - Path traversal a través de argumentos de comandos
    • Estado de Corrección: ✅ CORREGIDO en 1.3.0 - validación consciente de symlinks de todos los operandos, incluidas las redirecciones
    • Cobertura de Pruebas: 419 líneas de pruebas integrales, todas pasando

  • 📋 Resumen de Cobertura de Pruebas de Seguridad

    • Suite de Pruebas: Más de 2000 líneas de pruebas enfocadas en seguridad en src/tests/
    • Pruebas CVE: Pruebas explícitas para CVE-2025-54794, CVE-2025-54795, CVE-2025-53109
    • Cobertura: Path traversal, symlinks (más de 129 casos), inyección de comandos, bypass de shell

Arquitectura de Seguridad:

  • Validación de rutas multicapa (resolución canónica, verificación de límites, protección de symlinks)
  • Defensa en profundidad con operaciones atómicas y prevención de condiciones de carrera
  • Lista blanca de directorios con protección contra colisión de prefijos
  • Anotaciones de seguridad integrales para herramientas de análisis estático

Tipos de Archivos Soportados

Operaciones de Archivos de Texto

Herramientas de Lectura (read_file, read_multiple_files):

  • Archivos de texto: Lee cualquier archivo como texto codificado en UTF-8 (código fuente, archivos de configuración, markdown, JSON, XML, CSV, registros)
  • Archivos de documentos: Detecta y analiza automáticamente:
    • PDF (.pdf) - Extracción de texto plano a través de pdf-parse
    • Word (.docx) - Markdown con formato (encabezados, negrita, listas, tablas) a través de mammoth
    • PowerPoint (.pptx) - Extracción de texto plano a través de officeparser
    • Excel (.xlsx) - Extracción de texto plano a través de officeparser
    • Texto OpenDocument (.odt) - Extracción de texto plano a través de officeparser
    • Presentación OpenDocument (.odp) - Extracción de texto plano a través de officeparser
    • Hoja de cálculo OpenDocument (.ods) - Extracción de texto plano a través de officeparser
  • read_file admite cuatro modos para archivos de texto:
    • full: Lee el archivo completo
    • head: Lee las primeras N líneas
    • tail: Lee las últimas N líneas
    • range: Lee un rango arbitrario de líneas (por ejemplo, líneas 50-100, inclusivo, indexado desde 1)
  • read_multiple_files permite especificación de modo por archivo - cada archivo puede usar un modo diferente en una sola operación
  • Los archivos de documentos ignoran los parámetros de modo y siempre devuelven contenido completo
  • Producirá salida distorsionada para archivos binarios no soportados (imágenes, ejecutables, archivos comprimidos)

Herramientas de Escritura (write_file, write_multiple_files, edit_file):

  • Escribe contenido de texto codificado en UTF-8
  • Admite conversión de HTML a PDF/DOCX con formato enriquecido (encabezados, negrita, cursiva, tablas, listas, colores)
  • Puede crear: código fuente, archivos de configuración, markdown, JSON, XML, CSV, documentos de texto, PDF/DOCX formateados desde HTML
  • Respaldo de texto plano para PDF/DOCX cuando no se detecta HTML
  • No puede escribir archivos binarios (no hay conversión de base64 a binario disponible)

Operaciones de Archivos de Imagen

Herramienta de Adjuntar Imagen (attach_image):

  • Adjunta imágenes para análisis de visión de IA (requiere cliente MCP con capacidad de visión)
  • Formatos soportados: PNG, JPEG, GIF, WebP (SVG se devuelve como texto de marcado; BMP no es compatible)
  • Soporte por lotes: Puede adjuntar una sola imagen o múltiples imágenes en una llamada
  • Las imágenes se presentan a la IA como si fueran subidas directamente por el usuario
  • Permite análisis visual: leer texto en imágenes, analizar diagramas, describir escenas
  • Casos de uso:
    • Analizar capturas de pantalla para depuración
    • Extraer texto de imágenes (similar a OCR)
    • Comparar maquetas de UI (adjuntar múltiples capturas de pantalla a la vez)
    • Describir gráficos y diagramas
    • Identificar objetos en fotos
  • Devuelve imágenes en formato estándar MCP para procesamiento de visión del cliente
  • Solo funciona dentro de directorios permitidos

Ejemplo de Uso:

# Single image
User: "Attach /screenshots/error.png and tell me what's wrong"
AI: [Analyzes image] "This screenshot shows a TypeError on line 42..."

# Multiple images at once
User: "Attach both /screenshots/before.png and /screenshots/after.png and compare them"
AI: [Analyzes both images] "The 'before' screenshot shows..., while the 'after' screenshot..."

Compatibilidad con Clientes:

  • ✅ Funciona con: Claude Desktop, Claude.ai, Cursor, ChatGPT Desktop
  • ✅ Requiere: Cliente MCP con capacidades de visión
  • ❌ Los clientes sin visión recibirán un error

Nota: Actualmente no existe capacidad de escritura para archivos binarios. Puedes adjuntar imágenes para análisis de visión, pero no puedes crear ni modificar archivos de imagen a través de las herramientas del sistema de archivos.

Operaciones del Sistema de Archivos

Herramienta de Operaciones de Archivos (file_operations, move_file):

  • Funciona con cualquier tipo de archivo (texto o binario)
  • Operaciones: mover, copiar, renombrar
  • Maneja tanto archivos como directorios
  • Preserva el contenido del archivo sin modificaciones durante las operaciones

Edición de Archivos

Herramienta de Edición de Archivos (edit_file):

  • Modificación inteligente de archivos con estrategias de coincidencia automáticas (exacta → flexible → difusa)
  • Soporta múltiples ediciones secuenciales en una sola operación
  • Proporciona salida de diff detallada con estadísticas
  • Modo de vista previa opcional (dryRun: true)
  • Preserva la indentación y los finales de línea

Configuración de Desarrollo

# Clone the repository
git clone https://github.com/n0zer0d4y/vulcan-file-ops.git
cd vulcan-file-ops

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Start development server
npm start

Pruebas

El proyecto incluye una cobertura de pruebas integral. Ejecuta las pruebas con:

npm test

Contribuciones

No se aceptan solicitudes de extracción para este proyecto.

Los informes de errores y las solicitudes de funciones son bienvenidos a través de los issues de GitHub. Por favor incluye:

  • Para errores: pasos de reproducción, comportamiento esperado vs. real, detalles del entorno
  • Para funciones: descripción clara de lo que necesitas y tu caso de uso

Los issues existentes pueden cubrir tu tema, así que por favor busca primero.

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENSE para más detalles.