Lsp Server

An MCP (Model Context Protocol) server that bridges Claude Code to Language Server Protocol (LSP) servers, enabling semantic code intelligence capabilities.

Overview

lsp-mcp-server acts as a bridge between Claude Code and language servers, providing powerful code intelligence features:

• Go to Definition - Navigate to where symbols are defined
• Find References - Find all usages of a symbol across the workspace
• Hover Information - Get type information and documentation
• Code Completion - Get intelligent code suggestions
• Diagnostics - Access errors, warnings, and hints from the language server
• Symbol Search - Search for symbols in documents or across the workspace
• Rename - Safely rename symbols across the entire codebase
• Code Actions - Apply quick fixes, refactorings, and organize imports
• Call Hierarchy - See who calls a function and what it calls
• Type Hierarchy - Explore class inheritance and interface implementations
• Format Document - Format code using the language server's formatter
• Smart Search - Comprehensive symbol analysis in a single call
• File Analysis - Explore imports, exports, and file relationships

┌─────────────┐      ┌──────────────────┐      ┌───────────────────┐
│ Claude Code │────▶│  lsp-mcp-server  │────▶│ Language Servers  │
│   (MCP)     │◀────│   (this tool)    │◀────│ (TypeScript, etc) │
└─────────────┘      └──────────────────┘      └───────────────────┘
      stdio              stdio/JSON-RPC            stdio

Features

• 29 MCP Tools for comprehensive code intelligence
• 10 Languages Supported out of the box:
  • TypeScript / JavaScript
  • Python
  • Rust
  • Go
  • C / C++
  • Ruby
  • PHP
  • Elixir
  • Kotlin
  • Java
• Multi-root Workspace - Proper monorepo support with per-workspace server instances
• Push-based Diagnostics - Real-time error/warning caching from language servers
• Human-friendly Positions - All line/column numbers are 1-indexed
• Safe Rename - Preview changes before applying with dry-run mode
• Automatic Server Management - Servers start on-demand and restart on crash
• Configurable - Customize language servers, timeouts, and more
• Security Features - File size limits, workspace boundary validation, absolute path enforcement

Installation

Prerequisites

• Node.js 18.0.0 or higher
• Language servers for the languages you want to use:

# TypeScript/JavaScript
npm install -g typescript-language-server typescript

# Python
pip install python-lsp-server

# Rust
rustup component add rust-analyzer

# Go
go install golang.org/x/tools/gopls@latest

# C/C++
# Ubuntu/Debian:
sudo apt install clangd
# macOS:
brew install llvm

# Ruby
gem install solargraph

# PHP
npm install -g intelephense

# Elixir
mix escript.install hex elixir_ls
# Or download pre-built releases from:
# https://github.com/elixir-lsp/elixir-ls/releases

# Kotlin
# macOS:
brew install JetBrains/utils/kotlin-lsp
# Or download from:
# https://github.com/Kotlin/kotlin-lsp/releases

# Java (requires Java 20+, Maven, npm, protobuf)
git clone https://github.com/idelice/jls
cd jls && ./scripts/build.sh
# Add dist/ to PATH or symlink dist/lang_server_linux.sh as 'jls'

Install lsp-mcp-server

# Clone the repository
git clone <repository-url>
cd lsp-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Verify installation
node dist/index.js --help

Global Installation (Optional)

# Link globally for easy access
npm link

# Now you can run from anywhere
lsp-mcp-server

Configuration with Claude Code

1. Add to Claude Code MCP Settings

Create or edit the .mcp.json file in your home directory:

Location: ~/.mcp.json (user-level) or .mcp.json in your project root (project-level)

{
  "mcpServers": {
    "lsp": {
      "command": "node",
      "args": ["/absolute/path/to/lsp-mcp-server/dist/index.js"],
      "env": {
        "LSP_LOG_LEVEL": "info"
      }
    }
  }
}

Or if installed globally via npm link:

{
  "mcpServers": {
    "lsp": {
      "command": "lsp-mcp-server"
    }
  }
}

2. Restart Claude Code

After updating the configuration, restart Claude Code to load the new MCP server.

3. Verify Installation

In Claude Code, ask:

"Use lsp_server_status to check available language servers"

You should see a response showing the server is running.

4. Enforce LSP Tool Usage (Recommended)

