io.github.blackwell-systems/agent-lsp

Create a new speculative code session for simulating edits without committing to disk. Returns a session ID. Baseline diagnostics are captured lazily on first edit per file. Use this to explore what-if scenarios before applying changes.

Apply a range edit to a file within a simulation session. Changes are held in-memory only. The session captures baseline diagnostics on first edit to each file, then tracks versions for subsequent edits. Returns the new version number after the edit. All line/column positions are 1-indexed (matching editor line numbers).

Evaluate a simulation session by comparing current diagnostics against baselines. Returns errors introduced, errors resolved, net delta, and confidence (high for file scope, eventual for workspace). Use after simulate_edit to assess impact before committing.

Apply a sequence of edits and evaluate after each step. Returns per-step diagnostics and identifies the safe-to-apply-through step (last step with net delta == 0). Use this to find the safest partial application of a multi-step change. All line/column positions in each edit are 1-indexed.

Commit a simulation session. With apply=true, writes changes to disk and notifies LSP servers. With apply=false, returns a unified diff patch. Use after evaluate_session confirms the changes are safe.

Discard a simulation session and revert all in-memory changes by restoring baseline content. Use when simulation results show the changes would introduce errors.

Destroy a simulation session and release all resources. Call this after commit or discard to clean up. Sessions in terminal states (committed, discarded, destroyed) cannot be reused.

Preview the impact of an edit before writing to disk. Shows what errors would be introduced or resolved without touching the file. If net_delta is 0, the edit is safe to apply without further verification. Use before every apply_edit to catch problems early. All line/column positions are 1-indexed. For full function replacements, consider replace_symbol_body instead of apply_edit.

Replace the body of a named symbol (function, method, class) by dot-notation path, preserving the declaration/signature line. Resolves the symbol via document symbols without requiring line/column positions. Use symbol_path like 'MyStruct.Method' or 'Function'. For overload disambiguation, append [N] index (e.g. 'Handle[1]').

Insert code immediately after a named symbol definition. Resolves the symbol's end position via document symbols. Use for adding new methods after existing ones, appending related functions, etc.

Insert code immediately before a named symbol definition. Resolves the symbol's start position via document symbols. Use for adding imports, comments, decorators, or type definitions before their first consumer.

Delete a named symbol only if it has zero references across the workspace (verified via LSP references before deletion). Returns an error with the caller count if the symbol is still in use. Prevents accidental removal of active code.

Find all incoming callers of a function or method. Shortcut for find_callers with direction='incoming'. Use before deleting or refactoring a function to see who depends on it.

Deep exploration of a symbol: combines type info, source, callers, references, and test callers in one call. Use when navigating unfamiliar code and you need the full picture of what a symbol is and how it is used.

Preview an edit and apply it only if safe (net diagnostic delta == 0). Combines preview_edit + apply_edit into one step. Returns applied=true on success or applied=false with preview diagnostics when the edit would introduce errors.

Activate phase enforcement for a skill workflow. Once active, tool calls are checked against the skill's phase permissions. Phases advance automatically as you call tools from later phases. Use this at the start of a skill workflow to enable safety guardrails that prevent out-of-order operations (e.g., applying edits before completing blast-radius analysis).

Deactivate phase enforcement for the currently active skill. Tool calls will no longer be checked against phase permissions. Call this when the skill workflow is complete or when you need to exit the workflow early.

Get the current state of skill phase enforcement: active skill, current phase, allowed and forbidden tools, and tool call history. Use this to understand where you are in a skill workflow and what tools are available.

Jump to the definition of a symbol at a specific location in a file via LSP. Returns the file path and position where the symbol is defined. Useful for navigating to type declarations, function implementations, or variable assignments across the codebase.

Jump to the definition of the type of a symbol at a specific location in a file via LSP. Unlike go_to_definition (which goes to where the symbol itself is defined), this navigates to the type declaration. Useful for interface types, type aliases, and class definitions when working with instances or variables.

