Skip to main content
Glama

JavaLens: AI-First Code Analysis for Java

GitHub release License: MIT Java 21

An MCP server providing 75 semantic analysis tools for Java, built directly on Eclipse JDT for compiler-accurate code understanding.

Built for AI Agents

JavaLens exists because AI systems need compiler-accurate insights that reading source files cannot provide. When an AI uses grep or Read to find usages of a method, it cannot distinguish:

  • A method call from a method with the same name in an unrelated class

  • A field read from a field write

  • An interface implementation from an unrelated class

  • A cast to a type from other references to that type

This leads to incorrect refactorings, missed usages, and incomplete understanding of code behavior.

Related MCP server: java-jdtls-mcp-server

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:

Approach

Result

grep "save("

Returns 47 matches including orderService.save(), saveButton, comments

find_references

Returns exactly 12 calls to UserService.save()

AI Training Bias Warning

⚠️ Important for AI developers and users

AI models may exhibit trained bias toward native tools (Grep, Read, LSP) over MCP server tools, even when semantic analysis provides better results. This happens because:

  1. Training data contains extensive grep/text-search patterns

  2. Native tools are "always available" in the model's experience

  3. The model may not recognize when semantic analysis is superior

To get the best results:

Add guidance to your project instructions or system prompt (e.g., CLAUDE.md for Claude Code):

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

What is JavaLens?

JavaLens is an MCP server that gives AI assistants deep understanding of Java codebases. It provides semantic analysis, navigation, refactoring, and code intelligence tools that go beyond simple text search.

Why Not LSP?

Language Server Protocol was designed for IDE autocomplete and basic navigation—not for AI agent workflows that require deep semantic analysis.

Capability

Native LSP

JavaLens

Find all @Annotation usages

❌

✅

Find all new Type() instantiations

❌

✅

Find all casts to a type

❌

✅

Distinguish field reads from writes

❌

✅

Detect circular package dependencies

❌

✅

Calculate cyclomatic complexity

❌

✅

Find unused private methods

❌

✅

Detect possible null pointer bugs

❌

✅

Project-wide dead-code reachability from entry points

❌

✅

Find the tests that exercise a symbol, transitively

❌

✅

JavaLens wraps Eclipse JDT Core directly via OSGi, providing:

  • Fine-grained reference types: Find specifically casts, annotations, throws clauses, catch blocks, instanceof checks, method references, type arguments

  • Read vs write access distinction: Track where fields are mutated vs just read

  • Indexed search: JDT pre-builds an index at load time, so symbol/reference queries do not walk source files

  • Full AST access: Direct manipulation for complex refactorings

Installation

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.

This is the simplest path if you already have Java 21 and don't have Node.js. Download from Releases:

Platform

File

All platforms

javalens.zip or javalens.tar.gz

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.

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

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.

Auto-Load a Project

Set JAVA_PROJECT_PATH to auto-load a project when the server starts:

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

Note: Project loading happens asynchronously in the background. The MCP server responds immediately while the project loads. Use health_check to monitor loading status—it will show "project.status": "loading" until complete, then "loaded" when ready.

How Workspaces Work

Unlike in-memory code models, Eclipse JDT requires a workspace directory to store:

  • Search indexes for fast symbol lookup

  • Compilation state and caches

  • Project metadata

Workspaces Are Outside Your Source

JavaLens creates its workspace outside your source project to keep your codebase clean:

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)

Why this matters:

  1. No pollution: Your source tree stays clean—no .project or .classpath files

  2. No conflicts: Works alongside any build system without interference

  3. Session isolation: Each MCP session gets its own workspace, enabling concurrent analysis

Session Lifecycle

  1. JavaLens starts and creates a unique workspace: {base}/{uuid}/

  2. load_project creates linked folders pointing to your source

  3. JDT builds indexes in the workspace (not in your project)

  4. When the session ends, the workspace is cleaned up

Tools

Navigation (10 tools)

Tool

Description

search_symbols

Search types, methods, fields by glob pattern

go_to_definition

Navigate to symbol definition

find_references

Find all usages of a symbol

find_implementations

Find interface/class implementations

get_type_hierarchy

Get inheritance chain

get_document_symbols

Get all symbols in a file

get_symbol_info

Get detailed symbol information at position

get_type_at_position

Get type details at cursor

get_method_at_position

Get method details at cursor

get_field_at_position

Get field details at cursor

Fine-Grained Reference Search (9 tools)

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

Tool

Description

find_annotation_usages

Find all @Annotation usages

find_type_instantiations

Find all new Type() calls

find_casts

Find all (Type) expr casts

find_instanceof_checks

Find all x instanceof Type

find_throws_declarations

Find all throws Exception in signatures

find_catch_blocks

Find all catch(Exception e) blocks

find_method_references

Find all Type::method expressions

find_type_arguments

Find all List<Type> usages

find_reflection_usage

Find Class.forName(), Method.invoke(), and other reflection calls

Analysis (20 tools)

Tool

Description

get_diagnostics

Get compilation errors and warnings

validate_syntax

Fast syntax-only validation

get_call_hierarchy_incoming

Find all callers of a method

get_call_hierarchy_outgoing

Find all methods called by a method

find_field_writes

Find where fields are mutated

find_tests

Discover JUnit/TestNG test methods

find_unused_code

Find unused private members

find_unreachable_code

Project-wide dead code — members unreachable from any main method or test, over the whole-program call graph

find_affected_tests

The tests that exercise a symbol, directly or transitively — the set to run after changing it

find_possible_bugs

Detect null risks, empty catches, resource leaks

get_hover_info

Get documentation/signature for symbol

get_javadoc

Get parsed Javadoc

get_signature_help

Get method signature at call site

get_enclosing_element

Get containing method/class at position

analyze_change_impact

Blast radius — direct call sites by depth, or the full transitive closure over the project graph (transitive=true)

analyze_data_flow

Variable read/write/declaration tracking within a method; opt-in followCalls tracks null/taint facts across calls to sinks

analyze_control_flow

Branching, loops, return/throw points, nesting depth

get_di_registrations

Find Spring DI registrations (@Component, @Bean, @Autowired, @Inject)

get_jpa_model

Assembled JPA entity model — tables, id fields, relationships with resolved targets and mappedBy sides

get_http_endpoints

Assembled HTTP route table — Spring and JAX-RS paths composed from class prefixes, mapped to handler methods

Compound Analysis (4 tools)

Combine multiple queries to reduce round-trips:

Tool

Description

analyze_file

Get imports, types, diagnostics in one call

analyze_type

Get members, hierarchy, usages, diagnostics

analyze_method

Get signature, callers, callees, overrides

get_type_usage_summary

Get instantiations, casts, instanceof counts

Refactoring (16 tools)

All refactoring tools return text edits (and new-file content where a refactoring creates one) rather than applying changes directly:

Tool

Description

rename_symbol

Rename across entire project

organize_imports

Sort and clean imports

extract_variable

Extract expression to local variable

extract_method

Extract code block to new method

extract_constant

Extract to static final field

extract_interface

Create interface from class methods

extract_superclass

Move a member into a newly created superclass

inline_variable

Replace variable with its initializer

inline_method

Replace call with method body

change_method_signature

Modify params/return, update all callers

convert_anonymous_to_lambda

Convert anonymous class to lambda

encapsulate_field

Generate accessors and rewrite all direct field accesses

pull_up

Move a member into the superclass

push_down

Move a member into the subclasses

introduce_parameter_object

Bundle a method's parameters into a new class, updating callers

move_type_to_new_file

Move a nested type into its own top-level file

Quick Fixes (5 tools)

Tool

Description

suggest_imports

Find import candidates for unresolved type

get_quick_fixes

List available fixes for problem at position

apply_quick_fix

Apply fix by ID (add import, remove import, add throws, try-catch)

apply_cleanup

Apply one of 10 JDT clean-ups (convert loops, pattern matching, switch expressions, text blocks, ...) and return rewritten source

diagnose_and_fix

Diagnose a file and return each problem's top quick-fix edits in one call

