Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The lsp-mcp-server serves as a bridge between the Model Context Protocol (MCP) and the Language Server Protocol (LSP). Its primary purpose is to expose semantic code intelligence capabilities—such as "Go to Definition," "Find References," and "Workspace Symbol Search"—to MCP clients like Claude Code. By acting as a proxy, it allows LLM-based tools to interact with specialized language servers for various programming languages (e.g., TypeScript, Python, Rust) using a standardized set of tools.
Sources: CLAUDE.md:5-9, SKILL.md:1-5
Core System Components
The system is organized into a modular architecture where shared services are accessed by tool handlers through a global context. This design separates the protocol handling (MCP) from the service implementations and the individual tool logic.
System Architecture Diagram
The following diagram illustrates the high-level relationship between the MCP client, the lsp-mcp-server, and the underlying Language Servers.
Sources: CLAUDE.md:19-25, src/index.ts:505-515
Key Components Table
| Component | Responsibility | Relevant Files |
|---|---|---|
| Connection Manager | Manages lifecycles of LSP server instances keyed by serverId and workspaceRoot. | src/types.ts:219-242, CLAUDE.md:21 |
| Document Manager | Tracks document versions and ensures files are synchronized with LSP clients via didOpen and didChange. | src/services/document-manager.ts, src/types.ts:258-278 |
| Diagnostics Cache | Stores push-based publishDiagnostics notifications received from LSP servers. | CLAUDE.md:23, src/types.ts:284-306 |
| Tool Handlers | 29 specialized handlers that validate input, interact with services, and format LSP responses for MCP. | src/index.ts:68-490, CLAUDE.md:24 |
| Tool Context | A global container providing tool handlers access to shared services. | CLAUDE.md:41-45, src/index.ts:518-523 |
Data Flow and Tool Execution
A typical tool execution follows a structured path from validation to service coordination and finally to LSP communication.
Execution Flow Sequence
The diagram below shows the sequence of events when a user requests a symbol definition.
Sources: CLAUDE.md:47-57, src/tools/utils.ts:40-58
Key Logic Decisions
- Server Instance Keying: Servers are unique per
(serverId, workspaceRoot). This supports monorepos where different directories might require different server configurations. Sources: CLAUDE.md:28-30 - 1-Indexed Positions: While LSP uses 0-indexed positions, the MCP tools use 1-indexed lines and columns for human readability. Conversions are handled by utility functions
toLspPosition()andfromLspPosition(). Sources: CLAUDE.md:35-37, src/tools/utils.ts:182-184 - Idempotent Document Opening: The
prepareFileutility is used by most handlers to ensure the relevant language server is started and the file is opened before any semantic request is made. Sources: src/tools/utils.ts:40-58, CLAUDE.md:52-56
Security and Performance
The architecture incorporates several constraints to ensure stability and security when interacting with local files and external processes.
- Path Validation: All file paths must be absolute. Modification operations (rename, format) validate that the path resides within the detected workspace root to prevent directory traversal. Sources: src/schemas/tool-schemas.ts:42-47, CLAUDE.md:78-80
- File Size Limits: Files exceeding 10 MB are rejected to prevent memory exhaustion. Sources: CLAUDE.md:81-82
- Process Security: Language servers are spawned with
shell: falseto mitigate command injection risks. Sources: CLAUDE.md:83 - Lifecycle Management: Servers auto-start on first demand and auto-stop after an
idleTimeout(default 30 minutes) to conserve system resources. Sources: CLAUDE.md:65-69, src/types.ts:162
Summary
The lsp-mcp-server architecture provides a robust, thread-safe, and multi-server environment for code analysis. By abstracting the complexities of LSP—such as 0-indexed positioning, UTF-16 character offsets, and asynchronous diagnostic pushing—into a clean MCP tool interface, it enables advanced semantic navigation for AI agents. The use of a central ConnectionManager and DocumentManager ensures that file state and server lifecycles are handled consistently across all 29 provided tools.
Sources: CLAUDE.md:19-25, SKILL.md:1-5