io.github.pzalutski-pixel/javalens

Official

by pzalutski-pixel · Java

JavaLens

63 semantic Java analysis tools via Eclipse JDT: navigation, refactoring, code intelligence.

Provides 63 semantic Java analysis tools for navigation, refactoring, and intelligence.

Topics

ai-agentsclaudecode-analysiscode-intelligencedeveloper-toolseclipse-jdtide-toolsjavalspmcpmcp-serverrefactoringstatic-analysis

README.md21 KBView on GitHub

JavaLens: AI-First Code Analysis for Java

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

Built for AI Agents

JavaLens exists because AI systems need compiler-accurate insights that reading source files cannot provide. When an AI uses grep or Read 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
An interface implementation from an unrelated class
A cast to a type from other references to that type

This leads to incorrect refactorings, missed usages, and incomplete understanding of code behavior.

Compiler-Accurate Analysis

JavaLens provides compiler-accurate code analysis through Eclipse JDT—the same engine that powers Eclipse IDE. Unlike text search, JDT understands:

Type resolution across inheritance hierarchies
Method overloading and overriding
Generic type arguments
Import resolution and classpath dependencies
Java source from version 1.1 through Java 25 (markdown Javadoc, module imports, compact source files, flexible constructor bodies)
Lombok-generated members — a bundled agent makes @Data accessors and the like resolve, so code using them is not flagged as undefined

Example: Finding all places where UserService.save() is called:

Approach	Result
`grep "save("`	Returns 47 matches including `orderService.save()`, `saveButton`, comments
`find_references`	Returns exactly 12 calls to `UserService.save()`

AI Training Bias Warning

⚠️ Important for AI developers and users

AI models may exhibit trained bias toward native tools (Grep, Read, LSP) over MCP server tools, even when semantic analysis provides better results. This happens because:

Training data contains extensive grep/text-search patterns
Native tools are "always available" in the model's experience
The model may not recognize when semantic analysis is superior

To get the best results:

Add guidance to your project instructions or system prompt (e.g., CLAUDE.md for Claude Code):

markdown

## Code Analysis Preferences

For Java code analysis, prefer JavaLens MCP tools over text search:
- Use `find_references` instead of grep for finding usages
- Use `find_implementations` instead of text search for implementations
- Use `analyze_type` to understand a class before modifying it
- Use refactoring tools (rename_symbol, extract_method) for safe changes

Semantic analysis from JDT is more accurate than text-based search,
especially for overloaded methods, inheritance, and generic types.

What is JavaLens?

JavaLens is an MCP server that gives AI assistants deep understanding of Java codebases. It provides semantic analysis, navigation, refactoring, and code intelligence tools that go beyond simple text search.

Why Not LSP?

Language Server Protocol was designed for IDE autocomplete and basic navigation—not for AI agent workflows that require deep semantic analysis.

Capability	Native LSP	JavaLens
Find all `@Annotation` usages	❌	✅
Find all `new Type()` instantiations	❌	✅
Find all casts to a type	❌	✅
Distinguish field reads from writes	❌	✅
Detect circular package dependencies	❌	✅
Calculate cyclomatic complexity	❌	✅
Find unused private methods	❌	✅
Detect possible null pointer bugs	❌	✅
Project-wide dead-code reachability from entry points	❌	✅
Find the tests that exercise a symbol, transitively	❌	✅

JavaLens wraps Eclipse JDT Core directly via OSGi, providing:

Fine-grained reference types: Find specifically casts, annotations, throws clauses, catch blocks, instanceof checks, method references, type arguments
Read vs write access distinction: Track where fields are mutated vs just read
Indexed search: JDT pre-builds an index at load time, so symbol/reference queries do not walk source files
Full AST access: Direct manipulation for complex refactorings

Installation

Prerequisites

Java 21 or later (must be on PATH or set JAVA_HOME) — required for both install paths.
Node.js 18+ — required only if you use the npm/npx install path below. Skip if you use the direct-download path.