Metrics (5 tools)

Tool

Description

get_complexity_metrics

Cyclomatic/cognitive complexity, LOC per method

get_dependency_graph

Package/type dependencies as nodes and edges

find_circular_dependencies

Detect package cycles using Tarjan's SCC algorithm

find_large_classes

Find types exceeding method/field/line count thresholds

find_naming_violations

Check against Java naming conventions

Project & Infrastructure (6 tools)

Tool

Description

health_check

Server status and capabilities

load_project

Load Maven/Gradle/Bazel/plain Java project

get_project_structure

Get package hierarchy

get_classpath_info

Get classpath entries

get_type_members

Get members by type name

get_super_method

Find overridden method in superclass

Usage

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

Coordinate System

All line/column parameters are zero-based:

  • Line 0, Column 0 = first character of file

Path Handling

  • Response paths are relative by default

  • All paths use forward slashes for cross-platform consistency

  • Input paths can be relative or absolute

Important Notes

Disk Synchronization

Every answer is verified against the files on disk at query time. Before any tool logic runs, JavaLens content-hashes the known source files, detects edits, additions, and deletions (the agent reports nothing — the server discovers changes itself), repairs exactly what changed, waits for the search index to absorb the repair, and only then answers. There is no file watcher and no background thread — verification is synchronous inside the query the agent issued, so there are no race conditions.

The agent's loop is just: edit → query.

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

load_project is needed only on first use, when a response reports RELOAD_REQUIRED (a build file like pom.xml changed, so the classpath must be rebuilt), or to rebuild everything from scratch. If verification itself fails, the query returns VERIFICATION_FAILED rather than an unverified answer.

Cost: verification is hash-based and parallel — measured per query at ~2 ms for a 72-file project, ~25 ms at 1,000 files, ~180 ms at 10,000 files. Repairs cost only what changed (one edited file reconciles in well under a second), never a full reindex.

Manual mode: set JAVALENS_DISK_SYNC=manual to restore the pre-1.5.0 contract — answers reflect the last load and the agent calls load_project after editing files. Tool descriptions and the MCP instructions field always state the active contract, and health_check reports it as diskSync.

Refactoring Returns Edits

Refactoring tools return text edits but don't modify files. This gives visibility into what would change before applying.

Session Isolation

Each MCP session is independent with its own workspace UUID. Multiple sessions can analyze the same project concurrently.

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

System

Detection

Single-module

Multi-module / multi-project

Compiler compliance from build files

Generated sources

Annotation processors

Maven

pom.xml

✅

