Filesystem MCP Server

Fornece a agentes de IA acesso seguro a operações do sistema de arquivos local, como leitura, escrita e gerenciamento de arquivos e diretórios.

GitHub
53
Experimente este MCPPatrocinado

Documentação

Servidor MCP de Sistema de Arquivos

TypeScript Model Context Protocol Version License Status GitHub

Capacite seus agentes de IA com recursos robustos de sistema de arquivos, independentes de plataforma, agora com opções de transporte STDIO e HTTP Streamable.

Este servidor Model Context Protocol (MCP) fornece uma interface segura e confiável para agentes de IA interagirem com o sistema de arquivos local. Ele permite ler, escrever, atualizar e gerenciar arquivos e diretórios, com uma base TypeScript pronta para produção, apresentando logging abrangente, tratamento de erros, medidas de segurança e agora suportando tanto transportes STDIO quanto HTTP.

Sumário

Visão Geral

O Model Context Protocol (MCP) é um framework padrão que permite que modelos de IA interajam com segurança com ferramentas externas e fontes de dados (recursos). Este servidor implementa o padrão MCP para expor operações essenciais de sistema de arquivos como ferramentas, permitindo que agentes de IA:

  • Leiam e analisem conteúdos de arquivos.
  • Criem, modifiquem ou sobrescrevam arquivos.
  • Gerenciem diretórios e caminhos de arquivos.
  • Realizem atualizações direcionadas dentro de arquivos.

Construído com TypeScript, o servidor enfatiza segurança de tipos, modularidade e tratamento robusto de erros, tornando-o adequado para integração confiável em fluxos de trabalho de IA. Agora suporta tanto STDIO para comunicação direta de processos quanto HTTP para interações baseadas em rede.

Arquitetura

O servidor emprega uma arquitetura em camadas para clareza e manutenibilidade:

flowchart TB
    subgraph TransportLayer["Transport Layer"]
        direction LR
        STDIO["STDIO Transport"]
        HTTP["HTTP Transport (Express, JWT Auth)"]
    end

    subgraph APILayer["API Layer"]
        direction LR
        MCP["MCP Protocol Interface"]
        Val["Input Validation (Zod)"]
        PathSan["Path Sanitization"]

        MCP --> Val --> PathSan
    end

    subgraph CoreServices["Core Services"]
        direction LR
        Config["Configuration (Zod-validated Env Vars)"]
        Logger["Logging (Winston, Context-aware)"]
        ErrorH["Error Handling (McpError, ErrorHandler)"]
        ServerLogic["MCP Server Logic"]
        State["Session State (Default Path)"]

        Config --> ServerLogic
        Logger --> ServerLogic & ErrorH
        ErrorH --> ServerLogic
        State --> ServerLogic
    end

    subgraph ToolImpl["Tool Implementation"]
        direction LR
        FSTools["Filesystem Tools"]
        Utils["Core Utilities (Internal, Security, Metrics, Parsing)"]

        FSTools --> ServerLogic
        Utils -- Used by --> FSTools
        Utils -- Used by --> CoreServices
        Utils -- Used by --> APILayer
    end

    TransportLayer --> MCP
    PathSan --> FSTools

    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
    class TransportLayer,APILayer,CoreServices,ToolImpl layer
    class STDIO,HTTP,MCP,Val,PathSan,Config,Logger,ErrorH,ServerLogic,State,FSTools,Utils component
  • Camada de Transporte: Gerencia a comunicação via STDIO ou HTTP (com Express.js e autenticação JWT).
  • Camada de API: Gerencia a comunicação MCP, valida entradas usando Zod e sanitiza caminhos.
  • Serviços Principais: Supervisiona configuração (variáveis de ambiente validadas por Zod), logging sensível ao contexto, relatórios de erros padronizados, estado de sessão (como o diretório de trabalho padrão) e a instância principal do servidor MCP.
  • Implementação de Ferramentas: Contém a lógica específica para cada ferramenta de sistema de arquivos, aproveitando um conjunto refatorado de utilitários compartilhados categorizados em módulos internos, de segurança, métricas e análise.

