File Analysis Tools
Relevant source files
The following files were used as context for generating this wiki page:
File Analysis Tools in the lsp-mcp-server provide semantic insights into codebases by bridging the Model Context Protocol (MCP) with the Language Server Protocol (LSP). These tools enable developers and AI models to understand code structure, symbol relationships, and project-wide dependencies with higher accuracy than standard text-based search.
The suite includes tools for extracting document symbols, mapping file exports and imports, identifying related files, and performing "smart" searches that aggregate multiple LSP capabilities into a single request. Sources: SKILL.md:5-15, CLAUDE.md:8-12
Core Analysis Architecture
The file analysis system relies on a specialized workflow to ensure files are properly managed before querying. Most analysis tools follow a standardized data flow: input validation via Zod schemas, file preparation (opening the document in the LSP client), and semantic data extraction.
The prepareFile utility is central to this flow, handling path-to-URI conversion and ensuring the language server is synchronized with the document state. Sources: CLAUDE.md:61-71, src/tools/symbols.ts:63-65
Symbol Extraction and Navigation
Symbol-based tools provide a hierarchical or flat overview of identifiers within a file or workspace. These tools go beyond simple text matching by understanding the semantic "kind" of an identifier (e.g., Class, Method, Variable).
Document Symbols
lsp_document_symbols returns a structured outline of a specific file. It supports both hierarchical DocumentSymbol trees and flat SymbolInformation lists.
| Tool Name | Description | Key Parameters |
|---|---|---|
lsp_document_symbols | Returns a structured outline of functions, classes, and variables. | file_path |
lsp_workspace_symbols | Finds symbols across the entire project using fuzzy matching. | query, kinds, limit |
Sources: src/index.ts:133-162, src/tools/symbols.ts:61-82
Multi-Server Workspace Search
For polyglot projects, lsp_workspace_symbols queries all active language servers in parallel, merging and deduplicating results based on path, line, and symbol name.
Sources: src/tools/symbols.ts:88-154
Dependency and Relationship Analysis
These tools analyze how files interact through imports and exports. Unlike traditional search, these utilize regex-based extraction combined with LSP knowledge for high-fidelity mapping.
Export and Import Mapping
- Exports:
lsp_file_exportsidentifies the public API of a module. It can optionally fetch type signatures for each export by performing a hiddenhoverrequest for each symbol found. Sources: src/tools/symbols.ts:186-224 - Imports:
lsp_file_importsuses regex patterns to recognize ES modules (import), CommonJS (require), and TypeScript type-only imports. Sources: src/tools/symbols.ts:275-288
Related Files
lsp_related_files identifies bi-directional relationships:
- Imports: Files the target file depends on.
- Imported By: Other files in the current session that import the target file.
Note:imported_byonly sees files already opened in the current session. Sources: src/tools/symbols.ts:294-338, SKILL.md:144-148
Aggregate Analysis: Smart Search
The lsp_smart_search and lsp_find_symbol tools are "composite" tools designed to reduce round-trips by aggregating multiple LSP operations.
Smart Search Logic
When a user queries lsp_smart_search, the server concurrently or sequentially attempts to gather:
- Hover: Documentation and type signatures.
- Definition: The source location of the symbol.
- References: Usages across the codebase.
- Implementations: Concrete classes/methods for interfaces.
- Call Hierarchy: Incoming and outgoing function calls.
Summary of Analysis Capabilities
The File Analysis Tools provide a comprehensive suite for codebase exploration. By leveraging the ConnectionManager and DocumentManager, these tools ensure that even complex monorepos are handled correctly, providing context-aware results that simple text search cannot replicate. Sources: CLAUDE.md:20-25, SKILL.md:1-5