✅ (the reactor, ../ modules and per-module classpaths as Maven's effective model reports them; reactor modules are linked as sources, never as jars)

✅ (each module's level as maven-compiler-plugin applies it: release before source, plugin configuration before properties, inherited from parents)

✅ (subdirectories of each module's generated-sources under its effective build directory)

✅ (<annotationProcessorPaths>, resolved in Maven's local repository)

Gradle

settings.gradle(.kts) / build.gradle(.kts)

✅

✅ (projects, custom projectDirs, included builds, source sets and classpaths as Gradle reports them)

✅ (each project's sourceCompatibility)

✅ (the generated-source directories Gradle reports)

✅ (annotationProcessor configuration)

Bazel

MODULE.bazel / WORKSPACE.bazel / WORKSPACE

✅

✅ (the Java targets and their sources from bazel query; the classpath from each target's javac action)

✅ (each javac action's level as javac takes it: the toolchain default, .bazelrc flags, then the target's javacopts)

n/a (Bazel actions write into bazel-bin/, not target/generated-sources/)

✅ (each javac action's processor path)

Plain Java

src/ directory

✅

n/a

✅ (falls back to Runtime.version().feature() when no build file)

n/a

n/a

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:

Code

Meaning

BUILD_TOOL_UNAVAILABLE / BUILD_TOOL_FAILED / BUILD_TOOL_TIMEOUT

The build tool could not start, failed, or ran out of time; the message carries its last output

BUILD_MODEL_STATIC

The build tool reported no model, so the build files were read statically; the message says what that cannot see

MODULE_NOT_LOADED

A declared module or subproject was not loaded (directory missing, invalid path)

MODULE_LAYOUT_ASSUMED

A module's source roots were assumed from the conventional layout

INCLUDED_OUTSIDE_BUILD

A conventional source folder the build does not declare, a module of an inactive Maven profile, or a Gradle project beside a Maven build, stays linked

COMPILED_OUTPUT_INCLUDED

A module's compiled output holds classes with no source and stays on the classpath

COMPLIANCE_LEVEL_MIXED / COMPLIANCE_LEVEL_UNKNOWN / COMPLIANCE_LEVEL_UNSUPPORTED

Modules declare different levels, none, or one outside JDT's range

APT_PROCESSOR_JARS_MISSING

Declared annotation-processor jars are missing

BAZEL_NOT_BUILT

Bazel output the classpath needs has not been built

INDEX_INCOMPLETE / LIBRARY_INDEX_INCOMPLETE

Source files or libraries JDT's search index still lacks after repair; index-backed tool responses name them while it lasts

JRE_REGISTRATION_FAILED

The JDK could not be registered with JDT

EARLIER_PROJECT_KEPT

An earlier load's workspace project could not be removed

TIMEOUT_SECONDS_INVALID

JAVALENS_TIMEOUT_SECONDS is out of range or not a number

Configuration

Environment Variable

Description

Default

JAVA_PROJECT_PATH

Auto-load project on startup

(none)

JAVALENS_TIMEOUT_SECONDS

Time limit on each tool call, a whole number of seconds from 5 to 300 (values outside are clamped, other values ignored, each with a TIMEOUT_SECONDS_INVALID load warning); a call past it returns TIMEOUT. load_project and health_check are not limited

(none: no limit)

JAVALENS_DISK_SYNC

strict (every answer verified against disk) or manual (agent calls load_project after edits)

strict

JAVALENS_LOG_LEVEL

TRACE/DEBUG/INFO/WARN/ERROR (case-insensitive); logs go to stderr, stdout carries only JSON-RPC

INFO

JAVA_TOOL_OPTIONS

JVM options, e.g. -Xmx2g for large projects

(default: 512m via eclipse.ini)

JAVALENS_LOMBOK_JAR

Path to the Lombok agent jar attached at launch; overrides the bundled one

(bundled)

JAVALENS_MAVEN_ARGS

Extra arguments for the Maven runs that read the model, e.g. -Pextras -Dskip.x=true (split like shell words)

(none)

JAVALENS_GRADLE_ARGS

Extra arguments for the Gradle run that reads the model, e.g. -Penv=ci

(none)

JAVALENS_BAZEL_ARGS

Extra build flags for bazel aquery and bazel info, e.g. --config=ci

(none)

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

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.

Testing

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

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

Build-system coverage is structured as focused per-bug tests plus realistic end-to-end tests. The end-to-end tests load a single representative project per build system that exercises every fix in one pass — multi-module Maven with Lombok APT and cross-module references; multi-project Gradle with annotation processors; multi-target Bazel with cross-target deps. CI runs them on Linux and macOS; Windows line endings are covered by tests that write CRLF files explicitly.

Architecture

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

License

MIT License - see LICENSE for details.

Available Tools

75 tools
analyze_change_impactA

Analyze the blast radius of changing a symbol.

USAGE: analyze_change_impact(filePath="path/to/File.java", line=10, column=5) OUTPUT: All files and call sites affected, grouped by file. Every reference at every depth is listed and counted; nothing is cut. A place JDT could not confirm is listed in potentialMatches with its depth, and the member holding it is followed no further.

Options:

  • depth: How many levels of callers to follow, 1 to 3 (default 1); any other depth is INVALID_PARAMETER depth=1: direct references only depth=2: references + callers of those references depth=3: three levels deep

  • transitive: full reverse closure over the project call graph (default false). No depth ceiling; follows calls, instantiations, field accesses, and override declarations (callers through an interface or superclass count). Returns affectedMethods + affectedFiles instead of callSites. Supports project methods, fields, and types.

  • maxResults: cap on affectedMethods in transitive mode (default 200)

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), depth, +2 more.

analyze_control_flowB

Analyze the control flow structure of a method.

USAGE: analyze_control_flow(filePath="path/to/File.java", line=10, column=5) OUTPUT: Branching points, loops, returns, throws, and nesting depth

Reports:

  • Branch count (if/switch/ternary)

  • Loop count and types (for/while/do-while/enhanced-for)

  • Return points with line numbers

  • Throw points with exception types and line numbers

  • Try-catch blocks with caught exception types

  • Maximum nesting depth

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

analyze_data_flowA

Analyze data flow within a method.

USAGE: analyze_data_flow(filePath="path/to/File.java", line=10, column=5) OUTPUT: Variables with read/write/declaration info

Reports for each variable:

  • name and type

  • whether it is declared, read, written

  • whether it is a parameter, local variable, or field

  • return statement count and types

Useful for understanding side effects before extracting methods.

Options:

  • followCalls: opt-in interprocedural mode (default false). Tracks two fact kinds across argument-to-parameter hops into project callees and reports interproceduralFlows:

    • null facts - locals assigned null; sink = a dereference of the tracked value in a callee (potential NPE)

    • taint facts - this method's parameters, propagated through aliases and expressions; sink = the value escaping into a non-project (binary) callee May-analysis: reassignments do not kill facts. Returned values are not tracked back into callers.

  • maxCallDepth: call-edge bound for followCalls (default 2)

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), followCalls, +1 more.

analyze_fileA

Comprehensive file analysis in a single call.

USAGE: analyze_file(filePath="path/to/File.java") OUTPUT: File info, imports, types with member counts, diagnostics

Combines:

  • File info (path, package, line count)

  • All imports (with static/on-demand flags)

  • All types with member counts

  • Compilation diagnostics (errors/warnings)

Use this instead of multiple calls to get_document_symbols + get_diagnostics.

Requires load_project to be called first.

Inputs: filePath (required), includeMembers, includeDiagnostics.

analyze_methodA

Comprehensive method analysis in a single call.

USAGE: analyze_method(filePath="path/to/File.java", line=N, column=N) OUTPUT: Method info, parameters, exceptions, callers, callees, override info

Combines:

  • Method info (signature, modifiers, return type)

  • Parameters with types

  • Declared exceptions

  • Incoming calls (who calls this method)

  • Outgoing calls (what this method calls, in its lambdas included; a call in an anonymous or local class declared in it is a call of that class's member; creating an anonymous class is a call of the superclass constructor its constructor runs)

  • Override information (super method, overriding methods)

callers.count and callees.count are the exact numbers of distinct callers and callees; each list holds the first maxCallers (default 20) or maxCallees (default 50) of them, callers in search order and callees in source order. meta.totalCount counts both, meta.returnedCount those listed, and meta.truncated is true when either list is cut. A negative maxCallers or maxCallees is INVALID_PARAMETER.

The method is the one the position names, wherever it is declared: its file and line are those of its declaration, and its callees are read there. A method of a class file reports no file, line or callees (there is no source to read them from); its callers are those in the project's source files. callers.potentialMatches holds the references JDT could not confirm, the first maxCallers of them; overrides.potentialMatches the places naming the declaring type, or a subtype, as a supertype that JDT could not confirm. overrides.unresolvedSupertypes, present only when there are any, names each supertype of the declaring type the compiler cannot resolve, with the type whose declaration names it: the method may override a method of one of them.

Use this instead of multiple calls to get_method_at_position + call hierarchy tools.

IMPORTANT: Uses ZERO-BASED coordinates.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), maxCallees, +1 more.

analyze_typeA

Comprehensive type analysis in a single call.

USAGE: analyze_type(typeName="com.example.Foo") OUTPUT: Type info, members, hierarchy, usage summary, diagnostics

Combines:

  • Type info (name, kind, modifiers, location)

  • All members (methods, fields, constructors)

  • Type hierarchy (superclass, interfaces, subtypes)

  • Usage summary (instantiations, casts, etc.)

  • Diagnostics for the type's file

Use this instead of multiple calls to get_type_members + get_type_hierarchy + get_type_usage_summary.

hierarchy.unresolvedSupertypes, present only when there are any, names each supertype the compiler cannot resolve (a missing dependency), as the declaration writes it, with the type whose declaration names it: this type or one of its supertypes. The hierarchy's potentialMatches are places naming the type as a supertype that JDT could not confirm; the usage summary's are uses it could not confirm, the first maxUsages of each category. maxUsages below 0 is INVALID_PARAMETER.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: typeName (required), maxUsages, includeUsages.

apply_cleanupA

Apply a JDT code clean-up to a file and return the rewritten source.

USAGE: apply_cleanup(filePath="path/to/File.java", cleanupId="convert_loops") OUTPUT: changed flag, a label, and the full rewritten source (the file is NOT written — apply the returned source yourself).

Supported cleanupId values: - convert_loops: rewrite index- and iterator-based for loops as enhanced for loops - convert_to_lambda: convert anonymous classes implementing a functional interface to lambdas - pattern_matching_instanceof: use pattern matching for instanceof checks followed by a cast - convert_to_switch_expression: convert assignment/return switch statements to switch expressions - string_concat_to_text_block: convert multi-line string concatenations to text blocks - do_while_rather_than_while: replace while loops that always run once with do-while loops - invert_equals: invert equals() calls so the constant is the receiver (avoids NPEs) - boolean_value_rather_than_comparison: simplify comparisons with boolean literals (x == true -> x) - else_if: collapse else blocks containing a lone if into else-if chains - overridden_assignment: remove initializers that are overwritten before being read

Requires load_project to be called first.

Inputs: filePath (required), cleanupId (required).

apply_quick_fixA

Apply a fix by ID.

USAGE: apply_quick_fix(filePath="...", fixId="add_import:java.util.List") OUTPUT: Text edits to apply the fix

Fix ID formats:

  • add_import:{fullyQualifiedName} - Add an import statement

  • remove_import:{index} - Remove import at index

  • add_throws:{exceptionType} - Add throws declaration to method

  • surround_try_catch:{exceptionType} - Wrap statement in try-catch

IMPORTANT: Uses ZERO-BASED line numbers.

Requires load_project to be called first.

Inputs: fixId (required), filePath (required), line.

change_method_signatureA

Change method signature (parameters, return type, or name) and update all call sites.

Returns text edits for the method declaration and every place that must change. The caller should apply these edits to perform the change.

USAGE: Position on method declaration, provide changes OUTPUT: Edits for the declarations and every place updated

The method changes together with every method it overrides, every method that overrides it and every method a subtype inherits together with it, as rename_symbol renames them: one declaration edit each, each keeping its own parameter names and unchanged parameter types, and every call of any of them. A method related to a method of a class file is refused, naming that method: it cannot change. A place JDT's search reports but cannot confirm as a call, where a type or name does not resolve, is never rewritten: potentialMatches lists every one, to review by hand. An element of an annotation type is refused: it has no parameters; rename it with rename_symbol.

Every place JDT's change-signature refactoring updates is updated: calls, including the arguments of enum constants; Javadoc references (#method(Type) and Type#method(Type) links); a single static import of the method, renamed, or followed by an import of the new name when a member it names keeps the old name; the parameters of each lambda expression implementing the method; and, when a constructor without parameters is given some, its implicit super() calls: super(...) is added to each constructor of a direct subclass that calls it implicitly, and a constructor calling super(...) to each direct subclass that declares none. A call nested in another changed place, such as a chained call, changes within that place's edit.

Each edit replaces a span (type replace, with oldText and newText, or oldSignature and newSignature for a declaration, isDeclaration true) or inserts text (type insert, with line, column, offset and newText). A file's edits come in this order: declarations, the other places the search reports, in source order, lambda expressions, implicit super() calls, static imports.

PARAMETER OPERATIONS:

  • Add new parameter with default value for existing calls

  • Remove parameter (will remove from calls)

  • Rename parameter: give it its new name and, as oldName, the name it has now. Each declaration and lambda expression that names it so takes the new name in its parameter list and every reference to it in its body, a declaration's @param tag naming it too, and a Javadoc reference naming it takes the new name; calls keep their arguments. A declaration or lambda expression that names it otherwise keeps its own name. An oldName that names no parameter of the method is INVALID_PARAMETER.

  • Reorder parameters (specify all parameters in new order)

A renamed parameter's @param tag and references follow its declaration's or lambda expression's edit, in source order. The edits of the lambda expressions come in source order, file by file, as the other places do.

Every declaration keeps each kept parameter's modifiers and annotations as written. A changed type replaces only the type: the parameter is varargs when the new type ends in ..., and dimensions written after its name are dropped, as JDT does.

Refused as JDT refuses them (INVALID_PARAMETER 'newParameters', with JDT's messages): a blank parameter name or one that is no Java identifier; two parameters of one name; a name the change gives that a method changed with it already gives one of its parameters, naming that method; and a rename that changes what a name refers to: a renamed reference a local variable would capture (in the body, an anonymous class or a lambda expression), or a reference to a field or another variable the renamed parameter would capture. Each collision names the declaration it lies in and its place, as the file is now.

Compile errors that follow from the requested change (a changed return or parameter type breaking a caller, a removed parameter still used) do not refuse it. introducedProblems lists every compile error the applied edits introduce in each file the change edits or reports a place in, and JDT's note for each removed parameter a body still uses, at its first use, also where the code compiles because a field of that name captures it. Each entry gives filePath, line and column, as the file is now, and message, which names the method, field, initializer or type the error lies in ("a lambda expression in" it when it lies in one; an anonymous class by its number, as in Outer$1). Entries come by file, then line and column, then message. introducedProblems is present only when it has an entry.

warnings lists JDT's warnings on the new parameter names, in the order of the parameters, then one for each file holding a method reference that cannot be updated, in the order of methodReferences.

IMPORTANT: Uses ZERO-BASED coordinates.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), newName, +2 more.

convert_anonymous_to_lambdaA

Convert an anonymous class implementing a functional interface to a lambda expression.

Returns the text edit needed to convert the anonymous class to a lambda. The caller should apply this edit to perform the conversion.

USAGE: Position cursor on the 'new' keyword of the anonymous class OUTPUT: Edit to replace anonymous class with lambda

IMPORTANT: Uses ZERO-BASED coordinates. REQUIREMENTS: The anonymous class must implement a functional interface (exactly one abstract method).

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

diagnose_and_fixA

Diagnose a file and compute the quick-fix edits in one call: runs diagnostics, resolves the available fixes per fixable problem, and returns the top fix's edits for each, combined as editsByFile.

USAGE: diagnose_and_fix(filePath="path/to/File.java") OUTPUT: problems (each with its chosen fix when one exists) and editsByFile with the computed edits. NOTHING is written - apply the returned edits yourself.

A file with no fixable diagnostics returns empty problems/edits.

Requires load_project to be called first.

Inputs: filePath (required).

encapsulate_fieldA

Encapsulate a field: generate a getter/setter pair and rewrite all direct accesses (in this and other files) to go through them.

USAGE: Position on the field name; optionally name the accessors. OUTPUT: editsByFile with all required text edits; warnings from JDT's own condition checking, by the place each names (file, then position; those naming one place in JDT's order, those naming none last). Edits are returned as text - apply them yourself.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), getterName, +1 more.

extract_constantA

Extract an expression into a static final constant at class level.

Returns the text edits needed to extract the expression. The caller should apply these edits to perform the extraction.

USAGE: Select expression by providing start and end positions OUTPUT: Constant declaration and replacement edits

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: endLine (required), filePath (required), endColumn (required), startLine (required), +2 more.

extract_interfaceA

Extract an interface from a class containing selected public methods.

Returns the text for a new interface file and edits to add 'implements' clause to the original class. The interface imports each type its signatures name that it cannot see unimported, a member type by its canonical name (import pkg.Outer.Inner).

USAGE: Position on class, provide interface name, optionally specify methods OUTPUT: Interface file content and class modification edit

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), interfaceName (required), +1 more.

extract_methodA

Extract a code block into a new method.

USAGE: Select code range, provide method name OUTPUT: Text edits for method declaration and call site

The tool analyzes the selected code to:

  • Determine which variables become parameters

  • Determine return type based on variables modified

  • Generate appropriate method signature

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: endLine (required), filePath (required), endColumn (required), startLine (required), +2 more.

extract_superclassA

Extract a new superclass from a class: the member at the position moves up into a newly created superclass, and the class extends it.

USAGE: Position on the member to extract; provide the new superclass name. OUTPUT: createdFiles carries the new superclass file content; editsByFile carries the source class's edits; warnings, present only when there is one, JDT's findings from its condition checking, by the place each names (file, then position; those naming one place in JDT's order, those naming none last). Nothing is written - create the file and apply the edits yourself.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), superclassName (required).

extract_variableA

Extract an expression at the given position into a local variable.

Returns the text edits needed to extract the expression. The caller should apply these edits to perform the extraction.

USAGE: Select expression by providing start and end positions OUTPUT: Variable declaration and replacement edits

An expression of type void, or a null literal alone, is refused (INVALID_PARAMETER): no variable can be declared for it.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: endLine (required), filePath (required), endColumn (required), startLine (required), +2 more.

find_affected_testsA

Find the test methods that exercise a symbol, directly or transitively.

USAGE: find_affected_tests(filePath="path/to/File.java", line=10, column=5) OUTPUT: Test methods (JUnit 4/5, TestNG) from which the symbol is reachable, with locations - the set of tests to run after changing it.

The caller walk follows calls, instantiations, field accesses, and override declarations (a test calling through an interface or superclass covers the implementation). Non-test intermediate methods are walked through but not reported. Disabled tests are included with disabled=true (they cover the code but will not run). A symbol no test reaches returns an empty set.

Supports project methods, fields, and types as the target symbol.

Options:

  • maxResults: cap the reported list (default 100)

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), maxResults.

find_annotation_usagesA

Find all usages of an annotation type in the project.

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified annotation name as typeName OUTPUT: All locations where the annotation is applied

Examples:

  • find_annotation_usages(typeName="org.springframework.beans.factory.annotation.Autowired")

  • find_annotation_usages(typeName="org.junit.jupiter.api.Test")

  • find_annotation_usages(typeName="javax.persistence.Entity")

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: typeName (required), maxResults.

find_castsA

Find all casts to a type ((Foo) x expressions).

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified type name OUTPUT: All locations where casting to this type occurs

Useful for:

  • Identifying unsafe downcasts

  • Finding refactoring opportunities (replace cast with polymorphism)

  • Understanding type conversion patterns

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: typeName (required), maxResults.

find_catch_blocksA

Find all catch blocks for an exception type (catch(ExceptionType e)).

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified exception type name as typeName OUTPUT: All catch blocks that handle this exception type

Useful for:

  • Understanding exception handling patterns

  • Finding all handlers for a specific exception

  • Exception handling analysis and refactoring

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: typeName (required), maxResults.

find_circular_dependenciesA

Detect cycles in packages.

USAGE: find_circular_dependencies() USAGE: find_circular_dependencies(packageFilter="com.example") OUTPUT: List of circular dependency cycles

Uses Tarjan's SCC algorithm to efficiently detect all cycles. Reports cycle paths and affected packages.

maxCycleLength, the most packages a reported cycle joins, is 2 or more (a cycle joins at least two packages); below 2 is INVALID_PARAMETER.

Requires load_project to be called first.

Inputs: packageFilter, maxCycleLength.

find_field_writesA

Find all write accesses (mutations) to a field.

USAGE: Position cursor on a field declaration or reference OUTPUT: List of locations where the field is modified

IMPORTANT: Uses ZERO-BASED coordinates.

Unlike find_references which returns all usages, this returns only locations where the field value is changed (assignments, increments, etc). Useful for data flow analysis and understanding state mutations.

maxResults outside 0 to 1000 is INVALID_PARAMETER.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), maxResults.

find_implementationsA

Find implementations of an interface or extensions of a class.

USAGE: Position on a type (interface or class), find all implementors/subclasses OUTPUT: List of implementing/extending types with locations

IMPORTANT: Uses ZERO-BASED coordinates.

potentialMatches are the places naming the type, or one of its subtypes, as a supertype that JDT could not confirm: the class declaring each may be an implementation, and, for a method, may override it.

maxResults outside 0 to 1000 is INVALID_PARAMETER.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), maxResults.

