version: "1.0.0" name: java-lsp-tools description: Java LSP navigation, source-range handoff and troubleshooting for type lookup and file outlines.

Java LSP Tools

Two navigation tools backed by language-service providers, including the Java Language Server (jdtls). Availability and results depend on imported projects, provider scope and Java settings; they do not certify complete coverage.

If these tools are not already available in the current tool list, load them with tool_search using a query such as Java LSP symbol navigation lsp_java.

Tools

lsp_java_findSymbol

Locate Java types (classes, interfaces, enums, records) by name or pattern.

• Input: { query, limit? } — integer limit defaults to 20, max 50; caps output only, not provider search work.
• Source methods are searched only when java.symbols.includeSourceMethodDeclarations is enabled (off by default). Fields are not searched. Do not change user settings to make a query work.
• Output: { results: [{ name, kind, container?, documentUri, file?, outlineSupported, unsupportedReason?, selectionRange: { startLine, endLine } }], total, truncated? }.
• selectionRange contains 1-based inclusive navigation lines, usually only the name. It is not a full declaration or implementation read range.
• documentUri preserves the provider's exact URI. file is an absolute path, present only for supported file: workspace documents. outlineSupported means the location is eligible for the outline tool, not that the file exists or is readable.
• Prefer this tool for type-name lookup. For a member, inspect the known containing type's file outline; if the type is unknown, use text search.

lsp_java_getFileStructure

Get hierarchical outline of a Java file (classes, methods, fields) with line ranges.

• Input: { uri, limit? } — prefer the exact documentUri from a result with outlineSupported=true. Confirmed absolute or workspace-relative file paths also work. Do not guess paths. Integer limit defaults to 20, max 60, including child nodes.
• Only file: documents within the workspace are supported. The item limit caps output, not provider work.
• Output: { documentUri, file, symbols: [{ name, kind, startLine, endLine, readFileRange, range, detail?, children? }], truncated? }. file is absolute. readFileRange contains a 1-based offset and line-count limit covering the provider's full declaration range.
• For a reader accepting { filePath, offset, limit }, use filePath=file with the selected symbol's readFileRange. Adapt to other reader schemas; Native and CLI parameters are not necessarily identical.
• Select a member before reading a large class. truncated=true means count or depth limits omitted symbols; it does not mean the requested member is absent. Use targeted text search when the capped outline omits it.
• Use before read_file when you need to choose a precise line range in a known Java file

When to Use

Typical Workflow

lsp_java_findSymbol → lsp_java_getFileStructure → read_file (specific lines only)

If lsp_java_findSymbol returns a relevant result with outlineSupported=true and implementation is needed, pass documentUri to lsp_java_getFileStructure. Select the appropriate member's full range, then read it. Do not use the workspace symbol's selectionRange as a substitute for a full implementation.

Fallback

• Empty result: normalization is retried internally only when it changes the query. Retry once after initialization if reason=serverNotFullyReady; otherwise use text search. Initialization readiness is not index-completeness evidence.
• outlineSupported=false: use an authorized document reader supporting documentUri. Dependency, virtual, remote and outside-workspace documents are not supported by this outline tool; do not rewrite their URIs as workspace paths or bypass access boundaries.
• fileNotFound: confirm the file via type lookup or file search; do not guess.
• permissionDenied / fileSystemUnavailable: check permissions or the file system connection; symbol search does not repair these failures.
• ambiguousWorkspacePath: pass documentUri instead of a duplicated workspace-folder display name.
• Other tool errors: fall back to text search and an appropriate reader; do not repeatedly retry.