|
1 | 1 | --- |
2 | 2 | name: java-lsp-tools |
3 | | -description: Compiler-accurate Java code intelligence tools powered by the Java Language Server. ALWAYS load this skill when the workspace contains Java, Maven (pom.xml), or Gradle (build.gradle) projects. Use these tools to find symbol definitions, get type/call hierarchies, resolve types, inspect file outlines, and check imports in Java source files. Prefer over grep_search or read_file for any Java code navigation, understanding, debugging, or refactoring task. |
| 3 | +description: Compiler-accurate Java code navigation via the Java Language Server. Use lsp_java_findSymbol to locate symbols and lsp_java_getFileStructure to inspect file outlines. Prefer over grep_search for Java symbol navigation. |
4 | 4 | --- |
5 | 5 |
|
6 | 6 | # Java LSP Tools |
7 | 7 |
|
8 | | -Compiler-accurate Java code intelligence via the Java Language Server (jdtls). These 6 tools provide structured, low-token answers that are more precise than `grep_search` or `read_file` for Java code. |
9 | | - |
10 | | -## Activation |
11 | | - |
12 | | -These tools are **deferred** and must be discovered before first use. Activate all 6 tools at once with `tool_search_tool_regex` using pattern: |
13 | | - |
14 | | -`lsp_java_findSymbol|lsp_java_getFileStructure|lsp_java_getCallHierarchy|lsp_java_getTypeHierarchy|lsp_java_getTypeAtPosition|lsp_java_getFileImports` |
15 | | - |
16 | | -You only need to do this **once per session**. |
17 | | - |
18 | | -## When to Replace grep_search |
19 | | - |
20 | | -For Java source files, **always prefer these tools over generic alternatives**: |
21 | | - |
22 | | -| You're doing... | Use instead | Why | |
23 | | -|---|---|---| |
24 | | -| Find where a class/method is defined | `lsp_java_findSymbol` | ~60 tokens vs ~500 for grep (no comment/import noise) | |
25 | | -| Find all callers of a method | `lsp_java_getCallHierarchy("incoming")` | ~80 tokens vs ~3000 for grep (precise call sites only) | |
26 | | -| Find all implementations of an interface | `lsp_java_getTypeHierarchy("subtypes")` | ~60 tokens vs ~1000 for grep | |
27 | | -| Check a `var`/lambda/generic type | `lsp_java_getTypeAtPosition` | ~20 tokens vs guessing wrong | |
28 | | -| Search in non-Java files (xml, yaml, gradle) | Keep using `grep_search` | lsp_java_* tools only work on Java source | |
29 | | -| Search for string literals or comments | Keep using `grep_search` | lsp_java_* tools return symbol definitions only | |
30 | | - |
31 | | -**Rule of thumb**: If you're searching for a Java symbol name in `.java` files, there is almost always a `lsp_java_*` tool that returns more precise results with fewer tokens than `grep_search`. |
32 | | - |
33 | | -## Anti-patterns (Avoid these) |
34 | | - |
35 | | -❌ **Don't**: Use `grep_search("decodeLbs")` to find who calls `decodeLbs()` |
36 | | - - Returns 8+ matches including declaration, comments, imports → ~3000 output tokens |
37 | | - |
38 | | -✅ **Do**: Use `lsp_java_getCallHierarchy(uri, line, char, "incoming")` |
39 | | - - Returns only actual call sites → ~80 output tokens |
40 | | - |
41 | | -❌ **Don't**: Use `grep_search("class.*extends BaseDecoder")` to find subclasses |
42 | | -✅ **Do**: Use `lsp_java_getTypeHierarchy(uri, line, char, "subtypes")` |
43 | | - |
44 | | -❌ **Don't**: Read entire 1000+ line file to understand its structure |
45 | | -✅ **Do**: Use `lsp_java_getFileStructure(uri)` first, then `read_file` on specific line ranges |
| 8 | +Two compiler-accurate tools backed by the Java Language Server (jdtls). They return structured JSON with fewer tokens than `grep_search` or `read_file`. |
46 | 9 |
|
47 | 10 | ## Tools |
48 | 11 |
|
49 | | -All tools accept **workspace-relative paths** (e.g. `src/main/java/com/example/MyClass.java`) or full file URIs. All return structured JSON, each response < 200 tokens. |
50 | | - |
51 | | -### `lsp_java_getFileStructure` |
52 | | -Get hierarchical outline (classes, methods, fields) with line ranges. |
53 | | -Input: `{ uri }` → Output: symbol tree with `[L start-end]` ranges (~100 tokens) |
54 | | - |
55 | 12 | ### `lsp_java_findSymbol` |
56 | | -Search for symbol definitions by name across the workspace. Supports partial/fuzzy matching. |
57 | | -Input: `{ query }` → Output: up to 20 results with `{ name, kind, location }` (~60 tokens) |
| 13 | +Search for Java symbol definitions (classes, methods, fields) by name across the workspace. Supports partial matching. |
| 14 | +- Input: `{ query, limit? }` — limit defaults to 20, max 50 |
| 15 | +- Output: `{ name, kind, location }` per result (~60 tokens) |
| 16 | +- **Use instead of** `grep_search` when looking for where a class/method is defined |
58 | 17 |
|
59 | | -### `lsp_java_getFileImports` |
60 | | -Get all imports classified by source (jdk/project/external). |
61 | | -Input: `{ uri }` → Output: classified import list (~80 tokens) |
62 | | - |
63 | | -### `lsp_java_getTypeAtPosition` |
64 | | -Get compiler-resolved type signature at a specific position. |
65 | | -Input: `{ uri, line, character }` (0-based) → Output: fully resolved type (~20 tokens) |
66 | | - |
67 | | -### `lsp_java_getCallHierarchy` |
68 | | -Find all callers (incoming) or callees (outgoing) of a method. |
69 | | -Input: `{ uri, line, character, direction }` (0-based, direction: `"incoming"` | `"outgoing"`) → Output: list of `{ name, detail, location }` (~80 tokens) |
| 18 | +### `lsp_java_getFileStructure` |
| 19 | +Get hierarchical outline of a Java file (classes, methods, fields) with line ranges. |
| 20 | +- Input: `{ uri }` — workspace-relative path or full URI |
| 21 | +- Output: symbol tree with `L start-end` ranges (~100 tokens) |
| 22 | +- **Use instead of** `read_file` full scan when you need to understand a file's layout |
70 | 23 |
|
71 | | -### `lsp_java_getTypeHierarchy` |
72 | | -Find supertypes or subtypes/implementors of a type. |
73 | | -Input: `{ uri, line, character, direction }` (0-based, direction: `"supertypes"` | `"subtypes"`) → Output: list of `{ name, kind, location }` (~60 tokens) |
| 24 | +## When to Use |
74 | 25 |
|
75 | | -## Common Workflows |
| 26 | +| Task | Use | Not | |
| 27 | +|---|---|---| |
| 28 | +| Find class/method/field definition | `lsp_java_findSymbol` | `grep_search` | |
| 29 | +| See file outline before reading | `lsp_java_getFileStructure` | `read_file` full file | |
| 30 | +| Search non-Java files (xml, gradle) | `grep_search` | lsp tools | |
| 31 | +| Search string literals or comments | `grep_search` | lsp tools | |
76 | 32 |
|
77 | | -Most tasks follow the pattern: **findSymbol → getFileStructure → targeted tool**. |
| 33 | +## Typical Workflow |
78 | 34 |
|
79 | | -| Scenario | Workflow | Trigger | |
80 | | -|---|---|---| |
81 | | -| Debug a bug | `findSymbol` → `getFileStructure` → `read_file` (buggy method) → **`getCallHierarchy("incoming")`** → `read_file` (caller context) | When you found the buggy method and need to know ALL callers | |
82 | | -| Analyze impact | `findSymbol` → `getFileStructure` → `getCallHierarchy("incoming")` | Before editing a method, check who depends on it | |
83 | | -| Understand inheritance | `findSymbol` → `getTypeHierarchy("subtypes")` | When you see a base class and need all implementations | |
84 | | -| Check dependencies | `getFileImports` → `findSymbol` (dependency) → `getFileStructure` | When understanding external library usage | |
85 | | -| Resolve type ambiguity | `getFileStructure` → `getTypeAtPosition` | When you see `var`, generics, or lambda and need exact type | |
| 35 | +**findSymbol → getFileStructure → read_file (specific lines only)** |
86 | 36 |
|
87 | 37 | ## Fallback |
88 | 38 |
|
89 | | -- **`lsp_java_findSymbol` returns empty**: |
90 | | - - Symbol may not exist yet → switch to `read_file` + `grep_search` to confirm, then create it |
91 | | - - Spelling/query too specific → retry once with a shorter keyword (e.g. `"UserSvc"` instead of `"UserServiceImpl"`) |
92 | | -- **Path error** (e.g. "Unable to resolve nonexistent file"): Use `lsp_java_findSymbol` to discover the correct file path first, then retry. |
93 | | -- **Tool error / empty result** (jdtls not ready, file not in project): Fall back to `read_file` + `grep_search`. Don't retry more than once. |
| 39 | +- `findSymbol` returns empty → retry with shorter keyword, then fall back to `grep_search` |
| 40 | +- Path error → use `findSymbol` to discover correct path first |
| 41 | +- Tool error / jdtls not ready → fall back to `grep_search` + `read_file`, don't retry more than once |
0 commit comments