find_instanceof_checksA

Find all instanceof checks for a type (x instanceof Foo).

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified type name OUTPUT: All locations where instanceof checks against this type occur

Useful for:

  • Identifying type checking patterns

  • Finding polymorphism opportunities (replace instanceof with virtual dispatch)

  • Understanding type discrimination logic

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: typeName (required), maxResults.

find_large_classesA

Find classes that exceed size thresholds.

USAGE: find_large_classes(maxMethods=20, maxFields=10, maxLines=300) OUTPUT: List of classes exceeding any threshold with their metrics

Default thresholds:

  • maxMethods: 20 methods

  • maxFields: 10 fields

  • maxLines: 300 lines

Requires load_project to be called first.

Inputs: maxLines, maxFields, maxMethods.

find_method_referencesA

Find all method reference expressions (Foo::bar lambda syntax).

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Position on a method, or provide method details OUTPUT: All locations where the method is used as a method reference

Useful for:

  • Understanding functional programming patterns

  • Finding lambda-style usages of methods

  • Refactoring analysis

IMPORTANT: Uses ZERO-BASED coordinates.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), maxResults.

find_naming_violationsA

Check code against standard Java naming conventions.

USAGE: find_naming_violations(filePath="path/to/File.java") OUTPUT: List of naming convention violations