JavaLens is an analytical server, not a compiler. It uses Eclipse JDT 2025-12 to parse and understand Java source code from version 1.1 through 25. Java 21 is required only as the server runtime.

Install from GitHub Releases (recommended — Java only)

This is the simplest path if you already have Java 21 and don't have Node.js. Download from Releases:

Platform	File
All platforms	`javalens.zip` or `javalens.tar.gz`

Extract to a location of your choice (e.g., /opt/javalens or C:\javalens). Then point your MCP client at the bundled jar — see Configure MCP Client below.

Install via npm (requires Node.js 18+)

If you already have Node.js, npx will download and cache the JavaLens distribution (~23 MB) on first run:

json

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

Configure MCP Client

Add to your MCP configuration (e.g., .mcp.json for Claude Code):

json

{
  "mcpServers": {
    "javalens": {
      "command": "java",
      "args": ["-jar", "/path/to/javalens/javalens.jar", "-data", "/path/to/javalens-workspaces"]
    }
  }
}

The -data argument specifies where JavaLens stores its workspace metadata. See How Workspaces Work below.

Auto-Load a Project

Set JAVA_PROJECT_PATH to auto-load a project when the server starts:

json

{
  "mcpServers": {
    "javalens": {
      "command": "java",
      "args": ["-jar", "/path/to/javalens/javalens.jar", "-data", "/path/to/javalens-workspaces"],
      "env": {
        "JAVA_PROJECT_PATH": "/path/to/your/java/project"
      }
    }
  }
}

Note: Project loading happens asynchronously in the background. The MCP server responds immediately while the project loads. Use health_check to monitor loading status—it will show "project.status": "loading" until complete, then "loaded" when ready.

How Workspaces Work

Unlike in-memory code models, Eclipse JDT requires a workspace directory to store:

Search indexes for fast symbol lookup
Compilation state and caches
Project metadata

Workspaces Are Outside Your Source

JavaLens creates its workspace outside your source project to keep your codebase clean:

code

Your Java Project (unchanged)
├── src/main/java/
├── pom.xml
└── (no Eclipse files added)

JavaLens Workspace (specified by -data)
└── {session-uuid}/
    ├── .metadata/          <- JDT indexes and state
    └── javalens-project/   <- Links to your source (not copies)

Why this matters:

No pollution: Your source tree stays clean—no .project or .classpath files
No conflicts: Works alongside any build system without interference
Session isolation: Each MCP session gets its own workspace, enabling concurrent analysis

Session Lifecycle

JavaLens starts and creates a unique workspace: {base}/{uuid}/
load_project creates linked folders pointing to your source
JDT builds indexes in the workspace (not in your project)
When the session ends, the workspace is cleaned up

Tools

Tool	Description
`search_symbols`	Search types, methods, fields by glob pattern
`go_to_definition`	Navigate to symbol definition
`find_references`	Find all usages of a symbol
`find_implementations`	Find interface/class implementations
`get_type_hierarchy`	Get inheritance chain
`get_document_symbols`	Get all symbols in a file
`get_symbol_info`	Get detailed symbol information at position
`get_type_at_position`	Get type details at cursor
`get_method_at_position`	Get method details at cursor
`get_field_at_position`	Get field details at cursor

Fine-Grained Reference Search (9 tools)

These use JDT's unique reference type constants—not available through LSP:

Tool	Description
`find_annotation_usages`	Find all `@Annotation` usages
`find_type_instantiations`	Find all `new Type()` calls
`find_casts`	Find all `(Type) expr` casts
`find_instanceof_checks`	Find all `x instanceof Type`
`find_throws_declarations`	Find all `throws Exception` in signatures
`find_catch_blocks`	Find all `catch(Exception e)` blocks
`find_method_references`	Find all `Type::method` expressions
`find_type_arguments`	Find all `List<Type>` usages
`find_reflection_usage`	Find `Class.forName()`, `Method.invoke()`, and other reflection calls

Analysis (20 tools)

