javalens-mcp

An MCP server providing 75 semantic analysis tools for Java, built directly on Eclipse JDT for compiler-accurate code understanding.

Requirements

• Java 21 or later — required as the server runtime, analyzes Java source from version 1.1 through 25 (markdown Javadoc, module imports, compact source files, flexible constructor bodies)
• Node.js 18+ — required to run this package via npx. If you don't have Node.js, download JavaLens directly from GitHub Releases instead.

Lombok is supported out of the box: a bundled agent makes Lombok-generated members resolve, so @Data accessors appear in the model and code using them is not flagged as undefined. Set JAVALENS_LOMBOK_JAR to override the bundled agent jar.

Disk synchronization: every answer is verified against the files on disk at query time — no reload is needed after editing, adding, or deleting source files (the agent's loop is just edit → query). Verification is hash-based and parallel (~2 ms at 72 files, ~25 ms at 1,000, ~180 ms at 10,000 per query); repairs cost only what changed. load_project remains for first use, RELOAD_REQUIRED responses (build-file changes), and full resets. Set JAVALENS_DISK_SYNC=manual for the pre-1.5.0 contract where the agent reloads after edits.

Quick Start

{
  "mcpServers": {
    "javalens": {
      "command": "npx",
      "args": ["-y", "javalens-mcp"],
      "env": {
        "JAVA_PROJECT_PATH": "/path/to/your/java/project"
      }
    }
  }
}

What This Package Does

This npm package bundles the full JavaLens distribution (~23 MB). No runtime downloads, no network dependency after install. It:

1. Checks that Java 21+ is installed
2. Reads JVM configuration from the bundled eclipse.ini
3. Launches the JavaLens MCP server with stdio for protocol communication

Why JavaLens?

AI systems need compiler-accurate insights that reading source files cannot provide. When an AI uses grep to find usages of a method, it cannot distinguish a method call from a method with the same name in an unrelated class, a field read from a field write, or an interface implementation from an unrelated class.

| Approach | Result | |----------|--------| | grep "save(" | 47 matches including orderService.save(), saveButton, comments | | find_references | Exactly 12 calls to UserService.save() |

Features

Navigation (10 tools)

Search symbols, go to definition, find references, find implementations, type hierarchy, document symbols, and positional queries.

Fine-Grained Reference Search (9 tools)

JDT-unique capabilities not available through LSP: find annotation usages, type instantiations, casts, instanceof checks, throws declarations, catch blocks, method references, type arguments, and reflection usage detection.

Analysis (20 tools)

Diagnostics, syntax validation, call hierarchy (incoming/outgoing), field write tracking, test discovery, unused code detection, project-wide unreachable-code detection over the whole-program call graph, affected-test discovery (which tests exercise a symbol, transitively), possible bug detection, change impact analysis (with a full transitive mode), data flow analysis (with opt-in cross-method null/taint tracking), control flow analysis, Spring DI registration scanning, JPA entity-model assembly, and HTTP route-table assembly (Spring and JAX-RS).

Compound Analysis (4 tools)

Combine multiple queries to reduce round-trips: analyze file, analyze type, analyze method, and type usage summary.

Refactoring (16 tools)

All return text edits (and new-file content where a refactoring creates one) rather than modifying files directly: rename, organize imports, extract variable/method/constant/interface/superclass, inline variable/method, change method signature, convert anonymous to lambda, encapsulate field, pull up / push down members, introduce parameter object, and move a nested type to its own file.

Quick Fixes & Metrics (10 tools)

Import suggestions, quick fixes, 10 JDT clean-ups (convert loops, pattern matching, switch expressions, text blocks, ...), one-call diagnose-and-fix, cyclomatic complexity, dependency graphs, circular dependency detection, large class detection, and naming convention violations.

Project & Infrastructure (6 tools)

Health check, project loading, project structure, classpath info, type member lookup by name, and superclass method resolution.

Build System Support

Single-module and multi-module projects load end-to-end across Maven, Gradle, and Bazel.

| System | Detection | Multi-module | Compiler compliance | Generated sources | Annotation processors | |--------|-----------|:-:|:-:|:-:|:-:| | Maven | pom.xml | ✅ | ✅ | ✅ | ✅ | | Gradle | build.gradle / build.gradle.kts | ✅ | ✅ | ✅ | ✅ | | Bazel | MODULE.bazel / WORKSPACE.bazel / WORKSPACE | ✅ | ✅ | n/a | ✅ | | Plain Java | src/ directory | n/a | ✅ | n/a | n/a |

If mvn / gradle is missing or the subprocess fails, JavaLens reports a structured warning (e.g. MAVEN_SUBPROCESS_FAILED) in the load_project response so callers know the classpath is degraded.

Configuration

| Environment Variable | Description | Default | |---------------------|-------------|---------| | JAVA_PROJECT_PATH | Auto-load project on startup | (none) | | JAVALENS_TIMEOUT_SECONDS | Operation timeout | 30 | | JAVALENS_DISK_SYNC | strict (answers verified against disk per query) or manual (reload after edits) | strict | | JAVA_TOOL_OPTIONS | JVM options, e.g. -Xmx2g for large projects | 512m | | JAVALENS_LOG_LEVEL | TRACE/DEBUG/INFO/WARN/ERROR | INFO | | JAVALENS_LOMBOK_JAR | Path to the Lombok agent jar attached at launch; overrides the bundled one | (bundled) |

Documentation

Full documentation, tool reference, and architecture details: GitHub