Connection & Server Management
Relevant source files
The following files were used as context for generating this wiki page:
Connection and Server Management is the core orchestration layer of the lsp-mcp-server. It is responsible for bridging MCP tool requests to specific Language Server Protocol (LSP) instances. The system manages the entire lifecycle of language servers, including automatic discovery, initialization, state tracking, and graceful shutdown.
The architecture ensures that language servers are keyed by a combination of their server ID and the detected workspace root. This allows the system to support complex development environments, such as monorepos, where different sub-directories may require independent instances of the same language server.
Sources: CLAUDE.md:27-30, src/services/connection-manager.ts:54-58
Core Architecture & Components
The management logic is centralized in the ConnectionManagerImpl class, which interacts with individual LSPClient instances. It maintains a registry of active servers and ensures that requests are routed based on file extensions and project boundaries.
Server Keying and Monorepo Support
Servers are uniquely identified using a "Server Key" generated from the serverId and the workspaceRoot. This prevents collisions when the same language server (e.g., typescript-language-server) is used in different parts of a filesystem.
Sources: CLAUDE.md:27-30, src/services/connection-manager.ts:98-100
This diagram illustrates how a file path is resolved to a specific language server instance.
Sources: src/services/connection-manager.ts:63-94
Lifecycle States
Each server instance is tracked with a specific status, ensuring the manager knows when a server is ready for requests or needs a restart.
| State | Description |
|---|---|
starting | The server process is spawning and initializing. |
running | The server is initialized and ready to handle LSP requests. |
stopping | The server has received a shutdown request. |
stopped | The server has exited gracefully. |
crashed | The server exited with a non-zero code or failed to start. |
| Sources: src/types.ts:162-170, src/services/connection-manager.ts:251-260 |
Connection Lifecycle Management
Automatic Server Startup
The system typically operates on a "first-touch" basis. When an MCP tool like lsp_goto_definition is called, the prepareFile utility requests a client from the ConnectionManager. If no client exists for that workspace/language pair, one is automatically spawned.
Sources: SKILL.md:43-50, CLAUDE.md:55-64
The sequence of events during a lazy-start server initialization.
Sources: src/services/connection-manager.ts:176-217, CLAUDE.md:55-64
Fault Tolerance and Restarts
The ConnectionManager implements an exponential backoff strategy for crashed servers. It allows a maximum of 3 restart attempts within a 5-minute window. If a server exceeds these limits, it is marked as crashed and will not auto-restart to prevent resource exhaustion.
Sources: CLAUDE.md:66-67, src/services/connection-manager.ts:291-326
Idle Management
To conserve system resources, the manager tracks server activity. If a server remains unused for the duration of the idleTimeout (defaulting to 30 minutes), the manager triggers a graceful shutdown.
Sources: src/types.ts:121, src/services/connection-manager.ts:383-400
Configuration and Tool Integration
Server management is governed by the Config interface, which defines timeouts and server-specific command-line arguments.
| Configuration Field | Type | Description |
|---|---|---|
requestTimeout | number | Global default timeout for LSP requests in milliseconds. |
autoStart | boolean | Whether to start servers on the first request. |
idleTimeout | number | Milliseconds of inactivity before a server is stopped. |
servers | LSPServerConfig[] | Array of server definitions (command, args, extensions). |
| Sources: src/types.ts:107-124 |
Explicit Lifecycle Tools
While auto-start is preferred, the lsp-mcp-server provides tools for manual intervention:
lsp_server_status: Returns current PID, status, and capabilities for active servers.lsp_start_server: Manually triggers initialization for a workspace.lsp_stop_server: Terminates a specific instance or all instances of a language.
Sources: src/index.ts:365-397, src/types.ts:503-518
Class hierarchy showing the relationship between the manager, instance metadata, and the underlying LSP client.
Sources: src/types.ts:162-205
Conclusion
The Connection & Server Management system provides a robust, self-healing foundation for semantic code intelligence. By abstracting process management, workspace detection, and fault tolerance, it allows higher-level tool handlers to interact with language servers through a stable, unified interface without managing the complexities of the underlying LSP processes.
Sources: CLAUDE.md:16-24, src/services/connection-manager.ts:46-52