Recursos

  • Operações Abrangentes de Arquivos: Ferramentas para ler, escrever, listar, excluir, mover e copiar arquivos e diretórios.
  • Atualizações Direcionadas: A ferramenta update_file permite operações precisas de busca e substituição dentro de arquivos, suportando texto simples e regex.
  • Gerenciamento de Caminhos Sensível à Sessão: A ferramenta set_filesystem_default estabelece um diretório de trabalho padrão para resolver caminhos relativos durante uma sessão.
  • Suporte a Transporte Duplo:
    • STDIO: Para comunicação direta e eficiente quando executado como processo filho.
    • HTTP: Para interação baseada em rede, apresentando endpoints RESTful, Server-Sent Events (SSE) para streaming e autenticação baseada em JWT.
  • Segurança em Primeiro Lugar:
    • Sanitização de caminhos integrada para prevenir ataques de travessia de diretórios.
    • Autenticação JWT para transporte HTTP.
    • Validação de entrada com Zod.
  • Base Robusta: Inclui utilitários de nível de produção, agora reorganizados para melhor modularidade:
    • Utilitários Internos: Logging sensível ao contexto (Winston), tratamento padronizado de erros (McpError, ErrorHandler), gerenciamento de contexto de requisições.
    • Utilitários de Segurança: Sanitização de entrada, limitação de taxa, geração de UUID e IDs prefixados.
    • Utilitários de Métricas: Contagem de tokens.
    • Utilitários de Análise: Análise de datas em linguagem natural, análise parcial de JSON.
  • Configuração Aprimorada: Variáveis de ambiente validadas por Zod para configuração segura e confiável em termos de tipos.
  • Segurança de Tipos: Totalmente implementado em TypeScript para maior confiabilidade e manutenibilidade.

Instalação

Passos

  1. Clone o repositório: 
    git clone https://github.com/cyanheads/filesystem-mcp-server.git
cd filesystem-mcp-server
  2. Instale as dependências: 
    npm install
  3. Compile o projeto: 
    npm run build
    Isso compila o código TypeScript para JavaScript no diretório dist/ e torna o script principal executável. O executável estará localizado em dist/index.js.

Configuração

Configure o servidor usando variáveis de ambiente (um arquivo .env é suportado):

Configurações Principais do Servidor:

  • MCP_LOG_LEVEL (Opcional): Nível mínimo de logging (ex.: debug, info, warn, error). O padrão é debug.
  • LOGS_DIR (Opcional): Diretório para arquivos de log. O padrão é ./logs na raiz do projeto.
  • NODE_ENV (Opcional): Ambiente de execução (ex.: development, production). O padrão é development.

