Folder MCP

Um servidor para operações de pastas locais e acesso ao sistema de arquivos.

Documentação

folder-mcp (Em desenvolvimento, será lançado em breve)

Servidor do Model Context Protocol para Operações de Pasta

Um servidor do Model Context Protocol (MCP) que fornece ferramentas para ler e analisar estruturas de pastas, permitindo que LLMs interajam com sistemas de arquivos locais de forma segura e eficiente.

Visão Geral

folder-mcp foi criado com um propósito simples, porém poderoso: pegar sua pasta local e torná-la acessível a Grandes Modelos de Linguagem (LLMs) executados em qualquer lugar. Você não precisa enviar seus arquivos para a nuvem ou usar um serviço de terceiros.

Ele cria capacidades de RAG (Geração Aumentada por Recuperação) para seus arquivos locais, permitindo que LLMs leiam, pesquisem e analisem documentos de forma segura e estruturada. Este servidor implementa o padrão Model Context Protocol (MCP), permitindo que LLMs interajam com sistemas de arquivos locais por meio de um conjunto de ferramentas definidas. Este projeto foi projetado para funcionar com clientes MCP como Claude Desktop, Cursor, VsCode e outros, fornecendo uma maneira segura e eficiente de acessar e manipular arquivos dentro de pastas especificadas.

Recursos

✅ Acesso Seguro a Arquivos

Ler arquivos de pastas especificadas com validação de caminho
Verificações de segurança para prevenir ataques de travessia de diretório
Suporte a vários tipos de arquivo e codificações

✅ Operações de Sistema de Arquivos

Listar todos os arquivos em uma pasta recursivamente
Pesquisar arquivos por padrões de nome (suporte a glob)
Obter informações e metadados da pasta
Excluir diretórios comuns como node_modules e .git

✅ Integração MCP

Implementação padrão do servidor Model Context Protocol
Funciona com Claude Desktop e outros clientes MCP
Transporte Stdio para integração perfeita
Definições estruturadas de ferramentas com esquemas JSON

✅ Amigável para Desenvolvedores

Implementação em TypeScript com segurança total de tipos
Tratamento claro de erros e respostas informativas
Interface CLI simples para testes e desenvolvimento

Instalação

git clone https://github.com/okets/folder-mcp.git
cd folder-mcp
npm install
npm run build

Configuração

folder-mcp usa um sistema de configuração centralizado armazenado em config.yaml na raiz do projeto. Este arquivo YAML contém configurações para embeddings, cache, processamento, API, registro de logs e configurações de desenvolvimento.

Modelos de Embedding

O sistema suporta múltiplos modelos de embedding com aceleração de GPU via Ollama:

Model	Dimensions	Description
`nomic-v1.5`	768	Propósito geral de alta qualidade (padrão)
`mxbai-large`	1024	Modelo grande com excelente desempenho
`all-minilm`	384	Leve e rápido
`bge-small`	384	Embedding geral BAAI, versão pequena
`gte-base`	768	Modelo de Embeddings de Texto Geral

Estrutura de Configuração

# Embedding Model Configuration
embeddings:
  defaultModel: "nomic-v1.5"
  ollamaApiUrl: "http://127.0.0.1:11434"
  batchSize: 32
  timeoutMs: 30000
  models:
    # Model definitions with dimensions, descriptions, etc.

# Cache Configuration  
cache:
  defaultCacheDir: "~/.cache/folder-mcp"
  maxCacheSize: "10GB"
  cleanupIntervalHours: 24

# Text Processing Configuration
processing:
  defaultChunkSize: 1000
  defaultOverlap: 200
  maxConcurrentOperations: 10

# Development & Logging options
logging:
  level: "info"
  format: "json"
  
development:
  enableDebugOutput: false
  mockOllamaApi: false

Para opções de configuração detalhadas, consulte CONFIGURATION.md.

Status Atual

🚀 Versão 1.0 - Servidor MCP Básico (13/30 recursos planejados concluídos)

Esta é a versão inicial que fornece acesso seguro ao sistema de arquivos por meio do MCP. A visão completa inclui busca semântica, embeddings e análise inteligente de documentos - consulte ROADMAP.md para o plano de desenvolvimento completo.

O que funciona agora:

✅ Leitura básica de arquivos e operações de pasta
✅ Validação de segurança e proteção de caminho
✅ Pesquisa de arquivos baseada em padrões
✅ Integração com o protocolo MCP

Próximos passos: Divisão inteligente de texto, embeddings semânticos, busca vetorial (veja todos os 30 recursos planejados)

Uso

Como um Servidor MCP

Este servidor foi projetado para ser usado com clientes MCP como o Claude Desktop. Adicione-o à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "folder-mcp": {
      "command": "node",
      "args": [
        "C:\\Path\\To\\folder-mcp\\dist\\mcp-server.js",
        "C:\\Path\\To\\folder-mcp"
      ],
      "env": {}
    }
  }
}

⚠️ Nota Crítica de Integração com Claude Desktop: O protocolo MCP exige que SOMENTE mensagens JSON-RPC válidas vão para stdout. Qualquer saída de registro ou depuração para stdout quebrará a conexão. Todos os logs devem ser redirecionados apenas para stderr. Consulte CLAUDE_DESKTOP_SETUP.md para dicas detalhadas de solução de problemas.

Ferramentas Disponíveis

O servidor atualmente fornece as seguintes ferramentas:

get_status - Uma ferramenta de status do sistema que retorna informações de processamento para verificar a conexão
- Parâmetro opcional: name - Um nome para incluir na saudação