Tool	Description
`get_diagnostics`	Get compilation errors and warnings
`validate_syntax`	Fast syntax-only validation
`get_call_hierarchy_incoming`	Find all callers of a method
`get_call_hierarchy_outgoing`	Find all methods called by a method
`find_field_writes`	Find where fields are mutated
`find_tests`	Discover JUnit/TestNG test methods
`find_unused_code`	Find unused private members
`find_unreachable_code`	Project-wide dead code — members unreachable from any main method or test, over the whole-program call graph
`find_affected_tests`	The tests that exercise a symbol, directly or transitively — the set to run after changing it
`find_possible_bugs`	Detect null risks, empty catches, resource leaks
`get_hover_info`	Get documentation/signature for symbol
`get_javadoc`	Get parsed Javadoc
`get_signature_help`	Get method signature at call site
`get_enclosing_element`	Get containing method/class at position
`analyze_change_impact`	Blast radius — direct call sites by depth, or the full transitive closure over the project graph (`transitive=true`)
`analyze_data_flow`	Variable read/write/declaration tracking within a method; opt-in `followCalls` tracks null/taint facts across calls to sinks
`analyze_control_flow`	Branching, loops, return/throw points, nesting depth
`get_di_registrations`	Find Spring DI registrations (@Component, @Bean, @Autowired, @Inject)
`get_jpa_model`	Assembled JPA entity model — tables, id fields, relationships with resolved targets and mappedBy sides
`get_http_endpoints`	Assembled HTTP route table — Spring and JAX-RS paths composed from class prefixes, mapped to handler methods

Compound Analysis (4 tools)

Combine multiple queries to reduce round-trips:

Tool	Description
`analyze_file`	Get imports, types, diagnostics in one call
`analyze_type`	Get members, hierarchy, usages, diagnostics
`analyze_method`	Get signature, callers, callees, overrides
`get_type_usage_summary`	Get instantiations, casts, instanceof counts

Refactoring (16 tools)

All refactoring tools return text edits (and new-file content where a refactoring creates one) rather than applying changes directly:

Tool	Description
`rename_symbol`	Rename across entire project
`organize_imports`	Sort and clean imports
`extract_variable`	Extract expression to local variable
`extract_method`	Extract code block to new method
`extract_constant`	Extract to `static final` field
`extract_interface`	Create interface from class methods
`extract_superclass`	Move a member into a newly created superclass
`inline_variable`	Replace variable with its initializer
`inline_method`	Replace call with method body
`change_method_signature`	Modify params/return, update all callers
`convert_anonymous_to_lambda`	Convert anonymous class to lambda
`encapsulate_field`	Generate accessors and rewrite all direct field accesses
`pull_up`	Move a member into the superclass
`push_down`	Move a member into the subclasses
`introduce_parameter_object`	Bundle a method's parameters into a new class, updating callers
`move_type_to_new_file`	Move a nested type into its own top-level file

Quick Fixes (5 tools)

Tool	Description
`suggest_imports`	Find import candidates for unresolved type
`get_quick_fixes`	List available fixes for problem at position
`apply_quick_fix`	Apply fix by ID (add import, remove import, add throws, try-catch)
`apply_cleanup`	Apply one of 10 JDT clean-ups (convert loops, pattern matching, switch expressions, text blocks, ...) and return rewritten source
`diagnose_and_fix`	Diagnose a file and return each problem's top quick-fix edits in one call

Metrics (5 tools)

Tool	Description
`get_complexity_metrics`	Cyclomatic/cognitive complexity, LOC per method
`get_dependency_graph`	Package/type dependencies as nodes and edges
`find_circular_dependencies`	Detect package cycles using Tarjan's SCC algorithm
`find_large_classes`	Find types exceeding method/field/line count thresholds
`find_naming_violations`	Check against Java naming conventions

Project & Infrastructure (6 tools)

