JVM Source Lens

jvmsrc — Dale a tu agente de codificación un IDE de Java

El Problema

Usas un IDE para escribir Java. Tu agente de codificación no tiene uno.

Cuando tu agente se encuentra con un tipo de librería desconocido — por ejemplo, una superclase de una librería interna propietaria — gasta más de 25 turnos recorriendo ~/.gradle/caches, abriendo JARs manualmente con jar tf, eligiendo uno a ciegas, e intentando responder una pregunta que tu IDE respondería con una sola pulsación: ¿tiene esta superclase un método utilitario público llamado X?

La Solución

jvmsrc consulta tu herramienta de compilación (Gradle) para obtener el classpath resuelto de este proyecto, y luego entrega a tu agente código fuente real, firmas reales y estructura real — para la versión exacta que tu compilación realmente usa.

• Como servidor MCP – Conéctalo a Claude Code, Cursor, Windsurf, o cualquier otro host MCP y equipa a tu agente con seis herramientas de classpath diseñadas específicamente.
• Como CLI jvmsrc – El mismo motor, scripteable, compatible con pipes, y útil por sí solo cuando solo quieres leer una clase.

Claude Code resolviendo firmas de HandlerInterceptor mediante jvmsrc — 3 llamadas, respuesta correcta, sin recorrer caché.

Lo que ahorra, a diario

En proyectos JVM con librerías privadas y sin Javadocs públicos, jvmsrc es un multiplicador de fuerza:

• ~50K tokens ahorrados por investigación de "qué hay en esta clase externa" — aproximadamente 70% de reducción en costos.
• Más de 15 bucles de pánico del agente evitados al día — sin triturar cachés de Gradle, abrir JARs equivocados, o rendirse.
• Desbloquea la delegación de tareas complejas que tocan SDKs internos que antes tenías que hacer tú mismo.

La Diferencia en Acción

Sin jvmsrc (El molino ciego de 25 turnos)

Usuario: Sobrescribe el hook de auditoría de AbstractTradingService — ¿hay un método utilitario público en él que deberíamos reutilizar?

Agente:

1. Busca en el espacio de trabajo AbstractTradingService.java ➔ 0 hits
2. Ejecuta: find ~/.gradle -name "trading-core*"
3. Encuentra 4 versiones: 2.1.0, 2.3.0, 2.4.1, 3.0.0-SNAPSHOT
4. Adivina: Elige trading-core-2.4.1.jar (¡el proyecto realmente usa 3.0.0-SNAPSHOT!)
5. Ejecuta: jar tf y javap -p en el JAR equivocado
6. [22 turnos después] "No veo un método utilitario, tendrás que implementarlo tú mismo."

Realidad: 3.0.0-SNAPSHOT añadió maskSensitiveFields() como helper protegido exactamente para este caso. El agente no alucinó — simplemente estaba ciego.

Con jvmsrc (La resolución instantánea de 3 turnos)

Usuario: Sobrescribe el hook de auditoría de AbstractTradingService — ¿hay un método utilitario público en él que deberíamos reutilizar?

Agente:

1. search_classes("AbstractTradingService") ➔ Encuentra el FQN y la librería resuelta exacta.
2. get_class_structure(scope: "overview") ➔ Descubre maskSensitiveFields() en 3.0.0-SNAPSHOT.
3. get_method_signature("maskSensitiveFields") ➔ Obtiene la firma precisa y los genéricos.

Resultado: Escribe la sobrescritura correctamente al primer intento. Sin recorrer caché, sin adivinar, sin versión equivocada.

Cómo Funciona

1. Consulta a la Herramienta de Compilación: jvmsrc consulta tu herramienta de compilación activa (por ejemplo, Gradle) para obtener la configuración exacta del classpath resuelto.
2. Caché Inteligente: Almacena en caché el classpath resuelto, rastreando cambios en los archivos de compilación para mantenerse actualizado.
3. Herramientas de IA de Precisión: En lugar de volcar código completo, expone herramientas precisas y de alta granularidad (firmas, estructura, búsqueda) para mantener las ventanas de contexto pequeñas y el uso de tokens ultrabajo.

Instalación y Inicio Rápido

1. Instalar CLI

npm install -g jvmsrc

O úsalo directamente con npx:

npx jvmsrc mcp

