java-lsp-mcp

java-lsp-mcp

Inteligência semântica Java para clientes do Model Context Protocol (MCP), alimentada pelo Eclipse JDT Language Server e ECJ.

java-lsp-mcp oferece a agentes de codificação navegação semântica, diagnósticos, compilação, testes e prévias de refatoração. Ele nunca edita arquivos de origem: as alterações são retornadas como edições vinculadas a hash e diffs opcionais para o cliente aplicar.

Recursos

• Navegação em workspace e dependências
• Projetos Maven, Gradle, Eclipse, modulares e não gerenciados
• Diagnósticos do snapshot atual e compilação ECJ
• Testes JUnit em paralelo, execuções de teste JDWP suspensas, descoberta de testes afetados e cobertura JaCoCo
• Correções somente leitura, refatorações, importação e prévias de formatação
• Resultados limitados, paginados e amigáveis a agentes

Pré-requisitos

• Node.js 24+ — o servidor roda no seu Node; os lançadores de release usam node do PATH.
• Um JDK — apontado por JAVA_HOME ou --tooling-jdk. Ele executa o JDT LS e seus testes.
• Um workspace Java — Maven, Gradle, Eclipse, modular ou não gerenciado.

Os arquivos de release incluem JDT LS, JUnit e JaCoCo. Todo o resto vem dos pré-requisitos acima.

Instalação

Baixe o arquivo para sua plataforma na página de releases, descompacte-o e execute:

java-lsp-mcp/bin/java-lsp-mcp serve --workspace /absolute/path/to/project --trust-workspace

No Windows, use bin\java-lsp-mcp.cmd. Depois verifique com java-lsp-mcp doctor --workspace /project.

Para usar no VS Code, adicione o lançador a .vscode/mcp.json no seu projeto, ou, apenas para o seu usuário, salve-o em ~/.copilot/mcp-config.json

{
  "servers": {
    "java-lsp-mcp": {
      "command": "/absolute/path/to/java-lsp-mcp/bin/java-lsp-mcp",
      "args": ["serve", "--workspace", "/absolute/path/to/project", "--trust-workspace"]
    }
  }
}

java-lsp-mcp print-config generic --workspace /project --trust-workspace imprime o trecho equivalente para outros clientes.

Configuração

Flags para serve (um arquivo java-lsp-mcp.json ou java-lsp-mcp.toml no workspace e variáveis de ambiente JAVA_LSP_MCP_* também funcionam; flags têm prioridade, depois env, depois o arquivo):

Flag	O que faz
--workspace	O projeto no qual trabalhar (caminho absoluto, obrigatório).
--trust-workspace	Permite importação Maven/Gradle, compilação e execução de testes. Sem isso, o servidor apenas lê código — revise o projeto primeiro.
--tooling-jdk	JDK que executa o JDT LS (padrão: JAVA_HOME).
--project-jdk	JDK que executa seus testes (padrão: o JDK de ferramentas).
--offline	Nunca toque na rede; Maven/Gradle resolvem apenas a partir de caches.
--exclude-project	Deixa um módulo fora da importação, compilação e testes (repetível).
--test-classpath-entry	Diretório ou jar extra no classpath de runtime de testes (repetível).
--source-encoding	Substitui as configurações de recursos do Eclipse e a decodificação automática de fontes UTF-8/Windows-1252.
--timeout, --result-budget	Timeout compartilhado de operação em ms e orçamento de saída por resultado em bytes.
--log-level, --max-heap, --result-mode	Ajustes operacionais; todos os logs vão para stderr, nunca stdout.

As leituras de fonte respeitam --source-encoding primeiro e depois as configurações de codificação de recursos do Eclipse. Sem nenhum dos dois, UTF-8 válido é preservado e outros arquivos de fonte são lidos como Windows-1252, com um aviso SOURCE_ENCODING_FALLBACK no stderr. Arquivos de fonte nunca são convertidos ou modificados. Defina a codificação explicitamente para outras codificações legadas; codificações explícitas inválidas ou não suportadas ainda relatam erros.

Outros comandos: doctor verifica a configuração, version imprime versões, describe-tools imprime os esquemas completos de ferramentas legíveis por máquina, print-config gera configuração de cliente e clear-cache limpa o índice do workspace.

Se o Eclipse não conseguir restaurar metadados de workspace em cache porque um recurso gerado desapareceu, o servidor detecta a falha de recuperação, reconstrói seu cache JDT uma vez e tenta a inicialização novamente.

Ferramentas

As ferramentas baseadas em fonte suportam o fallback de codificação acima. Alvos de símbolo aceitam qualifiedName ou path mais um line obrigatório baseado em um. Omita column para selecionar a declaração mais interna que envolve essa linha; forneça um column de ponto de código Unicode baseado em um para uma posição exata. Colunas além da linha são limitadas ao seu final.

