Selection & Folding Ranges
Relevant source files
The following files were used as context for generating this wiki page:
Selection and Folding Ranges are semantic code intelligence features provided by the lsp-mcp-server. They allow users to understand and navigate the structure of a codebase by identifying nested semantic blocks (Selection Ranges) and logically collapsible regions like functions, classes, or comment blocks (Folding Ranges).
These features bridge the gap between raw text and semantic structure. Selection ranges provide a chain of enclosing expressions and statements starting from a specific cursor position, which is essential for determining the correct scope for refactoring operations like Code Actions. Folding ranges provide a high-level structural overview of a file, enabling quick navigation of large documents by identifying foldable sections.
Sources: src/index.ts:506-531, SKILL.md:Decision tree, SKILL.md:H. Canonical Workflow
Selection Ranges
Selection ranges retrieve a hierarchical chain of semantic regions enclosing a specific coordinate. This chain starts at the innermost expression (the specific character at the line/column) and moves outward to the statement, block, and eventually the entire file.
Data Flow and Architecture
The tool handler handleSelectionRange processes incoming requests by preparing the target file and communicating with the underlying Language Server.
The diagram shows the transformation from a 1-indexed MCP request to a flattened array of semantic nodes retrieved from the LSP.
Sources: src/tools/selection-range.ts:47-62, CLAUDE.md:Data Flow
Key Implementation Details
The server implements a flatten function to convert the LSP's recursive linked-list structure (using parent pointers) into a flat array of SelectionRangeNode objects. Each node contains:
- Range: 1-indexed start and end coordinates.
- Context: The trimmed source text of the first line in that range for quick identification.
Sources: src/tools/selection-range.ts:31-45, src/types.ts:707-717
Folding Ranges
Folding ranges identify regions of a file that can be collapsed, such as large comment blocks, import sections, or function bodies. This is used to generate a quick structural overview of a file.
Logic and Filtering
The system supports filtering folding ranges based on their specific LSP kind:
comment: Large blocks of documentation or multi-line comments.imports: The block of import statements at the top of a file.region: Explicitly defined code regions (e.g.,#regionin TS/C#).all: Returns every foldable block including language-specific blocks like classes and functions.
Sources: src/tools/folding-ranges.ts:30-49, src/schemas/tool-schemas.ts:382-387
Implementation Structure
The handleFoldingRanges function interacts with the LSPClient to fetch FoldingRange objects and converts them to the internal 1-indexed format.
The sequence shows the retrieval and coordinate conversion process for folding ranges.
Sources: src/tools/folding-ranges.ts:30-49, src/types.ts:213
Technical Summary Tables
API Input Schemas
| Parameter | Type | Required | Description |
|---|---|---|---|
file_path | String | Yes | Absolute path to the source file. |
line | Number | Yes (Selection) | 1-indexed line number. |
column | Number | Yes (Selection) | 1-indexed column number. |
kind_filter | Enum | No (Folding) | One of: all, comment, imports, region. |
Sources: src/schemas/tool-schemas.ts:373-389
Response Data Models
| Component | Field | Type | Description |
|---|---|---|---|
| SelectionRangeNode | range | Object | 1-indexed start/end lines and columns. |
context | String | Trimmed source text of the range's first line. | |
parent | Object | Pointer to the next enclosing range. | |
| FoldingRangeResult | start_line | Number | 1-indexed beginning of the fold. |
end_line | Number | 1-indexed end of the fold. | |
kind | String | Optional kind (e.g., "comment"). |
Sources: src/types.ts:707-725
Conclusion
Selection and Folding Ranges provide essential structural context for code analysis. Selection ranges allow the system to intelligently identify refactoring targets by traversing the semantic hierarchy of a file. Folding ranges offer a condensed view of a file's structure, facilitating navigation and documentation discovery. Both features rely on accurate 1-indexed to 0-indexed coordinate conversion and robust communication with the underlying Language Server.
Sources: SKILL.md:Decision tree, CLAUDE.md:Architecture