mcpls

Stop treating code as text. Give your AI agent a compiler's understanding.

mcpls is a universal bridge between AI coding assistants and language servers. It exposes the full power of LSP — type inference, cross-reference analysis, semantic navigation — through the Model Context Protocol, enabling AI agents to reason about code the way IDEs do.

Why mcpls?

AI coding assistants are remarkably capable, but they're working blind. They see code as text, not as the structured, typed, interconnected system it actually is.

mcpls changes that. By bridging MCP and LSP, it gives AI agents access to:

• Type information — Know exactly what a variable is, not what it might be
• Cross-references — Find every usage of a symbol across your entire codebase
• Semantic navigation — Jump to definitions, implementations, type declarations
• Real diagnostics — See actual compiler errors, not hallucinated ones
• Safe refactoring — Rename symbols with confidence, workspace-wide

Tip

Zero configuration for Rust projects. Just install mcpls and rust-analyzer — ready to go.

Installation

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/bug-ops/mcpls/main/scripts/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/bug-ops/mcpls/main/scripts/install.ps1 | iex

Both scripts detect your OS/architecture, download the matching release archive, verify its SHA256 checksum, and install mcpls to a per-user directory (~/.local/bin on Linux/macOS, $HOME\.local\bin on Windows) — no sudo/admin rights required.

Cargo, pre-built binaries & other methods

Cargo:

cargo install mcpls

Manual download:

Download the archive matching your platform from GitHub Releases. Each archive has a corresponding .sha256 checksum file published alongside it — the install scripts above verify this automatically; verify manually if downloading by hand.

Platform	Architecture	Archive
Linux	x86_64	mcpls-x86_64-unknown-linux-gnu.tar.gz
Linux	aarch64	mcpls-aarch64-unknown-linux-gnu.tar.gz
macOS	Intel	mcpls-x86_64-apple-darwin.tar.gz
macOS	Apple Silicon	mcpls-aarch64-apple-darwin.tar.gz
Windows	x86_64	mcpls-x86_64-pc-windows-msvc.zip
Windows	ARM64	mcpls-aarch64-pc-windows-msvc.zip

From source:

git clone https://github.com/bug-ops/mcpls
cd mcpls
cargo install --path crates/mcpls-cli

Prerequisites (language servers)

mcpls uses graceful degradation — if one language server fails, it continues with available servers.

Rust (rust-analyzer):

rustup component add rust-analyzer
# Or: brew install rust-analyzer (macOS)

Python (pyright, built-in default):

npm install -g pyright

Python (ty, with custom configuration):

uv tool install ty@latest

TypeScript:

npm install -g typescript-language-server typescript

Go (gopls):

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

[!IMPORTANT] At least one language server must be available.

Quick Start

1. Configure Claude Code (~/.claude/claude_desktop_config.json):

{
"mcpServers": {
"mcpls": {
"command": "mcpls",
"args": []
}
}
}

2. Experience the difference:

You: What's the return type of process_request on line 47?
Claude: [get_hover] It returns Result<Response, ApiError> where:
- Response is defined in src/types.rs:23
- ApiError is an enum with variants: Network, Parse, Timeout
You: Find everywhere ApiError::Timeout is handled
Claude: [get_references] Found 4 matches:
- src/handlers/api.rs:89 — retry logic
- src/handlers/api.rs:156 — logging
- src/middleware/timeout.rs:34 — wrapper
- tests/api_tests.rs:201 — test case

MCP Tools

Code Intelligence

Tool	What it does
get_hover	Type signatures, documentation, inferred types at any position
get_definition	Jump to where a symbol is defined — across files, across crates
get_references	Every usage of a symbol in your workspace
get_completions	Context-aware suggestions that respect types and scope
get_document_symbols	Structured outline — functions, types, constants, imports
workspace_symbol_search	Find symbols by name across the entire workspace
get_signature_help	Parameter info and active signature while typing a call
go_to_implementation	Jump to implementations of a trait method or interface member
go_to_type_definition	Jump to the type definition of an expression, distinct from get_definition for variable bindings
get_inlay_hints	Inferred type/parameter annotations an editor would render inline

Diagnostics & Analysis

Tool	What it does
get_diagnostics	Real compiler errors and warnings, not guesses
get_cached_diagnostics	Fast access to push-based diagnostics from LSP server
get_code_actions	Quick fixes, refactorings, and source actions at a position

Refactoring & Call Hierarchy

Tool	What it does
rename_symbol	Workspace-wide rename with full reference tracking
format_document	Apply language-specific formatting rules
prepare_call_hierarchy	Get callable items at a position for call hierarchy
get_incoming_calls	Find all callers of a function (who calls this?)
get_outgoing_calls	Find all callees of a function (what does this call?)

Server Monitoring

