feat(config): add server-specific heuristics for spawn filtering (#45)

* feat(config): add server-specific heuristics for spawn filtering

Add minimal heuristics to prevent spawning LSP servers in projects
where they are not applicable (e.g., rust-analyzer in Python project).

- Add ServerHeuristics struct with project_markers field (OR logic)
- Extend LspServerConfig with optional heuristics field
- Filter servers based on workspace markers before spawn_batch()
- Add default heuristics for rust-analyzer, pyright, typescript,
  gopls, clangd, zls
- Add comprehensive unit tests for heuristics logic

Servers without heuristics always attempt spawn (backward compatible).
Skipped servers are logged at INFO level.

Closes #37

* docs: update changelog for server heuristics feature

* patch: bump version to 0.3.2 and document server heuristics

- Update workspace version from 0.3.1 to 0.3.2
- Update CHANGELOG with release date
- Add Server Heuristics section to README documenting:
  - Default project markers for each language server
  - OR logic for marker detection
  - Custom heuristics configuration examples

Author: bug-ops

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [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

Cargo.lock

@@ -3,7 +3,7 @@ members = ["crates/*"]
 resolver = "2"
 
 [workspace.package]
-version = "0.3.1"
+version = "0.3.2"
 edition = "2024"
 rust-version = "1.85"
 authors = ["Andrei G. <k05h31@gmail.com>"]
@@ -24,7 +24,7 @@ clap = "4.5"
 dirs = "6.0"
 futures = "0.3"
 lsp-types = "0.97"
-mcpls-core = { path = "crates/mcpls-core", version = "0.3.1" }
+mcpls-core = { path = "crates/mcpls-core", version = "0.3.2" }
 predicates = "3.1"
 rmcp = "0.14"
 rstest = "0.26"

Cargo.toml

@@ -261,6 +261,47 @@ Claude: [get_references] Found 4 matches:
 | `MCPLS_LOG` | Log level (trace, debug, info, warn, error) | `info` |
 | `MCPLS_LOG_JSON` | Output logs as JSON | `false` |
 
+### Server Heuristics
+
+mcpls uses smart heuristics to spawn only relevant language servers. Each server checks for project markers before starting — if no markers are found, the server is skipped.
+
+| Language | Server | Project Markers |
+|----------|--------|-----------------|
+| Rust | rust-analyzer | `Cargo.toml`, `rust-toolchain.toml` |
+| Python | pyright | `pyproject.toml`, `setup.py`, `requirements.txt`, `pyrightconfig.json` |
+| TypeScript | typescript-language-server | `package.json`, `tsconfig.json`, `jsconfig.json` |
+| Go | gopls | `go.mod`, `go.sum` |
+| C/C++ | clangd | `CMakeLists.txt`, `compile_commands.json`, `Makefile`, `.clangd` |
+| Zig | zls | `build.zig`, `build.zig.zon` |
+
+> [!TIP]
+> Heuristics use OR logic — if ANY marker exists, the server spawns. This prevents spawning rust-analyzer in a Python-only project.
+
+#### Custom Heuristics
+
+Override or disable heuristics per server:
+
+```toml
+[[lsp_servers]]
+language_id = "rust"
+command = "rust-analyzer"
+file_patterns = ["**/*.rs"]
+
+# Custom markers (OR logic)
+[lsp_servers.heuristics]
+project_markers = ["Cargo.toml", "rust-toolchain.toml", ".rust-version"]
+```
+
+To always spawn a server regardless of project type, omit the `heuristics` section:
+
+```toml
+[[lsp_servers]]
+language_id = "python"
+command = "pyright-langserver"
+args = ["--stdio"]
+# No heuristics = always spawn
+```
+
 ### Full Configuration Example
 
 ```toml
@@ -275,6 +316,9 @@ args = []
 file_patterns = ["**/*.rs"]
 timeout_seconds = 30
 
+[lsp_servers.heuristics]
+project_markers = ["Cargo.toml", "rust-toolchain.toml"]
+
 [lsp_servers.initialization_options]
 cargo.features = "all"
 checkOnSave.command = "clippy"

README.md

@@ -9,7 +9,7 @@ use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 
 use serde::{Deserialize, Serialize};
-pub use server::LspServerConfig;
+pub use server::{LspServerConfig, ServerHeuristics};
 
 use crate::error::{Error, Result};