1. `read_file`

Leia o conteúdo de um arquivo específico dentro de uma pasta.

Parâmetros:

folder_path: Caminho para a pasta que contém o arquivo
file_path: Caminho relativo para o arquivo dentro da pasta

2. `search_files`

Pesquise arquivos que correspondam a um padrão específico.

Parâmetros:

folder_path: Caminho para a pasta a ser pesquisada
pattern: Padrão de arquivo (por exemplo, ".md", ".txt", "config.*")

3. `list_files`

Liste todos os arquivos em uma pasta recursivamente.

Parâmetros:

folder_path: Caminho para a pasta a ser listada

4. `get_folder_info`

Obtenha informações sobre uma pasta, incluindo contagem de arquivos e metadados.

Parâmetros:

folder_path: Caminho para a pasta a ser analisada

Recursos de Segurança

Validação de Caminho: Impede o acesso a arquivos fora da pasta especificada
Exclusões de Diretório: Exclui automaticamente pastas node_modules, .git e de cache
Tratamento de Erros: Tratamento gracioso de erros de permissão e caminhos inválidos

Arquitetura

Implementação do Servidor MCP

O servidor implementa o padrão Model Context Protocol com os seguintes componentes:

📡 MCP Client (Claude Desktop) ↔ 📞 Stdio Transport ↔ 🖥️ MCP Server ↔ 📁 File System

Padrão de Acesso a Arquivos

1. Client Request → 2. Tool Validation → 3. Path Security Check → 4. File Operation → 5. Response

Componentes do Servidor

Manipuladores de Ferramentas: Processam solicitações read_file, search_files, list_files e get_folder_info
Camada de Segurança: Valida caminhos e previne travessia de diretório
Operações de Arquivo: Usa Node.js fs e glob para acesso eficiente ao sistema de arquivos
Camada de Transporte: Transporte Stdio para comunicação com clientes MCP

Detalhes Técnicos

Dependências

@modelcontextprotocol/sdk: Implementação do protocolo MCP
glob: Pesquisa de arquivos baseada em padrões
typescript: Desenvolvimento com segurança de tipos
Bibliotecas adicionais para futuras capacidades de análise de arquivos

Padrões de Arquivo

O servidor usa padrões glob para pesquisa de arquivos:

* - Todos os arquivos
*.md - Apenas arquivos Markdown
**/*.js - Arquivos JavaScript recursivamente
config.* - Qualquer arquivo que comece com "config"

Diretórios Excluídos

Excluídos automaticamente de todas as operações:

**/node_modules/**
**/.git/**
**/.folder-mcp/**

Desenvolvimento

Compilando o Projeto

npm run build

Executando o Servidor

npm start

Modo de Desenvolvimento

npm run dev

Testando com Clientes MCP

O servidor pode ser testado com qualquer cliente compatível com MCP. Para o Claude Desktop, adicione a configuração ao seu arquivo de configurações.

Melhorias Futuras

📋 Roteiro de Desenvolvimento: Consulte ROADMAP.md para progresso visual e GITHUB_ISSUES.md para detalhamento de tarefas.

Recursos Planejados (17 tarefas restantes):

Fase 3: Divisão inteligente de texto e embeddings semânticos
Fase 4: Busca vetorial FAISS e correspondência de similaridade
Fase 5: Integração MCP aprimorada com busca semântica
Fase 6: Monitoramento de arquivos em tempo real e sistema de configuração
Fase 7: Otimização de desempenho e testes abrangentes
Fase 8: Documentação e lançamento no npm

Visão: Ferramenta Universal de Pasta para MCP

Transforme qualquer pasta em uma base de conhecimento inteligente com:

Análise multi-formato: PDF, Word, Excel, PowerPoint com preservação de estrutura
Embeddings semânticos: Modelo Nomic Embed para compreensão inteligente de conteúdo
Busca vetorial: Busca de similaridade com FAISS para recuperação sensível ao contexto
Divisão inteligente: Segmentação de conteúdo baseada em significado
Atualizações em tempo real: Monitoramento de arquivos com reindexação automática
Capacidades RAG: Permite que LLMs consultem o conteúdo da pasta de forma inteligente

Contribuindo

Faça um fork do repositório
Crie um branch de recurso (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

Construído com o SDK do Model Context Protocol
Usa TypeScript para segurança de tipos e experiência do desenvolvedor
Projetado para acesso seguro e eficiente ao sistema de arquivos
Compatível com Claude Desktop e outros clientes MCP

Habilite seu LLM a trabalhar com pastas locais por meio do Model Context Protocol! 🚀

Folder MCP

Documentação

folder-mcp (Em desenvolvimento, será lançado em breve)

Visão Geral

Recursos

Instalação

Configuração

Modelos de Embedding

Estrutura de Configuração

Status Atual

Uso

Como um Servidor MCP

Ferramentas Disponíveis

1. read_file

2. search_files

3. list_files

4. get_folder_info

Recursos de Segurança

Arquitetura

Implementação do Servidor MCP

Padrão de Acesso a Arquivos

Componentes do Servidor

Detalhes Técnicos

Dependências

Padrões de Arquivo

Diretórios Excluídos

Desenvolvimento

Compilando o Projeto

Executando o Servidor

Modo de Desenvolvimento

Testando com Clientes MCP

Melhorias Futuras

Recursos Planejados (17 tarefas restantes):

Visão: Ferramenta Universal de Pasta para MCP

Contribuindo

Licença

Agradecimentos

1. `read_file`

2. `search_files`

3. `list_files`

4. `get_folder_info`