Java语义分析MCP服务

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

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

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.

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:

Installation

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:

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.

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

JavaLens asks the build tool itself during the load and takes the model from its answer, writing nothing into the project tree:

• Maven: one run (--fail-at-end) of help:effective-pom and dependency:build-classpath. A module Maven cannot resolve (one that depends on a module of the same build that is not installed, typically) is named by a BUILD_TOOL_FAILED; the rest of the model is still Maven's. Modules declared only in an inactive profile, and Gradle projects of a settings.gradle beside the root pom, stay linked with INCLUDED_OUTSIDE_BUILD.
• Gradle: one run with an init script that reports projects, custom projectDirs, included builds, source sets, generated-source directories, classpath and per-project levels.
• Bazel: bazel query for the Java targets and sources and the build files, bazel aquery for each javac action, bazel info execution_root, all with --lockfile_mode=off.

When the tool cannot run or reports no model, JavaLens reads the build files itself as code (comments and strings declare nothing: poms as XML, Gradle settings and Bazel BUILD files through a lexer), lays modules out by convention where the files say nothing, and reports buildModel.source = static-read with a BUILD_MODEL_STATIC warning naming what such a read cannot see.

A change to any file the build reads, including one created after the load (gradle.properties, a version catalog, buildSrc, .mvn/maven.config, .bazelrc, a .bzl file, the pom of a module outside the root), makes the next query report RELOAD_REQUIRED naming it.

load_project and health_check both report a buildModel summary (build system, where the structure came from: build-tool, static-read or convention, analysis level, modules) and every load warning, so a degraded load is visible wherever the agent looks, including projects auto-loaded through JAVA_PROJECT_PATH. Warning codes:

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

Usage

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.

Configuration

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

Fine-Grained Reference Search (9 tools)

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

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")