Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

0.3.5 - 2026-03-17

Changed

Version bump to 0.3.5

0.3.4 - 2026-02-22

Changed

Version bump to 0.3.4

0.3.3 - 2026-02-04

Added

Recursive heuristics scanning (fixes #48) — LSP server heuristics now recursively scan workspace subdirectories for project markers, enabling detection of nested projects (e.g., Python bindings in python/ subfolder of a Cargo project). Features:
- is_applicable_recursive() method using ignore crate for efficient traversal
- Hardcoded exclusion list: node_modules, target, .git, __pycache__, .venv, venv, .tox, .mypy_cache, .pytest_cache, build, dist, .cargo, .rustup, vendor, coverage, .next, .nuxt
- Configurable heuristics_max_depth (default: 10) in [workspace] section
- Early termination on first marker match for performance
- Respects .gitignore patterns automatically

Changed

Default configuration — Include all 6 predefined LSP servers in ServerConfig::default() instead of just rust-analyzer. Servers included: rust-analyzer, pyright, typescript, gopls, clangd, zls. Heuristics ensure servers only spawn when project markers exist.
BREAKING: LspServerConfig::should_spawn signature — Method now accepts max_depth: Option<usize> parameter for recursive search depth control.

0.3.2 - 2026-02-03

Added

Server-Specific Heuristics (fixes #37):

Add ServerHeuristics struct with project_markers field for spawn filtering
Prevent spawning LSP servers in projects where they are not applicable
OR logic: server spawns if ANY marker file exists in workspace
Default heuristics for common LSP servers:
- rust-analyzer: Cargo.toml, rust-toolchain.toml
- pyright: pyproject.toml, setup.py, requirements.txt, pyrightconfig.json
- typescript-language-server: package.json, tsconfig.json, jsconfig.json
- gopls: go.mod, go.sum
- clangd: CMakeLists.txt, compile_commands.json, Makefile, .clangd
- zls: build.zig, build.zig.zon
User-configurable heuristics via [lsp_servers.heuristics] in mcpls.toml
Servers without heuristics always attempt spawn (backward compatible)
Skipped servers logged at INFO level for debugging
12 new unit tests for heuristics logic (329 total tests)

0.3.1 - 2026-01-24

Added

Custom Language Extension Mapping (3-phase implementation, fixes #33):

Configurable custom file extension-to-language ID mappings in mcpls.toml
Auto-config creation on first run with 30 sensible default language mappings (Rust, Python, TypeScript, Go, C/C++, Java, and 24 others)
Extension map automatically built from configuration and integrated through server initialization pipeline
Graceful fallback to plaintext language for unknown file extensions
Builder pattern for Translator initialization: Translator::new().with_extensions(HashMap)
Comprehensive test coverage with 4 new integration tests (317 total tests)
Platform-specific config paths: Linux/macOS ~/.config/mcpls/, macOS alternative ~/Library/Application Support/, Windows %APPDATA%\mcpls\
Default language extensions table in configuration documentation showing all 30 built-in mappings

Graceful LSP Server Degradation (5-phase implementation, fixes #32):

System now continues operating even when some LSP servers fail to initialize
Non-Rust developers can use mcpls without rust-analyzer installed
Structured error handling with new error types:
- ServerSpawnFailure struct for individual server failure details (language, command, error message)
- PartialServerInit variant for partial success scenarios
- AllServersFailedToInit variant for complete failure
- NoServersAvailable variant for when no servers can be initialized
ServerInitResult type for batch initialization result tracking:
- Tracks successful servers (HashMap) and failures (Vec) separately
- Helper methods: has_servers(), all_failed(), partial_success()
- Inspection methods: server_count(), failure_count()
spawn_batch() method for initializing multiple LSP servers:
- Sequential spawning with graceful degradation
- Never panics or returns early on individual failures
- Comprehensive logging (info for successes, error for failures)
- Returns complete failure information for user feedback
Refactored serve() function with three graceful degradation outcomes:
- All servers succeeded: serve normally
- Partial success: log warnings and continue with available servers
- All servers failed: return AllServersFailedToInit error
- No servers available: return NoServersAvailable error with clear message

Testing:

38 new tests covering all graceful degradation scenarios + 4 new tests for extension mapping (317 total tests, up from 275)
Tests for empty configs, single failures, multiple failures, edge cases, and extension mapping scenarios
Tests for logging behavior and error message formatting
Integration tests for complete serve() function degradation and extension map initialization

Documentation Updates:

Configuration documentation with extension mapping table and 30 built-in language mappings
Updated README with custom extension configuration examples
Added language_extensions section to TOML configuration reference

Changed

Language detection API — Breaking change: detect_language() now requires explicit HashMap<String, String> parameter instead of Option. This enables proper extension mapping support.
Error message clarity — SEC-01: Removed redundant "No LSP servers available" prefix from error messages to reduce information disclosure
Shorter tool descriptions — Condensed MCP tool descriptions for better compatibility with AI agent context windows
LSP server initialization — Switched from fail-fast to graceful degradation strategy
Error handling — More descriptive error messages showing which servers failed and why
Logging — Added warning-level logs for partial success scenarios
Documentation — Updated lib.rs crate documentation with graceful degradation and extension mapping overview

Fixed

Documentation link — Disambiguated error module link in crate docs (was causing rustdoc::broken-intra-doc-links warning)
Test isolation — Fixed test isolation issue in test_load_does_not_overwrite_existing_config by properly saving and restoring working directory, resolving llvm-cov coverage job failures

0.3.0 - 2025-12-28

Major feature release adding LSP notification handling and 3 new MCP tools for real-time diagnostics and server monitoring.

Added

New MCP Tools (3 tools):

get_cached_diagnostics — Fast access to push-based diagnostics from LSP server notifications. Returns cached diagnostics without triggering new analysis, ideal for quick error checks.
get_server_logs — Debug LSP issues with internal log messages (window/logMessage). Supports level filtering (error, warning, info, debug) and configurable limits.
get_server_messages — User-facing messages from the language server (window/showMessage). Captures prompts, warnings, and status updates that would normally appear in IDE popups.

LSP Notification Handling:

New NotificationCache for storing LSP server notifications (diagnostics, logs, messages)
Bounded channel-based storage with configurable limits (1000 diagnostics, 500 logs, 100 messages)
Cross-platform file URI handling with url::Url for Windows compatibility
Support for textDocument/publishDiagnostics, window/logMessage, and window/showMessage notifications

Enhanced Tool Descriptions:

All 16 MCP tools now have detailed #[tool(description)] explaining purpose, return values, and use cases
All parameter structs have #[schemars(description)] for JSON schema documentation
Helps AI agents understand when and how to use each tool

Testing:

28 new tests for notification handling (157 total tests, up from 129)
Tests for diagnostic caching with multiple severities, codes, and data
Tests for log filtering by level
Tests for message type handling
Cross-platform URI tests

Changed

MCP Tools reorganized — README now groups 16 tools into categories: Code Intelligence, Diagnostics & Analysis, Refactoring, Call Hierarchy, Server Monitoring
mcpls-core — url crate moved from dev-dependencies to dependencies for cross-platform URI handling
Documentation — Updated tools-reference.md with all 16 tools (was 8)

Fixed

Windows file URI format — Fixed cached diagnostics lookup on Windows. Was using format!("file://{}", path) which produces incorrect URIs on Windows (file://C:/... instead of file:///C:/...). Now uses Url::from_file_path() for cross-platform compatibility.

Removed

Dead code cleanup — Removed ~1100 lines of unused ToolHandler trait implementations from handlers.rs
ADR documents — Moved Architecture Decision Records to internal .local/ folder (not distributed)

0.2.2 - 2025-12-27

Patch release with critical bug fixes for LSP server process management.

Fixed

LSP child process lifetime — Fixed critical bug where the LSP server process (rust-analyzer) was killed immediately after initialization. The tokio::process::Child handle was not being stored, causing kill_on_drop to terminate the process. Now the server process stays alive for the lifetime of the MCP session.
Absolute workspace path — Fixed workspace path resolution to use absolute paths with canonicalization. Previously, when no workspace roots were configured, a relative path "." was used which resulted in invalid file://. URI that rust-analyzer couldn't handle.

Added

Codecov badge — Added code coverage badge to README with Codecov integration.

Changed

CI workflow — Fixed codecov upload by adding token for protected branches.
Test runner — Switched from cargo test to cargo nextest run in CI and documentation for faster test execution.

0.2.1 - 2025-12-27

Patch release with bug fix and documentation improvements.

Fixed

Infinite loop on EOF — Fixed infinite warning loop when LSP server terminates or stdin reaches EOF. Now returns ServerTerminated error cleanly instead of flooding logs with "Malformed header" warnings.

Added

Prerequisites section in README — Added rust-analyzer installation instructions with multiple methods (rustup, Homebrew, package managers). Includes important note about "LSP server process terminated unexpectedly" error when language server is missing.

0.2.0 - 2025-12-27

Enhanced LSP features release with 5 new MCP tools for advanced code intelligence.

Added

New MCP Tools (5 tools):

workspace_symbol_search — Search for symbols by name across the entire workspace with optional kind filtering and result limits
get_code_actions — Get available code actions (quick fixes, refactorings) at a position or range, with kind filtering support
prepare_call_hierarchy — Prepare call hierarchy at a cursor position, returning callable items for further exploration
get_incoming_calls — Find all callers of a function (who calls this?) with location information
get_outgoing_calls — Find all callees of a function (what does this call?) with call site ranges

Testing & Quality:

33 new unit tests for enhanced features (105 total tests, up from 72)
Comprehensive validation tests for position bounds and input parameters
Handler tests for all new MCP tools
Cross-platform file URI handling for Windows compatibility

Security Enhancements:

URI scheme validation for call hierarchy (enforces file:// scheme)
Path validation in all call hierarchy handlers
JSON size limits for call hierarchy item deserialization
Position upper bound validation (max 1,000,000 for line/character)

Changed

Updated test count from 72 to 105 tests
MCP tool handlers now use compact JSON serialization for better performance
Enhanced position validation with upper bounds across all position-based tools

Fixed

Cross-platform file URI handling now works correctly on Windows
URL crate added for proper file URI creation in tests

0.1.0 - 2025-12-25

Initial release of mcpls - Universal MCP to LSP bridge enabling AI agents to access semantic code intelligence.

Added

Core Features:

Universal MCP to LSP bridge exposing semantic code intelligence to AI agents
8 MCP tools for code intelligence:
- get_hover - Type information and documentation at cursor position
- get_definition - Symbol definition location (go-to-definition)
- get_references - Find all references to a symbol across workspace
- get_diagnostics - Compiler errors, warnings, and hints
- rename_symbol - Workspace-wide symbol renaming with preview
- get_completions - Code completion suggestions with documentation
- get_document_symbols - List all symbols in a document (outline view)
- format_document - Code formatting according to language server rules
LSP client implementation with JSON-RPC 2.0 transport over stdio
Support for multiple concurrent language servers (one per language)
Intelligent LSP server lifecycle management (spawn, initialize, shutdown)
Position encoding conversion (MCP 1-based to LSP 0-based, UTF-8/UTF-16/UTF-32)
Document state tracking with lazy loading and synchronization
Path validation and workspace boundary security
TOML configuration support with multiple discovery locations

Language Support:

Built-in rust-analyzer support (zero-config for Rust projects)
Configurable support for any LSP-compliant language server:
- Python (pyright, pylsp)
- TypeScript/JavaScript (typescript-language-server)
- Go (gopls)
- C/C++ (clangd)
- Java (jdtls)
- And any other LSP 3.17 compliant server

CLI & Configuration:

mcpls binary with stdio transport for MCP protocol
Configuration file support (mcpls.toml) with auto-discovery:
- --config flag
- $MCPLS_CONFIG environment variable
- ./mcpls.toml (current directory)
- ~/.config/mcpls/mcpls.toml (user config)
Structured logging (JSON and human-readable formats)
Log level control via --log-level and $MCPLS_LOG
Environment variable support for all settings
Workspace root auto-detection from current directory

Testing Infrastructure:

72+ unit and integration tests (100% pass rate)
Mock LSP server for isolated unit testing
Integration tests with real rust-analyzer
End-to-end MCP protocol tests
Test fixtures (Rust workspace, configuration files)
cargo-nextest configuration for parallel test execution
51.32% code coverage baseline

Documentation:

Comprehensive README with quick start guide
User documentation:
- Getting started guide with Claude Code integration
- Configuration reference with examples
- Tools reference (all 8 MCP tools documented)
- Troubleshooting guide with common issues
API documentation (rustdoc) for all public APIs
Architecture Decision Records (7 ADRs):
- ADR-001: Workspace structure
- ADR-002: Error handling strategy
- ADR-003: Async runtime selection
- ADR-004: Position encoding conversion
- ADR-005: Document state management
- ADR-006: Configuration format
- ADR-007: rmcp integration
Example configurations for multiple languages

Quality & CI/CD:

Comprehensive CI/CD pipeline with GitHub Actions
Multi-platform testing (Linux, macOS, Windows)
Security audit with cargo-deny (advisories, licenses, bans)
Clippy linting (pedantic + nursery level warnings)
rustfmt code formatting enforcement
Documentation completeness checks
Code coverage reporting with codecov
MSRV enforcement (Rust 1.85, Edition 2024)
Automated release workflow:
- Binary builds for 5 platforms (Linux x86_64, Linux musl, macOS x86_64, macOS aarch64, Windows x86_64)
- Automatic publishing to crates.io (mcpls-core first, then mcpls)
- GitHub Releases with binary artifacts
- Changelog integration

Performance & Optimization:

Optimized release profile with LTO and code generation settings
Binary size optimization (strip symbols, single codegen unit)
Async-first design for concurrent LSP server management
Efficient document synchronization (incremental updates)
Lazy initialization of LSP servers
Resource limits and timeouts

Security:

Path validation for all file operations (workspace boundary checks)
No unsafe code allowed (enforced by lints)
Regular dependency audits (cargo-deny)
License compliance verification (MIT OR Apache-2.0)
Secure LSP server process spawning
Input validation for all MCP tool parameters

Developer Experience:

Workspace-based Cargo project (mcpls-core library, mcpls CLI)
Comprehensive error messages with context
Tracing-based logging with structured output
Mock infrastructure for testing
Clear contribution guidelines
Issue and PR templates

Changed

N/A (initial release)

Deprecated

N/A (initial release)

Removed

N/A (initial release)

Fixed

N/A (initial release)

Security

Path validation prevents access outside workspace boundaries
All LSP file operations validated against workspace roots
Resource limits enforced for document tracking
No unsafe code (enforced via workspace lints)
Regular security audits via cargo-deny in CI
Dependency vulnerability scanning on every commit

Technical Details

Architecture:

flowchart TB
    A["AI Agent (Claude)"] <-->|"MCP Protocol"| B["mcpls Server (rmcp)"]
    B --> C["Translation Layer"]
    C --> D["LSP Client Manager"]
    D <-->|"LSP Protocol"| E["Language Servers"]

Dependencies:

rmcp 0.12 - Official MCP Rust SDK
lsp-types 0.97 - LSP type definitions
tokio 1.48 - Async runtime
serde/serde_json 1.0 - Serialization
clap 4.5 - CLI argument parsing
tracing 0.1 - Structured logging

Supported Platforms:

Linux x86_64 (glibc and musl)
macOS x86_64 (Intel)
macOS aarch64 (Apple Silicon)
Windows x86_64

Rust Version:

MSRV: 1.85
Edition: 2024
Stable Rust required

Installation Methods:

From crates.io: cargo install mcpls
From source: cargo install --path crates/mcpls-cli
Pre-built binaries from GitHub Releases

Configuration Example:

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

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

Usage with Claude Code: Add to ~/.claude/mcp.json:

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

Known Limitations

LSP servers must be installed separately (not bundled)
Language server initialization can take 1-5 seconds on first use
Limited to LSP 3.17 protocol features
No support for LSP extensions (server-specific features)
Document synchronization is full-text (not incremental at protocol level)

Future Roadmap

Phase 7 (Enhanced Features) — ✅ Completed in v0.2.0:

✅ Workspace symbol search across files
✅ Code actions (quick fixes, refactorings)
✅ Call hierarchy (incoming/outgoing calls)
Semantic tokens (syntax highlighting) — planned
Type hierarchy — planned
Inlay hints — planned

Phase 8 (Performance & Scale):

LSP server connection pooling
Response caching
Incremental document sync at protocol level
Batch request optimization
Memory usage optimization

Phase 9 (Developer Experience):

Configuration schema with validation
Better error messages with recovery suggestions
Progress reporting for long operations
Workspace auto-discovery
LSP server auto-detection and installation

FilesExpand file tree

CHANGELOG.md

Latest commit

History

CHANGELOG.md

File metadata and controls

Changelog

Unreleased

0.3.5 - 2026-03-17

Changed

0.3.4 - 2026-02-22

Changed

0.3.3 - 2026-02-04

Added

Changed

0.3.2 - 2026-02-03

Added

0.3.1 - 2026-01-24

Added

Changed

Fixed

0.3.0 - 2025-12-28

Added

Changed

Fixed

Removed

0.2.2 - 2025-12-27

Fixed

Added

Changed

0.2.1 - 2025-12-27

Fixed

Added

0.2.0 - 2025-12-27

Added

Changed

Fixed

0.1.0 - 2025-12-25

Added

Changed

Deprecated

Removed

Fixed

Security

Technical Details

Known Limitations

Future Roadmap