DrDexter6000/talking-cli

Servidor MCP de Sistema de Arquivos

Servidor Node.js que implementa o Protocolo de Contexto de Modelo (MCP) para operações no sistema de arquivos.

Funcionalidades

• Ler/escrever arquivos
• Criar/listar/excluir diretórios
• Mover arquivos/diretórios
• Pesquisar arquivos
• Obter metadados de arquivos
• Controle de acesso dinâmico a diretórios via Raízes (Roots)

Controle de Acesso a Diretórios

O servidor usa um sistema flexível de controle de acesso a diretórios. Os diretórios podem ser especificados via argumentos de linha de comando ou dinamicamente via Raízes (Roots).

Método 1: Argumentos de Linha de Comando

Especifique os diretórios permitidos ao iniciar o servidor:

mcp-server-filesystem /caminho/para/dir1 /caminho/para/dir2

Método 2: Raízes MCP (Recomendado)

Clientes MCP que suportam Raízes (Roots) podem atualizar dinamicamente os diretórios permitidos.

Raízes notificadas pelo Cliente ao Servidor substituem completamente os diretórios permitidos do lado do servidor quando fornecidas.

Importante: Se o servidor for iniciado sem argumentos de linha de comando E o cliente não suportar o protocolo de raízes (ou fornecer raízes vazias), o servidor lançará um erro durante a inicialização.

Este é o método recomendado, pois permite atualizações de diretório em tempo de execução via notificações roots/list_changed sem reinicialização do servidor, proporcionando uma experiência de integração mais flexível e moderna.

Como Funciona

O controle de acesso a diretórios do servidor segue este fluxo:

1. Inicialização do Servidor

   • O servidor inicia com diretórios dos argumentos de linha de comando (se fornecidos)
   • Se nenhum argumento for fornecido, o servidor inicia com diretórios permitidos vazios

2. Conexão e Inicialização do Cliente

   • O cliente conecta e envia uma solicitação initialize com capacidades
   • O servidor verifica se o cliente suporta o protocolo de raízes (capabilities.roots)

3. Manipulação do Protocolo de Raízes (se o cliente suportar raízes)

   • Na inicialização: O servidor solicita raízes do cliente via roots/list
   • O cliente responde com suas raízes configuradas
   • O servidor substitui TODOS os diretórios permitidos pelas raízes do cliente
   • Em atualizações em tempo de execução: O cliente pode enviar notifications/roots/list_changed
   • O servidor solicita raízes atualizadas e substitui os diretórios permitidos novamente

4. Comportamento de Fallback (se o cliente não suportar raízes)

   • O servidor continua usando apenas os diretórios da linha de comando
   • Nenhuma atualização dinâmica é possível

5. Controle de Acesso

   • Todas as operações do sistema de arquivos são restritas aos diretórios permitidos
   • Use a ferramenta list_allowed_directories para ver os diretórios atuais
   • O servidor requer pelo menos UM diretório permitido para operar

Nota: O servidor só permitirá operações dentro de diretórios especificados via args ou via Raízes.

API

Ferramentas

• read_text_file

  • Ler o conteúdo completo de um arquivo como texto
  • Entradas:
    • path (string)
    • head (número, opcional): Primeiras N linhas
    • tail (número, opcional): Últimas N linhas
  • Sempre trata o arquivo como texto UTF-8, independentemente da extensão
  • Não é possível especificar head e tail simultaneamente

• read_media_file

  • Ler um arquivo de imagem ou áudio
  • Entradas:
    • path (string)
  • Transmite o arquivo e retorna dados base64 com o tipo MIME correspondente

• read_multiple_files

  • Ler vários arquivos simultaneamente
  • Entrada: paths (string[])
  • Leituras com falha não interrompem toda a operação

• write_file

  • Criar novo arquivo ou sobrescrever existente (tenha cuidado com isso)
  • Entradas:
    • path (string): Localização do arquivo
    • content (string): Conteúdo do arquivo

• edit_file

  • Fazer edições seletivas usando correspondência de padrões avançada e formatação
  • Funcionalidades:
    • Correspondência de conteúdo baseada em linhas e multilinhas
    • Normalização de espaços em branco com preservação de indentação
    • Múltiplas edições simultâneas com posicionamento correto
    • Detecção e preservação de estilo de indentação
    • Saída de diff no estilo Git com contexto
    • Visualizar alterações com modo de execução simulada (dry run)
  • Entradas:
    • path (string): Arquivo a editar
    • edits (array): Lista de operações de edição
      • oldText (string): Texto a pesquisar (pode ser substring)
      • newText (string): Texto para substituir
    • dryRun (booleano): Visualizar alterações sem aplicar (padrão: false)
  • Retorna diff detalhado e informações de correspondência para execuções simuladas; caso contrário, aplica as alterações
  • Melhor Prática: Sempre use dryRun primeiro para visualizar as alterações antes de aplicá-las

• create_directory

  • Criar novo diretório ou garantir que exista
  • Entrada: path (string)
  • Cria diretórios pai, se necessário
  • Bem-sucedido silenciosamente se o diretório já existir

• list_directory

  • Listar o conteúdo do diretório com prefixos [FILE] ou [DIR]
  • Entrada: path (string)