To make Claude Code consistently prefer LSP tools over alternatives like Grep and Glob for code navigation, add instructions to your global ~/.claude/CLAUDE.md file:

## LSP Server - REQUIRED FIRST STEP

**BEFORE any code analysis, navigation, or codebase exploration, you MUST:**

1. Run `lsp_server_status` to check running servers
2. If the relevant language server is NOT running → run `lsp_start_server` immediately
3. ONLY AFTER the LSP server is running, proceed with analysis

This is a hard requirement, not a preference. Do NOT skip this step.

## LSP Tool Requirements

When LSP MCP tools are available, you MUST use them instead of alternatives:

| Task | REQUIRED Tool | FORBIDDEN Alternatives |
|------|---------------|----------------------|
| Find where X is defined | `lsp_goto_definition` | Grep, Read, Glob |
| Find where X is used | `lsp_find_references` | Grep |
| Find symbol by name | `lsp_workspace_symbols` or `lsp_find_symbol` | Glob, Grep |
| Understand file structure | `lsp_document_symbols` | Read entire file |
| Get type information | `lsp_hover` | Reading source code |
| Find implementations | `lsp_find_implementations` | Grep |
| Understand module API | `lsp_file_exports` | Read entire file |
| Check for errors | `lsp_diagnostics` | Running compiler manually |
| See file dependencies | `lsp_file_imports` or `lsp_related_files` | Grep for imports |

## Prohibited Patterns

When LSP is available, NEVER do these:

- NEVER use `Grep` to find function/class/symbol definitions
- NEVER use `Grep` to find where a symbol is referenced
- NEVER use `Glob` to find files containing a symbol name
- NEVER use `Read` to scan through a file looking for definitions
- NEVER use `Bash` with grep/rg/find for code navigation

These tools are still appropriate for:
- Searching for text/strings (not code symbols)
- Reading configuration files
- Reading documentation files
- File operations unrelated to code navigation

## LSP Tool Quick Reference

lsp_server_status # Check what's running lsp_start_server # Start a language server lsp_stop_server # Stop a language server lsp_goto_definition # Jump to where symbol is defined lsp_goto_type_definition # Jump to type definition lsp_find_references # Find all usages of a symbol lsp_find_implementations # Find concrete implementations lsp_workspace_symbols # Search symbols across project lsp_document_symbols # Get outline of a file lsp_document_highlights # Every occurrence in this file (read/write classified) lsp_hover # Get type/docs for symbol lsp_signature_help # Get function parameter hints lsp_inlay_hints # Inferred types + parameter names over a range lsp_completions # Get code completions lsp_diagnostics # Get errors/warnings for a file lsp_workspace_diagnostics # Get errors/warnings across opened files lsp_index_files # Warm up: batch-open files for workspace diagnostics lsp_file_exports # Get public API of a module lsp_file_imports # Get imports/dependencies of a file (regex, JS/TS) lsp_related_files # Find connected files (imports/imported by) lsp_folding_ranges # Foldable regions (functions, blocks, imports) lsp_selection_range # Semantic enclosing ranges (stmt/block/fn) lsp_rename # Rename symbol across codebase lsp_code_actions # Get/apply quick fixes and refactorings lsp_call_hierarchy # See callers and callees lsp_type_hierarchy # See type inheritance lsp_format_document # Format code lsp_smart_search # Combined: definition + refs + hover lsp_find_symbol # Find symbol by name (optionally scoped to a file)

This ensures Claude Code will:

• Always start the LSP server before analyzing code
• Use semantic LSP tools instead of text-based search for code navigation
• Fall back to Grep/Glob only for non-code searches (strings, config files, docs)

5. Install the LLM Usage Skill (Recommended)

This repository ships a SKILL.md — a self-contained, LLM-facing guide that teaches an assistant how to choose between the 29 lsp_* tools, what their gotchas are, and what canonical workflows look like. Installing it as a Claude Code skill lets the model load that guidance on demand instead of needing it pasted into every prompt.

Why install it in addition to the CLAUDE.md snippet above? The CLAUDE.md snippet enforces that LSP tools are used. SKILL.md teaches how to use them well — decision tree, workflows, gotchas, output shapes, error codes. The two complement each other.

Claude Code

Install at the user level (available in every project):