Conventions checked:

  • Classes/interfaces/enums: PascalCase

  • Methods: camelCase

  • Fields: camelCase

  • Constants (static final): UPPER_SNAKE_CASE

  • Parameters: camelCase

If filePath is omitted, scans all project files.

Requires load_project to be called first.

Inputs: filePath.

find_possible_bugsA

Find possible bugs and code quality issues.

USAGE: find_possible_bugs() USAGE: find_possible_bugs(filePath="path/to/File.java") OUTPUT: List of potential issues

Detects:

  • Null pointer risks (dereferencing potentially null values)

  • Resource leaks (unclosed streams, connections)

  • Empty catch blocks

  • Comparison issues (== on objects instead of equals)

  • Synchronization issues (sync on String)

severity (optional, compared case-insensitively): high, medium or low keeps the issues of that severity; all (the default) keeps every issue. Any other value is rejected with INVALID_PARAMETER.

A filePath naming no source file of the project is FILE_NOT_FOUND.

Requires load_project to be called first.

Inputs: filePath, severity.

find_referencesA

Find all references to a symbol across the project.

USAGE: Position on symbol, find all usages OUTPUT: List of reference locations with context

The references of a symbol of a class file, such as a JDK method, are those in the project's source files. A position on a name the compiler cannot resolve has no symbol: SYMBOL_NOT_FOUND. maxResults outside 0 to 1000 is INVALID_PARAMETER.

IMPORTANT: Uses ZERO-BASED coordinates.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), maxResults.

find_reflection_usageA

Find places where Java reflection API is used.

USAGE: find_reflection_usage() OUTPUT: All reflection calls grouped by method type

Detects calls to:

  • Class.forName(), Class.newInstance()

  • Class.getMethod/getDeclaredMethod/getField/getDeclaredField

  • Class.getConstructor/getDeclaredConstructor

  • Method.invoke(), Field.get/set(), Constructor.newInstance()

These usages are invisible to static reference searches and can break when types or methods are renamed.

maxResults caps the calls listed for each reflection method, all its overloads together (default 100), in source order: by file, then position. summary counts every call of each reflection method, and totalCalls and meta.totalCount count every call; meta.truncated is true when calls are left out. potentialMatches lists, the first maxResults of each reflection method in source order, the calls JDT could not confirm, each with its reflection method.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: maxResults.

find_testsA

Find test classes and methods in the project.

USAGE: find_tests() OUTPUT: List of test classes with their test methods

Supports:

  • JUnit 4 (@Test, @Before, @After, etc.)

  • JUnit 5 (@Test, @BeforeEach, @AfterEach, etc.)

  • TestNG annotations

Requires load_project to be called first.

Inputs: pattern, includeDisabled.

find_throws_declarationsA

Find all throws declarations of an exception type in method signatures.

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified exception type name as typeName OUTPUT: All methods that declare 'throws ExceptionType'

Useful for:

  • Understanding exception flow in the codebase

  • Finding all methods that can throw a specific exception

  • Exception handling analysis

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: typeName (required), maxResults.

find_type_argumentsA

Find all usages of a type as a generic type argument (List, Map<K, Foo>).

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified type name OUTPUT: All locations where the type is used as a generic argument

Useful for:

  • Understanding generic usage patterns

  • Finding all collections/containers of a type

  • API design analysis

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: typeName (required), maxResults.

find_type_instantiationsA

Find all instantiations of a type (new Foo() calls).

JDT-UNIQUE: This fine-grained search is not available in LSP.

USAGE: Provide fully qualified type name OUTPUT: All locations where the type is instantiated with 'new'

Useful for:

  • Understanding object creation patterns

  • Identifying factory method candidates

  • Finding coupling points

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: typeName (required), maxResults.

find_unreachable_codeA

Find code unreachable from any entry point, project-wide.

USAGE: find_unreachable_code() OUTPUT: Members (types, methods, fields) that no entry point reaches, with visibility and location, plus the roots used.

Roots are public static void main(String[]) methods and detected test methods (JUnit 4/5, TestNG; disabled tests still count). Reachability follows calls, instantiations, field accesses, field initializers, and overrides (a call through an interface or superclass reaches every override). A type is reported only when neither it nor any of its members is reachable.

IMPORTANT: results mean "unreachable from declared entry points", not "safe to delete" - reflection, dependency injection, and serialization entry points are invisible to the graph.

Options:

  • includeTestRoots: count test methods as entry points (default true)

  • maxResults: cap the reported list (default 100)

Requires load_project to be called first.

Inputs: maxResults, includeTestRoots.

find_unused_codeA

Find unused private methods and fields in the project.

USAGE: find_unused_code() USAGE: find_unused_code(filePath="path/to/File.java") OUTPUT: List of unused private members

Detects:

  • Unused private methods

  • Unused private fields

  • Write-only fields (set but never read)

Requires load_project to be called first.

Inputs: filePath, includeFields, includeMethods.

get_call_hierarchy_incomingA

Find all callers of a method (incoming calls).

USAGE: Position cursor on a method name OUTPUT: List of methods that call this method

IMPORTANT: Uses ZERO-BASED coordinates.

Useful for understanding who depends on a method before changing it.

The callers of a method of a class file, such as a JDK method, are those in the project's source files. maxResults outside 0 to 500 is INVALID_PARAMETER.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), maxResults.

get_call_hierarchy_outgoingA

Find all methods called by a method (outgoing calls).

USAGE: Position cursor on a method name OUTPUT: List of methods that this method calls

A call in a lambda written in the method is the method's call; a call in the body of an anonymous or local class declared in it is a call of that class's member, as get_call_hierarchy_incoming reports it. Creating an anonymous class, and its arguments, are calls of the method; the creation is a call of the superclass constructor the anonymous class's constructor runs (Object() for an interface), returning the anonymous class.

IMPORTANT: Uses ZERO-BASED coordinates.

Useful for understanding what a method depends on.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

get_classpath_infoA

Get project classpath information.

USAGE: Call to get all classpath entries for the loaded project OUTPUT: Source folders, libraries, and classpath containers

Useful for understanding project structure and dependencies.

Requires load_project to be called first.

Inputs: includeSource, includeLibraries, includeContainers.

get_complexity_metricsA

