JLens MCP 专家级导航指南 (V1.1.1)
JLens 是一个专门为 AI Agent 设计的 Model Context Protocol (MCP) 服务器，它通过真实的反射分析和字节码解析，赋予 Agent 深度理解 Java 工程的能力。相比于简单的文本搜索，JLens 能够识别类继承关系、方法签名、可见性修饰符以及复杂的 Maven 依赖拓扑。
1. 核心工具与交互细节 (Protocol Details)
1.1 类检查 (inspect_java_class)
交互逻辑：
- •状态机响应：
- •
status: "SUCCESS"：解析成功。查看decompiledSource字段获取逻辑，查看methods和fields获取结构。 - •
status: "LOCAL_SOURCE"：重要！ 目标类属于当前工作区。此时应忽略元数据，直接通过响应中的sourceFile路径使用read_file工具阅读源码。 - •
status: "NOT_FOUND"：类不存在。检查suggestion字段，可能需要先执行build_module。
- •
- •关键参数：
- •
bypassCache: 当发现类结构与实际代码不符（可能刚修改过源码）时，设为true以绕过 GAV 缓存进行实时解析。
- •
1.2 分页搜索 (search_java_class)
分页协议：
- •结果解析：如果响应中
hasMore为true，则必须记录nextCursor。 - •后续请求：在下一次调用时传入
cursor: "<nextCursor>"，直到hasMore为false。搜索结果已按全限定名字典序排列，确保分页稳定性。
1.3 依赖分析 (list_module_dependencies)
元数据解析：
- •返回标准的 Maven 依赖模型。Agent 应当关注
scope字段（如test,provided）以判断类在运行时是否可用。
2. 场景化任务流 (Task-Driven Workflows)
场景 A：排查 NoClassDefFoundError 或方法找不到错误
- •定位依赖：调用
list_module_dependencies检查是否有多个版本的 Jar 包包含冲突的类。 - •版本隔离检查：利用
inspect_java_class的版本隔离特性，分别为不同模块上下文加载该类，对比methods列表，找出缺失的方法。 - •构建验证：修改 pom.xml 后，调用
build_module刷新本地仓库并验证构建是否通过。
场景 B：大规模代码重构辅助
- •全局搜索：使用
search_java_class配合通配符（如com.api.*Service）找到所有相关接口。 - •逐一检查：利用
list_class_fields快速提取所有实现类的私有字段，评估状态存储情况。 - •源码跳转：发现
LOCAL_SOURCE时，自动切换到read_file修改代码。
3. 执行策略 (Execution Strategy)
3.1 协议优先级
- •探测注册服务：首先检查环境是否存在
jlens-mcp-server。 - •直接请求：若存在，使用标准的 MCP
call_tool请求。
3.2 命令行 Fallback (无注册服务时)
若未找到注册服务，Agent 必须自主使用 shell 工具按以下格式执行：
NPM 模式 (首选):
powershell
npx -y @bhxch/jlens-mcp-server --tool <tool_name> --args '<json_arguments>'
Python 模式:
bash
uvx jlens-mcp-server --tool <tool_name> --args '<json_arguments>'
4. 性能与限制提示
- •GAV 缓存：JLens 会按
GroupId:ArtifactId:Version共享缓存。对于第三方库（如 Spring），不同项目的解析结果是通用的，响应通常在 100ms 内。 - •首次索引：在大型项目上首次运行
search_java_class可能会触发全量索引（约 60s），后续请求将进入毫秒级。 - •JDK 要求：底层运行环境必须为 Java 25+。