mkdir -p ~/.claude/skills/lsp-mcp-server
cp SKILL.md ~/.claude/skills/lsp-mcp-server/SKILL.md

Or at the project level (committed to a specific repo, available only inside it):

mkdir -p .claude/skills/lsp-mcp-server
cp /path/to/lsp-mcp-server/SKILL.md .claude/skills/lsp-mcp-server/SKILL.md

Restart Claude Code (or start a new session). The skill is auto-discovered from its YAML frontmatter (name: lsp-mcp-server). Claude will invoke it via the Skill tool whenever code navigation, refactoring, or diagnostics are relevant.

To verify, ask Claude Code:

"What skills do you have available for LSP?"

You should see lsp-mcp-server listed.

Other Claude / Anthropic SDK integrations

SKILL.md is plain Markdown with YAML frontmatter, so it works anywhere you can ship a Markdown document:

• Anthropic API / Claude Agent SDK — load it via the Skills feature or include it in your system prompt.
• Custom agents — copy the content into your agent's system prompt or knowledge base.
• Other LLM CLIs (Gemini CLI, Copilot CLI, etc.) — drop it into whichever skill / instruction directory the client supports, or include it as reference context.

The file is intentionally self-contained: no external links to follow, no other files to install. One Markdown document is the whole skill.

Keeping it up to date

If you upgrade lsp-mcp-server (new tools, new behaviors), re-copy SKILL.md from the new version. A future release may break with a stale skill if, for example, a tool signature changes — pinning the skill to the server version you run is the simplest way to stay aligned.

Available Tools

Navigation Tools

lsp_goto_definition

Navigate to the definition of a symbol.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)

Output:
  - definitions: Array of locations with path, line, column, and context

Example prompt: "Go to the definition of the function at line 42, column 10 in /project/src/utils.ts"

lsp_goto_type_definition

Navigate to the type definition of a symbol (useful for finding the interface/class that defines a variable's type).

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)

Output:
  - definitions: Array of type definition locations

Example prompt: "Find the type definition for the variable at line 15, column 5 in /project/src/app.ts"

Reference Tools

lsp_find_references

Find all references to a symbol across the workspace.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - include_declaration: Whether to include the declaration (default: true)
  - limit: Maximum results (default: 100, max: 500)
  - offset: Skip results for pagination (default: 0)

Output:
  - references: Array of locations
  - total_count: Total number of references found
  - has_more: Whether there are more results

Example prompt: "Find all references to the 'UserService' class in /project/src/services/user.ts at line 5"

lsp_find_implementations

Find all implementations of an interface or abstract method.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - limit: Maximum results (default: 50, max: 100)

Output:
  - implementations: Array of implementation locations
  - total_count: Total implementations found
  - has_more: Whether there are more results

Example prompt: "Find all implementations of the interface at line 10 in /project/src/types.ts"

Information Tools

lsp_hover

Get hover information (type info, documentation) for a symbol.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)

Output:
  - contents: Markdown-formatted type information and documentation
  - range: The range of the hovered symbol (optional)

Example prompt: "What is the type of the variable at line 25, column 8 in /project/src/main.ts?"

lsp_signature_help

Get function/method signature information when inside a call expression.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)

Output:
  - signatures: Array of function signatures with parameters
  - active_signature: Index of the active signature
  - active_parameter: Index of the active parameter

Example prompt: "What are the parameters for the function call at line 30 in /project/src/api.ts?"

Symbol Tools

lsp_document_symbols

Get all symbols (functions, classes, variables, etc.) defined in a document.

Input:
  - file_path: Absolute path to the source file

Output:
  - symbols: Hierarchical array of symbols with name, kind, range, and children

Example prompt: "List all symbols in /project/src/components/Button.tsx"

lsp_workspace_symbols

Search for symbols across the entire workspace by name.

Input:
  - query: Search query (supports fuzzy matching)
  - kinds: Filter by symbol kinds (optional): Class, Function, Interface, Variable, etc.
  - limit: Maximum results (default: 50, max: 100)

Output:
  - symbols: Array of matching symbols with path and location
  - total_count: Total matches found
  - has_more: Whether there are more results

Example prompt: "Search for all classes containing 'Service' in the workspace"

lsp_find_symbol

Find a symbol by name and get comprehensive information about it - no file path needed.

