Installation & Quickstart
Relevant source files
The following files were used as context for generating this wiki page:
lsp-mcp-server is a Model Context Protocol (MCP) server that acts as a bridge between AI clients (such as Claude Code) and Language Server Protocol (LSP) servers. Its primary purpose is to provide semantic code intelligence—including definitions, references, hover information, and diagnostics—to the AI model by leveraging existing language-specific LSP implementations.
Sources: CLAUDE.md:5-7, package.json:3-5
The system is designed for high-level human readability, utilizing 1-indexed line and column numbers for all tool inputs and outputs. It supports a wide range of languages including TypeScript, Python, Rust, Go, C/C++, and more. Servers are managed dynamically and are keyed by a combination of the server ID and the workspace root, allowing for robust monorepo support.
Sources: CLAUDE.md:32-34, CLAUDE.md:28-30, SKILL.md:1-5
System Requirements
The project is built using TypeScript and runs on Node.js. It adheres to strict module conventions and security protocols to ensure safe execution.
| Requirement | Specification |
|---|---|
| Node.js | >= 18.0.0 |
| Module Type | ESM (ECMAScript Modules) |
| LSP Version | 3.18.0 |
| MCP SDK | ^1.0.0 |
Sources: package.json:41-43, package.json:7, package.json:33-34
Installation and Build
To install the dependencies and prepare the project for execution, use standard npm commands. The build process compiles the TypeScript source code into a dist/ directory.
# Install dependencies
npm install
# Compile TypeScript to dist/
npm run build
# Clean the dist/ directory
npm run clean
Sources: CLAUDE.md:11-12, CLAUDE.md:20, package.json:20-30
Quickstart Guide
Starting the Server
The server communicates via standard input/output (stdio). It can be started directly using Node.js after compilation.
npm start
# Equivalent to: node dist/index.js
Sources: CLAUDE.md:13, package.json:21
Server Lifecycle and Auto-start
In standard operation, explicit server management is rarely required. The lsp-mcp-server implements an auto-start mechanism where language servers are spawned upon the first tool call that references a specific file path.
- Auto-start: Triggered by tools like
lsp_goto_definitionorlsp_hoverwhen afile_pathis provided. - Idle Timeout: Unused servers are automatically shut down after a period of inactivity (default: 30 minutes).
- Crash Recovery: Crashed servers restart with exponential backoff, allowing up to 3 attempts within 5 minutes.
Sources: CLAUDE.md:63-66, SKILL.md:21-23, src/types.ts:110-111
Basic Workflow
The following diagram illustrates the typical initialization and data flow when a tool is first invoked.
The diagram shows the transition from a client request to language server initialization and eventual response.
Sources: CLAUDE.md:46-55, src/index.ts:742-760
Configuration
The server's behavior is governed by a configuration file. The path to this file is defined by the LSP_CONFIG_PATH environment variable.
Workspace Detection
The server identifies the project root by searching upwards for specific markers:
package.jsontsconfig.jsonCargo.tomlgo.modpyproject.toml.git
This can be manually overridden using the LSP_WORKSPACE_ROOT environment variable.
Sources: CLAUDE.md:86-89, src/types.ts:148-151
Core Configuration Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
autoStart | boolean | true | Automatically start LSP servers on first request. |
requestTimeout | number | 30000ms | Global timeout for LSP requests. |
idleTimeout | number | 1800000ms | Time before stopping idle servers. |
logLevel | string | 'info' | Logging verbosity (debug, info, warn, error). |
Sources: src/types.ts:103-115
Verification and Testing
Interactive Testing
To test the server interactively and verify that it correctly bridges to local language servers, use the MCP Inspector:
npx @modelcontextprotocol/inspector node dist/index.js
Sources: CLAUDE.md:23-25
Running Tests
The repository includes unit and integration tests to ensure reliable position conversion and schema validation.
# Run all unit tests
npm test
# Run integration tests
npm run test:integration
# Run a specific test file
npm test -- tests/unit/position.test.ts
Sources: CLAUDE.md:14-18
Summary
To get started with lsp-mcp-server, users must compile the TypeScript project and run the server using npm start. The server abstracts the complexities of the Language Server Protocol by automatically managing server lifecycles, detecting workspace roots, and providing a set of standardized MCP tools for semantic code analysis. Verification is best performed via the MCP Inspector or the provided Vitest test suite.
Sources: CLAUDE.md:11-25, src/index.ts:710-730