Reference & Highlight Tools
Relevant source files
The following files were used as context for generating this wiki page:
Reference & Highlight Tools are a set of specialized MCP (Model Context Protocol) tools within the lsp-mcp-server designed to provide semantic code intelligence by identifying symbol usages and occurrences across a codebase. These tools bridge the gap between human-readable editor positions and the underlying Language Server Protocol (LSP) queries, enabling capabilities such as finding all references of a function, locating concrete implementations of an interface, or highlighting symbol occurrences within a single document. Sources: src/index.ts:109-158, CLAUDE.md:7-14
The suite includes tools for finding global references, discovering implementations, and performing local document highlighting. These tools utilize the project's internal managers—specifically the ConnectionManager and DocumentManager—to ensure files are properly synchronized with the relevant language server before executing queries. Sources: src/index.ts:506-522, SKILL.md:28-40
Global Reference & Implementation Search
The system provides tools to search for a symbol's footprint across the entire workspace. This is primarily handled by lsp_find_references and lsp_find_implementations. These tools are more accurate than text-based search because they utilize the semantic model provided by language servers to handle aliases and re-exports. Sources: src/index.ts:133-158, SKILL.md:14-16
Data Flow for References
When a reference search is initiated, the system prepares the file, converts 1-indexed positions to LSP 0-indexed format, and queries the LSPClient. The results are then paginated according to user input. Sources: src/tools/references.ts:34-71
The diagram shows the sequence of operations from receiving a request to returning paginated results. Sources: src/tools/references.ts:37-67
Tool Schema: Find References
The FindReferencesSchema enforces strict validation on input parameters, ensuring line and column numbers are valid and providing default pagination limits. Sources: src/schemas/tool-schemas.ts:70-86
| Parameter | Type | Default | Description |
|---|---|---|---|
file_path | string | N/A | Absolute path to the source file. |
line | number | N/A | 1-indexed line number. |
column | number | N/A | 1-indexed column number. |
include_declaration | boolean | true | Include the symbol declaration in results. |
limit | number | 100 | Max results to return (Max 500). |
offset | number | 0 | Number of results to skip. |
Sources: src/schemas/tool-schemas.ts:70-86, tests/unit/schemas.test.ts:71-77
Local Document Highlights
The lsp_document_highlights tool is designed for efficient, local analysis within a single file. It classifies occurrences of a symbol at a specific position into three categories: text, read, and write. This is particularly useful for local rename previews or understanding variable usage within a specific scope. Sources: src/index.ts:400-415, src/tools/document-highlights.ts:35-39
Highlight Classification
The tool maps internal LSP highlight kinds to human-readable strings. Sources: src/tools/document-highlights.ts:29-33
- text: General occurrence of the symbol.
- read: The symbol is being read from.
- write: The symbol is being assigned a value.
The sequence shows how the highlight handler interacts with the LSP client to categorize symbol occurrences. Sources: src/tools/document-highlights.ts:35-61
Implementations & Smart Search Integration
The lsp_find_implementations tool specifically targets abstract members, interfaces, or classes to find their concrete realizations. Sources: src/index.ts:145-158, src/tools/references.ts:76-116
Smart Search Aggregation
Reference and implementation data are also exposed via lsp_smart_search, which aggregates multiple LSP calls into a single response to reduce round-trip latency for the AI agent. Sources: src/tools/smart-search.ts:75-195
The class diagram illustrates how reference and implementation data is structured within a comprehensive Smart Search response. Sources: src/types.ts:634-651
Tool Configuration: Implementations
| Field | Type | Constraint | Description |
|---|---|---|---|
limit | number | 1-100 | Limits the number of returned implementations. |
returned_count | number | Output Only | Number of items actually returned in the current call. |
has_more | boolean | Output Only | Indicates if more implementations exist beyond the limit. |
Sources: src/schemas/tool-schemas.ts:88-97, src/types.ts:511-516
Summary
Reference and Highlight tools provide the semantic glue for navigating complex codebases. By leveraging the LSP, lsp-mcp-server ensures that symbol searches remain accurate across refactors and complex dependency trees. The architecture prioritizes performance through local highlights and developer convenience through aggregated "Smart Search" tools, all while maintaining strict 1-indexed position consistency for the user. Sources: SKILL.md:165-175, CLAUDE.md:37-40