JavaLens

JavaLens：面向 AI 的 Java 代码分析

一个 MCP 服务，提供 75 种 Java 语义分析工具，直接基于 Eclipse JDT 构建，实现编译器级别的代码理解。

专为 AI Agent 打造

JavaLens 的存在，是因为AI 系统需要编译器级别的洞察，而阅读源文件无法提供这些洞察。AI 使用 grep 或 Read 查找方法的使用位置时，无法区分：

• 方法调用与无关类中同名的方法
• 字段读取与字段写入
• 接口实现与无关类
• 向某个类型进行的类型转换与对该类型的其他引用

这会导致错误的重构、遗漏使用位置，以及对代码行为理解不完整。

编译器级别的分析

JavaLens 基于 Eclipse JDT（Eclipse IDE 的同款引擎），提供编译器级别的代码分析。与文本搜索不同，JDT 能够理解：

• 跨继承层次结构的类型解析
• 方法重载与重写
• 泛型类型参数
• 导入解析与类路径依赖
• 从 1.1 版到 Java 25 的 Java 源码（Markdown Javadoc、模块导入、精简源文件、灵活的构造函数主体）
• Lombok 生成的成员——内置 Agent 可解析 @Data 访问器等成员，因此不会将使用这些成员的代码标记为未定义

**示例：**查找所有调用 UserService.save() 的位置：

方式	结果
grep "save("	返回 47 条匹配结果，包括 orderService.save()、saveButton 和注释
find_references	恰好返回 12 次对 UserService.save() 的调用

AI 训练偏差警告

⚠️ 致 AI 开发者和用户的重要提示

即使语义分析能提供更好的结果，AI 模型也可能因训练偏差而偏向原生工具（Grep、Read、LSP），而非 MCP 服务工具。这是因为：

1. 训练数据中包含大量 grep／文本搜索模式
2. 在模型的经验中，原生工具“始终可用”
3. 模型可能无法识别语义分析何时更胜一筹

为了获得最佳结果：

在项目说明或系统提示词中添加指导内容（例如，Claude Code 的 CLAUDE.md）：

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

什么是 JavaLens？

JavaLens 是一个 MCP 服务，可帮助 AI 助手深入理解 Java 代码库。它提供语义分析、导航、重构和代码智能工具，功能远超简单的文本搜索。

为什么不用 LSP？

Language Server Protocol 是为 IDE 自动补全和基本导航而设计的，并非为需要深入语义分析的 AI Agent 工作流而设计。

功能	原生 LSP	JavaLens
查找所有 @Annotation 的使用位置	❌	✅
查找所有 new Type() 实例化	❌	✅
查找所有向某个类型进行的类型转换	❌	✅
区分字段读取与写入	❌	✅
检测循环包依赖	❌	✅
计算圈复杂度	❌	✅
查找未使用的私有方法	❌	✅
检测可能的空指针错误	❌	✅
从入口点分析整个项目中死代码的可达性	❌	✅
传递式查找测试某个符号的测试	❌	✅

JavaLens 通过 OSGi 直接封装 Eclipse JDT Core，提供：

• 细粒度引用类型：精确查找类型转换、注解、throws 子句、catch 块、instanceof 检查、方法引用和类型参数
• 区分读写访问：追踪字段在何处被修改，而不只是读取
• 索引搜索：JDT 在加载时预先构建索引，因此符号／引用查询无需遍历源文件
• 完整的 AST 访问能力：可直接操作 AST，以执行复杂重构

安装

前置条件

• Java 21 或更高版本（必须位于 PATH 中，或设置 JAVA_HOME）——两种安装方式都需要。
• Node.js 18+——仅在使用下方的 npm/npx 安装方式时需要。使用直接下载方式时可跳过。

JavaLens 是一个分析服务，而非编译器。它使用 Eclipse JDT 2025-12 解析并理解 1.1 至 25 版本的 Java 源代码。Java 21 仅作为服务运行时的要求。

从 GitHub Releases 安装（推荐——仅需 Java）

如果你已经安装了 Java 21，但没有 Node.js，这是最简单的方式。从 Releases 下载：

平台	文件
所有平台	javalens.zip 或 javalens.tar.gz

解压到你选择的位置（例如 /opt/javalens 或 C:\javalens）。然后将 MCP 客户端指向捆绑的 jar——请参阅下方的配置 MCP 客户端。

通过 npm 安装（需要 Node.js 18+）