Tool	Description
`health_check`	Server status and capabilities
`load_project`	Load Maven/Gradle/Bazel/plain Java project
`get_project_structure`	Get package hierarchy
`get_classpath_info`	Get classpath entries
`get_type_members`	Get members by type name
`get_super_method`	Find overridden method in superclass

Usage

Basic Workflow

code

1. load_project(projectPath="/path/to/java/project")
2. search_symbols(query="*Service", kind="Class")
3. find_references(filePath="...", line=10, column=15)
4. analyze_type(typeName="com.example.UserService")

Coordinate System

All line/column parameters are zero-based:

Line 0, Column 0 = first character of file

Path Handling

Response paths are relative by default
All paths use forward slashes for cross-platform consistency
Input paths can be relative or absolute

Important Notes

Disk Synchronization

Every answer is verified against the files on disk at query time. Before any tool logic runs, JavaLens content-hashes the known source files, detects edits, additions, and deletions (the agent reports nothing — the server discovers changes itself), repairs exactly what changed, waits for the search index to absorb the repair, and only then answers. There is no file watcher and no background thread — verification is synchronous inside the query the agent issued, so there are no race conditions.

The agent's loop is just: edit → query.

code

1. Use JavaLens tools to analyze
2. Write changes to files
3. Use JavaLens tools to verify — answers already reflect the changes

load_project is needed only on first use, when a response reports RELOAD_REQUIRED (a build file like pom.xml changed, so the classpath must be rebuilt), or to rebuild everything from scratch. If verification itself fails, the query returns VERIFICATION_FAILED rather than an unverified answer.

Cost: verification is hash-based and parallel — measured per query at ~2 ms for a 72-file project, ~25 ms at 1,000 files, ~180 ms at 10,000 files. Repairs cost only what changed (one edited file reconciles in well under a second), never a full reindex.

Manual mode: set JAVALENS_DISK_SYNC=manual to restore the pre-1.5.0 contract — answers reflect the last load and the agent calls load_project after editing files. Tool descriptions and the MCP instructions field always state the active contract, and health_check reports it as diskSync.

Refactoring Returns Edits

Refactoring tools return text edits but don't modify files. This gives visibility into what would change before applying.

Session Isolation

Each MCP session is independent with its own workspace UUID. Multiple sessions can analyze the same project concurrently.

Build System Support

JavaLens loads three real build systems plus plain Java directories. Each is exercised end-to-end in CI against synthetic real-shaped fixtures (multi-module reactors with cross-module deps, real external libraries, annotation processors).

System	Detection	Single-module	Multi-module / multi-project	Compiler compliance from build files	Generated sources	Annotation processors
Maven	`pom.xml`	✅	✅ (reactor classpath aggregation, cross-module navigation)	✅ (`maven.compiler.release`/`source`/`target`)	✅ (`target/generated-sources/*`)	✅ (`<annotationProcessorPaths>` across the whole reactor)
Gradle	`build.gradle` / `build.gradle.kts`	✅	✅ (`settings.gradle include` parsed; per-subproject classpaths unioned)	✅ (`sourceCompatibility`)	✅ (`build/generated/sources/<task>/main/java`)	✅ (`annotationProcessor` configuration)
Bazel	`MODULE.bazel` / `WORKSPACE.bazel` / `WORKSPACE`	✅	✅ (every `BUILD.bazel` package scanned for sources; `bazel-bin` ↔ `bazel-out` symlink dedup)	✅ (`javacopts` `-source`/`-target`/`--release` parsed across `BUILD.bazel` files)	n/a (Bazel actions write into `bazel-bin/`, not `target/generated-sources/`)	✅ (any classpath jar with `META-INF/services/javax.annotation.processing.Processor` is auto-registered)
Plain Java	`src/` directory	✅	n/a	✅ (falls back to `Runtime.version().feature()` when no build file)	n/a	n/a

Subprocess invocations of mvn / gradle happen during project load. If a tool is missing or fails, JavaLens surfaces a structured LoadWarning (e.g. MAVEN_SUBPROCESS_FAILED, GRADLE_SUBPROCESS_FAILED, COMPLIANCE_LEVEL_UNKNOWN) in the load_project response so callers know analysis quality is degraded rather than silently getting an empty classpath.

