JavaLens: AI-First Code Analysis for Java

An MCP server providing 63 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

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

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:

1. Training data contains extensive grep/text-search patterns
2. Native tools are "always available" in the model's experience
3. 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):

## 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.

JavaLens wraps Eclipse JDT Core directly via OSGi, providing:

• 16 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: 10x faster than AST walking for large codebases
• Full AST access: Direct manipulation for complex refactorings

Installation

Prerequisites

• Java 21 or later (must be on PATH or set JAVA_HOME)

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

Install via npm

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

The distribution (~19 MB) is downloaded and cached on first run.

Download

Download from Releases:

Extract to a location of your choice (e.g., /opt/javalens or C:\javalens).

Configure MCP Client

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

{
  "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:

{
  "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:

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:

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

Session Lifecycle

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

Tools

Navigation (10 tools)

Fine-Grained Reference Search (9 tools)

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

Analysis (16 tools)

Compound Analysis (4 tools)

Combine multiple queries to reduce round-trips:

Refactoring (10 tools)

All refactoring tools return text edits rather than applying changes directly:

Quick Fixes (3 tools)

Metrics (5 tools)

Project & Infrastructure (6 tools)

Usage

Basic Workflow

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

No Live File Watching

JavaLens analyzes code at load time and does not watch for file changes. This is by design—the AI coding agent is responsible for maintaining synchronization:

Why not automatic watching?

1. AI agents make discrete edits with clear boundaries—auto-sync adds complexity without benefit
2. The agent controls when analysis should reflect changes
3. Avoids race conditions between file writes and index updates

Recommended pattern:

1. Use JavaLens tools to analyze
2. Write changes to files
3. Call load_project to refresh
4. Use JavaLens tools to verify changes

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

Configuration

Building from Source

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)

Architecture

┌─────────────────────────────────────────────────────────┐
│                      MCP Client                          │
└─────────────────────────────────────────────────────────┘
                            │ JSON-RPC over stdio
┌─────────────────────────────────────────────────────────┐
│  org.javalens.mcp                                        │
│    McpProtocolHandler → ToolRegistry → 56 Tools          │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│  org.javalens.core                                       │
│    JdtServiceImpl → WorkspaceManager, SearchService      │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│  Eclipse JDT Core (via OSGi/Equinox)                     │
│    IWorkspace, IJavaProject, SearchEngine, ASTParser     │
└─────────────────────────────────────────────────────────┘

License

MIT License - see LICENSE for details.