如果你已经安装了 Node.js，首次运行时，npx 会下载并缓存 JavaLens 发行包（约 23 MB）：

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

配置 MCP 客户端

将以下内容添加到 MCP 配置中（例如 Claude Code 的 .mcp.json）：

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

-data 参数指定 JavaLens 存储工作区元数据的位置。请参阅下方的工作区的工作方式。

自动加载项目

设置 JAVA_PROJECT_PATH，即可在服务启动时自动加载项目：

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

注意： 项目会在后台异步加载。加载期间，MCP 服务会立即响应。使用 health_check 监控加载状态——加载完成前会显示 "project.status": "loading"，就绪后则显示 "loaded"。

工作区的工作方式

与内存中的代码模型不同，Eclipse JDT 需要一个工作区目录来存储：

• 用于快速符号查找的搜索索引
• 编译状态和缓存
• 项目元数据

工作区位于源代码目录之外

JavaLens 会在你的源代码项目之外创建工作区，以保持代码库整洁：

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)

这很重要，原因如下：

1. 不会污染项目：源代码树保持整洁——不会出现 .project 或 .classpath 文件
2. 不会产生冲突：可与任何构建系统协同工作，互不干扰
3. 会话隔离：每个 MCP 会话都有独立的工作区，支持并发分析

会话生命周期

1. JavaLens 启动并创建唯一的工作区：{base}/{uuid}/
2. load_project 创建指向源代码的链接文件夹
3. JDT 在工作区中（而非项目中）构建索引
4. 会话结束时，工作区会被清理

工具

导航（10 个工具）

工具	描述
search_symbols	按 glob 模式搜索类型、方法和字段
go_to_definition	跳转到符号定义
find_references	查找符号的所有用法
find_implementations	查找接口/类的实现
get_type_hierarchy	获取继承链
get_document_symbols	获取文件中的所有符号
get_symbol_info	获取指定位置的详细符号信息
get_type_at_position	获取光标处的类型详情
get_method_at_position	获取光标处的方法详情
get_field_at_position	获取光标处的字段详情

精细化引用搜索（9 个工具）

这些工具使用 JDT 独有的引用类型常量，LSP 不提供这些常量：

工具	描述
find_annotation_usages	查找所有 @Annotation 用法
find_type_instantiations	查找所有 new Type() 调用
find_casts	查找所有 (Type) expr 强制类型转换
find_instanceof_checks	查找所有 x instanceof Type
find_throws_declarations	查找签名中的所有 throws Exception
find_catch_blocks	查找所有 catch(Exception e) 代码块
find_method_references	查找所有 Type::method 表达式
find_type_arguments	查找所有 List<Type> 用法
find_reflection_usage	查找 Class.forName()、Method.invoke() 及其他反射调用

分析（20 个工具）

工具	描述
get_diagnostics	获取编译错误和警告
validate_syntax	快速进行纯语法验证
get_call_hierarchy_incoming	查找某个方法的所有调用方
get_call_hierarchy_outgoing	查找某个方法调用的所有方法
find_field_writes	查找字段被修改的位置
find_tests	发现 JUnit/TestNG 测试方法
find_unused_code	查找未使用的私有成员
find_unreachable_code	项目范围的死代码——在整个程序调用图中，无法从任何主方法或测试到达的成员
find_affected_tests	直接或传递地测试某个符号的测试——更改该符号后应运行的测试集合
find_possible_bugs	检测空值风险、空 catch 和资源泄漏
get_hover_info	获取符号的文档/签名
get_javadoc	获取解析后的 Javadoc
get_signature_help	获取调用位置的方法签名
get_enclosing_element	获取指定位置所属的方法/类
analyze_change_impact	影响范围——按深度查找直接调用位置，或遍历项目图中的完整传递闭包（transitive=true）
analyze_data_flow	跟踪方法内变量的读取/写入/声明；选择启用 followCalls 后，可跨调用跟踪到达汇点的空值/污点信息
analyze_control_flow	分支、循环、return/throw 位置、嵌套深度
get_di_registrations	查找 Spring DI 注册（@Component、@Bean、@Autowired、@Inject）
get_jpa_model	汇总后的 JPA 实体模型——表、id 字段、关联及其解析后的目标和 mappedBy 端
get_http_endpoints	汇总后的 HTTP 路由表——由类前缀组合而成的 Spring 和 JAX-RS 路径，以及对应的处理方法

