Purpose
JavaLens exists for one reason: AI systems need compiler-level accurate insight, and merely reading source files cannot provide that. When AI uses grep or Read to find usages of a method, it cannot distinguish: method calls from methods with the same name in unrelated classes; field reads from field writes; interface implementations from unrelated classes; casts to a type from other references to that type. This leads to incorrect refactorings, missed usages, and an incomplete understanding of code behavior. JavaLens provides AI agents with semantic Java code analysis.
Main Capabilities
JavaLens is an MCP server that provides about 75 semantic analysis tools for Java, built directly on Eclipse JDT to achieve compiler-level accurate code understanding. It provides semantic analysis, navigation, refactoring, and code intelligence tools that go beyond simple text search.
The Language Server Protocol is designed for IDE autocompletion and basic navigation, not for AI agent workflows that require deep semantic analysis. JavaLens directly wraps Eclipse JDT Core through OSGi, providing: fine-grained reference types—precisely finding casts, annotations, throws clauses, catch blocks, instanceof checks, method references, type parameters; read and write access distinction—tracking where fields are modified versus only read; indexed search—JDT pre-builds indexes on load, so symbol/reference queries do not need to traverse source files; full AST access—direct manipulation for complex refactorings.
For compiler-level analysis, JavaLens provides compiler-level code analysis through Eclipse JDT (the same engine that powers the Eclipse IDE). Unlike text search, JDT understands: type resolution across inheritance hierarchies, method overloading and overriding, generic type parameters, import resolution and classpath dependencies, Java source from Java 1.1 to Java 25 (Markdown Javadoc, module imports, compact source files, flexible constructor bodies), and Lombok-generated members—the bundled agent enables @Data accessors and the like to resolve, so code that uses them is not flagged as undefined.
Tools are organized by category: navigation (10 tools), fine-grained reference search (9 tools, using JDT-exclusive reference type constants that LSP does not provide), analysis (20 tools), composite analysis (4 tools, merging multiple queries to reduce round trips), refactoring (16 tools), quick fixes (5 tools), metrics (5 tools), and project and infrastructure (6 tools).
How to Use
Requirements: Java 21 or higher (must be in PATH or have JAVA_HOME set) — required for both installation paths. Node.js 18+ — required only when using the npm/npx installation path. JavaLens is an analysis server, not a compiler. It uses Eclipse JDT 2025-12 to parse and understand Java 1.1 through 25 source code. Java 21 is only a server runtime requirement.
Install from GitHub Releases (recommended — requires only Java): Download from Releases and extract to any location (for example /opt/javalens or C:\javalens), then point the MCP client to the bundled jar.
Install via npm (requires Node.js 18+): If Node.js is already available, npx will download and cache the JavaLens distribution on first run (about 23 MB).
Configure the MCP client: Add to the MCP configuration (for example Claude Code's .mcp.json). The -data parameter specifies where JavaLens stores workspace metadata.
Auto-load project: Set JAVA_PROJECT_PATH to automatically load a project when the server starts. Note: project loading happens asynchronously in the background. The MCP server responds immediately while the project is loading. Use health_check to monitor loading status — it will show "project.status": "loading" before completion, and "loaded" once ready.
Workspace mechanism: Unlike in-memory code models, Eclipse JDT requires a workspace directory to store the search index (for fast symbol lookup), compilation state and caches, and project metadata. The workspace is located outside the source code to avoid polluting the source tree, avoid conflicts, and enable session isolation. Session lifecycle: JavaLens starts and creates a unique workspace {base}/{uuid}/; load_project creates a linked folder pointing to the source code; JDT builds the index in the workspace (not the project); the workspace is cleaned up when the session ends.
Coordinate system: TheRow/column parameters start from zero (row 0, column 0 = the first character of the file); response paths are relative by default; all paths use forward slashes for cross-platform consistency; input paths may be relative or absolute.
Disk sync: every answer is verified against the files on disk at query time. Before any tool logic runs, JavaLens hashes the contents of known source files, detects edits, additions, and deletions (the agent does not report them—the server discovers changes on its own), precisely repairs the changed parts, waits for the search index to absorb the repairs, and only then answers. There is no file watcher and no background thread—verification happens synchronously within the query issued by the agent, so there are no race conditions. The agent's loop is: edit → query. load_project is only needed on first use, when the response reports RELOAD_REQUIRED (for example, changes to build files such as pom.xml require rebuilding the classpath), or when rebuilding everything from scratch. If verification itself fails, the query returns VERIFICATION_FAILED instead of an unverified answer. Cost: verification is hash-based and parallel—measured at about 2 ms per query for a 72-file project, about 25 ms for 1,000 files, and about 180 ms for 10,000 files. Repair only costs the changed parts (a single edited file is reconciled within a second), never a full index rebuild. Manual mode: setting JAVALENS_DISK_SYNC=manual restores the pre-1.5.0 contract—answers reflect the last loaded state, and the agent calls load_project after editing files.
Refactoring returns edits: refactoring tools return text edits but do not modify files. This lets you see the changes that will occur before applying them. All refactoring tools return text edits (and file contents when refactoring creates new files) rather than applying changes directly.
Session isolation: each MCP session is independent and has its own workspace UUID. Multiple sessions can analyze the same project concurrently.
Build system support: JavaLens loads three real build systems as well as plain Java directories. Each is tested end-to-end in CI against synthetic realistic fixtures (multi-module reactors with cross-module dependencies, real external libraries, annotation processors). During project loading, mvn/gradle subprocesses are invoked. If a tool is missing or fails, JavaLens shows a structured LoadWarning in the load_project response (for example, MAVEN_SUBPROCESS_FAILED, GRADLE_SUBPROCESS_FAILED, COMPLIANCE_LEVEL_UNKNOWN), letting callers know that analysis quality has degraded, rather than silently getting an empty classpath.
Building from source: distribution output goes to org.javalens.product/target/products/. Build requirements: Java 21+ (server runtime), Maven 3.9+ (wrapper ./mvnw included). Running the full test suite (including end-to-end tests against real Maven, Gradle, and Bazel builds) also requires the corresponding tools to be in PATH: Maven (provided by the wrapper), Bazel 9+ (or bazelisk). Tests skip gracefully when tools are missing on a developer machine. Setting JAVALENS_TESTS_REQUIRE_TOOLS=true flips the gating: missing tools cause hard failures instead of skips. CI runs with this flag set, so any configuration gap becomes a real failure rather than silently weakening the test suite. The build system coverage structure is focused tests for each bug plus real end-to-end tests. The end-to-end tests load one representative project per build system, covering all fixes in a single pass—multi-module Maven with Lombok APT and cross-module references; multi-project Gradle with annotation processors; multi-target Bazel with cross-target dependencies. CI runs them on Linux, macOS, and Windows.
AI training bias warning: AI models may exhibit a training bias toward native tools (Grep, Read, LSP) over MCP server tools, even when semantic analysis provides better results. Reasons: training data contains a large number of grep/text search patterns; native tools are "always available" in the model's experience; the model may fail to recognize when semantic analysis is superior. For best results, add guidance in project instructions or the system prompt (for example, Claude Code's CLAUDE.md).
License: MIT License.
Applicable Scenarios
Suitable for having an AI assistant perform tasks in Java projects that require compiler-level accurate understanding: symbol resolution across inheritance hierarchies and method overloads/overrides, precisely finding method calls and field reads/writes, fine-grained reference location (casts, annotations, throws, catch, instanceof, method references, type parameters), safe refactoring (in the form of textedit previews), code metrics, and analyzing code annotated with Lombok or using new Java 25 features. Also suitable for concurrent analysis of multi-module Maven/Gradle/Bazel projects (session isolation).
Limitations
JavaLens is an analysis server, not a compiler. Running it requires Java 21+; the npm installation path additionally requires Node.js 18+. Source parsing supports Java 1.1 through 25. Refactoring tools do not directly modify files; instead they return text edits. Project loading is asynchronous and status must be monitored via health_check. Build system loading depends on mvn/gradle subprocesses; when tools are missing or fail, analysis quality degrades and is indicated via LoadWarning. When verification fails, VERIFICATION_FAILED is returned without providing an unverified answer.
