mcpls copilot-instructions.md

Copilot Instructions for mcpls

mcpls is a bridge between MCP (Model Context Protocol) and LSP (Language Server Protocol). AI clients speak MCP to mcpls; mcpls spawns and communicates with language servers over LSP.

AI Client ←→ [MCP/stdio] ←→ mcpls ←→ [LSP/stdio] ←→ language server

Key crates: mcpls-core/src/bridge/, lsp/, mcp/, config/.

Type safety

Prefer newtypes over primitive aliases for domain values. A raw u32 for a line number and a raw u32 for a column are indistinguishable to the compiler; a Line(u32) and Column(u32) make transpositions a compile error.

Encode protocol state in the type system where possible. A document that has been opened and one that has not should ideally be different types, not the same type with a boolean field. Typestate prevents calling operations that are only valid on open documents.

Avoid stringly-typed dispatch. Matching on &str method names to branch protocol behaviour should be replaced with a typed enum as soon as the set of methods is known and bounded.

Option<T> and Result<T, E> must not be unwrapped with .unwrap() or .expect() in production code paths. Use ?, if let, let-else, or explicit error mapping.

Idiomatic Rust

Prefer iterator adapters over manual loops. map, filter, flat_map, collect, and fold express intent more clearly and are easier to compose than for with a mutable accumulator.

Avoid unnecessary heap allocation. Prefer &str over String in function signatures where ownership is not required. Prefer Cow<str> when a function sometimes borrows and sometimes owns.

Use let-else (stabilised in Rust 1.65) to reduce nesting when early return on None or Err is needed:

// prefer
let Some(value) = option else { return Err(...) };
// over
let value = match option { Some(v) => v, None => return Err(...) };

Derive Clone, Debug, PartialEq on data types unless there is a specific reason not to. Their absence makes testing harder and the omission is rarely intentional.