Input:
  - name: Symbol name to search for (supports fuzzy matching)
  - kind: Filter to specific symbol kind (optional): Class, Function, Interface, etc.
  - include: Array of what to include: 'hover', 'definition', 'references', 'implementations', 'incoming_calls', 'outgoing_calls' (default: ['hover', 'definition', 'references'])
  - references_limit: Maximum references to return (default: 20)

Output:
  - query: The symbol that was searched for
  - match: The best matching symbol found
  - matches_found: Number of total matches
  - definition: Where the symbol is defined
  - hover: Type information and documentation
  - references: All usages of the symbol
  - implementations: Implementations (for interfaces)
  - incoming_calls: Functions that call this
  - outgoing_calls: Functions this calls

Example prompt: "Find the UserService class and show me all its references"

File Analysis Tools

lsp_file_exports

Get the public API surface of a file - all exported functions, classes, interfaces, and variables.

Input:
  - file_path: Absolute path to the source file
  - include_signatures: Include type signatures from hover (default: true, slower but more informative)

Output:
  - file: The file path
  - exports: Array of exported items with name, kind, line, column, and signature
  - note: Additional information

Example prompt: "What does /project/src/utils/index.ts export?"

lsp_file_imports

Get all imports and dependencies of a file.

Input:
  - file_path: Absolute path to the source file

Output:
  - file: The file path
  - imports: Array of imports with module, line, symbols, is_type_only, is_dynamic
  - note: Additional information

Example prompt: "What modules does /project/src/api/client.ts import?"

lsp_related_files

Find files connected to a given file - what it imports and what imports it.

Input:
  - file_path: Absolute path to the source file
  - relationship: Which relationships to include: 'imports', 'imported_by', or 'all' (default: 'all')

Output:
  - file: The file path
  - imports: Array of files this file imports
  - imported_by: Array of files that import this file
  - note: Additional information

Example prompt: "What files depend on /project/src/services/auth.ts?"

Diagnostic Tools

lsp_diagnostics

Get cached diagnostics (errors, warnings) for a file.

Input:
  - file_path: Absolute path to the source file
  - severity_filter: Filter by severity - 'all', 'error', 'warning', 'info', 'hint' (default: 'all')

Output:
  - diagnostics: Array of diagnostics with range, severity, message, and code
  - summary: Count of errors, warnings, info, and hints
  - note: Information about diagnostic caching

Example prompt: "Show me all errors in /project/src/index.ts"

lsp_workspace_diagnostics

Get diagnostics across all open files in the workspace.

Input:
  - severity_filter: Filter by severity - 'all', 'error', 'warning', 'info', 'hint' (default: 'all')
  - limit: Maximum diagnostics to return (default: 50, max: 200)
  - group_by: How to group results - 'file' or 'severity' (default: 'file')

Output:
  - items: Array of diagnostics with file, line, column, severity, message, and context
  - total_count: Total diagnostics found
  - returned_count: Number returned (may be limited)
  - files_affected: Number of files with diagnostics
  - summary: Count of errors, warnings, info, and hints
  - note: Information about diagnostic caching

Example prompt: "Show me all errors across the entire project"

Completion Tools

lsp_completions

Get code completion suggestions at a position.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - limit: Maximum suggestions (default: 20, max: 50)

Output:
  - completions: Array of completion items with label, kind, detail, and documentation
  - is_incomplete: Whether the list is incomplete

Example prompt: "What completions are available at line 15, column 10 in /project/src/app.ts?"

Refactoring Tools

lsp_rename

Rename a symbol across the workspace.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - new_name: The new name for the symbol
  - dry_run: Preview changes without applying (default: true)

Output:
  - changes: Map of file paths to arrays of edits
  - files_affected: Number of files that would be modified
  - edits_count: Total number of edits
  - applied: Whether changes were applied
  - original_name: The original symbol name (if available)

Example prompt: "Rename the function 'getUserData' to 'fetchUserData' at line 20 in /project/src/api.ts (dry run first)"

lsp_code_actions

Get available code actions (refactorings, quick fixes) at a position or range, and optionally apply them.

