Server Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Server Configuration in lsp-mcp-server defines the operational parameters for bridging Model Context Protocol (MCP) clients to various Language Server Protocol (LSP) implementations. It encompasses global settings, individual language server definitions, and the mechanism for detecting project roots. The configuration system ensures that the correct language server is instantiated with the appropriate arguments and environment variables based on the file type and workspace context.
The system utilizes a hierarchical approach, loading defaults from internal constants, merging them with external JSON configuration files, and allowing overrides via environment variables. This flexibility supports complex development environments, including monorepos and custom language server installations.
Sources: src/config.ts:80-149, src/types.ts:98-124
Configuration Data Structures
The configuration is structured around two primary interfaces: Config for global settings and LSPServerConfig for specific language server instances.
Global Configuration (Config)
| Option | Type | Description | Default |
|---|---|---|---|
servers | LSPServerConfig[] | List of configured language servers. | DEFAULT_SERVERS |
requestTimeout | number | Default timeout for LSP requests in milliseconds. | 30000 |
autoStart | boolean | Whether to start servers automatically on the first request. | true |
logLevel | string | Logging verbosity (debug, info, warn, error). | info |
idleTimeout | number | Time in ms before shutting down unused servers. | 1800000 (30m) |
Sources: src/types.ts:117-124, src/constants.ts
Language Server Configuration (LSPServerConfig)
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (e.g., "typescript", "python"). |
extensions | string[] | File extensions handled by this server. |
languageIds | string[] | LSP-standard language identifiers. |
command | string | The executable command to start the server. |
args | string[] | CLI arguments passed to the server command. |
env | Record<string, string> | Optional environment variables for the server process. |
rootPatterns | string[] | Files used to identify the project root (e.g., package.json). |
Sources: src/types.ts:98-115
Loading Logic and Priority
Configuration is loaded at server startup using the loadConfig() function. The system searches multiple locations in a specific order of priority, where later findings can override earlier ones.
- Defaults: Hardcoded values in
DEFAULT_CONFIGandDEFAULT_SERVERS. - Config Files: JSON files searched in:
- Current Working Directory (
.lsp-mcp.jsonorlsp-mcp.json) - XDG Config Directory (
~/.config/lsp-mcp/config.json) - User Home Directory (
~/.lsp-mcp.json)
- Current Working Directory (
- Environment Variables:
LSP_LOG_LEVEL(or legacyLSP_MCP_LOG_LEVEL)LSP_REQUEST_TIMEOUT(or legacyLSP_MCP_REQUEST_TIMEOUT)
Sources: src/config.ts:41-51, src/config.ts:80-149
Merging Behavior
When a user provides a server configuration in a JSON file, it is merged with the built-in servers. If the id of a user-defined server matches a built-in one, the user-defined configuration completely overrides the built-in version.
Sources: src/config.ts:63-78
Workspace and Root Detection
The configuration system relies on workspace detection to manage server instances. Each server is keyed by a combination of its serverId and the detected workspaceRoot.
The diagram shows the logic for resolving a workspace root and generating a unique server key.
Sources: src/utils/workspace.ts:77-118, src/utils/workspace.ts:207-211
Root Patterns
Workspace detection uses DEFAULT_ROOT_MARKERS (such as package.json, .git, tsconfig.json) unless specific rootPatterns are defined within a server's LSPServerConfig. The findWorkspaceRoot utility walks up the directory tree to find the outermost project root containing these markers.
Sources: src/utils/workspace.ts:77-118, src/constants.ts
Server Instance Lifecycle
Configuration values directly influence the lifecycle managed by the ConnectionManager.
- Auto-start: Controlled by
config.autoStart, servers are typically spawned on the first tool call for a matching file. - Idle Management: The
idleTimeoutsetting determines how long a server process remains active without receiving requests before theConnectionManagertriggers a shutdown to free system resources. - Request Timeouts: The
requestTimeout(global or per-server) is used by theLSPClientto race LSP requests against a timer, preventing the MCP server from hanging if a language server becomes unresponsive.
Sources: src/services/connection-manager.ts:57-93, src/services/connection-manager.ts:326-343, src/services/lsp-client.ts:581-608
Summary
The Server Configuration system provides the essential metadata required to bridge the gap between abstract MCP tool calls and concrete Language Server processes. By combining flexible discovery of configuration files with robust workspace root detection, it allows the lsp-mcp-server to operate seamlessly across diverse project structures and programming languages.
Sources: src/index.ts:738-744, CLAUDE.md:88-93