Java Filesystem & Web MCP Server

Um servidor MCP para agentes LLM realizarem operações no sistema de arquivos e acessarem recursos web.

GitHub
25
Experimente este MCPPatrocinado

Documentação

Java Filesystem & Web MCP Server

Este projeto implementa um servidor Model Context Protocol (MCP) que fornece operações de sistema de arquivos e ferramentas de acesso à web para agentes de Large Language Model (LLM). Ele permite que assistentes de IA interajam tanto com o sistema de arquivos local quanto com recursos web através de um conjunto de operações bem definidas.

Recursos

O servidor fornece as seguintes operações:

Operações de Sistema de Arquivos

  • Leitura de Arquivos: Ler o conteúdo completo de um arquivo com detecção adequada de codificação
  • Escrita de Arquivos: Criar ou sobrescrever arquivos com novo conteúdo
  • Edição de Arquivos: Fazer edições baseadas em linhas com geração de diff no estilo git
  • Busca de Arquivos: Buscar recursivamente por arquivos e diretórios usando padrões glob
  • Listagem de Diretórios: Obter listagens detalhadas do conteúdo de diretórios
  • Criação de Diretórios: Criar diretórios e estruturas de diretórios aninhados
  • Grep em Arquivos: Buscar padrões de texto dentro de arquivos com números de linha e contexto, semelhante ao comando grep do Unix
  • Comando Bash: Executar comandos bash no shell do sistema e capturar sua saída

Operações Web

  • Busca de Páginas Web: Recuperar conteúdo de páginas web com timeouts configuráveis
  • Extração de Conteúdo HTML: Extrair conteúdo de texto de documentos HTML

Essas operações são expostas como ferramentas para Large Language Models usando o Model Context Protocol (MCP), permitindo que sistemas de IA interajam com segurança com o sistema de arquivos e acessem recursos web.

Exemplo da ferramenta MCP Java com DevoxxGenie

Screenshot 2025-03-26 at 09 52 26

Começando

Pré-requisitos

  • Java 17 ou superior
  • Maven 3.6+
  • Spring Boot 3.3.6
  • Componentes Spring AI MCP Server

Compilando o Projeto

Compile o projeto usando Maven:

mvn clean package

Executando o Servidor

O servidor suporta dois modos de transporte:

Modo SSE (baseado em HTTP, padrão)

Execute o servidor para comunicação baseada em SSE:

java -jar target/devoxx-filesystem-0.0.1-SNAPSHOT.jar

Isso inicia um servidor HTTP na porta 8081 com o endpoint SSE em /sse.

Modo STDIO (para clientes MCP como Claude Desktop ou DevoxxGenie)

Para comunicação baseada em STDIO (exigida pela maioria dos clientes MCP):

java -Dspring.ai.mcp.server.stdio=true \
     -Dspring.main.web-application-type=none \
     -Dspring.main.banner-mode=off \
     -Dlogging.pattern.console= \
     -jar target/devoxx-filesystem-0.0.1-SNAPSHOT.jar

Flags importantes para o modo STDIO:

  • -Dspring.ai.mcp.server.stdio=true - Habilita o transporte STDIO
  • -Dspring.main.web-application-type=none - Desativa o servidor web
  • -Dspring.main.banner-mode=off - Desativa o banner do Spring Boot (necessário para evitar corromper a comunicação JSON-RPC)
  • -Dlogging.pattern.console= - Desativa o log do console

Serviços de Ferramentas

Ferramentas de Sistema de Arquivos

ReadFileService

readFile(String fullPathFile)

Lê o conteúdo completo de um arquivo do sistema de arquivos. Lida com várias codificações de texto e fornece mensagens de erro detalhadas se o arquivo não puder ser lido.

WriteFileService

writeFile(String path, String content)

Cria um novo arquivo ou sobrescreve completamente um arquivo existente com novo conteúdo. Cria diretórios pai se eles não existirem.

EditFileService

editFile(String path, String edits, Boolean dryRun)

Faz edições baseadas em linhas em um arquivo de texto. Cada edição substitui sequências exatas de linhas por novo conteúdo. Retorna um diff no estilo git mostrando as alterações feitas. O parâmetro dryRun permite visualizar alterações sem aplicá-las.

