Introduction & Capabilities
Relevant source files
The following files were used as context for generating this wiki page:
The lsp-mcp-server is a specialized Model Context Protocol (MCP) server designed to bridge AI interfaces, such as Claude Code, with Language Server Protocol (LSP) implementations. By acting as an intermediary, it empowers AI models with semantic code intelligence, moving beyond simple text-based analysis to provide deep architectural understanding of codebases.
The system exposes 29 distinct MCP tools that facilitate advanced operations including go-to-definition, reference tracking, workspace symbol search, and automated refactoring. It supports a wide array of languages including TypeScript, Python, Rust, Go, C/C++, and others through configurable language server backends.
Sources: CLAUDE.md:6-10, package.json:2-5, SKILL.md:1-5
Architecture Overview
The server operates as a multi-tier proxy. It receives requests from Claude Code via MCP over standard I/O (stdio) and translates them into LSP requests for various language server processes.
The diagram shows the data flow from the AI client through the MCP server to the underlying Language Servers.
Sources: CLAUDE.md:21-27, src/index.ts:503-518
Key Components
- ConnectionManager: Manages instances of language servers. It keys instances by a combination of
serverIdandworkspaceRoot, enabling support for monorepos where different directories may require different server configurations. Sources: CLAUDE.md:29-32, src/types.ts:182-198 - DocumentManager: Handles file versioning and synchronization between the MCP server and the LSP. It ensures files are "opened" in the language server before operations are performed. Sources: CLAUDE.md:24-25, src/services/document-manager.ts:86-101
- LSPClient: The concrete implementation (
LSPClientImpl) that manages the lifecycle of the language server process, including spawning the process and handling JSON-RPC communication. Sources: src/services/lsp-client.ts:104-125, src/types.ts:117-175 - DiagnosticsCache: A global store for
publishDiagnosticsnotifications emitted by language servers, allowing the system to provide push-based error reporting. Sources: CLAUDE.md:25, src/types.ts:245-263
Core Capabilities
The server provides a comprehensive suite of tools for semantic code navigation and manipulation. These are categorized into several primary capability areas.
Navigation and Search
The system allows for precise location of code elements across the workspace. Unlike grep, these tools understand the semantic structure of the code, such as aliases and re-exports.
| Tool | Capability | Description |
|---|---|---|
lsp_goto_definition | Definition Tracking | Finds where a function, class, or variable is defined. |
lsp_find_references | Usage Analysis | Locates every usage of a symbol across the codebase. |
lsp_workspace_symbols | Global Search | Finds symbols by name using fuzzy matching across the whole project. |
lsp_smart_search | Composite Info | Returns definition, hover, and references in a single call. |
Sources: src/index.ts:102-140, SKILL.md:14-36, src/schemas/tool-schemas.ts:50-100
Intelligence and Documentation
These tools provide context and metadata about the code without requiring the model to read the full source implementation.
- Hover Information (
lsp_hover): Provides type signatures and documentation for any symbol. Sources: src/index.ts:167-178, src/schemas/tool-schemas.ts:102-106 - Inlay Hints (
lsp_inlay_hints): Reveals inferred types and parameter names within a specific code range. Sources: src/index.ts:413-428, src/schemas/tool-schemas.ts:333-345 - Signature Help (
lsp_signature_help): Offers parameter hints during function calls, particularly useful for overloaded functions. Sources: src/index.ts:181-192, src/schemas/tool-schemas.ts:108-112
Hierarchy and Relationships
The server can trace complex code relationships, such as inheritance and call graphs.
The diagram illustrates the hierarchical relationships exposed by the LSP tools.
Sources: src/index.ts:318-350, src/schemas/tool-schemas.ts:271-290
Implementation Details
Position Handling
A critical design decision is the use of 1-indexed positions (line and column) for tool inputs and outputs. This matches the human-readable format used by code editors. Internally, the server converts these to the 0-indexed format required by the LSP.
- Conversion logic: Handled by
toLspPosition()andfromLspPosition(). - UTF-16: Character positions are handled as UTF-16 code units to ensure correct indexing for multi-byte characters like emojis.
Sources: CLAUDE.md:36-41, src/utils/position.ts
Server Lifecycle
Language servers are managed dynamically to optimize resource usage.
- Auto-Start: Servers launch automatically on the first request for a supported file type.
- Health Management: Crashed servers undergo exponential backoff (up to 3 attempts in 5 minutes).
- Idle Timeout: Unused servers automatically shut down after a default period (30 minutes).
Sources: CLAUDE.md:58-63, src/types.ts:68-100
Security & Validation
The server implements several safeguards to protect the host system and ensure stability:
- Absolute Path Validation: All tool inputs require absolute file paths, validated via Zod schemas. Sources: CLAUDE.md:68-69, src/schemas/tool-schemas.ts:30-40
- Workspace Boundary Checks: Operations that modify files (e.g.,
lsp_rename,lsp_format_document) usevalidatePathWithinWorkspace()to prevent directory traversal or unauthorized writes. Sources: CLAUDE.md:70-72 - Resource Limits: Files exceeding 10 MB are rejected to prevent memory exhaustion. Sources: CLAUDE.md:73-74
- Shell Security: Language server processes are spawned with
shell: falseto mitigate command injection risks. Sources: CLAUDE.md:75-76, src/services/lsp-client.ts:133-138
Conclusion
The lsp-mcp-server transforms raw source code into a semantically navigable model. By leveraging standard Language Servers and providing robust lifecycle management, it enables AI agents to perform complex engineering tasks—such as refactoring and architectural analysis—with a level of precision that text-based search cannot achieve.
Sources: SKILL.md:1-10, CLAUDE.md:6-10