Configurações de Transporte:

  • MCP_TRANSPORT_TYPE (Opcional): Transporte de comunicação (stdio ou http). O padrão é stdio.
    • Se http for selecionado:
      • MCP_HTTP_PORT (Opcional): Porta para o servidor HTTP. O padrão é 3010.
      • MCP_HTTP_HOST (Opcional): Host para o servidor HTTP. O padrão é 127.0.0.1.
      • MCP_ALLOWED_ORIGINS (Opcional): Lista separada por vírgulas de origens CORS permitidas (ex.: http://localhost:3000,https://example.com).
      • MCP_AUTH_SECRET_KEY (Obrigatório para Autenticação HTTP): Uma chave secreta segura (com pelo menos 32 caracteres) para autenticação JWT. CRÍTICO para produção.

Segurança do Sistema de Arquivos:

  • FS_BASE_DIRECTORY (Opcional): Define o diretório raiz para todas as operações do sistema de arquivos. Pode ser um caminho absoluto ou um caminho relativo à raiz do projeto (ex.: ./data_sandbox). Se definido, as ferramentas do servidor serão restritas a acessar arquivos e diretórios apenas dentro deste caminho especificado (e resolvido como absoluto) e seus subdiretórios. Este é um recurso de segurança crucial para prevenir acesso não intencional a outras partes do sistema de arquivos. Se não for definido (o que não é recomendado para ambientes de produção), um aviso será registrado e as operações não serão restritas.

Integração com LLM e API (Opcional):

  • OPENROUTER_APP_URL: URL do seu aplicativo para OpenRouter.
  • OPENROUTER_APP_NAME: Nome do seu aplicativo para OpenRouter. O padrão é MCP_SERVER_NAME.
  • OPENROUTER_API_KEY: Chave de API para serviços OpenRouter.
  • LLM_DEFAULT_MODEL: Modelo LLM padrão a ser usado (ex.: google/gemini-2.5-flash-preview-05-20).
  • LLM_DEFAULT_TEMPERATURE, LLM_DEFAULT_TOP_P, LLM_DEFAULT_MAX_TOKENS, LLM_DEFAULT_TOP_K, LLM_DEFAULT_MIN_P: Parâmetros padrão para chamadas LLM.
  • GEMINI_API_KEY: Chave de API para serviços Google Gemini.

Integração com Proxy OAuth (Opcional, para cenários avançados):

  • OAUTH_PROXY_AUTHORIZATION_URL, OAUTH_PROXY_TOKEN_URL, OAUTH_PROXY_REVOCATION_URL, OAUTH_PROXY_ISSUER_URL, OAUTH_PROXY_SERVICE_DOCUMENTATION_URL, OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS: Configuração para um proxy OAuth.

Consulte src/config/index.ts e o arquivo .clinerules para a lista completa e definições de esquema Zod.

Uso com Clientes MCP

Para permitir que um cliente MCP (como um assistente de IA) use este servidor:

  1. Execute o Servidor: Inicie o servidor a partir do seu terminal:

    node dist/index.js
# Or if you are in the project root:
# npm start

  2. Configure o Cliente: Adicione o servidor à configuração do seu cliente MCP. O método exato depende do cliente.

    Para Transporte STDIO (Padrão): Normalmente envolve especificar:

    • Comando: node
    • Argumentos: O caminho absoluto para o executável do servidor compilado (ex.: /path/to/filesystem-mcp-server/dist/index.js).
    • Variáveis de Ambiente (Opcional): Defina quaisquer variáveis de ambiente necessárias da seção Configuração.

    Exemplo de Configurações MCP para STDIO (Conceitual):

    {
  "mcpServers": {
    "filesystem_stdio": {
      "command": "node",
      "args": ["/path/to/filesystem-mcp-server/dist/index.js"],
      "env": {
        "MCP_LOG_LEVEL": "debug"
        // Other relevant env vars
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

    Para Transporte HTTP: O cliente precisará saber a URL do servidor (ex.: http://localhost:3010) e como autenticar (ex.: fornecendo um token Bearer JWT se MCP_AUTH_SECRET_KEY estiver definido). Consulte a documentação do seu cliente MCP para configuração de servidor HTTP.

Uma vez configurado e em execução, o cliente detectará o servidor e suas ferramentas disponíveis.

Ferramentas Disponíveis

O servidor expõe as seguintes ferramentas para interação com o sistema de arquivos:

FerramentaDescrição
set_filesystem_defaultDefine um caminho absoluto padrão para a sessão atual. Caminhos relativos usados em chamadas de ferramenta subsequentes serão resolvidos com base nesse padrão. É redefinido ao reiniciar o servidor.
read_fileLê o conteúdo completo de um arquivo especificado como texto UTF-8. Aceita caminhos relativos (resolvidos com base no padrão) ou absolutos.
write_fileEscreve conteúdo em um arquivo especificado. Cria o arquivo (e os diretórios pai necessários) se ele não existir, ou o sobrescreve se já existir. Aceita caminhos relativos ou absolutos.
update_fileRealiza operações direcionadas de busca e substituição em um arquivo existente usando uma matriz de blocos {search, replace}. Ideal para alterações localizadas. Suporta busca por texto simples ou regex (useRegex: true) e substituição de todas as ocorrências (replaceAll: true). Aceita caminhos relativos ou absolutos. O arquivo deve existir.
list_filesLista arquivos e diretórios em um caminho especificado. As opções incluem listagem recursiva (includeNested: true) e limitação do número de entradas (maxEntries). Retorna uma estrutura de árvore formatada. Aceita caminhos relativos ou absolutos.
delete_fileRemove permanentemente um arquivo específico. Aceita caminhos relativos ou absolutos.
delete_directoryRemove permanentemente um diretório. Use recursive: true para remover diretórios não vazios e seu conteúdo (use com cautela!). Aceita caminhos relativos ou absolutos.
create_directoryCria um novo diretório no caminho especificado. Por padrão (create_parents: true), também cria quaisquer diretórios pai necessários. Aceita caminhos relativos ou absolutos.
move_pathMove ou renomeia um arquivo ou diretório de um caminho de origem para um caminho de destino. Aceita caminhos relativos ou absolutos para ambos.
copy_pathCopia um arquivo ou diretório de um caminho de origem para um caminho de destino. Para diretórios, copia recursivamente por padrão (recursive: true). Aceita caminhos relativos ou absolutos.

Consulte os arquivos de registro de ferramentas (src/mcp-server/tools/*/registration.ts) para obter esquemas detalhados de entrada/saída (Zod/JSON Schema).

Estrutura do Projeto

O código-fonte está organizado para clareza e facilidade de manutenção:

filesystem-mcp-server/
├── dist/                 # Compiled JavaScript output (after npm run build)
├── logs/                 # Log files (created at runtime)
├── node_modules/         # Project dependencies
├── src/                  # TypeScript source code
│   ├── config/           # Configuration loading (index.ts)
│   ├── mcp-server/       # Core MCP server logic
│   │   ├── server.ts     # Server initialization, tool registration, transport handling
│   │   ├── state.ts      # Session state management (e.g., default path)
│   │   ├── tools/        # Individual tool implementations (one subdir per tool)
│   │   │   ├── readFile/
│   │   │   │   ├── index.ts
│   │   │   │   ├── readFileLogic.ts
│   │   │   │   └── registration.ts
│   │   │   └── ...       # Other tools (writeFile, updateFile, etc.)
│   │   └── transports/   # Communication transport implementations
│   │       ├── authentication/ # Auth middleware for HTTP
│   │       │   └── authMiddleware.ts
│   │       ├── httpTransport.ts
│   │       └── stdioTransport.ts
│   ├── types-global/     # Shared TypeScript types and interfaces
│   │   ├── errors.ts     # Custom error classes and codes (McpError, BaseErrorCode)
│   │   ├── mcp.ts        # MCP related types
│   │   └── tool.ts       # Tool definition types
│   ├── utils/            # Reusable utility modules, categorized
│   │   ├── internal/     # Core internal utilities (errorHandler, logger, requestContext)
│   │   ├── metrics/      # Metrics-related utilities (tokenCounter)
│   │   ├── parsing/      # Parsing utilities (dateParser, jsonParser)
│   │   ├── security/     # Security-related utilities (idGenerator, rateLimiter, sanitization)
│   │   └── index.ts      # Barrel export for all utilities
│   └── index.ts          # Main application entry point
├── .clinerules           # Cheatsheet for LLM assistants
├── .dockerignore
├── Dockerfile
├── LICENSE
├── mcp.json              # MCP server manifest (generated by SDK or manually)
├── package.json
├── package-lock.json
├── README.md             # This file
├── repomix.config.json
├── smithery.yaml         # Smithery configuration (if used)
└── tsconfig.json         # TypeScript compiler options

Para uma visão detalhada e atual da estrutura, execute: npm run tree (Este script pode precisar ser atualizado se src/scripts/tree.ts fizer parte das alterações).

Nota do Desenvolvedor: Este repositório inclui um arquivo .clinerules. Esta folha de referência fornece ao seu assistente de codificação LLM contexto essencial sobre padrões do código-fonte, localizações de arquivos e exemplos de uso. Mantenha-o atualizado conforme o servidor evolui!

Licença

Este projeto está licenciado sob a Apache License 2.0. Consulte o arquivo LICENSE para obter detalhes.

Feito com ❤️ e o Model Context Protocol