Construa um MCP Server que lê, resume e organiza arquivos locais — um assistente pessoal de organização.
O Assistente de Arquivos é um projeto que combina o poder do MCP com operações do sistema de arquivos. Vamos criar 4 tools que permitem ao Claude interagir com arquivos e pastas locais: ler conteúdo, buscar texto, gerar estatísticas e organizar arquivos automaticamente. Tudo usando os módulos pathlib e os da biblioteca padrão do Python.
As 4 tools do Assistente de Arquivos: ler_arquivo(caminho) — lê o conteúdo de um arquivo de texto e retorna com metadados (tamanho, data de modificação); buscar_em_arquivos(pasta, texto) — busca uma string em todos os arquivos de uma pasta recursivamente, retornando arquivo, linha e contexto; estatisticas_pasta(caminho) — conta arquivos por extensão, tamanho total, maior/menor arquivo; organizar_por_tipo(pasta) — move arquivos para subpastas organizadas por extensão (.pdf para PDFs/, .jpg para Imagens/, etc.). Todas usam pathlib.Path para manipulação segura de caminhos.
Use pathlib.Path em vez de os.path para todas as operações com caminhos. O pathlib oferece uma API mais intuitiva e orientada a objetos: Path("pasta").iterdir() para listar, path.suffix para extensão, path.stat().st_size para tamanho. Além disso, funciona corretamente em Windows, Linux e macOS sem ajustes manuais de barras.
A tool ler_arquivo é a mais básica e mais poderosa do nosso assistente. Ela lê o conteúdo de um arquivo de texto e retorna junto com metadados úteis como tamanho e data de modificação. O mais interessante é que o Claude naturalmente resume o conteúdo ao apresentá-lo ao usuário — você não precisa implementar lógica de resumo, o modelo faz isso sozinho.
A tool ler_arquivo(caminho: str) usa Path(caminho) para abrir o arquivo, lê o conteúdo com path.read_text(encoding="utf-8") e coleta metadados via path.stat(): tamanho em bytes/KB, data da última modificação formatada. O retorno combina os metadados e o conteúdo em uma string organizada. O Claude recebe tudo isso e pode resumir, analisar ou responder perguntas sobre o conteúdo — sem nenhum código extra de IA da sua parte.
Limite o tamanho da leitura! Se o usuário pedir para ler um arquivo de 500MB, o servidor vai tentar carregar tudo na memória e enviar como resposta da tool — isso pode travar o servidor ou estourar os limites do modelo. Defina um limite seguro (ex: 10.000 caracteres) e, se o arquivo for maior, retorne apenas o início com um aviso: "Arquivo truncado — mostrando os primeiros 10KB de 500MB."
A tool buscar_em_arquivos funciona como um "grep" inteligente: recebe uma pasta e um texto para buscar, e varre todos os arquivos recursivamente, retornando onde o texto foi encontrado com contexto. Imagine pedir ao Claude: "Busque 'TODO' em todos os arquivos do meu projeto" — essa tool torna isso possível.
A tool buscar_em_arquivos(pasta: str, texto: str) usa Path(pasta).rglob("*") para iterar recursivamente sobre todos os arquivos. Para cada arquivo de texto, lê as linhas e verifica se o texto buscado aparece (case-insensitive com .lower()). O retorno inclui: nome do arquivo, número da linha e a linha com contexto (a linha encontrada mais uma linha antes e depois). Limite o número de resultados (ex: máximo 50) para não sobrecarregar a resposta.
Use rglob("*") para busca recursiva (inclui subpastas) e filtre apenas arquivos com path.is_file(). Ignore arquivos binários verificando a extensão ou usando um try/except ao ler. Uma boa lista de extensões de texto: .txt, .py, .js, .md, .html, .css, .json, .yml, .toml, .cfg, .ini, .log. Ignorar pastas como .git, __pycache__ e node_modules acelera muito a busca.
Verificar que o caminho existe e é um diretório com Path(pasta).is_dir(). Retornar erro claro se não for.
Usar rglob("*") para percorrer arquivos, ler cada um com try/except, e verificar se o texto aparece em cada linha.
Montar string com arquivo:linha:conteúdo para cada match encontrado. Incluir contagem total: "Encontradas X ocorrências em Y arquivos."
A tool estatisticas_pasta analisa uma pasta e retorna um panorama completo: quantos arquivos existem, como estão distribuídos por extensão, qual o tamanho total, qual o maior e o menor arquivo, e quando o arquivo mais recente foi modificado. É como um "raio-X" do diretório.
A tool estatisticas_pasta(caminho: str) percorre todos os arquivos da pasta com Path(caminho).rglob("*"), coletando informações com path.stat() para cada arquivo. Ela calcula: total de arquivos, distribuição por extensão (usando um dicionário/Counter), tamanho total em bytes/KB/MB, maior e menor arquivo com seus nomes e tamanhos, e data do arquivo mais recente. O retorno é uma string formatada que o Claude apresenta como um relatório organizado.
Ferramentas de análise de diretório são surpreendentemente úteis no dia a dia. Estudos mostram que o usuário médio tem mais de 100.000 arquivos no computador e gasta cerca de 2,5 horas por semana procurando e organizando arquivos. Uma tool que fornece estatísticas rápidas permite identificar rapidamente pastas que precisam de limpeza, arquivos enormes que consomem espaço, e extensões inesperadas que podem indicar problemas.
Use collections.Counter para contar extensões de forma elegante: Counter(p.suffix.lower() for p in pasta.rglob("*") if p.is_file()). Para formatar tamanhos legíveis, crie uma função auxiliar que converte bytes para KB/MB/GB automaticamente. Ordene as extensões por contagem (mais comuns primeiro) para que o relatório mostre as informações mais relevantes no topo.
A tool mais impactante do nosso assistente: organizar_por_tipo analisa uma pasta e move cada arquivo para uma subpasta correspondente à sua extensão. Arquivos .pdf vão para uma pasta "PDFs/", .jpg e .png para "Imagens/", .py para "Python/", e assim por diante. Mas atenção: essa tool modifica o sistema de arquivos, então precisa pedir confirmação antes de agir.
A tool organizar_por_tipo(pasta: str, confirmar: bool = False) funciona em dois modos. Quando confirmar=False (padrão), ela apenas lista as mudanças planejadas: "Mover relatorio.pdf para PDFs/relatorio.pdf", "Mover foto.jpg para Imagens/foto.jpg", etc. Quando confirmar=True, ela executa as mudanças usando shutil.move(). O mapeamento de extensões para pastas usa um dicionário: {".pdf": "PDFs", ".jpg": "Imagens", ".png": "Imagens", ".py": "Python", ...}. Extensões desconhecidas vão para "Outros/".
Nunca mova arquivos automaticamente sem confirmação do usuário. O padrão da tool deve ser confirmar=False, retornando apenas a lista de mudanças planejadas. O Claude apresentará essa lista ao usuário e perguntará se deseja prosseguir. Somente quando o usuário confirmar, o Claude chamará a tool novamente com confirmar=True. Essa abordagem em dois passos previne movimentações acidentais de arquivos importantes.
Com todas as tools implementadas, vamos testar o Assistente de Arquivos em cenários reais. O objetivo é validar que o Claude consegue entender pedidos em linguagem natural, escolher a tool correta e apresentar os resultados de forma útil. Cada cenário testa uma combinação diferente de tools e capacidades.
Configure o servidor no Claude Desktop e crie uma pasta de teste com arquivos variados (textos, PDFs, imagens, código Python). Quanto mais diversa a pasta de teste, mais cenários você consegue validar. Observe como o Claude decide qual tool usar — às vezes ele combina várias em sequência, como primeiro chamar estatisticas_pasta para entender o que tem na pasta, depois ler_arquivo para inspecionar um arquivo específico.
"O que tem na minha pasta Downloads?" — O Claude deve chamar estatisticas_pasta e apresentar um resumo organizado com contagem por tipo, tamanho total, etc.
"Busque 'TODO' em todos os arquivos do meu projeto" — O Claude deve chamar buscar_em_arquivos e listar cada ocorrência com arquivo, linha e contexto.
"Leia o arquivo notas.txt e me faça um resumo" — O Claude deve chamar ler_arquivo e depois resumir o conteúdo naturalmente na resposta.
"Organize os arquivos da pasta Teste por tipo" — O Claude deve primeiro mostrar o plano (confirmar=False), perguntar e só depois executar (confirmar=True).
Crie uma pasta de teste dedicada com arquivos de exemplo antes de testar — nunca teste diretamente em pastas importantes. Use mkdir pasta_teste && touch pasta_teste/doc.pdf pasta_teste/foto.jpg pasta_teste/notas.txt pasta_teste/script.py para criar rapidamente uma estrutura de teste. Isso permite testar todas as tools sem risco de afetar arquivos reais, especialmente a tool de organização que move arquivos.
Próximo Módulo: 4.4 — Integração com API REST