javalens

JavaLens is an MCP server that provides compiler-accurate, semantic analysis for Java code. Built on Eclipse JDT, it exposes a suite of tools for navigation, references, type analysis, and fine-grained code intelligence that go beyond traditional text-based search. With JavaLens, AI agents can reliably resolve symbol references, distinguish between reads and writes to fields, and locate casts, type instantiations, and other nuanced language constructs. The server supports a suite of 56 semantic analysis tools organized into navigation, fine-grained reference search, and analysis capabilities to empower automated code understanding and refactoring workflows.

To use the server, run it with Java (as shown in the configuration) and connect your MCP client. You can leverage tools such as find_references, find_implementations, get_type_at_position, and go_to_definition for precise symbol analysis. The fine-grained set includes find_type_instantiations (new Type()), find_casts, find_instanceof_checks, and find_throws_declarations, among others. When a project is loaded, JavaLens builds and maintains a workspace outside your source to store indexes and metadata, ensuring your repository stays clean while enabling fast, accurate analysis. Use the health_check endpoint or status queries to monitor project loading status and readiness.

In practice, you can auto-load a project by configuring the environment variable JAVA_PROJECT_PATH and starting the server. The MCP client can then issue commands such as search_symbols, find_references, or get_symbol_info to gather context for AI reasoning, refactoring decisions, or code understanding tasks with compiler-backed accuracy.

Prerequisites:

• Java 21 or later installed and available on PATH, or JAVA_HOME set
• An MCP client library or tooling that can load an MCP configuration (e.g., Claude Code, integrated agent workflows)

1. Download the JavaLens MCP server:

• Visit the Releases page: https://github.com/pzalutski-pixel/javalens-mcp/releases
• Download the appropriate archive (javalens.zip or javalens.tar.gz)

2. Prepare the workspace directory:

• Create a location for workspaces, e.g. /path/to/javalens-workspaces
• Ensure the directory is writable by the user running the server

3. Run the server:

• Ensure you have Java installed

• Start the server with a command similar to:

  java -jar /path/to/javalens/javalens.jar -data /path/to/javalens-workspaces

4. (Optional) Auto-load a project at startup:

• If you want the MCP client to auto-load a project, set JAVA_PROJECT_PATH in the environment or configuration that points to your Java project

• Example in MCP config (shown in the README):

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

Tips and common considerations:

• Workspace management: JavaLens stores indexes and state in a dedicated workspace directory outside your source. This avoids polluting your repo with IDE metadata and supports session isolation for concurrent analyses.
• Auto-loading: If you enable JAVA_PROJECT_PATH, the server loads the project in the background. Use health_check to monitor whether the project is still loading or has finished (status transitions from loading to loaded).
• Environment variables: JAVA_PROJECT_PATH is optional but powerful for automatic project loading. You can extend env with other variables if needed for your workflow.
• PATH and JAVA_HOME: Ensure Java 21+ is accessible in the environment where the MCP server runs. If using JAVA_HOME, set it accordingly.
• Observability: Logs and health endpoints (e.g., health_check) can help diagnose startup or loading issues. If a project fails to load, verify the workspace path and project linkage in the -data workspace.
• Compatibility: The server relies on Eclipse JDT Core via OSGi. If you run into symbol resolution edge cases, ensure your project’s dependencies and classpath are properly represented in the linked workspace.