Vulcan File Ops

Servidor MCP que dá ao Claude Desktop e outros clientes MCP de desktop poderes de sistema de arquivos—ler, escrever, editar e gerenciar arquivos como assistentes de codificação de IA.

GitHub
9
Experimente este MCPPatrocinado

Documentação

Servidor MCP 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 pelo Usuário • Servidor de Operações de Arquivos de Alto Desempenho

Transforme seus assistentes de IA de desktop em poderosos parceiros de desenvolvimento. O Vulcan File Ops preenche a lacuna entre a IA conversacional (Claude Desktop, ChatGPT Desktop, etc.) e seu sistema de arquivos local, desbloqueando as mesmas capacidades de manipulação de arquivos encontradas em IDEs com IA, como Cursor, e extensões do VS Code, como Cline. Escreva código, refatore projetos, gerencie documentação e execute operações complexas de arquivos—igualando o poder de assistentes de codificação dedicados com IA. Com controles de segurança de nível empresarial, registro dinâmico de diretórios e filtragem inteligente de ferramentas, você mantém controle total enquanto seu assistente de IA cuida do trabalho pesado.

Sumário

Contexto

Model Context Protocol

O Model Context Protocol (MCP) permite que assistentes de IA acessem com segurança recursos e serviços externos. Este servidor implementa o MCP para operações de sistema de arquivos, permitindo que agentes de IA leiam, escrevam e gerenciem arquivos dentro de limites de diretórios controlados.

Principais Recursos

Esta implementação aprimorada oferece:

  • Acesso Dinâmico a Diretórios: Registro de diretórios em tempo de execução por meio de comandos conversacionais
  • Suporte a Documentos: Leitura/escrita de PDF, DOCX, PPTX, XLSX, ODT com conversão de HTML para documento
  • Operações em Lote: Leitura, escrita, edição, cópia, movimentação ou renomeação de múltiplos arquivos simultaneamente
  • Edição Avançada de Arquivos: Modificações baseadas em padrões com correspondência flexível e pré-visualização de diferenças
  • Modos de Leitura Flexíveis: Arquivo completo, início/fim ou intervalos arbitrários de linhas
  • Suporte a Visão de Imagens: Anexe imagens para análise e descrição por IA
  • Filtragem de Diretórios: Exclua pastas indesejadas (node_modules, dist, .git) das listagens, pois a ferramenta list_directory pode inflar a saída do servidor se esses tipos de pastas, normalmente ignoradas pelo git, forem incluídas
  • Ativação Seletiva de Ferramentas: Habilite apenas ferramentas ou categorias de ferramentas específicas
  • Alto Desempenho: Algoritmos de busca otimizados com detecção inteligente de recursão
  • Controles de Segurança: Validação de caminhos, restrições de acesso e aprovação de comandos de shell
  • Controle Local: Instalação totalmente local, sem dependências externas

Modelo de Acesso a Diretórios

Este servidor suporta múltiplas abordagens flexíveis para acesso a diretórios:

  1. Acesso Pré-configurado: Use --approved-folders para especificar diretórios na inicialização do servidor para acesso imediato
  2. Registro em Tempo de Execução: Os usuários podem instruir agentes de IA a registrar diretórios durante a conversa por meio da ferramenta register_directory
  3. Protocolo MCP Roots: Aplicativos clientes podem fornecer diretórios de trabalho dinamicamente
  4. Permissões Flexíveis: Combine múltiplas abordagens—comece com pastas aprovadas, adicione mais em tempo de execução
  5. Limites Seguros: Todas as operações validam contra diretórios registrados, independentemente do método de acesso

Instalação

Este servidor requer Node.js e pode ser instalado globalmente, localmente ou executado diretamente com npx. A maioria dos usuários deve usar npx para execução instantânea sem instalação.

Início Rápido (Recomendado para a Maioria dos Usuários)

Execute diretamente sem instalação:

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

Para desenvolvedores que desejam contribuir ou modificar o código, consulte Execução a partir do Repositório Local abaixo.

Instalação Global

Instale globalmente para acesso em todo o sistema:

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