组合分析（4 个工具）

组合多个查询以减少往返次数：

工具	描述
analyze_file	一次调用获取导入、类型和诊断信息
analyze_type	获取成员、层级结构、用法和诊断信息
analyze_method	获取签名、调用方、被调用方和重写方法
get_type_usage_summary	获取实例化、强制类型转换和 instanceof 的计数

重构（16 个工具）

所有重构工具返回文本编辑（如果重构会创建新文件，也会返回新文件内容），而不是直接应用更改：

工具	描述
rename_symbol	在整个项目中重命名
organize_imports	排序并清理导入
extract_variable	将表达式提取为局部变量
extract_method	将代码块提取为新方法
extract_constant	提取为 static final 字段
extract_interface	根据类方法创建接口
extract_superclass	将成员移入新创建的超类
inline_variable	用变量的初始值替换变量
inline_method	用方法体替换调用
change_method_signature	修改参数或返回值，并更新所有调用方
convert_anonymous_to_lambda	将匿名类转换为 lambda
encapsulate_field	生成访问器，并重写所有直接字段访问
pull_up	将成员移入超类
push_down	将成员移入子类
introduce_parameter_object	将方法参数封装到新类中，并更新调用方
move_type_to_new_file	将嵌套类型移入独立的顶层文件

快速修复（5 个工具）

工具	描述
suggest_imports	为无法解析的类型查找导入候选项
get_quick_fixes	列出指定位置问题的可用修复
apply_quick_fix	按 ID 应用修复（添加导入、移除导入、添加 throws、try-catch）
apply_cleanup	应用 10 种 JDT 清理操作之一（转换循环、模式匹配、switch 表达式、文本块等），并返回重写后的源代码
diagnose_and_fix	诊断文件，并通过一次调用返回每个问题的首选快速修复编辑

指标（5 个工具）

工具	描述
get_complexity_metrics	圈复杂度、认知复杂度、每个方法的代码行数
get_dependency_graph	将包和类型依赖表示为节点和边
find_circular_dependencies	使用 Tarjan SCC 算法检测包循环依赖
find_large_classes	查找方法数、字段数或行数超过阈值的类型
find_naming_violations	检查是否符合 Java 命名约定

项目与基础设施（6 个工具）

工具	描述
health_check	服务状态和功能
load_project	加载 Maven/Gradle/Bazel/纯 Java 项目
get_project_structure	获取包层次结构
get_classpath_info	获取类路径条目
get_type_members	按类型名称获取成员
get_super_method	查找超类中被重写的方法

用法

基本工作流

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

坐标系统

所有行号/列号参数均从 0 开始：

• 行 0，列 0 = 文件的第一个字符

路径处理

• 默认情况下，响应中的路径为相对路径
• 所有路径均使用正斜杠，以确保跨平台一致性
• 输入路径可以是相对路径或绝对路径

重要说明

磁盘同步

每个回答都会在查询时根据磁盘上的文件进行验证。在运行任何工具逻辑之前，JavaLens 会对已知源文件进行内容哈希，检测编辑、添加和删除（Agent 无需报告任何内容——服务会自行发现更改），仅修复发生变化的部分，等待搜索索引吸收修复，然后才给出回答。这里没有文件监视器，也没有后台线程——验证会在 Agent 发起的查询中同步执行，因此不会出现竞争条件。

Agent 的循环只有：编辑 → 查询。

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

只有在首次使用时、响应报告 RELOAD_REQUIRED 时（例如 pom.xml 等构建文件发生更改，必须重建类路径），或需要从头重建所有内容时，才需要使用 load_project。如果验证本身失败，查询会返回 VERIFICATION_FAILED，而不是未经验证的回答。

**开销：**验证基于哈希并行执行——实测每次查询耗时约为：72 个文件的项目约 2 ms，1,000 个文件约 25 ms，10,000 个文件约 180 ms。修复只需处理发生变化的内容（编辑单个文件后，协调时间远少于一秒），不会进行完整的重新索引。

**手动模式：**设置 JAVALENS_DISK_SYNC=manual，即可恢复 1.5.0 之前的约定——回答反映上次加载的内容，编辑文件后由 Agent 调用 load_project。工具说明和 MCP instructions 字段始终会说明当前生效的约定，health_check 则会通过 diskSync 报告该约定。

重构返回编辑内容

