Filesystem MCP Server

Servidor MCP de Sistema de Arquivos

Uma implementação de servidor Model Context Protocol (MCP) que fornece operações de sistema de arquivos, análise e manipulação por meio de uma interface padronizada de ferramentas.

Arquitetura

O servidor é construído sobre o SDK MCP e organizado em camadas distintas:

graph TD
    A[MCP Server Layer] --> B[Tool Registry]
    B --> C[Operations Layer]
    C --> D[File System Operations]
    C --> E[Analysis Operations]
    C --> F[Stream Operations]

Componentes

• Camada de Servidor: Gerencia a comunicação do protocolo MCP e o despacho de ferramentas
• Registro de Ferramentas: Gerencia o registro e a execução de ferramentas
• Camada de Operações: Implementa a funcionalidade principal
• Interface do Sistema de Arquivos: Fornece acesso seguro ao sistema de arquivos

Instalação

1. Clone o repositório:

git clone <repository-url>
cd filesystem-server

2. Instale as dependências:

npm install

3. Compile o servidor:

npm run build

4. Configure as configurações do MCP (cline_mcp_settings.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["path/to/filesystem-server/build/index.js"]
    }
  }
}

Referência de Ferramentas

Operações de Diretório

list_directory

Lista o conteúdo do diretório com metadados.

interface ListDirectoryParams {
    path: string;       // Directory path
    recursive?: boolean; // List recursively (default: false)
}

interface ListDirectoryResult {
    entries: {
        name: string;
        path: string;
        isDirectory: boolean;
        size: number;
        created: string;
        modified: string;
        accessed: string;
        mode: string;
    }[];
}

create_directory

Cria um novo diretório.

interface CreateDirectoryParams {
    path: string;       // Directory path
    recursive?: boolean; // Create parent directories (default: true)
}

Operações de Arquivo

read_file

Lê o conteúdo do arquivo com suporte a codificação.

interface ReadFileParams {
    path: string;     // File path
    encoding?: string; // File encoding (default: 'utf8')
}

write_file

Grava conteúdo em um arquivo.

interface WriteFileParams {
    path: string;     // File path
    content: string;  // Content to write
    encoding?: string; // File encoding (default: 'utf8')
}

append_file

Adiciona conteúdo a um arquivo.

interface AppendFileParams {
    path: string;     // File path
    content: string;  // Content to append
    encoding?: string; // File encoding (default: 'utf8')
}

Operações de Análise

analyze_text

Analisa propriedades de arquivos de texto.

interface AnalyzeTextParams {
    path: string; // File path
}

interface AnalyzeTextResult {
    lineCount: number;
    wordCount: number;
    charCount: number;
    encoding: string;
    mimeType: string;
}

calculate_hash

Calcula o hash do arquivo usando o algoritmo especificado.

interface CalculateHashParams {
    path: string;           // File path
    algorithm?: 'md5' | 'sha1' | 'sha256' | 'sha512'; // Hash algorithm
}

interface CalculateHashResult {
    hash: string;
    algorithm: string;
}

find_duplicates

Identifica arquivos duplicados em um diretório.

interface FindDuplicatesParams {
    path: string; // Directory path
}

interface FindDuplicatesResult {
    duplicates: {
        hash: string;
        size: number;
        files: string[];
    }[];
}

Operações de Compactação

create_zip

Cria um arquivo ZIP.

interface CreateZipParams {
    files: string[];  // Files to include
    output: string;   // Output ZIP path
}

extract_zip

Extrai um arquivo ZIP.

interface ExtractZipParams {
    path: string;    // ZIP file path
    output: string;  // Output directory
}

Tratamento de Erros

O servidor usa códigos de erro MCP padrão:

enum ErrorCode {
    ParseError = -32700,
    InvalidRequest = -32600,
    MethodNotFound = -32601,
    InvalidParams = -32602,
    InternalError = -32603
}

As respostas de erro incluem:

• Código de erro
• Mensagem legível por humanos
• Contexto adicional quando disponível

Exemplo de erro:

{
    "code": -32602,
    "message": "File not found: /path/to/file.txt"
}

Desenvolvimento

Estrutura do Projeto

src/
├── operations/     # Core operations implementation
├── tools/         # MCP tool definitions and handlers
├── __tests__/     # Test suites
├── index.ts       # Entry point
├── server.ts      # MCP server setup
├── types.ts       # Type definitions
└── utils.ts       # Utility functions

Executando Testes

Execute a suíte de testes:

npm test

Execute com cobertura:

npm run test:coverage

Modo de Desenvolvimento

Execute em modo de observação:

npm run watch

Qualidade do Código

Execute a verificação de lint no código:

npm run lint

Verificação de tipos:

npm run type-check

Dependências

Dependências principais:

• @modelcontextprotocol/sdk: Implementação do servidor MCP
• file-type: Detecção de tipo de arquivo
• mime-types: Consulta de tipos MIME
• crypto-js: Hash de arquivos
• archiver: Criação de ZIP
• extract-zip: Extração de ZIP
• iconv-lite: Codificação de texto
• chardet: Detecção de codificação

Dependências de desenvolvimento:

• typescript: Sistema de tipos
• jest: Testes
• eslint: Linting
• prettier: Formatação
• ts-node: Execução de TypeScript
• nodemon: Servidor de desenvolvimento

Contribuição

1. Faça um fork do repositório
2. Crie sua branch de funcionalidade
3. Escreva testes para novos recursos
4. Garanta que todos os testes passem
5. Envie um pull request

Licença

MIT