SearchFilesService

searchFiles(String path, String pattern)

Busca recursivamente por arquivos e diretórios que correspondem a um padrão. Pesquisa em todos os subdiretórios a partir do caminho inicial. A busca não diferencia maiúsculas de minúsculas e corresponde a nomes parciais.

ListDirectoryService

listDirectory(String path)

Obtém uma listagem detalhada de todos os arquivos e diretórios em um caminho especificado. Os resultados distinguem claramente entre arquivos e diretórios com metadados adicionais.

GrepFilesService

grepFiles(String directory, String pattern, String fileExtension, Boolean useRegex, Integer contextLines, Integer maxResults, Boolean ignoreCase)

Busca padrões de texto dentro de arquivos. Retorna arquivos correspondentes com números de linha e contexto. Semelhante ao comando 'grep' do Unix, mas com recursos adicionais para exibição de contexto. Suporta padrões regex, busca sem diferenciar maiúsculas de minúsculas e linhas de contexto antes/depois das correspondências.

CreateDirectoryService

createDirectory(List<String> directories)

Cria novos diretórios ou garante que diretórios existam. Pode criar vários diretórios em uma única operação. Se um diretório já existir, a operação é concluída silenciosamente. Perfeito para configurar estruturas de diretórios para projetos ou garantir que caminhos necessários existam.

BashService

executeBash(String command, String workingDirectory, Integer timeoutSeconds)

Executa um comando Bash no shell do sistema e retorna a saída. Esta ferramenta permite executar comandos do sistema e capturar seus fluxos de saída padrão e de erro. Use com cautela, pois alguns comandos podem ter efeitos em todo o sistema.

Ferramentas Web

FetchWebpageService

fetchWebpage(String url, Integer timeoutMs)

Busca ou lê uma página web a partir de uma URL e retorna seu conteúdo. O serviço usa jsoup para conectar à página web e recuperar seu conteúdo. O parâmetro opcional timeoutMs permite definir um timeout de conexão personalizado.

Testes

Executando Testes Unitários

Um conjunto abrangente de testes unitários é fornecido para todas as classes de serviço. Execute-os usando:

mvn test

Os testes usam JUnit 5 e Mockito para simular dependências externas, como a biblioteca jsoup para requisições web.

Executando Testes de Integração

Os testes de integração verificam o transporte STDIO iniciando o servidor como um subprocesso. Primeiro compile o JAR e depois execute os testes de integração:

mvn package -DskipTests
mvn test -Pintegration-tests

Clientes de Teste

Clientes de teste são fornecidos para demonstrar o uso do protocolo MCP:

  • ClientStdio.java - Demonstra comunicação por transporte STDIO
  • ClientSse.java - Demonstra comunicação por transporte SSE

Configuração

A aplicação é configurada via application.properties:

spring.main.web-application-type=none
spring.main.banner-mode=off
logging.pattern.console=

spring.ai.mcp.server.name=filesystem-server
spring.ai.mcp.server.version=0.0.1

logging.file.name=,/JavaFileSystemMCP/target/filesystem-server.log

Estrutura do Projeto

JavaFileSystemMCP/
  src/
    main/
      java/
        com/
          devoxx/
            mcp/
              filesystem/
                tools/
                  EditFileService.java
                  ReadFileService.java
                  WriteFileService.java
                  SearchFilesService.java
                  FetchWebpageService.java
                  ListDirectoryService.java
                  CreateDirectoryService.java
                  GrepFilesService.java
                  BashService.java
                McpServerApplication.java
      resources/
        application.properties
    test/
      java/
        com/
          devoxx/
            mcp/
              filesystem/
                tools/
                  ReadFileServiceTest.java
                  WriteFileServiceTest.java
                  EditFileServiceTest.java
                  SearchFilesServiceTest.java
                  FetchWebpageServiceTest.java
                  ListDirectoryServiceTest.java
                  CreateDirectoryServiceTest.java
                  GrepFilesServiceTest.java
                ClientStdio.java
  pom.xml
  README.md

Dependências

