lsp-mcp

The most complete MCP server for language intelligence — built for agents, not just protocol passthrough. 24 tools spanning navigation, diagnostics, refactoring, and formatting. CI-verified across 7 languages. Built directly against the LSP 3.17 specification.

Unlike typical MCP-LSP bridges, lsp-mcp maintains a persistent language server session — agents operate on a fully indexed, stateful workspace with real-time diagnostics and cross-file reasoning, not a cold-started stub that forgets context between calls.

Designed for agentic workflows where correctness, persistence, and cross-language reliability are required.

Most MCP-LSP bridges are stateless and loosely implemented. They lose workspace context between calls, skip parts of the spec, and behave inconsistently across languages.

That makes them unreliable for agents operating on real codebases.

lsp-mcp fixes that.

Why lsp-mcp

	lsp-mcp	other MCP-LSP implementations
Languages (CI-verified)	7	1–2
Tools	24	3–5
LSP spec compliance	3.17, built to spec	ad hoc
Connection model	persistent	per-request
Cross-file references	✓	rarely
Real-time diagnostic subscriptions	✓	✗
Test coverage	76% statements, 86% functions	rarely tested

Use Cases

Agent-driven analysis across large, multi-language repositories
Safe, workspace-wide refactoring with full context
CI pipelines that validate against real language server behavior
Code intelligence without relying on an IDE

Quick Start

{
  "mcpServers": {
    "lsp": {
      "type": "stdio",
      "command": "npx",
      "args": ["blackwell-systems/LSP-MCP", "<language-id>", "<path-to-lsp-binary>", "<lsp-args>"]
    }
  }
}

TypeScript:

{ "args": ["blackwell-systems/LSP-MCP", "typescript", "typescript-language-server", "--stdio"] }

Go:

{ "args": ["blackwell-systems/LSP-MCP", "go", "gopls"] }

Rust:

{ "args": ["blackwell-systems/LSP-MCP", "rust", "rust-analyzer"] }

Multi-Language Support

Every language below is integration-tested on every CI run — start_lsp, open_document, get_diagnostics, and get_info_on_location all verified against the real language server binary:

Language	Server	Install
TypeScript / JavaScript	`typescript-language-server`	`npm i -g typescript-language-server typescript`
Python	`pyright-langserver`	`npm i -g pyright`
Go	`gopls`	`go install golang.org/x/tools/gopls@latest`
Rust	`rust-analyzer`	`rustup component add rust-analyzer`
Java	`jdtls`	eclipse.jdt.ls snapshots
C / C++	`clangd`	`apt install clangd` / `brew install llvm`
PHP	`intelephense`	`npm i -g intelephense`

Tools

All tools require start_lsp to be called first.

Session

Tool	Description
`start_lsp`	Start the language server with a project root
`restart_lsp_server`	Restart without restarting the MCP server
`open_document`	Open a file for tracking (required before position queries)
`close_document`	Stop tracking a file

Analysis

Tool	Description
`get_diagnostics`	Errors and warnings — omit `file_path` for whole project
`get_info_on_location`	Hover info (type signatures, docs) at a position
`get_completions`	Completion suggestions at a position
`get_signature_help`	Function signature and active parameter at a call site
`get_code_actions`	Quick fixes and refactors for a range
`get_document_symbols`	All symbols in a file (functions, classes, variables)
`get_workspace_symbols`	Search symbols by name across the workspace

Navigation

Tool	Description
`get_references`	All references to a symbol across the workspace
`go_to_definition`	Jump to where a symbol is defined
`go_to_type_definition`	Jump to the type definition of a symbol
`go_to_implementation`	Jump to all implementations of an interface or abstract method
`go_to_declaration`	Jump to the declaration of a symbol (distinct from definition — e.g. C/C++ headers)

Refactoring

Tool	Description
`rename_symbol`	Get a `WorkspaceEdit` for renaming a symbol across the workspace
`prepare_rename`	Validate a rename is possible before committing
`format_document`	Get `TextEdit[]` formatting edits for a file
`format_range`	Get `TextEdit[]` formatting edits for a selection
`apply_edit`	Apply a `WorkspaceEdit` to disk (use with `rename_symbol` or `format_document`)
`execute_command`	Execute a server-side command (e.g. from a code action)

Utilities

Tool	Description
`did_change_watched_files`	Notify the server when files change on disk outside the editor
`set_log_level`	Change log verbosity at runtime

Recommended agent workflow:

start_lsp(root_dir="/your/project")
open_document(file_path=..., language_id=...)
get_diagnostics()                          # whole project, no file_path
get_info_on_location(...) / get_references(...)
close_document(...)

Language IDs: typescript, typescriptreact, javascript, javascriptreact, python, go, rust, java, c, cpp, php

Resources

Diagnostic resources support real-time subscriptions — the server sends notifications/resources/updated when diagnostics change.

Scheme	Description
`lsp-diagnostics://`	All open files
`lsp-diagnostics:///path/to/file`	Specific file (subscribable)
`lsp-hover:///path/to/file?line=N&column=N&language_id=X`	Hover at position
`lsp-completions:///path/to/file?line=N&column=N&language_id=X`	Completions at position

LSP 3.17 Conformance

lsp-mcp is implemented directly against the LSP 3.17 specification and validated through integration testing against real language servers. Coverage includes:

Full lifecycle (initialize → initialized → shutdown) with graceful SIGINT/SIGTERM handling
Progress protocol — workspace-ready detection waits for all $/progress tokens to complete before sending references
Server-initiated requests (workspace/configuration, window/workDoneProgress/create, dynamic registration) — all correctly responded to, unblocking servers that gate workspace loading on these responses
Correct JSON-RPC framing, error code handling, and response shape normalization across hover, completion, code actions, and diagnostics

See docs/lsp-conformance.md for the full method coverage matrix and spec section references.

Extensions

Language-specific extensions add tools, prompts, and resource handlers, loaded automatically by language ID at startup.

To add an extension, create src/extensions/<language-id>.ts implementing any subset of getToolHandlers, getToolDefinitions, getResourceHandlers, getSubscriptionHandlers, getPromptDefinitions, and getPromptHandlers. All features are namespaced by language ID.

Development

git clone https://github.com/blackwell-systems/LSP-MCP.git
cd LSP-MCP && npm install && npm run build
npm test                   # all unit test suites
npm run test:multi-lang    # 7-language integration test (requires language servers)

Coverage: ~76% statements, ~86% functions. To inspect MCP traffic: claude --mcp-debug.

License

MIT

LSP-MCP