重构工具会返回文本编辑内容，但不会修改文件。这样可以在应用更改之前查看将要进行的修改。

会话隔离

每个 MCP 会话彼此独立，并拥有自己的工作区 UUID。多个会话可以并发分析同一个项目。

构建系统支持

JavaLens 支持加载三种真实构建系统以及普通 Java 目录。每种系统都会在 CI 中使用符合真实项目结构的合成夹具进行端到端测试（包括具有跨模块依赖项的多模块构建、真实外部库和注解处理器）。

系统	检测方式	单模块	多模块 / 多项目	从构建文件读取编译器兼容级别	生成的源文件	注解处理器
Maven	pom.xml	✅	✅（包括 reactor、../ 模块，以及 Maven 有效模型报告的各模块类路径；reactor 模块会作为源代码关联，绝不会作为 jar）	✅（各模块的级别按照 maven-compiler-plugin 的应用方式确定：优先使用 release，再使用 source；插件配置优先于属性；从父级继承）	✅（各模块有效构建目录下 generated-sources 的子目录）	✅（<annotationProcessorPaths>，在 Maven 本地仓库中解析）
Gradle	settings.gradle(.kts) / build.gradle(.kts)	✅	✅（包括项目、自定义 projectDir、包含的构建、源集和 Gradle 报告的类路径）	✅（各项目的 sourceCompatibility）	✅（Gradle 报告的生成源文件目录）	✅（annotationProcessor 配置）
Bazel	MODULE.bazel / WORKSPACE.bazel / WORKSPACE	✅	✅（通过 bazel query 获取 Java 目标及其源文件；根据每个目标的 javac 操作获取类路径）	✅（各 javac 操作采用的级别：工具链默认值、.bazelrc 标志，然后是目标的 javacopts）	不适用（Bazel 操作会写入 bazel-bin/，而非 target/generated-sources/）	✅（各 javac 操作的处理器路径）
普通 Java	src/ 目录	✅	不适用	✅（没有构建文件时，回退到 Runtime.version().feature()）	不适用	不适用

JavaLens 会在加载期间直接向构建工具查询，并采用其返回的模型，不会向项目目录树写入任何内容：

• **Maven：**运行一次 help:effective-pom 和 dependency:build-classpath（使用 --fail-at-end）。无法解析的 Maven 模块（通常是依赖于同一构建中尚未安装的模块）会被标记为 BUILD_TOOL_FAILED；其余模型仍来自 Maven。仅在未激活配置文件中声明的模块，以及根 pom 旁边 settings.gradle 中的 Gradle 项目，仍会以 INCLUDED_OUTSIDE_BUILD 标记并保持链接。
• **Gradle：**运行一次带有初始化脚本的构建，报告项目、自定义 projectDir、包含的构建、源集、生成的源目录、类路径和各项目级别。
• **Bazel：**使用 bazel query 查询 Java 目标、源文件和构建文件；对每个 javac 操作运行 bazel aquery；运行 bazel info execution_root；所有命令均使用 --lockfile_mode=off。

当工具无法运行或未报告模型时，JavaLens 会将构建文件作为代码自行读取（注释和字符串不作声明：pom 按 XML 读取，Gradle 设置文件和 Bazel BUILD 文件通过词法分析器读取）；对于文件中未指定的内容，按约定布局模块，并报告 buildModel.source = static-read，同时发出 BUILD_MODEL_STATIC 警告，说明这种读取方式无法看到的内容。

任何构建读取的文件发生更改（包括加载后创建的文件，如 gradle.properties、版本目录、buildSrc、.mvn/maven.config、.bazelrc、.bzl 文件，以及根目录之外模块的 pom），下一次查询都会报告 RELOAD_REQUIRED 并指出该文件。

load_project 和 health_check 都会报告 buildModel 摘要（构建系统、结构来源：build-tool、static-read 或 convention、分析级别、模块）以及所有加载警告，因此无论 Agent 在何处查看，都能看到降级加载的情况，包括通过 JAVA_PROJECT_PATH 自动加载的项目。警告代码：