Find all implementations of an interface or abstract method at a specific location in a file via LSP. Returns the file paths and positions of all concrete implementations. Use this to navigate from an interface declaration or abstract method to the concrete classes that implement it.

Jump to the declaration of a symbol at a specific location in a file via LSP. Completes the 'go to X' family alongside go_to_definition, go_to_type_definition, and go_to_implementation. Most useful for languages with separate declaration and definition (e.g., C/C++ header files). Returns the file path and position where the symbol is declared.

Navigate to a symbol definition by dot-notation name (e.g. \"LSPClient.GetReferences\", \"http.Handler\") without needing file_path or line/column. Uses workspace symbol search to locate the definition. Useful when you know the symbol name but not its location.

Rename a symbol across the entire workspace via LSP. Returns a WorkspaceEdit (not applied automatically). Always use dry_run=true first to preview changes. Call find_references before renaming exported symbols to understand blast radius. After applying via apply_edit, call get_diagnostics to verify no errors were introduced.

Validate that a rename is possible at the given position before committing to rename_symbol. Returns the range that would be renamed and a placeholder name suggestion, or a message indicating rename is not supported at this position. Use this before rename_symbol to avoid attempting invalid renames. Returns null if the server does not support prepareRename.

Find all occurrences of the symbol at a position within the same file via LSP (textDocument/documentHighlight). Returns ranges and kinds: 1=Text, 2=Read, 3=Write. File-scoped and instant — does not trigger a workspace-wide reference search. Use this to find all local usages of a variable, parameter, or field without the overhead of find_references.

Find what calls this function and what it calls. Returns incoming callers, outgoing callees, or both (default). Use before deleting or refactoring a function to understand its role in the call graph. Works on functions and methods only; for types, use find_references instead.

Show type hierarchy for a type at a position. Returns supertypes (parent classes/interfaces), subtypes (subclasses/implementations), or both depending on the direction parameter. Direction defaults to \"both\". Use this to understand class and interface inheritance relationships.

Deep-dive into a symbol: type info, source code, callers (top 10), references (count + top 5 files), and test caller count in one call. Use when you need full context about a symbol before editing. Accepts file_path + line/column or position_pattern.

Get type information, documentation, and signature for a symbol at a specific location. Use this to understand what a function does, what type a variable has, or what a module exports before editing it. For finding all usages of the symbol, use find_references instead.

Get completion suggestions at a specific location in a file. Use this tool to retrieve code completion options based on the current context, including variable names, function calls, object properties, and more. Helpful for code assistance and auto-completion at a particular location. Use this when determining which functions you have available in a given package, for example when changing libraries.

Get function signature help at a specific location in a file via LSP. Returns available overloads and highlights the active parameter. Use this when the cursor is inside a function call's argument list to understand what parameters the function expects.

Get available quick fixes and code actions for a diagnostic or code range. Returns actionable fixes (add missing import, implement interface, fix type error) that can be applied via apply_edit. To auto-fix all diagnostics in a file, use the /lsp-fix-all skill via prompts/get.

List all symbols defined in a file (functions, types, methods, variables). Returns a hierarchical tree showing the file's structure. Use to get an overview before editing, or to find the exact name of a symbol for use with replace_symbol_body or find_references. Pass format: \"outline\" for compact markdown output optimized for LLM consumption.

Search for a symbol by name across the entire workspace. Returns matching symbols with name, kind, file, and location. Use when you know a symbol's name but not its file. Use detail_level: \"hover\" to also get type signatures and docs for each match.

Find all usages of a symbol across the codebase. Use before renaming, deleting, or changing any symbol to understand who calls it. Zero references means the symbol may be dead code; use safe_delete_symbol to remove it safely. For blast-radius analysis with test/non-test partitioning, use blast_radius instead.

Get inlay hints for a range within a document via LSP (textDocument/inlayHint). Inlay hints are inline annotations that IDEs display in source code — typically inferred type names (e.g. `: string`) and parameter name labels (e.g. `count:`). Useful in languages with type inference (TypeScript, Rust, Go) to see what the compiler knows without reading every type annotation. Returns an array of InlayHint objects, each with a position, label, and optional kind (1=Type, 2=Parameter). Returns an empty array if the language server does not support inlay hints.

Get semantic tokens for a range in a file. Returns each token's type (function, variable, keyword, parameter, type, etc.) and modifiers (readonly, static, deprecated, etc.) with 1-based line/character positions. Use this to understand the syntactic role of code elements — distinct from hover which gives documentation. Only available when the language server supports textDocument/semanticTokens.

Return the source code of the innermost symbol (function, method, class, struct, etc.) whose range contains the given cursor position. Calls textDocument/documentSymbol, walks the symbol tree to find the smallest enclosing symbol, then slices the file at that symbol's range. Returns symbol_name, symbol_kind, start_line (1-based), end_line (1-based), and source text. Use line+character or position_pattern (@@-syntax) to specify the cursor. character defaults to 1.

Fetch authoritative documentation for a named symbol from local toolchain sources (go doc, pydoc, cargo doc) without requiring an LSP hover response. Works on transitive dependencies not indexed by the language server. Returns the full doc text, extracted signature, and source tag. Falls back gracefully when the toolchain command fails or the language is unsupported.

Enumerate all exported symbols in the specified files, resolve their references across the workspace, and partition callers into test vs non-test. Returns affected_symbols (name, file, line), test_callers (with enclosing test function names), and non_test_callers. Use before editing a file to understand blast radius. Set include_transitive=true to surface second-order callers (callers of callers). Set scope='all' to include unexported symbols for comprehensive dead code detection.

Find all references to a library symbol across one or more consumer repositories. Adds each consumer_root as a workspace folder, waits for indexing, then calls find_references and partitions results by repo. Returns library_references (within the primary repo), consumer_references (map of root → locations), and warnings (roots that could not be indexed). Use before changing a shared library API to find all downstream callers.

Run git diff to identify changed files, analyze their exported symbols via blast_radius, and return affected symbols with risk classification. Risk levels: 'high' (callers from multiple packages), 'medium' (callers from same package only), 'low' (zero non-test callers). Use before committing to understand the blast radius of uncommitted or recently committed changes.

Initialize or reinitialize the LSP server with a specific project root directory. Call this before using find_references, inspect_symbol, or get_diagnostics when working in a project different from the one the server was started with. root_dir should be the workspace root (directory containing go.mod, package.json, Cargo.toml, etc.). Optional language_id (e.g. \"go\", \"typescript\", \"rust\") selects a specific configured server in multi-server mode — use this when working in a mixed-language repo to ensure the correct server handles the workspace. If unsure which server is active, call get_server_capabilities first.

Restart the LSP server process. Use this if the LSP server becomes unresponsive or after making significant changes to the project structure. Optionally provide a new root_dir to restart with a different workspace root.

Add a directory to the LSP workspace, enabling cross-repo references, definitions, and diagnostics. Useful when working across a library and its consumers — after adding the consumer repo, find_references on a library function returns call sites in both repos. Requires start_lsp to have been called first. Language servers that support multi-root workspaces (gopls, rust-analyzer, typescript-language-server) will re-index the new folder automatically.

Remove a directory from the LSP workspace. The language server will stop indexing that folder.

List all currently active workspace folders. Use this to see which roots the language server is indexing.

Open a file in the LSP server for analysis. Use this tool before performing operations like getting diagnostics, hover information, or completions for a file. The file remains open for continued analysis until explicitly closed. The language_id parameter tells the server which language service to use (e.g., 'typescript', 'javascript', 'haskell'). The LSP server starts automatically on MCP launch.

Close a file in the LSP server. Use this tool when you're done with a file to free up resources and reduce memory usage. It's good practice to close files that are no longer being actively analyzed, especially in long-running sessions or when working with large codebases.

Get diagnostic messages (errors, warnings) for files. Use this tool to identify problems in code files such as syntax errors, type mismatches, or other issues detected by the language server. When used without a file_path, returns diagnostics for all open files.

Return the language server's capability map and classify every agent-lsp tool as supported or unsupported based on what the server advertised during initialization. Use this to determine which tools will return results before calling them — saves round trips on servers that don't support certain LSP features (e.g. not all servers support type_hierarchy or inlay_hints). Requires start_lsp to have been called first.

Scan a workspace directory for source languages and check PATH for the corresponding LSP server binaries. Returns detected workspace languages (ranked by prevalence), installed servers with their paths, and a suggested_config array ready to paste into the agent-lsp MCP server args. Use this to set up agent-lsp for a new project or verify your configuration.

Compile the project at workspace_dir using the detected workspace language. Language-specific dispatch (no arbitrary shell execution): go build ./..., cargo build, tsc --noEmit, mypy . (Python typecheck proxy). Optional path param narrows scope. Returns: { success: bool, errors: [{file, line, column, message}], raw: string }. Does not require start_lsp.

Run the test suite for the detected workspace language. Language-specific dispatch: go test -json ./..., cargo test --message-format=json, pytest --tb=json, npm test. Optional path param narrows scope. Test failure locations are LSP-normalized — paste directly into go_to_definition. Returns: { passed: bool, failures: [{file, line, test_name, message, location}], raw: string }. Does not require start_lsp.

Given a source file path, return the test files that exercise it. Static lookup — no test execution. Go: *_test.go in same directory. Python: test_*.py / *_test.py in same dir and tests/ sibling. TypeScript/JS: *.test.ts, *.spec.ts etc. Rust: returns source file itself (tests inline). Does not require start_lsp.

Set the server logging level. Use this tool to control the verbosity of logs generated by the LSP MCP server. Available levels from least to most verbose: emergency, alert, critical, error, warning, notice, info, debug. Increasing verbosity can help troubleshoot issues but may generate large amounts of output.

Apply an edit to a file. Two modes: (1) WorkspaceEdit mode: pass workspace_edit with positional changes returned by rename_symbol or format_document; (2) Text-match mode: pass file_path + old_text + new_text to find and replace text. For full function/method body replacements, consider replace_symbol_body which resolves by symbol name instead of text matching. Always call preview_edit first to verify the edit is safe.

Execute a workspace command via LSP. Commands are server-defined identifiers returned by code actions (in the command field of a CodeAction). Use this after suggest_fixes to trigger a server-side operation such as applying a refactoring, generating code, or running a server-specific action. Returns the server-defined result or null.

Notify the language server that files have changed on disk outside the editor (workspace/didChangeWatchedFiles). Use this after writing files directly to disk so the server refreshes its caches. Change types: 1=created, 2=changed, 3=deleted. File URIs must use the file:/// scheme.

Get formatting edits for a file via LSP. Returns TextEdit[] for inspection (not applied automatically). Apply via apply_edit. Formats one file at a time; to find which files need formatting, use your shell (e.g. gofmt -l ./...).

Get formatting edits for a specific range within a document via LSP (textDocument/rangeFormatting). Returns TextEdit[] for the selected lines/characters only. Use this when you want to format a function, block, or selection rather than the entire file. The edits are NOT applied automatically.

Export the symbol reference cache as a gzip-compressed artifact for team sharing. The exported file can be committed to the repository (e.g. .agent-lsp/cache.db.gz) so teammates skip cold-start indexing. Requires start_lsp to have been called first.

Import a gzip-compressed cache artifact, replacing the current symbol reference cache. Use this to load a team-shared cache exported via export_cache. Validates database integrity after import. Requires start_lsp to have been called first.

Preview an edit and apply it only if safe (net_delta == 0). Combines preview_edit + apply_edit into one call. If the edit would introduce errors (net_delta > 0), returns the preview result with applied=false so you can decide.