Java MCP Filesystem Server

Um servidor MCP baseado em Java e seguro que fornece acesso controlado ao sistema de arquivos para assistentes de IA.

GitHub
1
Experimente este MCPPatrocinado

Documentação

Java MCP Filesystem Server

Uma implementação de servidor Model Context Protocol (MCP) em Java que fornece acesso ao sistema de arquivos para assistentes de IA. Este projeto multi-módulo oferece três mecanismos de transporte diferentes (stdio, HTTP, SSE), todos compartilhando lógica de negócios comum para operações de arquivos.

Recursos

Múltiplas Opções de Transporte

  • stdio: Aplicação autônoma para integração com linha de comando (Claude Desktop, etc.)
  • HTTP: Implementação baseada em servlet para comunicação HTTP
  • SSE: Servlet de Server-Sent Events para streaming em tempo real

Operações Abrangentes de Arquivos

O servidor expõe 10 ferramentas MCP para manipulação do sistema de arquivos:

  • read_file: Lê o conteúdo completo de um único arquivo
  • read_multiple_files: Lê eficientemente vários arquivos em uma única operação
  • write_file: Cria novos arquivos ou sobrescreve os existentes
  • edit_file: Faz edições baseadas em linhas com suporte à pré-visualização de diff
  • create_directory: Cria estruturas de diretórios simples ou aninhadas
  • list_directory: Lista o conteúdo de um diretório com indicadores de tipo
  • directory_tree: Obtém uma visão em árvore JSON recursiva dos diretórios
  • move_file: Move ou renomeia arquivos e diretórios
  • search_files: Busca recursivamente por arquivos que correspondem a padrões glob
  • get_file_info: Recupera metadados detalhados de arquivos (tamanho, timestamps, permissões)

Requisitos

  • Java 25
  • Gradle 9.x (para compilar a partir do código-fonte)
  • Contêiner de servlet (Tomcat, Jetty, etc.) para os módulos HTTP/SSE
  • GraalVM (opcional, para compilação de imagem nativa)

Compilando a partir do Código-Fonte

  1. Clone o repositório:
git clone <repository-url>
cd mcp-server-filesystem
  1. Compile todos os módulos:
./gradlew clean build

Isso cria os seguintes artefatos:

  • stdio: stdio/build/libs/stdio-1.0.0.jar - JAR de aplicação autônoma
  • http: http/build/libs/http-1.0.0.war - Arquivo WAR de servlet HTTP
  • sse: sse/build/libs/sse-1.0.0.war - Arquivo WAR de servlet SSE
  • tools: tools/build/libs/tools-1.0.0.jar - JAR de biblioteca compartilhada
  1. Compile módulos individuais:
./gradlew :stdio:build
./gradlew :http:build
./gradlew :sse:build
  1. Compile executável nativo (opcional, requer GraalVM):
./gradlew :stdio:nativeCompile

O executável nativo será criado em stdio/build/native/nativeCompile/mcp-server-filesystem e oferece tempos de inicialização mais rápidos e menor uso de memória.

Uso

Opção 1: Transporte stdio (Autônomo)

O transporte stdio usa stdin/stdout para comunicação.

java -jar stdio/build/libs/stdio-1.0.0.jar

Ou execute o executável nativo (se compilado com GraalVM):

./stdio/build/native/nativeCompile/mcp-server-filesystem

Configurando com o Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/stdio-1.0.0.jar"
      ]
    }
  }
}

Opção 2: Transporte HTTP (Servlet)

  1. Implante o arquivo WAR no seu contêiner de servlet:
cp http/build/libs/http-1.0.0.war $TOMCAT_HOME/webapps/
  1. O endpoint HTTP estará disponível em:
http://localhost:8080/v1/mcp
  1. Configure o tomcat server.xml
<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
    <Context path="/v1" docBase="http-1.0.0.war" reloadable="true" />
</Host>

Opção 3: Transporte SSE (Servlet)

  1. Implante o arquivo WAR no seu contêiner de servlet:
cp sse/build/libs/sse-1.0.0.war $TOMCAT_HOME/webapps/
  1. Os endpoints SSE estarão disponíveis em:
SSE endpoint: http://localhost:8080/v2/sse
Messages endpoint: http://localhost:8080/v2/messages
  1. Configure o tomcat server.xml
<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
    <Context path="/v2" docBase="sse-1.0.0.war" reloadable="true" />
</Host>

Comandos de Desenvolvimento

# Run all tests
./gradlew test

# Run tests for tools module
./gradlew :tools:test

# Build without tests
./gradlew build -x test

# Generate test coverage report
./gradlew :tools:test jacocoTestReport

Dependências Principais

  • io.modelcontextprotocol.sdk:mcp:0.15.0 - SDK MCP para Java
  • jakarta.servlet:jakarta.servlet-api:6.1.0 - API de Servlet
  • io.github.java-diff-utils:java-diff-utils:4.12 - Geração de diff para operações de edição
  • com.fasterxml.jackson.core:jackson-databind:2.19.1 - Processamento de JSON
  • Spock Framework 2.4-M6-groovy-4.0 - Testes

Considerações de Segurança

IMPORTANTE: Esta implementação não possui validação de caminho nem restrições de diretório. Todas as operações do sistema de arquivos são irrestritas e limitadas apenas pelas permissões do usuário que executa o servidor.

  1. Sem Restrições de Caminho: As operações de arquivos podem acessar qualquer caminho para o qual o usuário tenha permissões
  2. Permissões do Usuário: O servidor executa com as mesmas permissões do usuário que o inicia
  3. Uso em Produção: Considere implementar validação de caminho antes de implantar em ambientes de produção

Nota: As descrições do esquema das ferramentas referenciam "diretórios permitidos", mas esse recurso não existe na implementação atual.

Exemplos de Ferramentas

Lendo um Arquivo

{
  "tool": "read_file",
  "parameters": {
    "path": "/Users/myuser/documents/example.txt"
  }
}

Editando um Arquivo com Pré-visualização

{
  "tool": "edit_file",
  "parameters": {
    "path": "/Users/myuser/documents/example.txt",
    "edits": [
      {
        "oldText": "Hello World",
        "newText": "Hello MCP"
      }
    ],
    "dryRun": true
  }
}

Buscando Arquivos

{
  "tool": "search_files",
  "parameters": {
    "path": "/Users/myuser/projects",
    "pattern": "*.java",
    "excludePatterns": ["**/build/**", "**/target/**"]
  }
}

Solução de Problemas

Problemas Comuns

  1. O servidor não inicia: Verifique se o Java 25 está instalado e no seu PATH
  2. A implantação do WAR falha: Certifique-se de que seu contêiner de servlet suporta Jakarta Servlet API 6.1 3Erros de permissão: O servidor só pode acessar arquivos para os quais o usuário em execução tenha permissões

Depuração

Verifique os logs da aplicação (stdout/stderr para stdio, logs do contêiner para HTTP/SSE) para mensagens de erro.

Histórico de Versões

  • 1.0.0 - Arquitetura multi-módulo com transportes stdio, HTTP e SSE
  • 0.7.2 - Versão anterior com implementação de módulo único

Contribuindo

Contribuições são bem-vindas! Por favor, garanta:

  1. O código segue as convenções de nomenclatura do Java
  2. Novas ferramentas são adicionadas ao módulo compartilhado tools
  3. Os esquemas das ferramentas são definidos adequadamente em ToolSchemas.java
  4. As alterações são testadas com um cliente MCP
  5. Os testes são escritos usando o Spock Framework no módulo tools

Licença

[Especifique sua licença aqui]

Autor

Bruno Rozendo

Agradecimentos