Get cyclomatic complexity, cognitive complexity, LOC.

USAGE: get_complexity_metrics(filePath="path/to/File.java") OUTPUT: The file's line counts, a summary and risk assessment over its methods and, with includeDetails (default true), each method's metrics with the type declaring it

Metrics:

  • Cyclomatic Complexity: Count of decision points (+1 for if/for/while/case/catch)

  • Cognitive Complexity: Penalizes nesting and breaks in linear flow

  • LOC: Physical and logical lines of code

Risk levels:

  • High: CC > 10

  • Medium: CC 6-10

  • Low: CC <= 5

Requires load_project to be called first.

Inputs: filePath (required), includeDetails.

get_dependency_graphA

Get package/type dependencies.

USAGE: get_dependency_graph(scope="type", name="com.example.OrderService") USAGE: get_dependency_graph(scope="package", name="com.example.service") OUTPUT: Dependency graph with nodes and edges

Each node has a name and a kind. A node that denotes a type is named by the type's fully qualified name with '$' between nested types (com.example.Outer$Inner), however the source names it, so each type is one node. A node that denotes a type, or a member of one (a static import), also has the package of that type as JDT resolves it ("(default package)" for the default package). A node that denotes a package (every node at package scope, and an on-demand package import) has no package; neither has a name that does not resolve.

At package scope the graph covers the package and its subpackages: each import is an edge from the package of the file declaring it to the package it imports, and every edge's source and target is a node, as is the requested package. A name that is no package of the project's source folders, a library's package such as java.util included, is SYMBOL_NOT_FOUND.

depth is 1 or more at either scope; below 1 is INVALID_PARAMETER. At type scope it is how many steps of dependencies are followed from the type: 1 lists the type's own dependencies, 2 also those of each dependency with source, and so on. Package scope does not use it.

Dependency types tracked:

  • import: Direct imports

  • extends: Superclass inheritance

  • implements: Interface implementation

  • field: Field type dependencies

  • parameter: Method parameter types

  • return: Method return types

Requires load_project to be called first.

Inputs: name (required), scope (required), depth, includeExternal.

get_diagnosticsA

Get compilation diagnostics (errors and warnings) for a file or project.

USAGE: get_diagnostics() for all files, or get_diagnostics(filePath="...") for one file OUTPUT: List of compilation errors and warnings with locations

Useful for finding syntax errors, type mismatches, missing imports, etc.

severity (optional, compared case-insensitively): error or warning keeps the diagnostics of that severity; all (the default) keeps both. Any other value is rejected with INVALID_PARAMETER.

Every file is checked and every diagnostic kept is counted in totalDiagnostics, errorCount and warningCount; maxResults limits only the diagnostics listed, and meta.truncated says when the list is cut.

Requires load_project to be called first.

Inputs: filePath, severity, maxResults.

get_di_registrationsA

Find all dependency injection registrations in the project.

USAGE: get_di_registrations() OUTPUT: Components, configurations, beans, and injection points

Scans for:

  • Spring components: @Component, @Service, @Repository, @Controller, @RestController

  • Configuration: @Configuration

  • Bean definitions: @Bean

  • Injection points: @Autowired, @Inject (javax and jakarta)

Returns empty categories for non-Spring projects (does not error).

maxResults caps the matches listed for each annotation type (default 200). Each summary count is the exact number of registrations in its category; meta.totalCount counts every registration, meta.returnedCount those listed, and meta.truncated is true when an annotation type has more matches than maxResults. potentialMatches lists, the first maxResults of each annotation type, the annotations JDT could not confirm, each with the annotation it names; none is a registration.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: maxResults.

get_document_symbolsA

Get all symbols (types, methods, fields) in a source file.

USAGE: Provide a file path to get all symbols in that file OUTPUT: Hierarchical list of all types, methods, fields, and nested types

Returns symbols with their locations, kinds, and modifiers. A record's components are listed as its first children.

Types are listed as declared at top level and as members of other types. Local and anonymous classes, those declared in method, field or initializer bodies, are not listed.

maxResults outside 0 to 2000 is INVALID_PARAMETER.

Requires load_project to be called first.

Inputs: filePath (required), maxResults, includePrivate.

get_enclosing_elementA

Get the enclosing element at a position.

USAGE: Position anywhere in code OUTPUT: Enclosing method, type, and package info

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

get_field_at_positionA

Get field information at a specific position.

USAGE: Position on a field reference or declaration OUTPUT: Field type, modifiers, constant value if applicable

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

get_hover_infoA

Get hover information (documentation) for a symbol at a position.

USAGE: Position on any symbol OUTPUT: Signature, Javadoc, and quick info similar to IDE hover

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

get_http_endpointsA

Assemble the project's HTTP route table.

USAGE: get_http_endpoints() OUTPUT: route -> handler entries (HTTP method, effective path, handler method, framework, location), sorted by path.

Supports:

  • Spring verb shortcuts: @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping; the class-level @RequestMapping value is composed as the path prefix.

  • JAX-RS (jakarta.ws.rs and javax.ws.rs): @GET/@POST/... verbs with class-level and method-level @Path composed.

Method-level @RequestMapping(method=...) routes are not assembled; verb-shortcut annotations are the supported Spring form.

Handlers are listed where a framework can register them: in a named top-level or static member class, interface, record or enum. A verb-annotated method of an anonymous class, a local class or a non-static inner class, or an element of an annotation type, is no route and is not listed. A handler whose signature names a type that does not resolve is listed like any other.

Projects without these frameworks return an empty table.

potentialMatches lists, the first maxResults by file and position, the verb annotations JDT could not confirm, each with the annotation it names; none is a route.

Options:

  • maxResults: cap the reported endpoints (default 200)

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: maxResults.

get_javadocA

Get parsed Javadoc documentation for a symbol.

USAGE: Position on any documented symbol OUTPUT: Parsed Javadoc with summary, @param, @return, @throws, etc.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

get_jpa_modelA

Assemble the project's JPA entity model.

USAGE: get_jpa_model() OUTPUT: Entities with table name, id field, and relationships (kind, target entity, mappedBy side), with locations.

Scans @Entity types (jakarta.persistence and javax.persistence) and reads @Table, @Id, and @OneToMany/@ManyToOne/@OneToOne/ @ManyToMany field annotations. Relationship targets are resolved from the field's type binding, including through collection type arguments (List -> Order).

Projects without JPA on the classpath return an empty model.

potentialMatches lists, the first maxResults by file and position, the @Entity annotations JDT could not confirm, each with the annotation it names; none is an entity.

Options:

  • maxResults: cap the reported entities (default 100)

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: maxResults.

get_method_at_positionA

Get method information at a specific position.

USAGE: Position on a method reference or declaration OUTPUT: Method signature, parameters, return type, modifiers, exceptions

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

get_project_structureA

Get project structure showing package hierarchy.

USAGE: Call to see the package tree of the loaded project OUTPUT: Source roots with packages and file counts

maxDepth outside 1 to 20 is INVALID_PARAMETER.

Requires load_project to be called first.

Inputs: maxDepth, includeFiles.

get_quick_fixesA

List available fixes for a problem at position.

USAGE: get_quick_fixes(filePath="...", line=10) OUTPUT: List of quick fixes with fixId, label, and category