Input:
  - file_path: Absolute path to the source file
  - start_line: Start line number (1-indexed)
  - start_column: Start column number (1-indexed)
  - end_line: End line number (optional, defaults to start line)
  - end_column: End column number (optional, defaults to start column)
  - kinds: Filter by action kinds (optional): quickfix, refactor, refactor.extract, refactor.inline, source.organizeImports, etc.
  - apply: If true, apply the action at action_index (default: false)
  - action_index: Index of action to apply when apply=true (default: 0)

Output:
  - actions: Array of available code actions with title, kind, and edits
  - total_count: Number of available actions
  - applied: The action that was applied (if apply=true and successful)

Example prompt: "What refactoring options are available for the function at line 50 in /project/src/utils.ts?"

Example prompt: "Apply the first quick fix for the error at line 15 in /project/src/api.ts"

lsp_format_document

Format a document using the language server's formatting capabilities.

Input:
  - file_path: Absolute path to the source file
  - tab_size: Spaces per tab (default: 2)
  - insert_spaces: Use spaces instead of tabs (default: true)
  - apply: Apply formatting to file (default: false)

Output:
  - edits: Array of formatting edits with range and new_text
  - edits_count: Number of edits
  - applied: Whether edits were applied

Example prompt: "Format /project/src/messy-file.ts using the language server"

Hierarchy Tools

lsp_call_hierarchy

Get the call hierarchy for a function - who calls it and what it calls.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - direction: 'incoming' (callers), 'outgoing' (callees), or 'both' (default: 'both')

Output:
  - item: The call hierarchy item at the position
  - incoming_calls: Array of functions that call this function
  - outgoing_calls: Array of functions this function calls

Example prompt: "Show me all functions that call handleRequest at line 100 in /project/src/server.ts"

lsp_type_hierarchy

Get the type hierarchy for a class or interface - supertypes and subtypes.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - direction: 'supertypes' (parents), 'subtypes' (children), or 'both' (default: 'both')

Output:
  - item: The type hierarchy item at the position
  - supertypes: Array of parent types/interfaces
  - subtypes: Array of child types/implementations

Example prompt: "What classes implement the Repository interface at line 5 in /project/src/types.ts?"

Combined Tools

lsp_smart_search

Comprehensive symbol search combining multiple LSP operations in one call.

Input:
  - file_path: Absolute path to the source file
  - line: Line number (1-indexed)
  - column: Column number (1-indexed)
  - include: Array of what to include: 'hover', 'definition', 'references', 'implementations', 'incoming_calls', 'outgoing_calls' (default: ['hover', 'definition', 'references'])
  - references_limit: Maximum references to return (default: 20)

Output:
  - symbol_name: Name of the symbol
  - hover: Type information and documentation
  - definition: Where the symbol is defined
  - references: All usages of the symbol
  - implementations: Implementations (for interfaces)
  - incoming_calls: Functions that call this
  - outgoing_calls: Functions this calls

Example prompt: "Give me a complete analysis of the processData function at line 75 in /project/src/processor.ts - definition, all references, and what calls it"

Server Management Tools

lsp_server_status

Get status of running language servers.

Input:
  - server_id: Specific server to check (optional, omit for all servers)

Output:
  - servers: Array of server status objects with id, status, capabilities, uptime, etc.

Example prompt: "Show the status of all language servers"

lsp_start_server

Manually start a language server for a specific workspace.

Input:
  - server_id: Server ID from configuration (e.g., 'typescript', 'python')
  - workspace_root: Absolute path to the workspace/project root

Output:
  - status: 'started'
  - server_id: The server that was started
  - workspace_root: The workspace root
  - capabilities: List of supported capabilities

Example prompt: "Start the TypeScript language server for /home/user/my-project"

lsp_stop_server

Stop a running language server.

Input:
  - server_id: Server ID to stop
  - workspace_root: Workspace root (optional, omit to stop all instances)

Output:
  - status: 'stopped'
  - server_id: The server that was stopped
  - was_running: Whether the server was actually running

Example prompt: "Stop the Python language server"

Supported Languages

The following languages are supported out of the box:

Language	Server	Command	File Extensions	Root Patterns
TypeScript/JavaScript	typescript-language-server	typescript-language-server --stdio	.ts, .tsx, .js, .jsx, .mjs, .cjs	tsconfig.json, jsconfig.json, package.json
Python	pylsp	pylsp	.py, .pyi	pyproject.toml, setup.py, requirements.txt, Pipfile
Rust	rust-analyzer	rust-analyzer	.rs	Cargo.toml
Go	gopls	gopls serve	.go	go.mod, go.work
C/C++	clangd	clangd --background-index	.c, .h, .cpp, .hpp, .cc, .cxx	compile_commands.json, CMakeLists.txt, Makefile
Ruby	solargraph	solargraph stdio	.rb, .rake, .gemspec	Gemfile, .ruby-version, Rakefile
PHP	intelephense	intelephense --stdio	.php, .phtml	composer.json, index.php
Elixir	elixir-ls	elixir-ls	.ex, .exs, .heex, .leex	mix.exs, .formatter.exs
Kotlin	kotlin-lsp	kotlin-lsp	.kt, .kts	build.gradle, build.gradle.kts, settings.gradle, settings.gradle.kts
Java	jls	jls	.java	pom.xml, build.gradle, build.gradle.kts, settings.gradle, settings.gradle.kts, BUILD, .classpath

You can add additional languages by providing a custom configuration (see Configuration).

Configuration

Configuration File

Create a configuration file at one of these locations (in order of priority):

1. ./.lsp-mcp.json (current directory)
2. ./lsp-mcp.json (current directory)
3. ~/.config/lsp-mcp/config.json (XDG config)
4. ~/.lsp-mcp.json (home directory)

Or set LSP_CONFIG_PATH environment variable to specify a custom path.

Example configuration:

{
  "servers": [
    {
      "id": "typescript",
      "extensions": [".ts", ".tsx", ".js", ".jsx"],
      "languageIds": ["typescript", "typescriptreact", "javascript", "javascriptreact"],
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "rootPatterns": ["tsconfig.json", "package.json"]
    },
    {
      "id": "python",
      "extensions": [".py"],
      "languageIds": ["python"],
      "command": "pylsp",
      "args": [],
      "rootPatterns": ["pyproject.toml", "setup.py", "requirements.txt"]
    }
  ],
  "requestTimeout": 30000,
  "autoStart": true,
  "logLevel": "info",
  "idleTimeout": 1800000
}

Configuration Options

Option	Type	Default	Description
servers	array	Built-in defaults	Language server configurations
requestTimeout	number	30000	Request timeout in milliseconds
autoStart	boolean	true	Auto-start servers on first request
logLevel	string	"info"	Log level: debug, info, warn, error
idleTimeout	number	1800000	Idle timeout before stopping servers (30 min)

Server Configuration

Each server in the servers array has:

Option	Type	Required	Description
id	string	Yes	Unique identifier for the server
extensions	string[]	Yes	File extensions this server handles
languageIds	string[]	Yes	LSP language identifiers
command	string	Yes	Command to start the server
args	string[]	Yes	Command arguments
env	object	No	Environment variables
initializationOptions	object	No	LSP initialization options
rootPatterns	string[]	No	Files/dirs that indicate project root

Environment Variables

Variable	Description
LSP_LOG_LEVEL	Override log level (debug, info, warn, error)
LSP_CONFIG_PATH	Path to configuration file
LSP_WORKSPACE_ROOT	Override workspace root detection

Security Features

lsp-mcp-server includes several security measures:

• Absolute Path Enforcement - All file paths must be absolute to prevent path traversal attacks
• Workspace Boundary Validation - File modifications (rename, format, code actions) are restricted to within the workspace root
• File Size Limits - Files larger than 10 MB are rejected to prevent memory exhaustion
• No Shell Execution - Language servers are spawned with shell: false to prevent command injection

Usage Examples with Claude Code

Basic Navigation

"I'm looking at /project/src/services/auth.ts. Can you tell me what the validateToken function at line 45 does? Use lsp_hover to get its documentation."

"Go to the definition of UserRepository used at line 23, column 15 in /project/src/controllers/user.ts"

Finding Usages

"Find all places where the handleError function is called in my codebase. It's defined at line 10 in /project/src/utils/error.ts"

"I want to refactor the Config interface. First, find all its implementations using lsp_find_implementations"

Code Quality

"Check /project/src/index.ts for any TypeScript errors using lsp_diagnostics"

"Show me all errors and warnings across the entire project using lsp_workspace_diagnostics"

Safe Refactoring