Instalação Local

Instale em um projeto específico:

npm install @n0zer0d4y/vulcan-file-ops

Pré-requisitos

Node.js (versão 14 ou superior) deve estar instalado em seu sistema. Isso fornece npm e npx, que são necessários para executar este pacote.

  • Baixar Node.js: https://nodejs.org/
  • Verificar instalação: Execute node --version e npm --version

Dependências

O servidor não possui dependências de serviços externos e opera inteiramente localmente. Todos os pacotes necessários são baixados automaticamente ao usar npx.

Uso

Este servidor pode ser usado diretamente com npx (recomendado) ou instalado globalmente/localmente. A abordagem com npx não requer instalação e sempre usa a versão mais recente.

Configuração Básica

Adicione à configuração do seu cliente MCP.

Para clientes baseados em JSON, como Claude Desktop e Cursor, use o formato JSON mcpServers. Para Codex, use C:\Users\<username>\.codex\config.toml e o formato de tabela TOML mcp_servers mostrado abaixo.

Opção 1: Usando npx (Recomendado—Sem Necessidade de Instalação)

{
  "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

Opção 2: Usando Instalação Global

Após executar npm install -g @n0zer0d4y/vulcan-file-ops:

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

Opção 3: Usando Instalação Local

Após executar npm install @n0zer0d4y/vulcan-file-ops em seu projeto:

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

Opção 4: Execução a partir do Repositório Local (Para Desenvolvedores)

Se você clonou este repositório e deseja executar a partir do código-fonte:

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

Em seguida, configure seu 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 execução a partir do repositório local, prefira node dist/cli.js com um caminho absoluto. Isso funciona de forma confiável no Codex e evita ambiguidade de PATH.

Configuração Avançada

Pastas Aprovadas

Pré-configure diretórios específicos para acesso imediato na inicialização do 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: Execução a partir do Repositório Local

Para usuários que executam a partir de um repositório clonado (após npm run build):

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

Codex com Pastas Aprovadas (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 Caminho:

  • Windows: Inclua a letra da unidade (ex.: C:/, D:/). Use barras normais em JSON para evitar escapar barras invertidas.
  • macOS/Linux: Comece com / para caminhos absolutos, ou use ~ para o diretório pessoal.

Benefícios:

  • Acesso Instantâneo: Os diretórios são validados e prontos imediatamente quando o servidor inicia
  • Segurança: Apenas os diretórios especificados são acessíveis (a menos que o protocolo MCP Roots seja usado)
  • Conveniência: Sem necessidade de registrar diretórios manualmente via conversa
  • Visibilidade para IA: Os diretórios aprovados são incorporados dinamicamente nas descrições das ferramentas register_directory e list_allowed_directories, garantindo que os assistentes de IA possam ver quais diretórios são pré-aprovados e evitem tentativas redundantes de registro

Como os Assistentes de IA Veem as Pastas Aprovadas:

Quando você configura --approved-folders, o servidor injeta dinamicamente essa informação nas descrições das ferramentas register_directory e list_allowed_directories. Isso garante:

  • ✅ Os assistentes de IA podem ver quais diretórios já estão acessíveis
  • ✅ A IA sabe que NÃO deve registrar novamente diretórios pré-aprovados ou seus subdiretórios
  • ✅ Visibilidade clara sem exigir que a IA chame list_allowed_directories primeiro
  • ✅ Funciona de forma confiável em todos os clientes MCP (incluindo Cursor, Claude Desktop, etc.)

Exemplo do que a IA vê na descrição da ferramenta:

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:

  • Os caminhos devem ser absolutos: Windows requer letra da unidade (C:/path), Unix/Mac começa com / ou ~
  • Lista de diretórios separada por vírgulas (sem espaços, a menos que façam parte do caminho)
  • Os diretórios são validados na inicialização; o servidor será encerrado se qualquer caminho for inválido
  • Funciona em conjunto com a ferramenta register_directory em tempo de execução para acesso adicional
  • O protocolo MCP Roots (se usado pelo cliente) substituirá as pastas aprovadas pelas raízes do espaço de trabalho

Filtragem de Diretórios

Exclua pastas específicas das listagens de diretórios:

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

Seleção de Ferramentas

Habilite apenas categorias específicas de ferramentas:

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

Ou habilite ferramentas individuais:

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

Configuração Combinada

Todas as opções de configuração podem ser combinadas:

Exemplo 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"
      ]
    }
  }
}

