Position & URI Utilities
Relevant source files
The following files were used as context for generating this wiki page:
The Position & URI Utilities represent a critical translation layer between the Model Context Protocol (MCP) environment and the Language Server Protocol (LSP) ecosystem. Since MCP tools typically interact with human-readable, 1-indexed coordinates and standard absolute file paths, and LSP servers require 0-indexed, UTF-16 code unit offsets and file:// URIs, these utilities ensure seamless interoperability across the server.
The scope of these utilities includes path normalization, URI conversion, coordinate indexing translation, and file system safety checks. They are primarily utilized by Tool Handlers to prepare inputs for LSP requests and format LSP responses for the client.
Sources: CLAUDE.md:33-40, src/utils/uri.ts:28-33
URI Management and Path Normalization
The system standardizes all document identifiers using the file:// URI scheme required by the LSP specification. It provides robust bidirectional conversion between absolute filesystem paths and URIs, handling platform-specific differences such as Windows drive letters and character encoding.
Core URI Functions
| Function | Description | Source |
|---|---|---|
pathToUri | Converts an absolute path to a file:/// URI, encoding special characters and handling Windows drive syntax. | src/utils/uri.ts:40-57 |
uriToPath | Converts a file:// URI back to an absolute filesystem path, decoding URI components. | src/utils/uri.ts:65-83 |
normalizePath | Resolves symlinks and normalizes path separators. | src/utils/uri.ts:91-101 |
validatePathWithinWorkspace | Ensures a path is contained within the workspace root to prevent directory traversal attacks. | src/utils/uri.ts:282-293 |
URI Conversion Flow
The following diagram illustrates how the server transforms a user-provided file path into an LSP-compatible URI.
Coordinate and Position Translation
LSP uses 0-indexed line and character offsets where characters are counted in UTF-16 code units. This is often incompatible with MCP tools or human editors that use 1-indexed systems. The position.ts utility handles this logic, including complex cases like multi-byte emoji characters.
Indexing Rules
- External (MCP): 1-indexed lines and columns.
- Internal (LSP): 0-indexed lines and character offsets.
Sources: CLAUDE.md:33-37, src/schemas/tool-schemas.ts:46-56
Key Position Functions
| Function | Logic | Source |
|---|---|---|
toLspPosition | Subtracts 1 from line/column; provides UTF-16 adjustment if content is provided. | src/utils/position.ts |
fromLspPosition | Adds 1 to line/column; maps UTF-16 units back to column numbers. | src/utils/position.ts |
getLineContent | Safely retrieves a specific line from a file content string (1-indexed). | src/utils/position.ts |
Sources: src/utils/position.ts, tests/unit/position.test.ts:40-96
File System Integration and Safety
The utilities include a "prepare" phase that integrates URI management with the DocumentManager. This ensures that before any LSP operation is performed, the file is properly validated, converted, and synchronized with the target language server.
Path Validation and Security
The server enforces several security boundaries during path processing:
- Absolute Path Enforcement: All incoming paths are validated via Zod to be absolute.
- Binary Detection: Files are checked via extension blocklists and null-byte detection to prevent processing binary data.
- Size Limits: Files exceeding
MAX_FILE_SIZE_BYTES(10MB) are rejected to prevent memory exhaustion. - Workspace Boundary: For destructive operations (rename, format), the system validates that the target path is within the detected workspace root.
Sources: src/utils/uri.ts:133-159, src/utils/uri.ts:188-213, src/utils/uri.ts:282-293, src/schemas/tool-schemas.ts:37-44
The prepareFile Workflow
This sequence shows how uri.ts and position.ts are utilized in a standard tool execution.
Language Identification
The URI utilities are used by the DocumentManager to map file extensions to LSP language identifiers. This is essential for the didOpen notification sent to language servers.
| Extension | Language ID |
|---|---|
.ts, .tsx | typescript, typescriptreact |
.js, .jsx, .mjs | javascript, javascriptreact |
.py, .pyi | python |
.rs | rust |
.go | go |
| Other | plaintext (fallback) |
Sources: src/services/document-manager.ts:37-81
Conclusion
The Position & URI Utilities provide the foundation for data consistency across the lsp-mcp-server. By abstracting the complexities of URI encoding, platform path variations, and UTF-16 coordinate translation, these utilities allow the rest of the system to operate on simplified, human-friendly representations of code locations while maintaining strict compliance with the Language Server Protocol.