O projeto usa:

  • Spring Boot 3.3.6
  • Componentes Spring AI MCP Server
  • Jackson para processamento JSON
  • jsoup para análise de HTML e recuperação de conteúdo web
  • JUnit 5 e Mockito para testes

Notas de Implementação

  • O servidor é projetado para operar usando o mecanismo de transporte STDIO
  • O modo banner e o log do console são desativados para permitir que o transporte STDIO funcione corretamente
  • O tratamento de erros fornece informações detalhadas sobre problemas encontrados durante as operações
  • Cada serviço de ferramenta inclui tratamento abrangente de erros e retorna resultados em um formato JSON padronizado
  • O EditFileService inclui geração sofisticada de diff para rastreamento de alterações
  • O SearchFilesService suporta padrões glob para correspondência flexível de arquivos
  • O FetchWebpageService inclui timeouts configuráveis e tratamento robusto de erros para requisições web

Integração com o Suporte MCP do DevoxxGenie

Este servidor pode ser facilmente integrado ao DevoxxGenie usando o suporte MCP (Model Context Protocol). Veja como configurá-lo:

Configuração no DevoxxGenie

  1. No DevoxxGenie, acesse a tela de configuração do servidor MCP
  2. Configure o servidor com as seguintes definições:

    • Nome: JavaFilesystem (ou qualquer nome descritivo)

    • Tipo de Transporte: STDIO

    • Comando: Caminho completo para o seu executável Java (por exemplo, /Library/Java/JavaVirtualMachines/liberica-jdk-23.jdk/Contents/Home/bin/java)

    • Argumentos:

      -Dspring.ai.mcp.server.stdio=true
-Dspring.main.web-application-type=none
-Dspring.main.banner-mode=off
-Dlogging.pattern.console=
-jar
~/JavaFileSystemMCP/target/devoxx-filesystem-0.0.1-SNAPSHOT.jar

      Insira cada argumento em uma nova linha. Talvez seja necessário alterar o caminho para -jar apontando para onde você compilou o jar.

      Importante: A flag -Dspring.main.banner-mode=off é necessária para desativar o banner do Spring Boot, que de outra forma interferiria na comunicação JSON-RPC via STDIO.

Uso com DevoxxGenie

Uma vez configurado, o DevoxxGenie descobrirá automaticamente as ferramentas fornecidas por este servidor MCP. O assistente de IA pode então usar essas ferramentas para:

  1. Ler e escrever arquivos no sistema local
  2. Buscar por arquivos e diretórios
  3. Listar o conteúdo de diretórios
  4. Fazer edições em arquivos existentes
  5. Buscar padrões de texto dentro de arquivos (grep)
  6. Criar diretórios e estruturas de diretórios aninhados
  7. Executar comandos bash no shell do sistema
  8. Buscar páginas web e extrair conteúdo

Todas as operações serão realizadas com as permissões do usuário que executa o aplicativo DevoxxGenie.

Uso com Claude Desktop

Edite seu arquivo claude_desktop_config.json com o seguinte:

{
  "mcpServers": {
    "filesystem": {
      "command": "/Library/Java/JavaVirtualMachines/liberica-jdk-23.jdk/Contents/Home/bin/java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dspring.main.banner-mode=off",
        "-Dlogging.pattern.console=",
        "-jar",
        "~/JavaFileSystemMCP/target/devoxx-filesystem-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Talvez seja necessário alterar o caminho para -jar apontando para onde você compilou o jar.

Importante: A flag -Dspring.main.banner-mode=off é necessária para desativar o banner do Spring Boot, que de outra forma interferiria na comunicação JSON-RPC via STDIO.

image

Considerações de Segurança

Ao usar este servidor, esteja ciente de que:

  • O agente LLM terá acesso para ler e escrever arquivos no sistema host
  • O agente pode executar comandos bash com as permissões do usuário que executa o aplicativo
  • O agente pode buscar conteúdo de qualquer URL web acessível
  • Considere executar o servidor com permissões apropriadas e em um ambiente controlado
  • O servidor não implementa mecanismos de autenticação ou autorização
  • Considere regras de firewall de rede se a restrição de acesso web for necessária