Exemplo 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: Execução a partir do Repositório Local

Para usuários que executam a partir de um repositório clonado (após 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 Diretórios

Para acessar um diretório específico, instrua o agente de IA:

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

A IA usará a ferramenta register_directory para obter acesso e, em seguida, realizará operações dentro desse diretório.

API

Ferramentas Disponíveis por Categorias

Operações de Leitura

read_file

Leia o conteúdo de arquivos com modos flexíveis (completo, início, fim, intervalo)

Nota: Esta ferramenta é limitada a operações de arquivo único. RECOMENDADO: Use read_multiple_files em vez disso, que suporta operações de arquivo único e em lote para maior flexibilidade.

Entrada:

  • path (string): Caminho do arquivo
  • mode (string, opcional): Modo de leitura
    • full - Ler o arquivo inteiro (padrão)
    • head - Ler as primeiras N linhas
    • tail - Ler as últimas N linhas
    • range - Ler um intervalo arbitrário de linhas (ex.: linhas 50-100)
  • lines (número, opcional): Número de linhas para o modo início/fim
  • startLine (número, opcional): Linha inicial para o modo intervalo
  • endLine (número, opcional): Linha final para o modo intervalo

Saída: Conteúdo do arquivo como texto. Suporta arquivos de texto e documentos (PDF, DOCX, PPTX, XLSX, ODT, ODP, ODS)

attach_image

Anexe imagens para análise de visão por IA

Entrada:

  • path (string | string[]): Caminho para o arquivo de imagem, ou array de caminhos para anexar múltiplas imagens de uma vez

Saída: Conteúdo da imagem em formato MCP para processamento por modelos de visão. Suporta PNG, JPEG, GIF, WebP, BMP, SVG

read_multiple_files

Leia em lote múltiplos arquivos simultaneamente

Entrada:

  • files (array): Lista de objetos de arquivo com caminho e configurações opcionais de modo

Saída: Conteúdo de todos os arquivos. Falhas de leitura não interrompem a operação

Operações de Escrita

write_file

Crie ou substitua o conteúdo de um arquivo

Nota: Esta ferramenta é limitada a operações de arquivo único. RECOMENDADO: Use write_multiple_files em vez disso, que suporta operações de arquivo único e em lote para maior flexibilidade.

Criação automática de diretórios:

  • Se o diretório pai do arquivo de destino não existir, mas estiver dentro das suas pastas aprovadas configuradas, o servidor criará automaticamente a estrutura de diretórios necessária antes de escrever o arquivo
  • Se o caminho estiver fora das pastas aprovadas, a operação falha com um erro claro e nenhum diretório é criado

Entrada:

  • path (string): Caminho do arquivo
  • content (string): Conteúdo do arquivo (texto ou HTML para conversão em PDF/DOCX)

Saída: Confirmação de sucesso. Suporta conversão de HTML para PDF/DOCX com formatação rica

write_multiple_files

Cria ou substitui vários arquivos simultaneamente

Criação automática de diretórios:

  • Para cada arquivo solicitado, se o diretório pai não existir, mas estiver dentro das suas pastas aprovadas configuradas, o servidor criará automaticamente a estrutura de diretórios necessária antes da gravação
  • Caminhos fora das pastas aprovadas são rejeitados durante a validação e nenhum diretório é criado; a operação falha com uma lista detalhada de caminhos inválidos

Entrada:

  • files (array): Lista de objetos de arquivo com caminho e conteúdo

Saída: Status para cada arquivo. Falhas de gravação não interrompem outros arquivos

edit_file

Aplica modificações precisas em arquivos de texto e código com correspondência inteligente. Suporta operações de arquivo único e de vários arquivos.

Entrada de Arquivo Único (modo: 'single'):

  • mode (string, opcional): Defina como "single" (padrão se omitido para compatibilidade retroativa)
  • path (string): Caminho do arquivo
  • edits (array): Lista de operações de edição, cada uma contendo:
    • oldText (string): Texto a ser pesquisado (inclua 3-5 linhas de contexto)
    • newText (string): Texto de substituição
    • instruction (string, opcional): Descrição do que esta edição faz
    • expectedOccurrences (number, opcional): Contagem esperada de correspondências (padrão: 1)
  • matchingStrategy (string, opcional): Estratégia de correspondência
    • exact - Correspondência caractere por caractere (mais rápida, mais segura)
    • flexible - Correspondência insensível a espaços em branco, preserva indentação
    • fuzzy - Correspondência regex baseada em tokens (mais permissiva)
    • auto - Tenta exata → flexível → difusa (padrão)
  • dryRun (boolean, opcional): Visualizar alterações sem gravar (padrão: false)
  • failOnAmbiguous (boolean, opcional): Falhar quando as correspondências forem ambíguas (padrão: true)

Entrada de Vários Arquivos (modo: 'multiple'):

  • mode (string): Defina como "multiple"
  • files (array): Matriz de solicitações de edição de arquivo (máx. 50), cada uma contendo:
    • path (string): Caminho do arquivo
    • edits (array): Lista de operações de edição para este arquivo (mesma estrutura acima)
    • matchingStrategy (string, opcional): Estratégia de correspondência por arquivo
    • dryRun (boolean, opcional): Modo de execução simulada (dry-run) por arquivo
    • failOnAmbiguous (boolean, opcional): Tratamento de ambiguidade por arquivo
  • failFast (boolean, opcional): Parar na primeira falha com reversão (true, padrão) ou continuar (false)

Recursos:

  • Processamento concorrente para operações com vários arquivos
  • Operações atômicas com reversão automática em caso de falha (quando failFast: true)
  • Preservação de quebras de linha entre plataformas
  • Saída de diff detalhada com estatísticas

Saída: Diff detalhado com estatísticas. Para operações com vários arquivos, inclui resultados por arquivo e estatísticas resumidas com informações de reversão para operações atômicas.

Importante: Use caracteres de nova linha reais em oldText/newText, NÃO sequências de escape como \n.

Operações de Sistema de Arquivos

make_directory

Cria um ou vários diretórios (como o Unix mkdir -p)

Entrada:

  • paths (string | array): Caminho único ou matriz de caminhos

Saída: Confirmação de sucesso. Cria diretórios pai recursivamente, idempotente

list_directory

Lista o conteúdo do diretório com vários formatos de saída

Entrada:

  • path (string): Caminho do diretório
  • format (string, opcional): Formato de saída
    • simple - Listagem básica [DIR]/[FILE] (padrão)
    • detailed - Com tamanhos, carimbos de data/hora e estatísticas
    • tree - Visualização de árvore de texto hierárquica
    • json - Dados estruturados com metadados completos
  • sortBy (string, opcional): Ordem de classificação
    • name - Alfabética (padrão)
    • size - Maiores primeiro
  • excludePatterns (array, opcional): Padrões glob a excluir (ex.: ['*.log', 'temp*'])

Saída: Listagem do diretório no formato especificado com metadados

move_file

Move ou renomeia arquivos e diretórios

Nota: Esta ferramenta está limitada a operações de arquivo único. RECOMENDADO: Use file_operations em vez disso, que suporta operações de mover, copiar e renomear para arquivos únicos e em lote com maior flexibilidade.

Entrada:

  • source (string): Caminho de origem
  • destination (string): Caminho de destino

Saída: Confirmação de sucesso

file_operations

Operações em lote de arquivos (mover, copiar, renomear)

Entrada:

  • operation (string): Tipo de operação
    • move - Mover arquivos
    • copy - Duplicar arquivos
    • rename - Renomear arquivos
  • files (array): Lista de pares origem-destino
  • onConflict (string, opcional): Resolução de conflitos
    • skip - Pular arquivos existentes
    • overwrite - Substituir arquivos existentes
    • error - Falhar em conflitos (padrão)

Saída: Status para cada operação. Máximo de 100 arquivos por operação

delete_files

Exclui um ou vários arquivos e diretórios

Entrada:

  • paths (array): Lista de caminhos a excluir
  • recursive (boolean, opcional): Habilitar exclusão recursiva
  • force (boolean, opcional): Forçar exclusão de arquivos somente leitura

Saída: Status para cada exclusão. Não recursivo por padrão por segurança

get_file_info

Recupera metadados de arquivos e diretórios

Entrada:

  • path (string): Caminho do arquivo ou diretório

Saída: Tamanho, carimbos de data/hora, permissões e informações de tipo

register_directory

Habilita acesso em tempo de execução a novos diretórios

Entrada:

  • path (string): Caminho do diretório a registrar

Saída: Confirmação de sucesso. O diretório se torna acessível para operações

list_allowed_directories

Exibe os caminhos de diretório atualmente acessíveis

Entrada: Nenhuma

Saída: Lista de todos os diretórios permitidos

Operações de Busca

glob_files

Encontra arquivos usando correspondência de padrões glob

Entrada:

  • path (string): Diretório a pesquisar
  • pattern (string): Padrão glob (ex.: **/*.ts)
  • excludePatterns (array, opcional): Padrões a excluir

Saída: Lista de caminhos de arquivos correspondentes

grep_files

Pesquisa padrões de texto dentro de arquivos

Entrada:

  • pattern (string): Padrão regex a pesquisar
  • path (string, opcional): Diretório a pesquisar
  • -i (boolean, opcional): Insensível a maiúsculas/minúsculas
  • -A/-B/-C (number, opcional): Linhas de contexto antes/depois das correspondências
  • type (string, opcional): Filtro de tipo de arquivo (js, py, ts, etc.)
  • output_mode (string, opcional): Formato de saída
    • content - Linhas correspondentes com números de linha (padrão)
    • files_with_matches - Apenas caminhos de arquivo
    • count - Contagens de correspondências por arquivo
  • head_limit (number, opcional): Limitar resultados

Saída: Linhas correspondentes com contexto, caminhos de arquivo ou contagens de correspondências

Operações de Shell

execute_shell

Executa comandos de shell com controles de segurança

Entrada:

  • command (string): Comando de shell a executar
  • description (string, opcional): Finalidade do comando
  • workdir (string, opcional): Diretório de trabalho (deve estar dentro dos diretórios permitidos). Se não for fornecido, process.cwd() é usado e validado
  • timeout (number, opcional): Tempo limite em milissegundos (padrão: 30000)

Saída: Código de saída, stdout, stderr e metadados de execução

Segurança:

  • Pelo menos um diretório aprovado deve ser configurado antes de executar comandos de shell
  • O diretório de trabalho (seja explícito ou o process.cwd() padrão) é sempre validado em relação aos diretórios permitidos
  • Todos os caminhos de arquivo/diretório nos argumentos do comando são extraídos e validados automaticamente em relação aos diretórios permitidos
  • Comandos que referenciam caminhos fora dos diretórios aprovados são bloqueados, impedindo contornos de restrição de diretório

Exemplos de Edição de Vários Arquivos

Refatoração em lote em vários arquivos:

{
  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
}

Configuração por arquivo:

{
  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 exemplos detalhados de uso, consulte Guia de Uso da Ferramenta

Segurança

Este servidor MCP implementa controles de segurança de nível empresarial para proteger contra vulnerabilidades comuns de sistemas de arquivos. Todas as medidas de segurança são baseadas nas melhores práticas do setor e abordam padrões CVE conhecidos.

Protegido Contra

Travessia de Caminho e Contorno de Diretório (CWE-22)

  • Padrão Protegido: CVE-2025-54794 / CVE-2025-53110
  • Mitigação: Validação de caminho canônico com requisitos de separador de caminho impede ataques de colisão de prefixo
  • Implementação: Usa isPathWithinAllowedDirectories() que exige caminhos reais de subdiretório (não apenas correspondências de prefixo)
  • Exemplo: Bloqueia /path/to/allowed_evil quando /path/to/allowed é aprovado

Injeção de Comandos (CWE-78)

  • Padrão Protegido: CVE-2025-54795
  • Mitigação: Validação em múltiplas camadas, incluindo detecção de substituição de comando, extração de comando raiz e correspondência de padrões perigosos
  • Implementação: Bloqueia $() e padrões ` `, >(), <(); valida todos os comandos em cadeias; exige aprovação para operações perigosas
  • Exemplo: Impede tentativas de injeção echo "; malicious_cmd; echo"

Contorno de Diretório em Comandos de Shell (CWE-22)

  • Padrão Protegido: Contorno de restrição de caminho via caminhos absolutos em comandos de shell
  • Mitigação: Extração e validação de caminhos para todos os caminhos de arquivo/diretório incorporados nos argumentos do comando
  • Implementação: Extrai caminhos de strings de comando (lida com caminhos Windows/Unix, aspas, caminhos relativos, variáveis de ambiente), valida cada caminho em relação aos diretórios permitidos antes da execução
  • Exemplo: Bloqueia type C:\Windows\System32\drivers\etc\hosts e cat /etc/passwd quando esses caminhos estão fora dos diretórios aprovados
  • Escopo: Aplica-se a todos os comandos de shell executados via ferramenta execute_shell - caminhos nos argumentos são validados assim como operações de sistema de arquivos

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

  • Padrão Protegido: CVE-2025-53109
  • Mitigação: Todos os caminhos resolvidos via realpath() antes da validação para seguir symlinks até os destinos reais
  • Implementação: Destinos de symlink devem estar dentro dos diretórios permitidos; valida diretórios pai para novos arquivos
  • Exemplo: Bloqueia symlinks que apontam para /etc/passwd mesmo que o symlink esteja em um diretório permitido

Travessia de Diretório

  • Mitigação: Normalização estrita de caminho e validação apenas contra diretórios aprovados
  • Implementação: Rejeita tentativas de travessia ../; valida diretórios pai antes da criação de arquivos
  • Exemplo: Bloqueia acesso a /unauthorized/path independentemente de tentativas de travessia

Controles de Segurança

Validação de Caminho

  • Resolução de Caminho Canônico: Todos os caminhos normalizados e resolvidos antes da validação
  • Requisito de Separador: Subdiretórios devem incluir separadores de caminho (impede colisão de prefixo)
  • Resolução Realpath: Symlinks resolvidos para destinos reais antes das verificações de acesso
  • Validação do Diretório Pai: A criação de novos arquivos valida se o diretório pai está dentro do escopo permitido

Execução de Comandos

  • Lista de Permissões de Comandos: Apenas comandos pré-aprovados executam sem confirmação
  • Detecção de Padrões: Bloqueia padrões perigosos (destrutivos, escalonamento de privilégios, execução em rede)
  • Bloqueio de Substituição de Comando: Impede $(), crases, substituição de processo
  • Extração de Comando Raiz: Analisa todos os comandos em operações encadeadas para aprovação
  • Validação de Argumentos de Caminho: Extrai e valida todos os caminhos de arquivo/diretório nos argumentos do comando em relação aos diretórios permitidos (impede contorno via caminhos absolutos em comandos)

Controles de Acesso

  • Lista de permissões de diretórios: Operações restritas a diretórios explicitamente aprovados
  • Registro em tempo de execução: Diretórios adicionais exigem registro explícito via ferramenta register_directory
  • Validação atômica: Caminhos validados antes de qualquer operação de arquivo começar
  • Segurança multiplataforma: Tratamento adequado de diferenças de caminho Windows/Unix e caminhos UNC

Melhores Práticas de Segurança

  1. Minimize diretórios aprovados: Aprove apenas diretórios que exigem acesso de IA
  2. Use filtragem de diretórios: Exclua pastas sensíveis (por exemplo, .git, node_modules) das listagens
  3. Limite o acesso às ferramentas: Habilite apenas as ferramentas necessárias via --enabled-tools ou --enabled-tool-categories
  4. Aprovação de comandos: Pré-aprove comandos seguros via --approved-commands; exija aprovação para outros
  5. Monitore operações: Revise os logs do cliente MCP para tentativas de acesso inesperadas
  6. Atualizações regulares: Mantenha o servidor atualizado para receber correções de segurança

Auditoria de Segurança

Este servidor foi auditado de forma abrangente contra vulnerabilidades conhecidas e achados de análise estática:

Status de Proteção CVE:

  • ✅ CVE-2025-54794 (Contorno de Restrição de Caminho) - CORRIGIDO
  • ✅ CVE-2025-54795 (Injeção de Comandos) - PROTEGIDO
  • ✅ CVE-2025-53109 (Ataques de Symlink) - PROTEGIDO
  • ✅ CVE-2025-53110 (Contorno de Contenção de Diretório) - PROTEGIDO
  • ✅ Contorno de Diretório de Execução de Shell - CORRIGIDO (Novembro de 2024)

Últimas Auditorias de Segurança:

  • 📋 Relatório de Auditoria de Vulnerabilidades Snyk - Novembro de 2025
    • Status: 5/6 achados do Snyk validados como falsos positivos, 1 achado corrigido
    • Nível de Risco: BAIXO - Proteção abrangente contra travessia de caminho verificada
    • Análise Estática: Taxa de falsos positivos do Snyk de 83% devido à validação personalizada não reconhecida
    • Cobertura de Testes: Mais de 2000 linhas de testes de segurança validam todas as medidas de proteção
  • 📋 Auditoria Manual de CVE - Novembro de 2025
    • Status: Vulnerabilidade crítica make_directory identificada e corrigida
    • Foco: Análise de padrões CVE-2025-54794/54795 e estratégias de mitigação
    • Data: 4 de novembro de 2025 (Pesquisa Manual de CVE)
  • 📋 Auditoria de Contorno de Diretório de Comandos Shell - Novembro de 2025
    • Status: ✅ Corrigido em Novembro de 2024 (documentação retrospectiva)
    • Problema: Comandos Shell anteriormente podiam acessar arquivos fora dos diretórios aprovados via caminhos absolutos
    • Severidade: ALTA (CVSS ~7.5) - Travessia de caminho via argumentos de comando
    • Status da Correção: ✅ CORRIGIDO - Extração e validação de caminho implementadas
    • Cobertura de Testes: 419 linhas de testes abrangentes, todos passando
  • 📋 Resumo da Cobertura de Testes de Segurança
    • Suíte de Testes: Mais de 2000 linhas de testes focados em segurança em src/tests/
    • Testes CVE: Testes explícitos para CVE-2025-54794, CVE-2025-54795, CVE-2025-53109
    • Cobertura: Travessia de caminho, symlinks (mais de 129 casos), injeção de comandos, contorno de shell

Arquitetura de Segurança:

  • Validação de caminho em múltiplas camadas (resolução canônica, verificação de limites, proteção contra symlinks)
  • Defesa em profundidade com operações atômicas e prevenção de condições de corrida
  • Lista de permissões de diretórios com proteção contra colisão de prefixos
  • Anotações de segurança abrangentes para ferramentas de análise estática

Tipos de Arquivo Suportados

Operações de Arquivos de Texto

Ferramentas de Leitura (read_file, read_multiple_files):

  • Arquivos de texto: Lê qualquer arquivo como texto codificado em UTF-8 (código-fonte, arquivos de configuração, markdown, JSON, XML, CSV, logs)
  • Arquivos de documento: Detecta e analisa automaticamente:
    • PDF (.pdf) - Extração de texto simples via pdf-parse
    • Word (.docx) - Markdown com formatação (títulos, negrito, listas, tabelas) via mammoth
    • PowerPoint (.pptx) - Extração de texto simples via officeparser
    • Excel (.xlsx) - Extração de texto simples via officeparser
    • OpenDocument Text (.odt) - Extração de texto simples via officeparser
    • OpenDocument Presentation (.odp) - Extração de texto simples via officeparser
    • OpenDocument Spreadsheet (.ods) - Extração de texto simples via officeparser
  • read_file suporta quatro modos para arquivos de texto:
    • full: Lê o arquivo inteiro
    • head: Lê as primeiras N linhas
    • tail: Lê as últimas N linhas
    • range: Lê um intervalo arbitrário de linhas (por exemplo, linhas 50-100, inclusivo, indexado a partir de 1)
  • read_multiple_files permite especificação de modo por arquivo - cada arquivo pode usar um modo diferente em uma única operação
  • Arquivos de documento ignoram parâmetros de modo e sempre retornam o conteúdo completo
  • Produzirá saída confusa para arquivos binários não suportados (imagens, executáveis, arquivos compactados)

Ferramentas de Escrita (write_file, write_multiple_files, edit_file):

  • Escreve conteúdo de texto codificado em UTF-8
  • Suporta conversão de HTML para PDF/DOCX com formatação rica (títulos, negrito, itálico, tabelas, listas, cores)
  • Pode criar: código-fonte, arquivos de configuração, markdown, JSON, XML, CSV, documentos de texto, PDF/DOCX formatados a partir de HTML
  • Fallback de texto simples para PDF/DOCX quando HTML não é detectado
  • Não pode escrever arquivos binários (nenhuma conversão de base64 para binário disponível)

Operações de Arquivos de Imagem

Ferramenta de Anexar Imagem (attach_image):

  • Anexa imagens para análise de visão por IA (requer cliente MCP com capacidade de visão)
  • Formatos suportados: PNG, JPEG, GIF, WebP, BMP, SVG
  • Suporte a lote: Pode anexar uma única imagem ou múltiplas imagens em uma chamada
  • As imagens são apresentadas à IA como se tivessem sido enviadas diretamente pelo usuário
  • Permite análise visual: leitura de texto em imagens, análise de diagramas, descrição de cenas
  • Casos de uso:
    • Analisar capturas de tela para depuração
    • Extrair texto de imagens (semelhante a OCR)
    • Comparar mockups de UI (anexar múltiplas capturas de tela de uma vez)
    • Descrever gráficos e tabelas
    • Identificar objetos em fotos
  • Retorna imagens no formato padrão MCP para processamento de visão do cliente
  • Funciona apenas dentro de diretórios permitidos

Exemplo 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..."

Compatibilidade com Clientes:

  • ✅ Funciona com: Claude Desktop, Claude.ai, Cursor, ChatGPT Desktop
  • ✅ Requer: cliente MCP com capacidades de visão
  • ❌ Clientes sem visão receberão um erro

Nota: Atualmente não há capacidade de escrita para arquivos binários. Você pode anexar imagens para análise de visão, mas não pode criar ou modificar arquivos de imagem através das ferramentas do sistema de arquivos.

Operações do Sistema de Arquivos

Ferramenta de Operações de Arquivo (file_operations, move_file):

  • Funciona com qualquer tipo de arquivo (texto ou binário)
  • Operações: mover, copiar, renomear
  • Lida com arquivos e diretórios
  • Preserva o conteúdo do arquivo sem modificação durante as operações

Edição de Arquivos

Ferramenta de Edição de Arquivo (edit_file):

  • Modificação inteligente de arquivos com estratégias automáticas de correspondência (exata → flexível → difusa)
  • Suporta múltiplas edições sequenciais em uma operação
  • Fornece saída diff detalhada com estatísticas
  • Modo de pré-visualização opcional (dryRun: true)
  • Preserva indentação e finais de linha

Configuração de Desenvolvimento

# 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

Testes

O projeto inclui cobertura abrangente de testes. Execute os testes com:

npm test

Contribuindo

Pull requests não estão sendo aceitos para este projeto.

Relatórios de bugs e solicitações de recursos são bem-vindos através de issues do GitHub. Por favor, inclua:

  • Para bugs: etapas de reprodução, comportamento esperado vs. real, detalhes do ambiente
  • Para recursos: descrição clara do que você precisa e seu caso de uso

Issues existentes podem já cobrir seu tópico, então pesquise primeiro.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.