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. When Claude asks "what type is this variable?" it's guessing from context. When it refactors a function, it's hoping it found all the callers.

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
• Intelligent completions — Get suggestions that respect scope and types
• Safe refactoring — Rename symbols with confidence, workspace-wide

[!TIP] Zero configuration for Rust projects. Just install mcpls and a language server — ready to go.

Prerequisites

For Rust projects, install rust-analyzer:

# Via rustup (recommended)
rustup component add rust-analyzer

# Or via Homebrew (macOS)
brew install rust-analyzer

# Or via package manager (Linux)
# Ubuntu/Debian: sudo apt install rust-analyzer
# Arch: sudo pacman -S rust-analyzer

[!IMPORTANT] mcpls requires a language server to be installed. Without rust-analyzer, you'll see "LSP server process terminated unexpectedly" errors.

Installation

From crates.io

cargo install mcpls

Pre-built binaries

Download from GitHub Releases:

From source

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

Quick Start

1. Configure Claude Code

Add mcpls to your MCP configuration (~/.claude/claude_desktop_config.json):

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

2. Configure language servers (optional)

For languages beyond Rust, create ~/.config/mcpls/mcpls.toml:

[[lsp_servers]]
language_id = "python"
command = "pyright-langserver"
args = ["--stdio"]
file_patterns = ["**/*.py"]

[[lsp_servers]]
language_id = "typescript"
command = "typescript-language-server"
args = ["--stdio"]
file_patterns = ["**/*.ts", "**/*.tsx"]

3. 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

Diagnostics & Analysis

Refactoring

Call Hierarchy

Server Monitoring

Configuration

Environment Variables

Full Configuration Example

[workspace]
roots = ["/path/to/project"]
position_encodings = ["utf-8", "utf-16"]

[[lsp_servers]]
language_id = "rust"
command = "rust-analyzer"
args = []
file_patterns = ["**/*.rs"]
timeout_seconds = 30

[lsp_servers.initialization_options]
cargo.features = "all"
checkOnSave.command = "clippy"

[lsp_servers.env]
RUST_BACKTRACE = "1"

[!NOTE] See Configuration Reference for all options.

Supported Language Servers

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

Architecture

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

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 — First-time setup
• Configuration Reference — All options explained
• Tools Reference — Deep dive into each tool
• Troubleshooting — Common issues and solutions
• Installation Guide — Platform-specific instructions

Development

# Build
cargo build

# Test (uses nextest for speed)
cargo nextest run

# Run locally
cargo run -- --log-level debug

Requirements: Rust 1.85+ (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.