"I want to rename the getData function to fetchData. It's at line 50 in /project/src/api.ts. First do a dry run to see what would change."

"The dry run looks good. Now apply the rename by setting dry_run to false."

Code Exploration

"List all the symbols in /project/src/models/User.ts to understand its structure"

"Search the workspace for all classes that contain 'Controller' in their name"

"Find the UserService class and tell me everything about it - definition, references, and what calls it"

File Analysis

"What does /project/src/utils/index.ts export?"

"What files depend on /project/src/services/auth.ts? Use lsp_related_files"

"Show me all the imports in /project/src/api/client.ts"

Completions

"What methods are available on the object at line 30, column 5 in /project/src/app.ts? Use lsp_completions"

Code Actions and Refactoring

"What refactoring options are available for the code selection from line 20 to 35 in /project/src/utils.ts?"

"Organize imports in /project/src/components/App.tsx using lsp_code_actions with kinds filter for source.organizeImports"

"Apply the first quick fix for the error at line 15 in /project/src/api.ts"

Understanding Code Flow

"Show me the call hierarchy for the processOrder function at line 50 in /project/src/orders.ts - I want to see what calls it"

"What does the authenticate function call? Use lsp_call_hierarchy with outgoing direction"

"Show me the type hierarchy for the BaseRepository class - what are its subtypes?"

Comprehensive Analysis

"Give me a complete analysis of the UserService class at line 10 in /project/src/services/user.ts - I want definition, all references, implementations, and call hierarchy. Use lsp_smart_search"

Formatting

"Format /project/src/unformatted.ts using the language server (preview first, don't apply)"

Troubleshooting

Language Server Not Found

Error: Failed to start language server: typescript-language-server

Solution: Install the language server:

npm install -g typescript-language-server typescript

No Diagnostics Showing

Issue: lsp_diagnostics returns empty results

Explanation: Diagnostics are push-based. The language server sends them when files are opened or changed.

Solution:

1. Open the file using another tool first
2. Wait a moment for the server to analyze
3. Try again

Server Crashes Repeatedly

Issue: Server keeps crashing and restarting

Solution:

1. Check LSP_LOG_LEVEL=debug for detailed logs
2. Verify the language server is properly installed
3. Check if the workspace has valid configuration (e.g., tsconfig.json for TypeScript)

Position Errors

Issue: "Invalid position" errors

Remember: All positions are 1-indexed (first line is 1, first column is 1), not 0-indexed.

Path Errors

Issue: "File path must be absolute" errors

Remember: All file paths must be absolute (e.g., /home/user/project/src/file.ts, not src/file.ts).

Timeout Errors

Issue: Requests timing out

Solution: Increase the timeout:

export LSP_REQUEST_TIMEOUT=60000  # 60 seconds

Or in configuration:

{
  "requestTimeout": 60000
}

File Too Large

Issue: "File too large" errors

Explanation: Files larger than 10 MB are rejected to prevent memory issues.

Solution: Work with smaller files or split large files into modules.

Development

Building

npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm run typecheck    # Type-check only

Testing

npm test             # Run unit tests
npm run test:watch   # Watch mode

Interactive Testing

Use the MCP Inspector for interactive testing:

npx @modelcontextprotocol/inspector node dist/index.js

Linting

npm run lint         # Check for issues
npm run lint:fix     # Auto-fix issues

Architecture

Multi-root Workspace Support

Server instances are keyed by (serverId, workspaceRoot) pairs. This means:

• Each workspace gets its own language server instance
• Monorepos work correctly with multiple tsconfig.json files
• Server settings are isolated per workspace

Diagnostics Caching

Unlike other LSP features that are request-based, diagnostics are push-based:

1. Language servers send publishDiagnostics notifications
2. lsp-mcp-server caches these in memory
3. lsp_diagnostics and lsp_workspace_diagnostics tools read from the cache

This means diagnostics are available immediately after files are opened, without an explicit request.

Automatic Server Lifecycle

• Servers start automatically when needed (if autoStart: true)
• Crashed servers restart with exponential backoff (max 3 attempts in 5 minutes)
• Idle servers shut down after the configured timeout

Version

See package.json for the current version. The MCP server reports its version dynamically at startup, so it is always in sync with the package.

License

MIT

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting pull requests.