[!IMPORTANTE]
Requiere Node ≥ 20 y Java en PATH (para el descompilador CFR + javap).

2. Añadir el servidor MCP

Pega esto en la configuración de tu asistente de IA (Cursor, Claude Code, Windsurf, etc.), y luego reinicia el host:

{
  "mcpServers": {
    "jvmsrc": {
      "command": "jvmsrc",
      "args": ["mcp"]
    }
  }
}

Opcional: jvmsrc config (o jvmsrc config --project /path/to/gradle-project) imprime un bloque listo para pegar más sugerencias de entorno. La mayoría de los usuarios pueden omitirlo y copiar el fragmento de arriba.

Referencia del Servidor MCP

El servidor MCP se ejecuta sobre stdio mediante jvmsrc mcp. La configuración predeterminada no necesita variables de entorno:

{
  "mcpServers": {
    "jvmsrc": {
      "command": "jvmsrc",
      "args": ["mcp"]
    }
  }
}

Credenciales de repositorio privado (opcional)

Solo se necesitan cuando tu compilación de Gradle requiere variables de entorno de credenciales para un repositorio privado estilo Maven/Artifactory/Nexus. Los hosts MCP a menudo no heredan tu shell interactivo, por lo que esas variables deben establecerse en el proceso MCP de jvmsrc (luego reinicia el servidor).

REPO_USER / REPO_PASS a continuación son solo nombres de ejemplo — no son requeridos por jvmsrc. Usa los nombres de variables que documenten los scripts de Gradle de tu proyecto:

{
  "mcpServers": {
    "jvmsrc": {
      "command": "jvmsrc",
      "args": ["mcp"],
      "env": {
        "REPO_USER": "your-username",
        "REPO_PASS": "your-password"
      }
    }
  }
}

Omite el bloque env por completo cuando el proyecto no los necesite.

Herramientas que recibe tu agente

[!CONSEJO]
Cada respuesta de fuente incluye sourceAvailable: true para fuentes reales (Javadoc, nombres de parámetros, genéricos), false para descompilación CFR (estructura confiable, los nombres pueden ser sintéticos).

[!NOTA]
Multimódulo: omite modulePath y jvmsrc elige automáticamente el módulo propietario único; si falla, lista los modulePath candidatos. Métodos: search_classes coincide con nombres de métodos declarados cuando el índice tiene enriquecimiento de fuente; para texto de cuerpo en un JAR conocido usa search_in_artifact. get_class_source methodNames también recorre superclases para nombres no coincidentes.

Cómo se Compara

Público Objetivo

Principalmente proyectos Java + Spring Boot en Gradle. Otros lenguajes JVM (Kotlin, Scala) y Android funcionan hoy con el mejor esfuerzo posible y están en la hoja de ruta como objetivos de primera clase — consulta ROADMAP.md.

Si usas Maven o Bazel, está planificado pero aún no disponible. Marca el repositorio con una estrella o abre un issue y lo priorizaré en consecuencia.

Referencia Detallada

jvmsrc com.example.MyClass -p /path/to/gradle-project          # shorthand for get
jvmsrc get com.example.MyClass -p /path/to/project -q > MyClass.java
jvmsrc resolve -p /path/to/project --force-refresh
jvmsrc config jdk-roots add /path/to/jdks                      # one-time JDK roots setup
jvmsrc doctor java -p /path/to/project                         # check JDK requirement + selection
jvmsrc diagnostics last                                         # latest failure message
jvmsrc mcp                                                     # run as MCP server

Documentación del Proyecto

Compilación desde el Código Fuente

git clone https://github.com/Sintexer/jvm-source-lens.git
cd jvm-source-lens
bun install && bun run setup:cfr && bun run build
node dist/cli.js --version

Flujo de trabajo completo para contribuidores: CONTRIBUTING.md.

Construí jvmsrc porque seguía encontrándome con el mismo obstáculo: agentes que son excelentes escribiendo Java pero ciegos al classpath real. Si te ahorra los mismos 25 turnos de idas y vueltas que me ahorró a mí, eso es exactamente por lo que esto existe. ¿Encontraste un error, tienes una idea o solo quieres decir que te ayudó? Abre un issue o un PR — leo todo.

Licencia

MIT — ver LICENSE.