MCP Java Dev Tools

Ponte entre ferramentas de codificação agentivas e o comportamento em tempo real do Java Runtime por meio de um agente sidecar leve.

GitHub

Experimente este MCPPatrocinado

Documentação

mcp-java-dev-tools

MCP Java Dev Tools conecta ferramentas de codificação agênticas ao comportamento dinâmico do runtime Java por meio de um agente auxiliar leve.

A análise estática só leva você até certo ponto. Ao anexar diretamente a uma JVM em execução, esta ferramenta revela sinais de runtime no nível de bytecode que a análise estática sozinha não consegue ver — permitindo inspeção verificada por sondas, verificações de regressão direcionadas, validação de caminhos de runtime e fluxos de depuração determinísticos.

O agente de runtime é construído com ByteBuddy e trabalha junto com o JDWP, em vez de substituí-lo. Acima da camada de sonda, o sistema adiciona síntese de dados ciente de frameworks e contratos de ferramentas estritos com falha fechada — para que orquestradores de agentes possam tomar decisões baseadas em provas reais de runtime, não em inferências.

O foco atual são entrypoints HTTP. O suporte a protocolos não-HTTP está no horizonte, mas ainda não foi implementado — serão necessários modelos concretos e alvos de validação antes que os contratos principais possam ser generalizados.

Para fluxos de trabalho de operadores e fluxos de execução de ponta a ponta, consulte docs/how-it-works/README.md.

Requisitos

Requisito	Versão
Node.js	`v24.13.0` (testado)
npm	`11.6.2` (testado)
JDK	`21+`
Maven	`3.8.6+`

Build

npm.cmd install
npm.cmd run build
mvn -f java-agent\pom.xml package

Isso produz dois artefatos:

Servidor MCP → dist/server.js
Pacote do agente Java → java-agent/core/core-probe/target/mcp-java-dev-tools-agent-0.1.0-all.jar

O auxiliar de ciclo de vida Java 21 é empacotado separadamente em java-agent/core/core-jvm-attach/target/mcp-java-dev-tools-core-jvm-attach-0.1.8.jar.

Fundação opcional do servidor MCP Java

mcp-server/ é um servidor MCP opcional em Java 21, Spring Boot e Spring AI MCP para o caminho de migração v0.1.9. Ele expõe as ferramentas MCP migradas de Probe e ciclo de vida da JVM; o servidor MCP TypeScript existente em dist/server.js permanece como padrão de produção.

Compile e verifique a fundação de forma independente:

bash ./scripts/package-java-mcp-server.sh
# Windows PowerShell: .\scripts\package-java-mcp-server.ps1

O JAR executável é mcp-server/application/target/mcp-java-dev-tools-server-0.1.9.jar. Seu diretório adjacente sidecar/ contém os artefatos auxiliares e de agente empacotados; ele usa apenas STDIO, reservando stdout para MCP JSON-RPC e enviando diagnósticos para stderr. Consulte mcp-server/README.md para conhecer os limites do módulo e o escopo de migração adiado.

Instalação

Instalador

O fluxo do instalador é dividido em scripts de instalação e atualização (habilidades Codex e Kiro).

./scripts/install.sh

Isso instala o conjunto padrão de habilidades:

mcp-java-dev-tools-line-probe-run
mcp-java-dev-tools-regression-suite
mcp-java-dev-tools-regression-plan-crafter
mcp-java-dev-tools-regression-result
mcp-java-dev-tools-issue-report
mcp-java-dev-tools-bug-drill
mcp-java-dev-tools-bug-fix
mcp-java-dev-tools-failure-lens
mcp-java-dev-tools-probe-registry-manager

Para atualizar/substituir habilidades instaladas existentes (e adicionar novas habilidades ausentes):

./scripts/update.sh

Ambos os scripts:

executam npm run build:compile
executam mvn -f java-agent/pom.xml package
sincronizam as habilidades fornecidas no diretório de habilidades do cliente de destino
por padrão, solicitam um primeiro workspace e geram a saída do bloco de configuração de env do MCP (específica do cliente)

Comportamento do Kiro e do Claude Code durante instalação/atualização:

habilidades gerenciadas obsoletas que correspondem a mcp-java-dev-tools-* são detectadas e podem ser excluídas interativamente
habilidades gerenciadas instaladas são validadas após a sincronização (SKILL.md + presença esperada da pasta)
orientações de reinício/recarregamento são exibidas para que a lista visível de ferramentas/habilidades seja atualizada a partir do diretório de habilidades sincronizado

A entrada de env padrão do registro MCP pode ser ignorada:

./scripts/install.sh --client codex --no-configure-mcp-env
# Or: ./scripts/install.sh --client claude --no-configure-mcp-env

A entrada de env do MCP captura:

MCP_JAVA_AGENT_JAR (obrigatório; caminho absoluto para o jar do agente Java compilado)

Launcher de Integração Spring

Use o launcher auxiliar para executar um aplicativo Spring com escopo de inclusão do agente Java e porta de sonda inferidos automaticamente:

./spring-integration/run-spring-app-with-mcp.sh

Comportamento:

solicita o caminho absoluto do projeto Spring, a porta do aplicativo (padrão 8080) e a porta JDWP opcional
infere o pacote de inclusão a partir de src/main/java
atribui a porta da sonda começando em 9173 e incrementa se estiver ocupada
abre uma nova janela do Git Bash e inicia o aplicativo Spring com JAVA_TOOL_OPTIONS incluindo -javaagent

Configuração Manual

Configuração do Agente Java

A JVM de destino deve executar Java 21 ou mais recente. Java 17 não é suportado porque o reactor Java e o auxiliar de ciclo de vida dinâmico compilam para Java 21.

Adicione o seguinte como argumento JVM ao iniciar seu aplicativo, substituindo {desktopName}:

-javaagent:C:\Users\{desktopName}\repository\mcp-java-dev-tools\java-agent\core\core-probe\target\mcp-java-dev-tools-agent-0.1.8.jar=host=0.0.0.0;port=9191;exclude=com.nimbly.mcpjavadevtools.agent.**,**.config.**,**Test

Dica: O filtro include é opcional. Se omitido, o agente infere um escopo de inclusão a partir dos metadados do comando de inicialização (sun.java.command), geralmente o pacote da classe de inicialização (por exemplo, com.acme.app.**). Defina include explicitamente quando a inferência for ambígua ou ampla demais.

include suporta caminhos base separados por vírgula:

globs de pacote (por exemplo, com.thirdparty.service.**)

FQCNs de classes exatas (por exemplo, com.example.ApiClass)

segmentação mista de módulo/classe em um único valor (por exemplo, com.example.app.**,com.example.api.**,com.thirdparty.SomeClass)

Para confirmar que o agente está instrumentando suas classes, verifique os logs de inicialização em busca de linhas como:

[mcp-probe]: com.yourpackagename.yourclassname

Se você não vir suas classes listadas, verifique seu filtro include.

Anexação Dinâmica (Java 21+)

O auxiliar de ciclo de vida separado descobre PIDs de JVMs locais e carrega dinamicamente apenas um JAR de agente com o manifesto esperado do Sidecar Agent. Ele exige um PID exato e confirmação explícita; a descoberta é intencionalmente não verificada e não expõe linhas de comando ou propriedades de destino.

java -jar java-agent\core\core-jvm-attach\target\mcp-java-dev-tools-core-jvm-attach-0.1.8.jar discover
java -jar java-agent\core\core-jvm-attach\target\mcp-java-dev-tools-core-jvm-attach-0.1.8.jar attach --pid {pid} --expected-process-start-epoch-ms {process-start-epoch-ms} --agent-jar {absolute-agent-jar-path} --confirm true
java -jar java-agent\core\core-jvm-attach\target\mcp-java-dev-tools-core-jvm-attach-0.1.8.jar deactivate --pid {pid} --expected-process-start-epoch-ms {process-start-epoch-ms} --agent-jar {absolute-agent-jar-path} --confirm true

No Java 21, o carregamento dinâmico do agente é bem-sucedido por padrão, mas emite o aviso JEP 451. -XX:+EnableDynamicAgentLoading suprime esse aviso apenas quando os operadores escolhem explicitamente. -XX:-EnableDynamicAgentLoading e -XX:+DisableAttachMechanism retornam resultados de ciclo de vida com falha fechada. VirtualMachine.detach() encerra a sessão do auxiliar; ele não descarrega classes do agente. A desativação desabilita a instrumentação de propriedade do Sidecar Agent e relata classes não restauráveis.

