MCP Java Dev Tools

Puente entre herramientas de codificación agentivas y el comportamiento en tiempo real de Java mediante un agente sidecar ligero.

GitHub

Prueba este MCPPatrocinado

Documentación

mcp-java-dev-tools

MCP Java Dev Tools conecta herramientas de codificación agénticas con el comportamiento en vivo del runtime de Java a través de un agente auxiliar ligero.

El análisis estático solo te lleva hasta cierto punto. Al adjuntarse directamente a una JVM en ejecución, esta herramienta expone señales de runtime a nivel de bytecode que el análisis estático por sí solo no puede ver — habilitando inspección verificada por sondas, comprobaciones de regresión dirigidas, validación de rutas de runtime y flujos de depuración deterministas.

El agente de runtime está construido con ByteBuddy y funciona junto a JDWP en lugar de reemplazarlo. Sobre la capa de sondas, el sistema añade síntesis de datos consciente del framework y contratos de herramientas estrictos con cierre ante fallos — para que los orquestadores de agentes puedan tomar decisiones basadas en pruebas reales de runtime, no en inferencias.

El enfoque actual está en los puntos de entrada HTTP. El soporte para protocolos no HTTP está en el horizonte pero aún no está implementado — necesitará modelos concretos y objetivos de validación antes de que los contratos centrales puedan generalizarse.

Para flujos de trabajo de operadores y flujos de ejecución de extremo a extremo, consulta docs/how-it-works/README.md.

Requisitos

Requisito	Versión
Node.js	`v24.13.0` (probado)
npm	`11.6.2` (probado)
JDK	`21+`
Maven	`3.8.6+`

Compilación

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

Esto produce dos artefactos:

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

El helper del ciclo de vida de Java 21 se empaqueta por separado en java-agent/core/core-jvm-attach/target/mcp-java-dev-tools-core-jvm-attach-0.1.8.jar.

Base opcional del servidor MCP en Java

mcp-server/ es un servidor MCP opcional en Java 21, Spring Boot y Spring AI MCP para la ruta de migración de v0.1.9. Expone las herramientas MCP migradas de Probe y del ciclo de vida de la JVM; el servidor MCP TypeScript existente en dist/server.js sigue siendo el predeterminado de producción.

Compila y verifica la base de forma independiente:

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

El JAR ejecutable es mcp-server/application/target/mcp-java-dev-tools-server-0.1.9.jar. Su directorio adyacente sidecar/ contiene los artefactos empaquetados del helper y del agente; usa solo STDIO, reservando stdout para MCP JSON-RPC y enviando diagnósticos a stderr. Consulta mcp-server/README.md para conocer sus límites de módulo y el alcance de migración diferido.

Instalación

Instalador

El flujo del instalador se divide en scripts de instalación y actualización (habilidades de Codex y Kiro).

./scripts/install.sh

Esto instala el conjunto de habilidades predeterminado:

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 actualizar/sobrescribir las habilidades instaladas existentes (y añadir nuevas habilidades faltantes):

./scripts/update.sh

Ambos scripts:

ejecutan npm run build:compile
ejecutan mvn -f java-agent/pom.xml package
sincronizan las habilidades incluidas en el directorio de habilidades del cliente objetivo
por defecto solicitan un primer espacio de trabajo y generan el bloque de salida de configuración de env de MCP (específico del cliente)

Comportamiento de Kiro y Claude Code durante la instalación/actualización:

las habilidades gestionadas obsoletas que coincidan con mcp-java-dev-tools-* se detectan y pueden eliminarse de forma interactiva
las habilidades gestionadas instaladas se validan después de la sincronización (SKILL.md + presencia esperada de la carpeta)
se imprime orientación sobre reinicio/recarga para que la lista visible de herramientas/habilidades se actualice desde el directorio de habilidades sincronizado

La entrada de env del registro MCP predeterminado se puede omitir:

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

La entrada de env de MCP captura:

MCP_JAVA_AGENT_JAR (obligatorio; ruta absoluta al JAR del agente Java compilado)

Lanzador de integración con Spring

Usa el lanzador auxiliar para ejecutar una aplicación Spring con alcance de inclusión del agente Java y puerto de sonda inferidos automáticamente:

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

Comportamiento:

solicita la ruta absoluta del proyecto Spring, el puerto de la aplicación (predeterminado 8080) y el puerto JDWP opcional
infiere el paquete de inclusión desde src/main/java
asigna el puerto de sonda comenzando en 9173 y lo incrementa si está ocupado
abre una nueva ventana de Git Bash e inicia la aplicación Spring con JAVA_TOOL_OPTIONS incluyendo -javaagent

Configuración manual

Configuración del agente Java

La JVM objetivo debe ejecutarse en Java 21 o superior. Java 17 no es compatible porque el reactor de Java y el helper dinámico del ciclo de vida se compilan para Java 21.