代码	含义
BUILD_TOOL_UNAVAILABLE / BUILD_TOOL_FAILED / BUILD_TOOL_TIMEOUT	构建工具无法启动、运行失败或超时；消息中包含其最后输出
BUILD_MODEL_STATIC	构建工具未报告模型，因此静态读取了构建文件；消息会说明这种方式无法看到的内容
MODULE_NOT_LOADED	未加载已声明的模块或子项目（目录缺失、路径无效）
MODULE_LAYOUT_ASSUMED	根据惯例假定了模块的源根目录
INCLUDED_OUTSIDE_BUILD	未由构建声明的常规源文件夹、未激活 Maven 配置文件中的模块，或 Maven 构建旁边的 Gradle 项目，仍会保持链接
COMPILED_OUTPUT_INCLUDED	模块的编译输出中包含没有源文件的类，并会保留在类路径中
COMPLIANCE_LEVEL_MIXED / COMPLIANCE_LEVEL_UNKNOWN / COMPLIANCE_LEVEL_UNSUPPORTED	模块声明的级别不同、未声明级别，或级别超出 JDT 支持范围
APT_PROCESSOR_JARS_MISSING	声明的注解处理器 JAR 缺失
BAZEL_NOT_BUILT	尚未构建类路径所需的 Bazel 输出
INDEX_INCOMPLETE / LIBRARY_INDEX_INCOMPLETE	修复后，JDT 的搜索索引仍缺少源文件或库；在问题持续期间，依赖索引的工具响应会指出这些内容
JRE_REGISTRATION_FAILED	无法向 JDT 注册 JDK
EARLIER_PROJECT_KEPT	无法移除先前加载时的工作区项目
TIMEOUT_SECONDS_INVALID	JAVALENS_TIMEOUT_SECONDS 超出范围或不是数字

配置

环境变量	说明	默认值
JAVA_PROJECT_PATH	启动时自动加载项目	（无）
JAVALENS_TIMEOUT_SECONDS	每次工具调用的时间限制，以秒为单位的整数，范围为 5 到 300（超出范围的值会被限制在范围内，其他值会被忽略，并分别产生 TIMEOUT_SECONDS_INVALID 加载警告）；超时的调用会返回 TIMEOUT。load_project 和 health_check 不受限制	（无：不限制）
JAVALENS_DISK_SYNC	strict（每个回答都与磁盘内容核对）或 manual（编辑后由 Agent 调用 load_project）	strict
JAVALENS_LOG_LEVEL	TRACE/DEBUG/INFO/WARN/ERROR（不区分大小写）；日志输出到 stderr，stdout 仅传输 JSON-RPC	INFO
JAVA_TOOL_OPTIONS	JVM 选项，例如大型项目可使用 -Xmx2g	（默认值：通过 eclipse.ini 设置为 512m）
JAVALENS_LOMBOK_JAR	启动时附加的 Lombok 代理 jar 路径；会覆盖捆绑的代理	（捆绑版）
JAVALENS_MAVEN_ARGS	用于读取模型的 Maven 运行的额外参数，例如 -Pextras -Dskip.x=true（按 shell 单词拆分）	（无）
JAVALENS_GRADLE_ARGS	用于读取模型的 Gradle 运行的额外参数，例如 -Penv=ci	（无）
JAVALENS_BAZEL_ARGS	用于 bazel aquery 和 bazel info 的额外构建标志，例如 --config=ci	（无）

从源代码构建

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

发布包输出到 org.javalens.product/target/products/。

构建要求

• Java 21+（服务运行时）
• Maven 3.9+（已包含包装器 ./mvnw）

要运行完整测试套件（包括针对真实 Maven、Gradle 和 Bazel 构建的端到端测试），相应工具也必须位于 PATH 中：

• Maven（由包装器提供）
• Gradle 8+
• Bazel 9+（或 bazelisk）

开发者机器上缺少工具时，测试会正常跳过。设置 JAVALENS_TESTS_REQUIRE_TOOLS=true 可启用严格检查：缺少工具时会直接失败，而不是跳过。CI 会设置此标志，因此任何环境配置缺失都会作为真实故障显现，而不会在不知情的情况下削弱测试套件。

测试

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

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

构建系统覆盖测试由针对具体缺陷的专项测试和真实场景端到端测试组成。端到端测试会为每种构建系统加载一个具有代表性的项目，并在一次测试中覆盖所有修复——包括带有 Lombok APT 和跨模块引用的多模块 Maven 项目、带有注解处理器的多项目 Gradle 项目，以及带有跨目标依赖的多目标 Bazel 项目。CI 会在 Linux 和 macOS 上运行这些测试；针对 Windows 换行符的测试会显式写入 CRLF 文件。

架构

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

许可证

MIT 许可证——详情请参阅 LICENSE。