Para CI local, declare sidecarLifecycle.activation no Artifact do projeto em vez de anexar por meio de um wrapper de shell. A inicialização suportada é uma invocação direta de java/java.exe com um caminho relativo de -jar; o orquestrador de execução é dono da anexação, verificação canônica da Probe, continuidade de retomada, limpeza de cancelamento e desativação terminal sob um único suiteRunId.

{
  "sidecarLifecycle": {
    "activation": "dynamic_attach_local",
    "targetStartupName": "orders-service",
    "probeId": "orders-service",
    "verifyProbeAfterAttach": true
  }
}

IntelliJ IDEA — Passo a Passo

Abra Run > Edit Configurations... no menu superior
Selecione a configuração de execução para seu aplicativo de destino (ou crie uma se não existir)
Expanda o menu suspenso Modify options e habilite Add VM options se ainda não estiver visível
No campo VM options, cole o argumento completo de -javaagent:... acima
Clique em Apply e depois em OK
Execute seu aplicativo normalmente — o agente anexa na inicialização

Encontrando o caminho do JAR: Se você não tiver certeza do caminho absoluto, clique com o botão direito no JAR do agente no painel do Projeto e escolha Copy Path > Absolute Path.

No Windows, use barras invertidas no caminho (C:\Users\...). No macOS/Linux, use barras normais (/home/... ou /Users/...).

Eclipse — Passo a Passo

Vá para Run > Run Configurations... (ou Debug Configurations... se estiver depurando)
Selecione seu aplicativo em Java Application, ou crie um novo
Abra a aba Arguments
No campo VM arguments, cole o argumento completo de -javaagent:... acima
Clique em Apply e depois em Run (ou Debug)

Encontrando o caminho do JAR: Navegue até o JAR no seu sistema de arquivos, clique com o botão direito e copie o caminho completo. Cole-o no argumento do agente, substituindo o caminho do espaço reservado.

No Windows, o Eclipse aceita barras normais e invertidas em caminhos, mas barras invertidas são mais seguras. Coloque o caminho entre aspas se ele contiver espaços: -javaagent:"C:\path with spaces\agent.jar"=...

Configuração de Runtime

Opções do Agente Java

Tamanho do Buffer de Histórico de Captura

Controla quantas capturas de método o agente retém por ponto de sonda.

Método	Valor
Argumento do agente	`captureMethodBufferSize=<1..32>`
Propriedade JVM	`-Dmcp.probe.capture.method.buffer.size=<1..32>`
Variável de ambiente	`MCP_PROBE_CAPTURE_METHOD_BUFFER_SIZE=<1..32>`

O padrão é 3. Aumente isso se precisar de um histórico de captura mais profundo para um único ponto de sonda.

Variáveis de Ambiente do Servidor MCP

Obrigatórias

Variável	Finalidade
`MCP_JAVA_AGENT_JAR`	Caminho absoluto para o jar do agente Java compilado usado para inicialização de runtime com sondas

Opcionais

Variável	Padrão	Notas
`MCP_JAVA_REQUEST_MAPPING_RESOLVER_JAR`	—	Substituição opcional de jar único. Um caminho ausente recai sobre artefatos Request Mapper empacotados ou compilados no repositório.
`MCP_JAVA_REQUEST_MAPPING_RESOLVER_CLASSPATH`	—	Substituição opcional de classpath para um Request Mapper e adaptadores externos. Caminhos ausentes recaem sobre artefatos empacotados ou compilados no repositório.
`MCP_JAVA_BIN`	—
`MCP_JAVA_ATTACH_HELPER_JAR`	—	Caminho absoluto opcional para o auxiliar de ciclo de vida Java 21 empacotado; a ferramenta MCP resolve o artefato auxiliar compilado no repositório caso contrário.
`MCP_JVM_LIFECYCLE_ALLOWED_PROBE_HOSTS`	—	Hosts de Probe não-loopback permitidos para anexação dinâmica, separados por vírgula. Loopback é sempre permitido.
`MCP_PROBE_LINE_SELECTION_MAX_SCAN_LINES`	`120`	Faixa: 10–2000
`MCP_PROBE_WAIT_MAX_RETRIES`	`1`	Máx: 10
`MCP_PROBE_WAIT_UNREACHABLE_RETRY_ENABLED`	`false`
`MCP_PROBE_WAIT_UNREACHABLE_MAX_RETRIES`	`3`	Máx: 10
`MCP_PROBE_INCLUDE_EXECUTION_PATHS`	`false`	Defina `true` para incluir arrays de `executionPaths` em payloads de sonda
`MCP_STDIO_MAX_BUFFER_SIZE`	`33554432`	Tamanho máximo de frame MCP JSON-RPC delimitado por nova linha em bytes. Faixa: 1048576–67108864.