• list_directory_with_sizes

  • Listar o conteúdo do diretório com prefixos [FILE] ou [DIR], incluindo tamanhos de arquivo
  • Entradas:
    • path (string): Caminho do diretório a listar
    • sortBy (string, opcional): Ordenar entradas por "name" ou "size" (padrão: "name")
  • Retorna listagem detalhada com tamanhos de arquivo e estatísticas resumidas
  • Mostra total de arquivos, diretórios e tamanho combinado

• move_file

  • Mover ou renomear arquivos e diretórios
  • Entradas:
    • source (string)
    • destination (string)
  • Falha se o destino existir

• search_files

  • Pesquisar recursivamente arquivos/diretórios que correspondam ou não a padrões
  • Entradas:
    • path (string): Diretório inicial
    • pattern (string): Padrão de pesquisa
    • excludePatterns (string[]): Excluir quaisquer padrões.
  • Correspondência de padrão no estilo glob
  • Retorna caminhos completos para correspondências

• directory_tree

  • Obter estrutura JSON recursiva em árvore do conteúdo do diretório
  • Entradas:
    • path (string): Diretório inicial
    • excludePatterns (string[]): Excluir quaisquer padrões. Formatos glob são suportados.
  • Retorna:
    • Array JSON onde cada entrada contém:
      • name (string): Nome do arquivo/diretório
      • type ('file'|'directory'): Tipo de entrada
      • children (array): Presente apenas para diretórios
        • Array vazio para diretórios vazios
        • Omitido para arquivos
  • A saída é formatada com indentação de 2 espaços para legibilidade

• get_file_info

  • Obter metadados detalhados de arquivo/diretório
  • Entrada: path (string)
  • Retorna:
    • Tamanho
    • Hora de criação
    • Hora de modificação
    • Hora de acesso
    • Tipo (arquivo/diretório)
    • Permissões

• list_allowed_directories

  • Listar todos os diretórios que o servidor tem permissão para acessar
  • Nenhuma entrada necessária
  • Retorna:
    • Diretórios dos quais este servidor pode ler/escrever

Anotações de ferramenta (dicas MCP)

Este servidor define Anotações de Ferramenta MCP em cada ferramenta para que os clientes possam:

• Distinguir ferramentas somente leitura das ferramentas com capacidade de escrita.
• Entender quais operações de escrita são idempotentes (seguras de repetir com os mesmos argumentos).
• Destacar operações que podem ser destrutivas (sobrescrever ou alterar dados intensamente).

O mapeamento para ferramentas do sistema de arquivos é:

Ferramenta	readOnlyHint	idempotentHint	destructiveHint	Notas
read_text_file	true	–	–	Somente leitura
read_media_file	true	–	–	Somente leitura
read_multiple_files	true	–	–	Somente leitura
list_directory	true	–	–	Somente leitura
list_directory_with_sizes	true	–	–	Somente leitura
directory_tree	true	–	–	Somente leitura
search_files	true	–	–	Somente leitura
get_file_info	true	–	–	Somente leitura
list_allowed_directories	true	–	–	Somente leitura
create_directory	false	true	false	Recriar o mesmo diretório é uma não operação
write_file	false	true	true	Sobrescreve arquivos existentes
edit_file	false	false	true	Reaplicar edições pode falhar ou aplicar em dobro
move_file	false	false	true	Exclui o arquivo de origem

Nota: idempotentHint e destructiveHint são significativos apenas quando readOnlyHint é false, conforme definido pela especificação MCP.

Uso com Claude Desktop

Adicione isso ao seu claude_desktop_config.json:

Nota: você pode fornecer diretórios em área restrita (sandbox) para o servidor montando-os em /projects. Adicionar a flag ro tornará o diretório somente leitura para o servidor.

Docker

Nota: todos os diretórios devem ser montados em /projects por padrão.

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Usuarios/nomedousuario/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/caminho/para/outro/dir/permitido,dst=/projects/outro/dir/permitido,ro",
        "--mount", "type=bind,src=/caminho/para/arquivo.txt,dst=/projects/caminho/para/arquivo.txt",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Usuarios/nomedousuario/Desktop",
        "/caminho/para/outro/dir/permitido"
      ]
    }
  }
}

No Windows, use cmd /c para executar npx:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Usuarios/nomedousuario/Desktop",
        "/caminho/para/outro/dir/permitido"
      ]
    }
  }
}

Uso com VS Code

Para instalação rápida, clique nos botões de instalação abaixo...

Para instalação manual, você pode configurar o servidor MCP usando um destes métodos:

Método 1: Configuração do Usuário (Recomendado) Adicione a configuração ao seu arquivo de configuração MCP de nível de usuário. Abra a Paleta de Comandos (Ctrl + Shift + P) e execute MCP: Open User Configuration. Isso abrirá seu arquivo mcp.json de usuário onde você pode adicionar a configuração do servidor.

Método 2: Configuração do Espaço de Trabalho Alternativamente, você pode adicionar a configuração a um arquivo chamado .vscode/mcp.json em seu espaço de trabalho. Isso permitirá que você compartilhe a configuração com outras pessoas.

Para mais detalhes sobre a configuração MCP no VS Code, veja a documentação oficial do VS Code sobre MCP.

Você pode fornecer diretórios em área restrita (sandbox) para o servidor montando-os em /projects. Adicionar a flag ro tornará o diretório somente leitura para o servidor.

Docker

Nota: todos os diretórios devem ser montados em /projects por padrão.

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

No Windows, use:

{
  "servers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}