Supported fixes:

  • UndefinedType: Suggest imports for unresolved types, each fixId naming the type as an import does (add_import:pkg.Outer.Inner for a member type); a type in the default package, or in a package its module does not export to the project (such as the JDK's internal packages), cannot be imported and is never suggested; the package's name never decides. Every candidate is ranked by relevance (equally relevant ones by name), then the 10 most relevant are listed

  • UnusedImport: Remove unused import

  • UnhandledException: Add throws or surround with try-catch

Fixes are listed by relevance. meta.totalCount counts every fix for the problems at the position, meta.returnedCount those listed, and meta.truncated is true when import candidates are left out.

IMPORTANT: Uses ZERO-BASED line numbers.

Requires load_project to be called first.

Inputs: line (required), filePath (required), column.

get_signature_helpA

Get method signature help at a position.

USAGE: Position on a method call or declaration OUTPUT: Method signatures with parameter info

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

get_super_methodA

Find the method that this method overrides or implements.

USAGE: Position on a method that overrides/implements another OUTPUT: The superclass/interface method being overridden

The overridden method is the one the compiler binds: the nearest declaration in the superclass chain, else in the interfaces, visible from the method's package. unresolvedSupertypes, present only when there are any, names each supertype of the declaring type the compiler cannot resolve (a missing dependency), as the declaration writes it, with the type whose declaration names it: the method may override a method of one of them.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

get_symbol_infoA

Get detailed information about any symbol at a position.

USAGE: Position on any symbol (type, method, field, variable) OUTPUT: Comprehensive info including kind, modifiers, signature, location

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

get_type_at_positionA

Get type information at a specific position.

USAGE: Position on a type reference or declaration OUTPUT: Type details including kind, modifiers, superclass, interfaces

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

get_type_hierarchyA

Get the type hierarchy (supertypes and subtypes) for a Java type.

USAGE: Position on a type, returns full inheritance chain OUTPUT: Superclasses, interfaces, and all subtypes

Can be called with either:

  • File position (filePath, line, column) - finds type at cursor

  • Type name (typeName) - looks up type by qualified name

IMPORTANT: Uses ZERO-BASED coordinates when using file position.

unresolvedSupertypes, present only when there are any, names each supertype the compiler cannot resolve (a missing dependency), as the declaration writes it, with the type whose declaration names it: this type or one of its supertypes. The superclasses then run to the last that resolves and end with java.lang.Object. potentialMatches are the places naming the type, or a subtype, as a supertype that JDT could not confirm.

maxResults, the most entries each of superclasses, interfaces and subtypes lists (totalSuperclasses, totalInterfaces and totalSubtypes count all of them, and meta.truncated says when a list is cut), is 1 to 50; outside that range is INVALID_PARAMETER.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: line, column, filePath, typeName, +1 more.

get_type_membersA

Get all members (methods, fields, nested types) of a specific type.

USAGE: Provide a type name to get all its members OUTPUT: Lists of methods, fields, and nested types with their details

Options:

  • includeInherited: Also include members from superclasses/interfaces

  • memberKind: Filter to "method" (constructors included), "field" or "type" only, compared case-insensitively. "field" returns every field, including static final constants and enum constants; each field's kind is field, constant or enumConstant. Any other value is rejected with INVALID_PARAMETER.

With includeInherited, unresolvedSupertypes, present only when there are any, names each supertype the compiler cannot resolve (a missing dependency), as the declaration writes it, with the type whose declaration names it: the members it would give are not listed.

Requires load_project to be called first.

Inputs: typeName (required), memberKind, includeInherited.

get_type_usage_summaryA

Get comprehensive usage summary for a type across the codebase.

USAGE: get_type_usage_summary(typeName="com.example.Foo") OUTPUT: Instantiations, casts, instanceof checks, type arguments, annotations

Aggregates all usage patterns in a single call:

  • Instantiations (new Foo())

  • Casts ((Foo) x)

  • Instanceof checks (x instanceof Foo)

  • Type arguments (List)

  • Annotation usages (if annotation type)

Each category's count is the exact number of its usages; its locations list holds the first maxPerCategory of them (1 to 50, default 10; any other value is rejected with INVALID_PARAMETER). totalUsages and meta.totalCount count every usage, meta.returnedCount the locations listed, and meta.truncated is true when a category lists fewer locations than its count. A category's potentialMatches stand beside its locations.

Use this to understand how a type is used throughout the project.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

Requires load_project to be called first.

Inputs: typeName (required), maxPerCategory.

go_to_definitionA

Navigate to symbol definition.

USAGE: Position cursor on a symbol reference, returns definition location. OUTPUT: File path, line, column of the definition.

IMPORTANT: Uses ZERO-BASED coordinates. If editor shows 'Line 14, Column 5', pass line=13, column=4

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

health_checkA

Check server status and project state.

USAGE: Call on startup to verify server is operational. OUTPUT: Server status, project info if loaded (a loaded project reports its buildModel summary and any load warnings, as load_project does), capabilities. configuration.timeoutSeconds is the time limit on each tool call that JAVALENS_TIMEOUT_SECONDS sets (5 to 300), or null when no limit is set; a call past the limit answers TIMEOUT. load_project and health_check are never limited.

WORKFLOW:

  1. Call health_check to verify server is running

  2. If no project loaded, call load_project next

  3. Use returned capabilities to understand available features

Inputs: no named parameters.

inline_methodA

Inline a method call by replacing it with the method body.

Returns the text edit needed to inline the method call. The caller should apply this edit to perform the inlining.

USAGE: Position cursor on a method call OUTPUT: Edit to replace call with method body

IMPORTANT: Uses ZERO-BASED coordinates.

LIMITATIONS:

  • Method must be in the same project (source available)

  • Works best with simple methods (no complex control flow)

  • Single return statement is handled, multiple returns may need review

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

inline_variableA

Inline a local variable by replacing all usages with its initializer expression.

Returns the text edits needed to inline the variable. The caller should apply these edits to perform the inlining.

USAGE: Position cursor on variable declaration or usage OUTPUT: Edits to delete declaration and replace usages with initializer

IMPORTANT: Uses ZERO-BASED coordinates. SAFETY: Will refuse if variable is modified after initialization.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

introduce_parameter_objectA

Bundle a method's parameters into a new parameter-object class and rewrite the method and all callers to use it. The class is generated as a member of the declaring type.

USAGE: Position on the method name; optionally name the class and parameter. OUTPUT: editsByFile with all required edits; warnings from JDT's condition checking, by the place each names (file, then position; those naming one place in JDT's order, those naming none last). Edits are returned as text - apply them yourself.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required), className, +1 more.

load_projectA

Load a Java project for analysis. MUST be called before using other analysis tools.

USAGE: load_project(projectPath="/path/to/project") OUTPUT: Project structure summary including packages, source files, buildModel (build system, source of the structure: build-tool, static-read or convention, analysis level, modules) and warnings (present only when the load was degraded)

Supports:

  • Maven projects (pom.xml)

  • Gradle projects (settings.gradle, settings.gradle.kts, build.gradle or build.gradle.kts)

  • Bazel projects (MODULE.bazel or WORKSPACE)

  • Plain Java projects with src/ directory

WORKFLOW:

  1. Call load_project with absolute path to project root

  2. Wait for project to load (may take a few seconds for large projects)

  3. Use health_check to verify project is loaded

  4. Begin using analysis tools (search_symbols, find_references, etc.)

SYNC (strict mode): answers are always verified against the files on disk - no reload is needed after editing, adding, or deleting source files. Call load_project only on first use, when a response reports RELOAD_REQUIRED (a file the build reads changed), or to rebuild everything from scratch.

Inputs: projectPath (required).

move_type_to_new_fileA

Move a member (nested) type into its own top-level file. Non-static member types gain a field referencing the former enclosing instance.

USAGE: Position on the nested type's name. OUTPUT: createdFiles carries the new top-level file content; editsByFile carries the enclosing file's edits; warnings, present only when there is one, JDT's findings from its condition checking, by the place each names (file, then position; those naming one place in JDT's order, those naming none last). Nothing is written - create the file and apply the edits yourself.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

organize_importsA

Organize imports in a Java file.

Removes unused imports and sorts remaining imports alphabetically. Returns the organized import block that should replace the existing imports.

USAGE: organize_imports(filePath="path/to/File.java") OUTPUT: Organized import statements and list of changes

Requires load_project to be called first.

Inputs: filePath (required).

pull_upA

Pull a method or field up into the superclass and remove it from the declaring subclass.

USAGE: Position on the member name in the subclass. OUTPUT: editsByFile covering the superclass (member added) and the subclass (member removed); warnings from JDT's condition checking, by the place each names (file, then position; those naming one place in JDT's order, those naming none last). Edits are returned as text - apply them yourself.