Añade lo siguiente como argumento de JVM al lanzar tu aplicación, reemplazando {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

Consejo: El filtro include es opcional. Si se omite, el agente infiere un alcance de inclusión a partir de los metadatos del comando de inicio (sun.java.command), normalmente el paquete de la clase de inicio (por ejemplo com.acme.app.**). Establece include explícitamente cuando la inferencia sea ambigua o demasiado amplia.

include admite rutas base separadas por comas:

globs de paquetes (por ejemplo com.thirdparty.service.**)

FQCN de clases exactas (por ejemplo com.example.ApiClass)

combinación de módulo/clase en un solo valor (por ejemplo com.example.app.**,com.example.api.**,com.thirdparty.SomeClass)

Para confirmar que el agente está instrumentando tus clases, revisa los registros de inicio en busca de líneas como:

[mcp-probe]: com.yourpackagename.yourclassname

Si no ves tus clases listadas, verifica tu filtro include.

Adjunto dinámico (Java 21+)

El helper separado del ciclo de vida descubre los PIDs de JVM locales y carga dinámicamente solo un JAR de agente con el manifiesto esperado de Sidecar Agent. Requiere un PID exacto y confirmación explícita; el descubrimiento es intencionalmente no verificado y no expone líneas de comando ni propiedades del objetivo.

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

En Java 21, la carga dinámica del agente tiene éxito por defecto pero emite la advertencia JEP 451. -XX:+EnableDynamicAgentLoading suprime esa advertencia solo cuando los operadores la eligen explícitamente. -XX:-EnableDynamicAgentLoading y -XX:+DisableAttachMechanism devuelven resultados de ciclo de vida con cierre ante fallos. VirtualMachine.detach() cierra la sesión del helper; no descarga las clases del agente. La desactivación deshabilita la instrumentación propiedad de Sidecar Agent e informa las clases no restaurables.

Para CI local, declara sidecarLifecycle.activation en el Artifact del proyecto en lugar de adjuntar a través de un wrapper de shell. El inicio compatible es una invocación directa de java/java.exe con una ruta relativa de -jar; el orquestador de ejecución es dueño del adjunto, la verificación canónica de Probe, la continuidad de reanudación, la limpieza de cancelación y la desactivación terminal bajo un único suiteRunId.

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

IntelliJ IDEA — Paso a Paso

Abre Run > Edit Configurations... desde el menú superior
Selecciona la configuración de ejecución para tu aplicación objetivo (o crea una si no existe)
Expande el menú desplegable Modify options y habilita Add VM options si aún no está visible
En el campo VM options, pega el argumento completo de -javaagent:... de arriba
Haz clic en Apply, luego en OK
Ejecuta tu aplicación normalmente — el agente se adjunta al inicio

Encontrar la ruta del JAR: Si no estás seguro de la ruta absoluta, haz clic derecho en el JAR del agente en el panel del Proyecto y elige Copy Path > Absolute Path.

En Windows, usa barras invertidas en la ruta (C:\Users\...). En macOS/Linux, usa barras normales (/home/... o /Users/...).

Eclipse — Paso a Paso

Ve a Run > Run Configurations... (o Debug Configurations... si estás depurando)
Selecciona tu aplicación bajo Java Application, o crea una nueva
Abre la pestaña Arguments
En el campo VM arguments, pega el argumento completo de -javaagent:... de arriba
Haz clic en Apply, luego en Run (o Debug)

Encontrar la ruta del JAR: Navega hasta el JAR en tu sistema de archivos, haz clic derecho y copia la ruta completa. Pégala en el argumento del agente, reemplazando la ruta del marcador de posición.

En Windows, Eclipse acepta tanto barras normales como invertidas en las rutas, pero las barras invertidas son más seguras. Envuelve la ruta entre comillas si contiene espacios: -javaagent:"C:\path with spaces\agent.jar"=...

Configuración de runtime

Opciones del agente Java

Tamaño del buffer de historial de capturas

Controla cuántas capturas de métodos retiene el agente por punto de sonda.

Método	Valor
Argumento del agente	`captureMethodBufferSize=<1..32>`
Propiedad de JVM	`-Dmcp.probe.capture.method.buffer.size=<1..32>`
Variable de entorno	`MCP_PROBE_CAPTURE_METHOD_BUFFER_SIZE=<1..32>`

El valor predeterminado es 3. Auméntalo si necesitas un historial de capturas más profundo para un solo punto de sonda.

Variables de entorno del servidor MCP

Obligatorias

Variable	Propósito
`MCP_JAVA_AGENT_JAR`	Ruta absoluta al JAR del agente Java compilado usado para el inicio de runtime conectado por sondas

Opcionales

Variable	Predeterminado	Notas
`MCP_JAVA_REQUEST_MAPPING_RESOLVER_JAR`	—	Anulación opcional de un solo JAR. Una ruta faltante recurre a los artefactos empaquetados o compilados en el repositorio de Request Mapper.
`MCP_JAVA_REQUEST_MAPPING_RESOLVER_CLASSPATH`	—	Anulación opcional del classpath para un Request Mapper y adaptadores externos. Las rutas faltantes recurren a los artefactos empaquetados o compilados en el repositorio.
`MCP_JAVA_BIN`	—
`MCP_JAVA_ATTACH_HELPER_JAR`	—	Ruta absoluta opcional al helper empaquetado del ciclo de vida de Java 21; la herramienta MCP de lo contrario resuelve el artefacto helper compilado en el repositorio.
`MCP_JVM_LIFECYCLE_ALLOWED_PROBE_HOSTS`	—	Hosts de Probe no loopback permitidos para adjunto dinámico, separados por comas. Loopback siempre está permitido.
`MCP_PROBE_LINE_SELECTION_MAX_SCAN_LINES`	`120`	Rango: 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`	Establece `true` para incluir arrays de `executionPaths` en las cargas útiles de las sondas
`MCP_STDIO_MAX_BUFFER_SIZE`	`33554432`	Tamaño máximo de marco MCP JSON-RPC delimitado por nueva línea en bytes. Rango: 1048576–67108864.

MCP_STDIO_MAX_BUFFER_SIZE controla el límite de marco de entrada stdio de MCP usado por el servidor de compatibilidad TypeScript. Está acotado para proteger el proceso de entradas ilimitadas; aumentarlo no anula los límites de tamaño de encabezado del objetivo HTTP o del proxy.

Matriz de alcance de configuración

Configuración	Consumido por	Afecta
`.mcpjvm/probe-config.json`	Servidor MCP	Enrutamiento canónico multi-sonda con workspaces/perfiles/sondas
`include` / `exclude` en `-javaagent:...` (o `mcp.probe.include` / `MCP_PROBE_INCLUDE`)	Agente Java	Qué clases se instrumentan en tiempo de ejecución
`MCP_PROBE_INCLUDE_EXECUTION_PATHS`	Servidor MCP	Si los arrays `executionPaths` se incluyen en las cargas útiles de sonda devueltas

Endpoints de Sonda

Estas rutas son fijas y no se pueden sobrescribir.

Endpoint	Ruta
Estado	`/__probe/status`
Reiniciar	`/__probe/reset`
Capturar	`/__probe/capture`

Habilidades

Habilidad	Propósito
`mcp-java-dev-tools-line-probe-run`	Ejecución de sondas a nivel de línea
`mcp-java-dev-tools-regression-suite`	Orquestación de comprobaciones de regresión
`mcp-java-dev-tools-regression-plan-crafter`	Crear y refinar especificaciones deterministas de planes de regresión persistidos (`metadata.json`, `contract.json`, `plan.md`)
`mcp-java-dev-tools-regression-result`	Renderizado de resultados derivados de artefactos con plantillas de visualización extensibles (tabla de endpoints predeterminada)
`mcp-java-dev-tools-issue-report`	Reporte de problemas saneado a partir de evidencia de sesión, tiempo de ejecución y sonda
`mcp-java-dev-tools-bug-drill`	Diagnóstico acotado a nivel de método usando Síntesis de Rutas y evidencia de Sonda en vivo
`mcp-java-dev-tools-bug-fix`	Localización de problemas solo-propuesta y planificación de correcciones Java con evidencia de Sonda
`mcp-java-dev-tools-failure-lens`	Reproducción de excepciones pegadas respaldada por Sidecar acotado sin diagnóstico solo-estático
`mcp-java-dev-tools-jvm-lifecycle`	Descubrimiento seguro del Agente Sidecar local Java 21+, adjuntado, verificación de Sonda y desactivación

Contribuciones

La guía de contribuciones vive en CONTRIBUTING.md.

La guía distingue entre:

contribuciones de sintetizador y adaptador
herramientas de sonda y contribuciones de generación de recetas

Comienza allí antes de abrir una solicitud de extracción grande o cambiar contratos públicos de herramientas.

Herramientas MCP

Herramienta
`debug_check`
`artifact_management`
`probe`
`route_synthesis`
`failure_analysis`	Análisis de trazas de Failure Lens y comparación de reproducción en tiempo de ejecución
`execution_profile_export`	Exportación determinista de reproducción para PowerShell, shell, Postman y rendimiento
`execution_orchestration`
`jvm_lifecycle`	Descubrimiento de JVM local y operaciones del ciclo de vida del Agente Sidecar

Comportamiento en tiempo de ejecución del Artefacto de configuración de Sonda:

La configuración del registro se carga desde el .mcpjvm/probe-config.json del workspace descubierto.
Las ediciones de archivos se recargan automáticamente con debounce.
artifact_management con artifactType=probe_config y action=reload permanece disponible como actualización manual determinista/respaldo.