Smart Search Tool
Relevant source files
The following files were used as context for generating this wiki page:
The Smart Search Tool is a composite utility within the lsp-mcp-server designed to provide comprehensive semantic information about a code symbol in a single request. By aggregating multiple Language Server Protocol (LSP) operations—such as hover, definition, references, and call hierarchies—it allows clients to gather full context without making multiple sequential tool calls.
This tool is particularly useful for deep code analysis, enabling developers or AI agents to understand a symbol's type signature, its origin, and its impact across the codebase simultaneously. It handles partial failures gracefully, ensuring that if one LSP operation (e.g., call hierarchy) fails or is unsupported, the other requested data is still returned.
Sources: src/index.ts:354-356, SKILL.md:104-112, src/tools/smart-search.ts:93-96
Architecture and Data Flow
The Smart Search Tool operates by orchestrating several underlying LSP client methods. When a request is received, the server identifies the target file, ensures the language server is running, and then executes a series of asynchronous queries based on the user's include parameters.
Execution Flow
The following diagram illustrates how handleSmartSearch processes a request by delegating to the LSPClient:
The tool first calls prepareFile, which validates the absolute path, identifies the correct LSP client instance, and ensures the document is open in the DocumentManager.
Sources: src/tools/smart-search.ts:98-101, CLAUDE.md:65-72, src/tools/smart-search.ts:106-253
Key Components and Functions
handleSmartSearch
The primary entry point for the tool. It accepts a SmartSearchInput and returns a SmartSearchResponse. It specifically extracts the symbol name from the source text using the range returned by the hover operation.
Sources: src/tools/smart-search.ts:97-254
handleFindSymbol
A variant of the smart search logic that allows finding a symbol by name alone across the entire workspace. It uses workspaceSymbols to locate the best match (prioritizing exact matches) and then automatically triggers the handleSmartSearch logic on the resolved location to provide full context.
Sources: src/tools/smart-search.ts:285-308, src/tools/smart-search.ts:391-450
flattenDocumentSymbols
A recursive utility used by findSymbolInFile to convert hierarchical LSP DocumentSymbol trees into a flat list, facilitating easier searching and filtering by name or kind.
Sources: src/tools/smart-search.ts:46-79
API Configuration
The Smart Search Tool uses Zod schemas to validate inputs, ensuring all line/column numbers are 1-indexed and file paths are absolute.
Tool Input Schema (lsp_smart_search)
| Parameter | Type | Default | Description |
|---|---|---|---|
file_path | String | (Required) | Absolute path to the source file. |
line | Number | (Required) | 1-indexed line number. |
column | Number | (Required) | 1-indexed column number. |
include | Array | ['definition', 'references', 'hover'] | List of operations: definition, references, hover, implementations, incoming_calls, outgoing_calls. |
references_limit | Number | 10 | Max number of references/implementations to return. |
Sources: src/schemas/tool-schemas.ts:233-254, src/index.ts:357-376
Data Models
The response object aggregates data from various LSP capabilities into a structured format:
| Field | Type | Description |
|---|---|---|
symbol_name | string | The identified name of the symbol at the position. |
hover | object | Contains contents (markdown) and the symbol's range. |
definition | object | Location of the symbol's definition (path, line, column). |
references | object | List of usage locations and total count. |
incoming_calls | array | List of callers and their source ranges. |
Sources: src/tools/smart-search.ts:103-253, src/types.ts
Implementation Details
The implementation of handleSmartSearch is designed to be resilient. Each sub-operation is wrapped in its own try-catch block. This is critical because different Language Servers (e.g., gopls, clangd, typescript-language-server) have varying levels of support for features like Call Hierarchy or Implementation.
// Example of resilient implementation for incoming calls
if (include.includes('incoming_calls')) {
try {
const items = await client.prepareCallHierarchy(uri, position);
if (items && items.length > 0) {
const item = items[0]!;
const incomingCalls = await client.callHierarchyIncomingCalls(item);
// Map results...
}
} catch {
// Ignore call hierarchy errors, continue with other operations
}
}
Sources: src/tools/smart-search.ts:192-220
Position Handling
Internally, the server converts the human-friendly 1-indexed positions provided by the tool input into the 0-indexed format required by the LSP standard using the toPosition utility.
Sources: CLAUDE.md:55-58, src/tools/smart-search.ts:101
Conclusion
The Smart Search Tool is the most efficient way to explore a codebase using the lsp-mcp-server. By bundling multiple semantic queries into a single execution flow, it reduces network/stdio overhead and provides a high-density information packet about any given symbol. It serves as the primary "discovery" tool when a developer needs to quickly understand the role and impact of a specific function, class, or variable.
Sources: SKILL.md:157-160, src/index.ts:468-469