The superclass is the Java model's, for local and anonymous classes in and after lambda bodies too. A member is refused when JDT's own type hierarchy leaves that superclass out (a class declared in a lambda body, a local class read by the handle of another of the same name), naming it: JDT's pull up would act on another class. A member is also refused when the superclass has a subclass declared in a lambda body, naming it: JDT's pull up cannot read that class. And a member is refused when JDT's own type hierarchy of the superclass does not hold every subtype with source as the Java model does (a class declared in a lambda body at any depth, a local class held by the handle of another of the same name), naming each type it leaves out and each it holds that is no subtype: JDT's pull up reads the subtypes from that hierarchy.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

push_downA

Push a method or field down into the declaring class's subclasses and remove it from the declaring class.

USAGE: Position on the member name in the superclass. OUTPUT: editsByFile covering the superclass (member removed) and each subclass (member added); warnings from JDT's condition checking, by the place each names (file, then position; those naming one place in JDT's order, those naming none last). Edits are returned as text - apply them yourself.

The direct subclasses are those of the Java model, local and anonymous classes in and after lambda bodies included. A member whose class has an anonymous direct subclass is refused, naming each anonymous subclass: push down cannot add a member to an anonymous class. A member whose class has a direct subclass that JDT's own type hierarchy leaves out (a class declared in a lambda body, a local class read by the handle of another of the same name) is refused, naming each such subclass: JDT's push down would not write the member into it.

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Inputs: line (required), column (required), filePath (required).

rename_symbolA

Rename a symbol (variable, method, field, class, etc.) across the project.

Returns text edits for all occurrences that need to be changed. The caller should apply these edits to perform the rename.

USAGE: Position on symbol, provide new name OUTPUT: List of text edits to apply, and the files to rename

Each edit replaces exactly the symbol's simple name, also where a reference is qualified (an import, a static import, a qualified name in code or in a Javadoc link). An annotation element written as the single value of its annotation, @Tag("x"), is named before that value: @Tag(label = "x").

A type is renamed with its explicit constructors. A top-level type whose file is named after it renames that file: renamedFiles lists it, as {filePath, newFilePath}; apply the edits (editsByFile is keyed by the current paths), then rename the file. renamedFiles is present only when a file is renamed. A top-level type renamed to the name of a file that already exists in its folder is refused: INVALID_PARAMETER.

A method is renamed together with every method it overrides, every method that overrides it and every method a subtype inherits together with it, in and after lambda bodies included, and every call of them. A method of a class file, or a method renamed together with one, is refused, naming that method: it cannot be renamed.

A rename JDT's rename refactoring finds a conflict for is refused: INVALID_PARAMETER for newName, naming every conflict in JDT's words, by the place each names (a name another declaration in scope already has, a reference the renamed element would take over or lose, a unit with syntax errors, a native method, a static import of the new name). The conflicts of a type, a field, a local variable, a type parameter and a private, static or constructor method are those JDT's rename processors find; those of any other method are the conditions of JDT's method rename (RenameMethodProcessor, RenameVirtualMethodProcessor) checked on the Java model's own hierarchy, local and anonymous classes in lambda bodies included. JDT's warnings on a rename that goes ahead (such as a discouraged name, a constructor's name, or a method of the hierarchy with the new name and other parameter types) are listed in warnings, by place; warnings is present only when there is one.

A place JDT's search reports but cannot confirm as a reference, where a type or name does not resolve, is never edited: potentialMatches lists every one, to review by hand. A position on a name the compiler cannot resolve has no symbol to rename: SYMBOL_NOT_FOUND.

IMPORTANT: Uses ZERO-BASED coordinates.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

A module is renamed in its declaration and its references. A package (renamed with its folder, which no text edit does), a package declaration, an import declaration or the import list is refused: INVALID_PARAMETER for position, naming it. So is a type, field or method of a library (binary), which has no source to edit.

Requires load_project to be called first.

Inputs: line (required), column (required), newName (required), filePath (required).

search_symbolsA

Search the project's source declarations by name pattern. Supports glob patterns: * (any chars), ? (single char)

USAGE: search_symbols(query="*Service", kind="class") OUTPUT: One page of matching declarations with locations

KIND (optional, compared case-insensitively):

  • class, interface, enum, record, annotation: exactly the types of that kind (class excludes interfaces, enums, records and annotation types)

  • method: method declarations (constructors are not included, and lambda expressions are not method declarations)

  • field: every field declaration, including static final constants and enum constants; each result's kind is field, constant or enumConstant (record components are not field declarations) Without kind, every type is searched (no methods or fields). Any other kind is rejected with INVALID_PARAMETER. Anonymous classes have no name to match and are never results.

A method's or field's containingType is its declaring type's fully qualified name (pkg.Outer$Inner; an anonymous class is pkg.Outer$1). A type in the default package reports its package as "(default package)".

EXAMPLES:

  • search_symbols(query="Order*") - types starting with Order

  • search_symbols(query="*Repository", kind="interface")

  • search_symbols(query="get*", kind="method")

  • search_symbols(query="log", kind="field")

PAGINATION: the kind and pattern filters apply first, then offset and maxResults select the page. meta.totalCount counts every matching declaration; pagination.hasMore (and meta.truncated) is true when more follow this page, so request offset + returned next. maxResults outside 0 to 1000 is INVALID_PARAMETER.

A query naming the declaring type (Type.member) makes JDT resolve each declaration of the name and keep those of that type and its subtypes; one in a type whose own supertypes do not all resolve may be in that hierarchy, and is a potential match, never a result.

potentialMatches, present only when there are any, holds the places JDT's search reports as possible matches but cannot confirm, because a type or name there does not resolve (a missing dependency or a compile error): count is their exact number, and locations lists them, as many as the results it stands beside may list. They are never counted or listed as results.

IMPORTANT: Requires load_project to be called first.

Inputs: query (required), kind, offset, maxResults.

suggest_importsA

Find import candidates for unresolved type.

USAGE: suggest_imports(typeName="List") OUTPUT: List of matching types with fully qualified names and relevance

Searches project sources, JDK, and libraries for types matching the simple name that the project can import: a type in the default package, or in a package its module does not export to the project (such as the JDK's internal packages), is never a candidate; the package's name never decides. Every candidate is ranked by relevance (java.util types ranked higher than java.awt, etc.; equally relevant ones by fully qualified name), then the first maxResults are returned. totalCandidates and meta.totalCount count every candidate; meta.truncated is true when candidates are left out.

Requires load_project to be called first.

Inputs: typeName (required), maxResults.

validate_syntaxA

Quick syntax-only validation for a file or inline code.

USAGE: validate_syntax(filePath="...") or validate_syntax(content="...") OUTPUT: Syntax errors (no semantic analysis for speed)

Much faster than get_diagnostics - use for quick syntax checks.

Requires load_project to be called first.

Inputs: content, fileName, filePath.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 75 tools

    Disambiguation3/5

    Many tools overlap in purpose: composite analyzers (analyze_file, analyze_type, analyze_method) duplicate granular tools, and multiple position-based info tools (get_symbol_info, get_hover_info, get_type_at_position, get_javadoc) retrieve similar data. Descriptions clarify intended use, but the large set of near-neighbors creates meaningful misselection risk.

    Naming Consistency4/5

    Consistent snake_case with a verb_noun pattern for the vast majority (find_references, get_type_hierarchy, extract_method, apply_quick_fix). A few outliers like health_check, pull_up, and push_down lack a clear verb_noun form, but remain readable and stylistically consistent.

    Tool Count1/5

    75 tools is far beyond the typical 3-15 range and exceeds the 50+ threshold for extreme mismatch. The breadth of Java analysis features justifies many tools, but the set is excessively large and will severely burden tool selection.

    Completeness5/5

    Covers navigation, search, refactoring, diagnostics, metrics, dependency analysis, framework detection (Spring, JPA, JAX-RS), tests, and impact analysis. Only minor gaps like extract class or safe delete exist; the core Java code intelligence lifecycle is fully represented.

    Maintenance

    ActivityMaintained
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers