Symbol Search & Outline
Relevant source files
The following files were used as context for generating this wiki page:
The Symbol Search & Outline system provides semantic navigation and structural analysis of codebases by leveraging the Language Server Protocol (LSP). It allows users to retrieve a hierarchical outline of a specific file (Document Symbols), search for symbols across an entire workspace (Workspace Symbols), and analyze the public API surface (File Exports) or dependency structure (File Imports/Related Files) of modules.
This system is exposed via the Model Context Protocol (MCP) as a set of specialized tools that bridge LLM requests to underlying language servers. By utilizing real semantic models rather than plain text search, these tools accurately identify functions, classes, and variables even across polyglot projects or complex alias structures.
Sources: src/index.ts:474-500, SKILL.md:14-19, src/tools/symbols.ts:98-105
Architectural Overview
The system operates by receiving MCP tool calls, validating them via Zod schemas, and delegating the logic to specific handlers that communicate with active LSP clients.
This diagram illustrates the data flow from an MCP tool request through validation to the final LSP server communication.
Sources: src/index.ts:518-568, src/tools/symbols.ts:107-120
Document Symbols & Outlining
The lsp_document_symbols tool provides a structured outline of a single file. It identifies all functions, classes, interfaces, and variables along with their nested relationships.
Implementation Logic
The handler handleDocumentSymbols prepares the file, retrieves symbols from the LSP client, and converts them into a recursive SymbolResult structure. It handles two types of LSP symbols:
- DocumentSymbol: Provides hierarchical data including children and selection ranges.
- SymbolInformation: Provides flat location data.
Sources: src/tools/symbols.ts:56-94
Data Structure: SymbolResult
| Field | Type | Description |
|---|---|---|
name | string | The name of the symbol (e.g., function name). |
kind | string | The standard LSP kind (e.g., "Class", "Method"). |
range | object | The full range of the symbol in the source. |
selection_range | object | The range of the identifier itself. |
children | SymbolResult[] | Nested symbols (recursive). |
Sources: src/types.ts:607-619
Workspace-Wide Search
Workspace search is handled by lsp_workspace_symbols and the composite lsp_find_symbol tool. Unlike document symbols, these tools do not require a file path and can perform fuzzy matching across all project files.
Merging Polyglot Results
In projects with multiple active language servers (e.g., a repository with both TypeScript and Python), the system queries all running servers in parallel. Each server query is capped with a 5-second timeout to prevent a single buggy server from blocking the entire request. Results are then merged and deduplicated by the key format path:line:name.
Sources: src/tools/symbols.ts:114-159
Relevance Sorting
Results are sorted using the following priority:
- Exact Matches: Symbols matching the query exactly (case-insensitive).
- Prefix Matches: Symbols starting with the query string.
- Lexicographical: Standard alphabetical sorting for remaining matches.
Sources: src/tools/symbols.ts:178-190
API Surface & Dependency Analysis
The system provides tools to understand how a file interacts with the rest of the codebase without reading the full source.
File Exports and Imports
- lsp_file_exports: Returns top-level symbols. If
include_signaturesis enabled, it performs atextDocument/hoverrequest for each symbol to extract its type signature. - lsp_file_imports: Uses regex patterns to identify ES modules (
import), CommonJS (require), and TypeScript type imports within the file content.
Sources: src/tools/symbols.ts:223-261, src/tools/symbols.ts:285-333
Related Files Relationship
The lsp_related_files tool determines relationships based on two directions:
- Imports: Local files imported by the target file (detected via relative path parsing).
- Imported By: Scans other documents currently cached in the session to see if they import the target file.
Sources: src/tools/symbols.ts:354-399
Smart Search Integration
The lsp_smart_search and lsp_find_symbol tools act as composite handlers. They combine multiple LSP capabilities into a single response to provide "full context" for a symbol.
The Smart Search flow aggregates definition, hover, and reference data to reduce the number of tool calls required by the LLM.
Sources: src/tools/smart-search.ts:65-155
Key Tool Schemas
| Tool Name | Key Parameters | Purpose |
|---|---|---|
lsp_document_symbols | file_path | Get a structured outline of a file. |
lsp_workspace_symbols | query, kinds | Search for a symbol name project-wide. |
lsp_find_symbol | name, include | Find a symbol and get its definition/hover/references in one call. |
lsp_file_exports | file_path, include_signatures | List the public API of a module. |
Sources: src/schemas/tool-schemas.ts:89-119, src/schemas/tool-schemas.ts:291-325
Summary
The Symbol Search & Outline system provides the semantic "map" of the codebase. It transitions from local file structures (Document Symbols) to global search (Workspace Symbols) and high-level module summaries (Exports/Imports). By combining these with smart_search capabilities, the server enables efficient navigation without the overhead of multiple sequential LSP requests.
Sources: SKILL.md:21-35, src/tools/smart-search.ts:350-394