Tool	What it does
get_server_logs	Debug LSP issues with internal log messages
get_server_messages	User-facing messages from the language server

Configuration

Server Heuristics

mcpls uses smart heuristics to spawn only relevant language servers. Each server checks for project markers before starting.

Language	Server	Project Markers
Rust	rust-analyzer	Cargo.toml, rust-toolchain.toml
Python	pyright	pyproject.toml, setup.py, requirements.txt
TypeScript	typescript-language-server	package.json, tsconfig.json
Go	gopls	go.mod, go.sum
C/C++	clangd	CMakeLists.txt, compile_commands.json, Makefile
Zig	zls	build.zig, build.zig.zon

[!TIP] Heuristics use OR logic — if ANY marker exists, the server spawns.

Custom heuristics:

[[lsp_servers]]
language_id = "rust"command = "rust-analyzer"
[lsp_servers.heuristics]
project_markers = ["Cargo.toml", "rust-toolchain.toml", ".rust-version"]

Environment Variables

Variable	Description	Default
MCPLS_CONFIG	Path to configuration file	Auto-detected
MCPLS_TRUST_PROJECT_CONFIG	Load a ./mcpls.toml found in the current directory	false
MCPLS_LOG	Log level (trace, debug, info, warn, error)	info
MCPLS_LOG_JSON	Output logs as JSON	false

[!NOTE] The two boolean flags above accept 1/0, true/false, yes/no, y/n, and on/off (case-insensitive).

Config file locations:

Platform	Default Location
Linux	$XDG_CONFIG_HOME/mcpls/mcpls.toml, else ~/.config/mcpls/mcpls.toml
macOS	~/Library/Application Support/mcpls/mcpls.toml
Windows	%APPDATA%\mcpls\mcpls.toml

[!WARNING] A ./mcpls.toml in the current directory is not loaded automatically: it can control which command mcpls spawns as an LSP server, so running mcpls against an untrusted checkout must not execute commands from that checkout without explicit consent. Pass --trust-project-config (or set MCPLS_TRUST_PROJECT_CONFIG=true) only for repositories you trust.

Full Configuration Example

[workspace]
roots = ["/path/to/project"]
heuristics_max_depth = 10max_documents = 100# 0 = unlimitedmax_file_size = 10485760# bytes, 0 = unlimited
[[lsp_servers]]
language_id = "rust"command = "rust-analyzer"args = []
file_patterns = ["**/*.rs"]
timeout_seconds = 30request_timeout_seconds = 30
[lsp_servers.heuristics]
project_markers = ["Cargo.toml", "rust-toolchain.toml"]
[lsp_servers.initialization_options]
cargo.features = "all"checkOnSave.command = "clippy"
[[language_extensions]]
extensions = ["nu"]
language_id = "nushell"

See Configuration Reference for all options.

Supported Language Servers

mcpls works with any LSP 3.17 compliant server. Battle-tested with:

View supported servers

Language	Server	Notes
Rust	rust-analyzer	Zero-config, built-in support
Python	pyright (default), ty	Full type inference
TypeScript/JS	typescript-language-server	JSX/TSX support
Go	gopls	Modules and workspaces
C/C++	clangd	compile_commands.json
Java	jdtls	Maven/Gradle projects
Zig	zls	build.zig support
And 24+ others	Any LSP 3.17 server	See docs

Architecture

View architecture diagram

flowchart TB
subgraph AI["AI Agent (Claude)"]
end
subgraph mcpls["mcpls Server"]
MCP["MCP Server<br/>(rmcp)"]
Trans["Translation Layer"]
LSP["LSP Clients<br/>Manager"]
MCP --> Trans --> LSP
end
subgraph Servers["Language Servers"]
RA["rust-analyzer"]
PY["pyright"]
TS["tsserver"]
Other["..."]
end
AI <-->|"MCP Protocol<br/>(JSON-RPC 2.0)"| mcpls
mcpls <-->|"LSP Protocol<br/>(JSON-RPC 2.0)"| Servers

Loading

Key design decisions:

• Single binary — No Node.js, Python, or other runtime dependencies
• Async-first — Tokio-based, handles multiple LSP servers concurrently
• Memory-safe — Pure Rust, zero unsafe blocks
• Resource-bounded — Configurable limits on documents and file sizes

Documentation

• Getting Started
• Configuration Reference
• Tools Reference
• Troubleshooting
• Agent Skill — packaged Agent Skill teaching an AI coding agent to install, configure, and run the mcpls CLI

Development

cargo build # Build
cargo nextest run # Test
cargo run -- --log-level debug # Run locally

Requirements: Rust 1.88+ (Edition 2024)

Contributing

Contributions welcome. See CONTRIBUTING.md for guidelines.

License

Dual-licensed under Apache 2.0 or MIT at your option.

---

mcpls — Because AI deserves to understand code, not just read it.