Hover, Completion & Hints
Relevant source files
The following files were used as context for generating this wiki page:
The Hover, Completion, and Hints systems in the lsp-mcp-server provide semantic code intelligence by bridging Model Context Protocol (MCP) tool calls to Language Server Protocol (LSP) endpoints. These features allow users to retrieve type signatures, documentation, intelligent code completions, parameter hints, and inferred type annotations directly from a language server.
These tools are essential for understanding code flow, variable types, and API contracts without manually reading source files. They rely on the underlying language server's ability to maintain a semantic model of the codebase, handling complex scenarios like overloads, aliases, and deep type inference.
Sources: CLAUDE.md, SKILL.md, src/index.ts:241-314
Architecture and Data Flow
The system operates by receiving an MCP request, validating it against a Zod schema, and delegating the execution to a specific tool handler. The tool handler uses a prepareFile utility to ensure the target document is open and that a connection to the appropriate language server is established.
Tool Request Execution Flow
The flow shows how a human-readable 1-indexed position is converted for the LSP server and how the result is mapped back for the user.
Sources: CLAUDE.md, src/tools/hover.ts:74-85, src/index.ts:803-840
Hover and Signature Help
The Hover and Signature Help modules provide immediate contextual documentation and parameter information.
Hover Information (lsp_hover)
The handleHover function retrieves type signatures and documentation for a symbol at a specific file position. It converts various LSP content formats (MarkupContent, MarkedString, or raw strings) into a consistent string format for the MCP client.
Sources: src/tools/hover.ts:41-94, src/schemas/tool-schemas.ts:88-92
Signature Help (lsp_signature_help)
The handleSignatureHelp function provides hints for function calls, specifically useful for identifying expected arguments and navigating overloaded functions.
Sources: src/tools/hover.ts:100-155, src/schemas/tool-schemas.ts:94-98
| Feature | Tool Name | Purpose |
|---|---|---|
| Hover | lsp_hover | Get type signature and documentation for any symbol. |
| Signature Help | lsp_signature_help | Get parameter hints for function calls and overloads. |
| Sources: src/index.ts:148-175 |
Inlay Hints
Inlay Hints provide visual annotations directly in the code for inferred types and parameter names. This is particularly useful for languages with heavy type inference like TypeScript or Rust.
The handleInlayHints function queries a specific range within a file. Because querying large files can be resource-intensive, the system allows a limit on the number of hints returned (defaulting to 100).
Sources: src/tools/inlay-hints.ts:41-86, src/schemas/tool-schemas.ts:311-325
Inlay Hint Components
- Label: The actual text displayed (e.g.,
: stringorname:). - Kind: Classified as either
typeorparameter. - Position: The 1-indexed line and column where the hint should appear.
Sources: src/types.ts:1068-1081, src/tools/inlay-hints.ts:31-34
Code Completions
The lsp_completions tool provides intelligent suggestions at a cursor position. It returns available methods, properties, variables, and types valid in the current semantic context.
The sequence diagram illustrates the request-response cycle for retrieving code completion suggestions.
Sources: src/types.ts:167-168, src/index.ts:258-275, src/tools/index.ts:52
Completion Data Structure
| Field | Type | Description |
|---|---|---|
label | string | The text to display in the suggestion list. |
kind | string | The type of completion (e.g., Method, Variable, Property). |
detail | string | Optional extra info (like type signature). |
documentation | string | Markdown or plain text documentation. |
| Sources: src/types.ts:803-810 |
Key Implementation Details
Position Handling
A critical design decision is the use of 1-indexed positions for all MCP tool inputs and outputs. Internally, the server converts these to the LSP-standard 0-indexed UTF-16 code units before communicating with language servers.
Sources: CLAUDE.md, src/tools/utils.ts:153-157
Implementation Example: Inlay Hints
// src/tools/inlay-hints.ts:55-61
const range = {
start: toPosition(start_line, start_column, content),
end: toPosition(end_line, end_column, content),
};
const result = await client.inlayHints(uri, range);
Sources: src/tools/inlay-hints.ts:55-61
Conclusion
The Hover, Completion, and Hints module transforms raw LSP data into actionable intelligence for the MCP environment. By handling the complexities of position conversion, document state management, and content formatting, it enables users to perform deep semantic analysis of codebases through a simplified tool interface.
Sources: SKILL.md, src/index.ts:854-880