code-analysis

# Code Analysis with LSP Use LSP tools for accurate, compiler-verified code understanding. These tools require the `mcpls` MCP server to be configured. ## Positions Positions are **1-based**: line 1, column 1 is the first character. If you read a file and see line numbers in the output, use those directly — no conversion needed (mcpls translates to 0-based LSP positions internally). File paths must be absolute. Relative paths will not resolve correctly. ## Tool Reference ### Code Intelligence | Tool | Purpose | When to use | |---|---|---| | `get_hover` | Type signature, inferred type, and documentation at a position | "What type is X?", "What does this function do?" | | `get_definition` | Navigate to where a symbol is defined | Read a function/type implementation before reasoning about it | | `get_references` | Find all usages of a symbol across the workspace | Before renaming, deleting, or changing a symbol's signature | | `get_completions` | Context-aware suggestions respecting types and scope | Exploring unknown APIs, discovering available methods | | `get_document_symbols` | Structured outline of a file (functions, types, constants, fields) | Understanding file structure without reading every line | | `workspace_symbol_search` | Search for a symbol by name across the entire workspace | Know a name but not which file defines it | ### Diagnostics and Correctness | Tool | Purpose | When to use | |---|---|---| | `get_diagnostics` | Real compiler errors and warnings for a file | After editing code — always call to verify correctness | | `get_cached_diagnostics` | Previously cached diagnostics (no fresh check) | Quick check when file has not changed recently | | `get_code_actions` | Quick fixes, refactorings, source actions at a position | Fix diagnostics automatically, add missing imports | ### Refactoring | Tool | Purpose | When to use | |---|---|---| | `rename_symbol` | Workspace-wide rename with full reference tracking | Always prefer over manual find-and-replace | | `format_document` | Apply language-specific formatting rules | After editing, before committing | ### Call Hierarchy | Tool | Purpose | When to use | |---|---|---| | `prepare_call_hierarchy` | Get callable items at a position | First step before incoming/outgoing calls | | `get_incoming_calls` | Find all callers of a function | "Who calls this?" — impact analysis | | `get_outgoing_calls` | Find all callees of a function | "What does this call?" — dependency analysis | ### Server Monitoring | Tool | Purpose | When to use | |---|---|---| | `get_server_logs` | Internal log messages from the language server | Debug "no results" issues, server startup failures | | `get_server_messages` | User-facing messages from the language server | Check for server notifications, progress, errors | ## Workflow Patterns ### Diagnostic-Driven Editing After editing a file: 1. Save the file to disk (diagnostics reflect the file on disk, not in-memory). 2. Call `get_diagnostics` on the changed file. 3. For each error, call `get_code_actions` to find available fixes. 4. Apply fixes or edit manually. 5. Repeat until `get_diagnostics` returns an empty list. ### Impact Analysis Before Refactoring 1. Call `get_references` on the symbol you intend to change. 2. Review all usage sites to understand the blast radius. 3. Make the change (or use `rename_symbol` for renames). 4. Call `get_diagnostics` on all affected files. ### Type Exploration 1. Call `get_hover` on an unknown symbol to see its type and documentation. 2. Call `get_definition` to read the implementation. 3. Call `get_references` to understand how other code uses it. ### Call Graph Analysis 1. Call `prepare_call_hierarchy` on a function — this returns a call hierarchy item. 2. Pass the item to `get_incoming_calls` to see what calls it (consumers). 3. Pass the item to `get_outgoing_calls` to see what it calls (dependencies). 4. Repeat recursively to trace deeper call chains. ### Workspace Navigation 1. Call `workspace_symbol_search` with a partial name to find symbols across the project. 2. Call `get_definition` on the result to jump to the source. 3. Call `get_document_symbols` on the target file to understand its full structure. ## Configuration mcpls auto-detects language servers based on project markers: | Language | Server | 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` | Custom servers can be added in `~/.config/mcpls/mcpls.toml`: ```toml [[lsp_servers]] language_id = "rust" command = "rust-analyzer" args = [] file_patterns = ["*.rs"] timeout_seconds = 30 [lsp_servers.initialization_options] check.command = "clippy" ``` Environment variables: | Variable | Description | Default | |---|---|---| | `MCPLS_CONFIG` | Path to config file | `~/.config/mcpls/mcpls.toml` | | `MCPLS_LOG` | Log level (trace/debug/info/warn/error) | `info` | | `MCPLS_LOG_JSON` | Output logs as JSON | `false` | ## Troubleshooting ### No results from get_hover or get_definition 1. The file may not be indexed yet. mcpls opens files lazily — the first access to a file triggers indexing, which may take a few seconds for large projects. 2. Call `get_server_logs` to check if the language server is running and has finished indexing. 3. Verify the language server is installed and in `$PATH` (e.g., `which rust-analyzer`). 4. Check that the project has the expected marker files (e.g., `Cargo.toml` for Rust). ### get_diagnostics returns stale results - Diagnostics reflect the file **on disk**. If you edited the file but did not save, the diagnostics will be for the old content. Always save before calling `get_diagnostics`. - After a save, the language server needs time to re-analyze. Wait briefly and retry. - Use `get_cached_diagnostics` only when you know the file has not changed — it returns push-based diagnostics from the server's last notification, which may be outdated. ### Language server not starting 1. Check `get_server_logs` for startup errors. 2. Verify the server binary is installed: `which rust-analyzer`, `which pyright`, etc. 3. Check the config file (`~/.config/mcpls/mcpls.toml`) for misconfigured `command` or `args`. 4. Ensure the project root contains the expected marker files for auto-detection. 5. For non-standard setups, add an explicit `[[lsp_servers]]` entry in the config. ### Slow responses - Initial indexing can take 10-30 seconds for large Rust workspaces. Subsequent calls are fast. - Set `timeout_seconds` higher in the config for large projects. - Check `get_server_logs` for memory or CPU warnings from the language server. - For rust-analyzer, ensure `rust-analyzer.cargo.buildScripts.enable` is not causing excessive build script evaluation. ### rename_symbol fails or misses references - `rename_symbol` only works on symbols the language server can resolve. If a symbol is in a macro expansion or generated code, the rename may be partial. - Always call `get_references` first to verify the server can see all usage sites. - After rename, call `get_diagnostics` on affected files to catch any breakage. ## Edge Cases - **Macro-generated code**: `get_hover` and `get_definition` may not resolve symbols inside procedural macro expansions. Use `get_references` on the macro invocation site instead. - **Conditional compilation**: Symbols behind `#[cfg(...)]` may not be visible depending on the active feature set. Configure the language server's feature flags accordingly. - **Multi-root workspaces**: mcpls supports multiple roots via the `roots` config option. Each root gets its own language server instance. - **Large files**: `get_document_symbols` on very large files (10k+ lines) may be slow. Prefer targeted `get_hover` or `workspace_symbol_search` instead. - **Cross-crate navigation**: `get_definition` may jump into dependency source code (e.g., `~/.cargo/registry/`). This is expected behavior — the language server resolves through the full dependency graph.