javalens-mcp

Check server status and project state.

USAGE: Call on startup to verify server is operational. OUTPUT: Server status, project info if loaded, capabilities.

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

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, build system

Supports:

• Maven projects (pom.xml)

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

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

Search for types, methods, fields by name pattern. Supports glob patterns: * (any chars), ? (single char)

USAGE: search_symbols(query="*Service", kind="Class") OUTPUT: List of matching symbols with locations

EXAMPLES:

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

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

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

PAGINATION: Use offset parameter for large result sets

IMPORTANT: Requires load_project to be called first.

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.

Find all references to a symbol across the project.

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

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

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.

Requires load_project to be called first.

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.

Requires load_project to be called first.

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.

Requires load_project to be called first.

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", "field", or "type" only

Requires load_project to be called first.

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.

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

Requires load_project to be called first.

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.

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.

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.

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.

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.

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.

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.

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.

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

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

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.

Requires load_project to be called first.

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.

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.

Requires load_project to be called first.

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

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

IMPORTANT: Uses ZERO-BASED coordinates.

Useful for understanding what a method depends on.

Requires load_project to be called first.

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.

Requires load_project to be called first.

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.

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.

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)

Requires load_project to be called first.

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

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

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.

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

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

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.

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 OUTPUT: All locations where the annotation is applied

Examples:

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

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

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

Requires load_project to be called first.

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

Requires load_project to be called first.

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

Requires load_project to be called first.

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

Requires load_project to be called first.

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

Requires load_project to be called first.

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

Requires load_project to be called first.

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.

Requires load_project to be called first.

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

Requires load_project to be called first.

Comprehensive file analysis in a single call.

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.

Comprehensive type analysis in a single call.

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.

Requires load_project to be called first.

Comprehensive method analysis in a single call.

Combines:

• Method info (signature, modifiers, return type)

• Parameters with types

• Declared exceptions

• Incoming calls (who calls this method)

• Outgoing calls (what this method calls)

• Override information (super method, overriding methods)

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

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

Get comprehensive usage summary for a type across the codebase.

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)

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

Requires load_project to be called first.

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.

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.

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.

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

Returns text edits for the method declaration and all call sites. The caller should apply these edits to perform the change.

USAGE: Position on method declaration, provide changes OUTPUT: Edits for declaration and all call sites

PARAMETER OPERATIONS:

• Add new parameter with default value for existing calls

• Remove parameter (will remove from calls)

• Rename parameter

• Reorder parameters (specify all parameters in new order)

IMPORTANT: Uses ZERO-BASED coordinates.

Requires load_project to be called first.

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.

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.

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.

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. Results are sorted by relevance (java.util types ranked higher than java.awt, etc.).

Requires load_project to be called first.

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

• UnusedImport: Remove unused import

• UnhandledException: Add throws or surround with try-catch

IMPORTANT: Uses ZERO-BASED line numbers.

Requires load_project to be called first.

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.

Get cyclomatic complexity, cognitive complexity, LOC.

USAGE: get_complexity_metrics(filePath="path/to/File.java") OUTPUT: Complexity metrics with risk assessment

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.

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

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.

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.

Requires load_project to be called first.

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

Options:

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

Requires load_project to be called first.

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.

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.

Requires load_project to be called first.

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

Requires load_project to be called first.

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.

Requires load_project to be called first.

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.

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.