Configuration

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

Building from Source

bash

git clone https://github.com/pzalutski-pixel/javalens-mcp.git
cd javalens-mcp
./mvnw clean verify

Distributions are output to org.javalens.product/target/products/.

Build Requirements

Java 21+ (server runtime)
Maven 3.9+ (wrapper included as ./mvnw)

To run the full test suite (which includes end-to-end tests against real Maven, Gradle, and Bazel builds), the corresponding tools must also be on PATH:

Maven (provided by the wrapper)
Gradle 8+
Bazel 9+ (or bazelisk)

Tests gracefully skip when a tool is missing on a developer machine. Set JAVALENS_TESTS_REQUIRE_TOOLS=true to flip the gate: missing tools cause a hard failure instead of a skip. CI runs with this flag set so any provisioning gap surfaces as a real failure rather than weakening the suite silently.

Testing

bash

# Full suite, gentle (missing tools skip)
./mvnw verify

# Full suite, strict (missing tools fail; what CI does)
JAVALENS_TESTS_REQUIRE_TOOLS=true ./mvnw verify

Build-system coverage is structured as focused per-bug tests plus realistic end-to-end tests. The end-to-end tests load a single representative project per build system that exercises every fix in one pass — multi-module Maven with Lombok APT and cross-module references; multi-project Gradle with annotation processors; multi-target Bazel with cross-target deps. CI runs them on Linux, macOS, and Windows.

Architecture

mermaid

flowchart TD
    Client["<b>MCP Client</b>"]
    MCP["<b>org.javalens.mcp</b><br/>McpProtocolHandler → ToolRegistry → 75 Tools"]
    Core["<b>org.javalens.core</b><br/>JdtServiceImpl → WorkspaceManager, SearchService"]
    JDT["<b>Eclipse JDT Core</b> (via OSGi / Equinox)<br/>IWorkspace, IJavaProject, SearchEngine, ASTParser"]

    Client -->|"JSON-RPC over stdio"| MCP
    MCP --> Core
    Core --> JDT

License

MIT License - see LICENSE for details.

Install

Configuration

Environment variables

JAVA_PROJECT_PATH

Auto-load project on startup

JAVALENS_TIMEOUT_SECONDSdefault 30

Operation timeout in seconds

JAVALENS_LOG_LEVELdefault INFO

Log level: TRACE, DEBUG, INFO, WARN, ERROR

claude_desktop_config.json

{
  "mcpServers": {
    "javalens": {
      "command": "npx",
      "args": [
        "-y",
        "javalens-mcp@1.5.1"
      ],
      "env": {
        "JAVA_PROJECT_PATH": "<YOUR_JAVA_PROJECT_PATH>",
        "JAVALENS_TIMEOUT_SECONDS": "30",
        "JAVALENS_LOG_LEVEL": "INFO"
      }
    }
  }
}

Topics

JavaLens: AI-First Code Analysis for Java

Built for AI Agents

Compiler-Accurate Analysis

AI Training Bias Warning

What is JavaLens?

Why Not LSP?

Installation

Prerequisites

Install from GitHub Releases (recommended — Java only)

Install via npm (requires Node.js 18+)

Configure MCP Client

Auto-Load a Project

How Workspaces Work

Workspaces Are Outside Your Source

Session Lifecycle

Tools

Navigation (10 tools)

Fine-Grained Reference Search (9 tools)

Analysis (20 tools)

Compound Analysis (4 tools)

Refactoring (16 tools)

Quick Fixes (5 tools)

Metrics (5 tools)

Project & Infrastructure (6 tools)

Usage

Basic Workflow

Coordinate System

Path Handling

Important Notes

Disk Synchronization

Refactoring Returns Edits

Session Isolation

Build System Support

Configuration

Building from Source

Build Requirements

Testing

Architecture

License

Install

Configuration