java-lsp-mcp

java-lsp-mcp

Inteligencia semántica de Java para clientes del Protocolo de Contexto de Modelos (MCP), impulsada por Eclipse JDT Language Server y ECJ.

java-lsp-mcp brinda a los agentes de codificación navegación semántica, diagnósticos, compilación, pruebas y vistas previas de refactorización. Nunca edita archivos fuente: los cambios se devuelven como ediciones vinculadas a hash y diffs opcionales para que el cliente los aplique.

Características

• Navegación por espacio de trabajo y dependencias
• Proyectos Maven, Gradle, Eclipse, modulares y no gestionados
• Diagnósticos de instantánea actual y compilación ECJ
• Pruebas JUnit en paralelo, lanzamientos de prueba JDWP suspendidos, descubrimiento de pruebas afectadas y cobertura JaCoCo
• Correcciones, refactorizaciones, importación y vistas previas de formato de solo lectura
• Resultados acotados y paginados aptos para agentes

Requisitos previos

• Node.js 24+ — el servidor se ejecuta en tu Node; los lanzadores de versión usan node de PATH.
• Un JDK — señalado por JAVA_HOME o --tooling-jdk. Ejecuta JDT LS y tus pruebas.
• Un espacio de trabajo Java — Maven, Gradle, Eclipse, modular o no gestionado.

Los archivos de versión incluyen JDT LS, JUnit y JaCoCo. Todo lo demás proviene de los requisitos previos anteriores.

Instalación

Descarga el archivo para tu plataforma desde la página de versiones, descomprímelo y ejecuta:

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

En Windows usa bin\java-lsp-mcp.cmd. Luego verifica con java-lsp-mcp doctor --workspace /project.

Para usarlo en VS Code, agrega el lanzador a .vscode/mcp.json en tu proyecto, o solo para tu usuario, guárdalo en ~/.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 el fragmento equivalente para otros clientes.

Configuración

Banderas para serve (un archivo java-lsp-mcp.json o java-lsp-mcp.toml en el espacio de trabajo y las variables de entorno JAVA_LSP_MCP_* también funcionan; las banderas tienen prioridad, luego el entorno, luego el archivo):

Bandeja	Qué hace
--workspace	El proyecto en el que trabajar (ruta absoluta, obligatoria).
--trust-workspace	Permitir importación Maven/Gradle, compilación y ejecución de pruebas. Sin esto, el servidor solo lee código — revisa el proyecto primero.
--tooling-jdk	JDK que ejecuta JDT LS (por defecto JAVA_HOME).
--project-jdk	JDK que ejecuta tus pruebas (por defecto el JDK de herramientas).
--offline	Nunca tocar la red; Maven/Gradle resuelven solo desde cachés.
--exclude-project	Dejar un módulo fuera de importación, compilación y pruebas (repetible).
--test-classpath-entry	Directorio o jar adicional en el classpath de ejecución de pruebas (repetible).
--source-encoding	Anular la configuración de recursos de Eclipse y la decodificación automática de fuentes UTF-8/Windows-1252.
--timeout, --result-budget	Tiempo de espera de operación compartido en ms y presupuesto de salida por resultado en bytes.
--log-level, --max-heap, --result-mode	Ajuste operativo; todos los registros van a stderr, nunca a stdout.

Las lecturas de fuentes respetan --source-encoding primero, luego la configuración de codificación de recursos de Eclipse. Sin ninguno, se conserva UTF-8 válido y otros archivos fuente se leen como Windows-1252, con una advertencia SOURCE_ENCODING_FALLBACK en stderr. Los archivos fuente nunca se convierten ni modifican. Establece la codificación explícitamente para otras codificaciones heredadas; las codificaciones explícitas inválidas o no admitidas aún informan errores.

Otros comandos: doctor verifica la configuración, version imprime versiones, describe-tools imprime los esquemas completos de herramientas legibles por máquina, print-config genera configuración de cliente y clear-cache borra el índice del espacio de trabajo.

Si Eclipse no puede restaurar los metadatos del espacio de trabajo en caché porque un recurso generado desapareció, el servidor detecta la recuperación fallida, reconstruye su caché JDT una vez y reintenta el inicio.

Herramientas

Las herramientas basadas en fuentes admiten la alternativa de codificación anterior. Los objetivos de símbolos aceptan qualifiedName o path más un line obligatorio basado en uno. Omite column para seleccionar la declaración más interna que encierra esa línea; proporciona un column de punto de código Unicode basado en uno para una posición exacta. Las columnas más allá de la línea se limitan a su final.