MCP_STDIO_MAX_BUFFER_SIZE controla o limite de frame de entrada stdio do MCP usado pelo servidor de compatibilidade TypeScript. Ele é limitado para proteger o processo de entrada ilimitada; aumentá-lo não substitui os limites de tamanho de cabeçalho do alvo HTTP ou do proxy.

Matriz de Escopo de Configuração

Configuração	Consumido Por	Afeta
`.mcpjvm/probe-config.json`	Servidor MCP	Roteamento canônico multi-sonda com workspaces/perfis/sondas
`include` / `exclude` em `-javaagent:...` (ou `mcp.probe.include` / `MCP_PROBE_INCLUDE`)	Agente Java	Quais classes são instrumentadas em tempo de execução
`MCP_PROBE_INCLUDE_EXECUTION_PATHS`	Servidor MCP	Se arrays `executionPaths` são incluídos nos payloads de sonda retornados

Endpoints de Sonda

Estes caminhos são fixos e não podem ser sobrescritos.

Endpoint	Caminho
Status	`/__probe/status`
Reset	`/__probe/reset`
Capture	`/__probe/capture`

Habilidades

Habilidade	Propósito
`mcp-java-dev-tools-line-probe-run`	Execução de sonda em nível de linha
`mcp-java-dev-tools-regression-suite`	Orquestração de verificação de regressão
`mcp-java-dev-tools-regression-plan-crafter`	Criar e refinar especificações determinísticas de planos de regressão persistidos (`metadata.json`, `contract.json`, `plan.md`)
`mcp-java-dev-tools-regression-result`	Renderização de resultados derivados de artefatos com modelos de exibição extensíveis (tabela de endpoint padrão)
`mcp-java-dev-tools-issue-report`	Relato sanitizado de problemas a partir de evidências de sessão, runtime e sonda
`mcp-java-dev-tools-bug-drill`	Diagnóstico limitado em nível de método usando Síntese de Rota e evidências de Sonda ao vivo
`mcp-java-dev-tools-bug-fix`	Localização de problemas somente por proposta e planejamento de correção Java com evidência de Sonda
`mcp-java-dev-tools-failure-lens`	Reprodução limitada de exceção colada com suporte Sidecar, sem diagnóstico somente estático
`mcp-java-dev-tools-jvm-lifecycle`	Descoberta segura de Agente Sidecar Java 21+ local, anexação, verificação de Sonda e desativação

Contribuindo

As orientações de contribuição estão em CONTRIBUTING.md.

O guia distingue entre:

contribuições de sintetizador e adaptador
ferramentas de sonda e contribuições de geração de receitas

Comece por lá antes de abrir um pull request grande ou alterar contratos públicos de ferramentas.

Ferramentas MCP

Ferramenta
`debug_check`
`artifact_management`
`probe`
`route_synthesis`
`failure_analysis`	Análise de rastreamento Failure Lens e comparação de reprodução em runtime
`execution_profile_export`	Exportação determinística de replay para PowerShell, shell, Postman e desempenho
`execution_orchestration`
`jvm_lifecycle`	Descoberta de JVM local e operações de ciclo de vida do Agente Sidecar

Comportamento em runtime do Artefato de configuração de Sonda:

A configuração do registro é carregada do .mcpjvm/probe-config.json do workspace descoberto.
Edições de arquivo são recarregadas automaticamente com debounce.
artifact_management com artifactType=probe_config e action=reload permanece disponível como atualização manual determinística/fallback.