io.github.blackwell-systems/agent-lsp

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).

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.

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.

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 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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 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.

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 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.