bug-ops/zeph/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

Diagnostics and Correctness

Refactoring

Call Hierarchy

Server Monitoring

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:

Custom servers can be added in ~/.config/mcpls/mcpls.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:

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.

1. Call get_server_logs to check if the language server is running and has finished indexing.
2. Verify the language server is installed and in $PATH (e.g., which rust-analyzer).
3. 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.