Navigation Tools
Relevant source files
The following files were used as context for generating this wiki page:
Navigation Tools in the lsp-mcp-server provide a semantic interface for exploring codebases via the Language Server Protocol (LSP). Unlike text-based search, these tools leverage the abstract syntax tree and semantic model maintained by language servers to provide accurate location data for definitions, references, and symbol hierarchies. The scope of these tools ranges from basic identifier lookup to complex relationship mapping, such as call and type hierarchies.
These tools are exposed through the Model Context Protocol (MCP) as high-level functions that handle file preparation, coordinate conversion (from human-readable 1-indexed to LSP 0-indexed), and result formatting.
Sources: src/index.ts:742-763, SKILL.md:16-24
Core Navigation Components
The navigation system relies on a standardized data flow where tool handlers interact with LSPClient instances through a centralized ToolContext. Every navigation request typically passes through a prepareFile utility which ensures the target document is synchronized with the language server before the request is dispatched.
Data Flow Architecture
The following diagram illustrates the lifecycle of a navigation request, from the MCP call to the LSP response processing.
The system ensures that file paths are absolute and positions are correctly mapped between the human-readable UI and the underlying protocol.
Sources: CLAUDE.md:46-55, src/tools/utils.ts:44-63
Primary Navigation Tools
The primary tools focus on locating specific identifiers and their relationships within the codebase.
Definition and Type Lookup
Tools like lsp_goto_definition and lsp_goto_type_definition allow users to jump to the source of a symbol or the declaration of its type.
| Tool | Purpose | Key Input Fields |
|---|---|---|
lsp_goto_definition | Find where a function, class, or variable is defined. | file_path, line, column |
lsp_goto_type_definition | Find the type that defines a variable or parameter. | file_path, line, column |
Sources: src/index.ts:114-149, src/schemas/tool-schemas.ts:51-63
Symbol Exploration
Symbols provide a structured view of the codebase, either within a single file or across the entire workspace.
- Document Symbols: Returns a hierarchical outline of a specific file (functions, classes, etc.).
- Workspace Symbols: Allows searching for symbols by name across all indexed files using fuzzy matching.
- File Exports: Specifically filters document symbols to show the public API surface of a module.
Advanced Relationship Mapping
For deeper architectural analysis, the Navigation Tools provide capabilities to trace execution flows and inheritance patterns.
Call and Type Hierarchies
- Call Hierarchy: Traces incoming callers or outgoing callees for a specific function.
- Type Hierarchy: Navigates inheritance trees, identifying supertypes (parents) and subtypes (children).
Smart Search and Find Symbol
lsp_smart_search and lsp_find_symbol act as composite tools. lsp_smart_search aggregates definition, hover info, references, and call hierarchy into a single MCP response to reduce round-trips for the LLM.
Data Structures and Results
Navigation results are standardized into LocationResult objects to ensure consistency across different tools.
| Field | Type | Description |
|---|---|---|
path | string | Absolute path to the file. |
line | number | 1-indexed start line. |
column | number | 1-indexed start column. |
context | string | The trimmed source line for quick preview. |
symbol_name | string? | Extracted identifier name if available. |
Sources: src/types.ts:592-602, src/tools/utils.ts:89-115
Conclusion
The Navigation Tools represent the semantic core of the lsp-mcp-server, providing high-fidelity code intelligence. By bridging the gap between raw file content and the language server's semantic understanding, these tools enable efficient and accurate traversal of complex, multi-language codebases.