Herramienta	Propósito
java_status	Estado de preparación y tiempo de ejecución
java_outline	Declaraciones de fuentes
java_search_symbols	Símbolos de espacio de trabajo/dependencias por lotes con paginación en caché; omite line para cada coincidencia, pasa line para mantener solo la declaración más cercana
java_find_definition	Declaraciones de símbolos por lotes; objetivo por nombre calificado o ruta de archivo + línea de fuente
java_find_references	Usos semánticos con paginación en caché; objetivo por nombre calificado o ruta de archivo + línea de fuente
java_call_hierarchy	Llamantes y llamados; los llamantes entrantes por defecto al ámbito de producción
java_type_hierarchy	Supertipos, subtipos, implementaciones
java_diagnostics	Diagnósticos de instantánea actual; falla rápido con JDT_BUSY cuando JDT está ocupado y los diagnósticos están desactualizados
java_compile	Compilación ECJ con diagnósticos, recuperación de requisitos previos y un reintento limpio cuando no se confirman errores de sintaxis
java_update_projects	Re-sincronización de configuración Maven/Gradle en JDT (force para reimportación completa)
java_run_tests	Ejecución JUnit después de compilación/recuperación incremental automática; los fallos de compilación persistentes incluyen diagnósticos; debug: true lanza JDWP suspendido
java_find_affected_tests	Pruebas conectadas estáticamente
java_find_unused_code	Miembros privados no utilizados candidatos
java_code_actions	Correcciones y refactorizaciones disponibles
java_edit_preview	Renombrar, acción, importación, vistas previas de formato
java_debug_targets	Descubrir JVM locales iniciadas con el agente JDWP
java_debug_attach, java_debug_sessions, java_debug_detach	Ciclo de vida de sesión de depuración JDWP
java_debug_set_breakpoints, java_debug_wait_for_stop	Reemplazar puntos de interrupción de fuente (las rutas con barra/barra invertida identifican el mismo archivo) y esperas de eventos de detención acotadas
java_debug_threads, java_debug_stack_trace, java_debug_variables	Inspección filtrada de hilos/pila, locales, colecciones y objetos en tiempo de ejecución
java_debug_execute	Continuar y pasar por encima, entrar o salir
java_debug_hot_swap	Reemplazo de código en caliente ECJ/JDI con informe de cambios y marcos activos

java_search_symbols y java_find_definition requieren una matriz queries de 1–20 objetos de parámetros. Agrupa búsquedas relacionadas para recopilar contexto en una sola llamada. Cada entrada tiene sus propias opciones, valores predeterminados, límite y cursor. La respuesta contiene results en orden de entrada; las entradas fallidas contienen error con code, message y details opcional, mientras que otras entradas aún se completan. Los parámetros de consulta única de nivel superior se rechazan.

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

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

La búsqueda de símbolos y las consultas de referencias conservan instantáneas de resultados independientes cuando hay otra página disponible. Las páginas posteriores reutilizan las coincidencias recopiladas y la clasificación de usos de referencias; una solicitud nueva sin cursor realiza una nueva búsqueda. La caché compartida caduca las entradas dos minutos después de su creación y usa evicción LRU con límites de 32 conjuntos de resultados y 16 MiB de resultados serializados. El acceso no extiende la caducidad. Los cambios en el espacio de trabajo y las reconexiones de JDT invalidan las continuaciones en caché. Una instantánea caducada o eviccionada devuelve STALE_RESULT_SET; reinicia sin cursor. Los resultados que exceden el límite de bytes de la caché omiten el almacenamiento en caché y conservan la paginación ordinaria.

La verificación de fuentes lee, decodifica y aplica hash a cada archivo Java una vez por verificación, reutilizando la instantánea sincronizada. La verificación sin cambios aún ofrece el documento a JDT (incluido reintentar una sincronización inicial fallida) y evita notificaciones de cambio de archivo observado innecesarias.

La compilación reintenta una compilación incremental fallida una vez como compilación limpia cuando los diagnósticos actuales no contienen códigos de error de sintaxis JDT confirmados. Los errores de sintaxis se verifican antes del filtrado de severidad o la paginación. Ambos intentos comparten el tiempo de espera de compilación y preservan las exclusiones de proyecto y el ámbito compileProjectOnly, incluidos los requisitos previos cargados. Las compilaciones limpias explícitas, la cancelación, los estados desconocidos y los fallos de solicitud/configuración no activan un reintento. java_compile.buildAttempts registra los tipos de compilación intentados y los estados; sus diagnósticos describen el resultado final.

java_run_tests compila de forma incremental por defecto y usa la misma política de recuperación antes de lanzar pruebas. Las compilaciones exitosas se reutilizan hasta que cambia la generación del espacio de trabajo; compile: "none" aún omite la compilación y compile: "clean" solicita una compilación limpia directamente. Los resultados de prueba normales incluyen buildAttempts (vacío cuando se reutilizó una compilación). Los fallos de compilación persistentes devuelven status: "compile-failed" y un objeto compilation con estado de compilación, intentos, recuentos de diagnósticos, ubicaciones/mensajes, total y diagnosticsTruncated para la muestra de diagnóstico acotada. Los recuentos de pruebas y los fallos de pruebas permanecen separados de los diagnósticos del compilador. Los lanzamientos de depuración usan la misma política de compilación; los fallos de compilación devuelven detalles del compilador en el error de la herramienta.

Ejecuta java-lsp-mcp describe-tools para los esquemas completos de herramientas legibles por máquina.

Contribuciones

Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md.

Compila desde el código fuente con:

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

Seguridad

Revisa SECURITY.md antes de otorgar confianza al espacio de trabajo. Informa vulnerabilidades de forma privada.

Licencia

MIT. Consulta LICENSE.