Ferramenta	Propósito
java_status	Status de prontidão e runtime
java_outline	Declarações de fonte
java_search_symbols	Símbolos em lote de workspace/dependências com paginação em cache; omita line para todas as correspondências, passe line para manter apenas a declaração mais próxima
java_find_definition	Declarações de símbolos em lote; alvo por nome qualificado ou caminho de arquivo + linha de fonte
java_find_references	Usos semânticos com paginação em cache; alvo por nome qualificado ou caminho de arquivo + linha de fonte
java_call_hierarchy	Chamadores e chamados; chamadores de entrada usam escopo de produção por padrão
java_type_hierarchy	Super tipos, subtipos, implementações
java_diagnostics	Diagnósticos do snapshot atual; falha rápido com JDT_BUSY quando o JDT está ocupado e os diagnósticos estão desatualizados
java_compile	Compilação ECJ com diagnósticos, recuperação de pré-requisitos e uma nova tentativa limpa quando nenhum erro de sintaxe é confirmado
java_update_projects	Re-sincronização de configuração Maven/Gradle no JDT (force para reimportação completa)
java_run_tests	Execução JUnit após compilação/recuperação incremental automática; falhas de compilação persistentes incluem diagnósticos; debug: true inicia JDWP suspenso
java_find_affected_tests	Testes conectados estaticamente
java_find_unused_code	Membros privados não utilizados candidatos
java_code_actions	Correções e refatorações disponíveis
java_edit_preview	Prévia de renomear, ação, importação, formatação
java_debug_targets	Descobrir JVMs locais iniciadas com o agente JDWP
java_debug_attach, java_debug_sessions, java_debug_detach	Ciclo de vida da sessão de depuração JDWP
java_debug_set_breakpoints, java_debug_wait_for_stop	Substituir pontos de interrupção de fonte (caminhos com barra/barra invertida identificam o mesmo arquivo) e esperas limitadas por eventos de parada
java_debug_threads, java_debug_stack_trace, java_debug_variables	Inspeção filtrada de thread/stack, locais, coleções e objetos em runtime
java_debug_execute	Continuar e avançar passo sobre, entrar ou sair
java_debug_hot_swap	Substituição de código quente ECJ/JDI com relatório de alterações e frames ativos

java_search_symbols e java_find_definition exigem um array queries de 1–20 objetos de parâmetro. Agrupe consultas relacionadas para reunir contexto em uma chamada. Cada entrada tem suas próprias opções, padrões, limite e cursor. A resposta contém results na ordem de entrada; entradas com falha contêm error com code, message e details opcional, enquanto outras entradas ainda são concluídas. Parâmetros de consulta única de nível superior são rejeitados.

{"queries":[{"query":"OrderService"},{"query":"Customer","scope":"all"}]}

{"queries":[{"target":{"qualifiedName":"com.example.OrderService"},"expand":["body"]},{"target":{"path":"src/Customer.java","line":12}}]}

Pesquisa de símbolos e consultas de referência mantêm snapshots de resultados independentes quando outra página está disponível. Páginas subsequentes reutilizam as correspondências coletadas e a classificação de uso de referências; uma nova solicitação sem cursor realiza uma nova consulta. O cache compartilhado expira entradas dois minutos após a criação e usa evicção LRU com limites de 32 conjuntos de resultados e 16 MiB de resultados serializados. O acesso não estende a expiração. Alterações no workspace e reconexões do JDT invalidam continuações em cache. Um snapshot expirado ou evictado retorna STALE_RESULT_SET; reinicie sem cursor. Resultados que excedem o limite de bytes do cache ignoram o cache e mantêm paginação normal.

A verificação de fonte lê, decodifica e aplica hash a cada arquivo Java uma vez por verificação, reutilizando o snapshot sincronizado. A verificação inalterada ainda oferece o documento ao JDT (incluindo tentar novamente uma sincronização inicial com falha) e evita notificações desnecessárias de alteração de arquivo observado.

A compilação tenta novamente uma compilação incremental sem sucesso uma vez como uma compilação limpa quando os diagnósticos atuais não contêm códigos de erro de sintaxe JDT confirmados. Erros de sintaxe são verificados antes da filtragem de severidade ou paginação. Ambas as tentativas compartilham o timeout de compilação e preservam exclusões de projeto e escopo compileProjectOnly, incluindo pré-requisitos carregados. Compilações limpas explícitas, cancelamento, status desconhecidos e falhas de solicitação/configuração não acionam uma nova tentativa. java_compile.buildAttempts registra os tipos de compilação tentados e status; seus diagnósticos descrevem o resultado final.

java_run_tests compila incrementalmente por padrão e usa a mesma política de recuperação antes de iniciar testes. Compilações bem-sucedidas são reutilizadas até que a geração do workspace mude; compile: "none" ainda pula a compilação e compile: "clean" solicita uma compilação limpa diretamente. Resultados normais de teste incluem buildAttempts (vazio quando uma compilação foi reutilizada). Falhas de compilação persistentes retornam status: "compile-failed" e um objeto compilation com status de compilação, tentativas, contagens de diagnóstico, locais/mensagens, total e diagnosticsTruncated para a amostra de diagnóstico limitada. Contagens de teste e falhas de teste permanecem separadas dos diagnósticos do compilador. Execuções de depuração usam a mesma política de compilação; compilações com falha retornam detalhes do compilador no erro da ferramenta.

Execute java-lsp-mcp describe-tools para os esquemas completos de ferramentas legíveis por máquina.

Contribuindo

Contribuições são bem-vindas. Veja CONTRIBUTING.md.

Compile a partir do código-fonte com:

npm ci
npm run fetch-runtime
npm run check
bin/java-lsp-mcp serve --workspace /absolute/path/to/project --trust-workspace

Segurança

Revise SECURITY.md antes de conceder confiança ao workspace. Relate vulnerabilidades em particular.

Licença

MIT. Veja LICENSE.