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

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

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.

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