# io.github.blackwell-systems/agent-lsp (npm · @blackwell-systems/agent-lsp)

Orchestrates language servers into 65 code-intelligence tools across 30 languages, token-optimized.

- Trust score: 75/100 (medium)
- Change this week: −8
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-04

## Components

- npm · `@blackwell-systems/agent-lsp`: 75/100 (this document), [markdown](https://verifymcp.io/servers/blackwell-systems-agent-lsp/blackwell-systems-agent-lsp.md), [page](https://verifymcp.io/servers/blackwell-systems-agent-lsp/blackwell-systems-agent-lsp)

## Channel facts

- Registry: `npm`
- Package: `@blackwell-systems/agent-lsp`
- Version: `0.17.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-04.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 0 of 6 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 4 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 83/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 9724 tokens (~140/item across 69 items; 65 tools + 4 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 99% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add blackwell-systems-agent-lsp -- npx -y @blackwell-systems/agent-lsp
```

### Codex

```bash
codex mcp add blackwell-systems-agent-lsp -- npx -y @blackwell-systems/agent-lsp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "blackwell-systems-agent-lsp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@blackwell-systems/agent-lsp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add blackwell-systems-agent-lsp --command npx --arg -y --arg @blackwell-systems/agent-lsp
```

### Hermes

```yaml
mcp_servers:
  blackwell-systems-agent-lsp:
    command: "npx"
    args: ["-y", "@blackwell-systems/agent-lsp"]
```

### Other

```json
{
  "mcpServers": {
    "blackwell-systems-agent-lsp": {
      "command": "npx",
      "args": [
        "-y",
        "@blackwell-systems/agent-lsp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-04 (score 75, +1)

No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-02 (score 74, +1)

No change was recorded against any check on this day. Stability & Change Management went from 17 to 20. That category is still filling its 30-day observation window: 5 days of observed history at the previous scan, 6 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-31 (score 73, +44)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 29, −54)

- [security regression] Malware scan: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Schema quality: 100 → unverified
- [functional] Package version: 0.16.0 → 0.17.0

### 2026-07-27 (score 83, +36)

- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] Schema quality: unverified → 100
- [functional] First check of Schema quality: fail
- [functional] First check of Schema quality: excellent
- [functional] First check of Tool coverage: 99
- [functional] First check of Schema quality: fail

### 2026-07-26 (score 47)

First indexed and scored.

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

## MCP tools (65)

### `activate_skill` (~140 tokens)

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

Input parameters:

- `mode` (string): Enforcement mode: warn (log violations but allow) or block (return error with recovery guidance). Default: warn
- `skill_name` (string, required): Name of the skill to activate (e.g. lsp-rename, lsp-refactor, lsp-safe-edit, lsp-verify)

### `add_workspace_folder` (~115 tokens)

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.

Input parameters:

- `path` (string, required): Absolute path to the workspace folder to add/remove

### `apply_edit` (~160 tokens)

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.

Input parameters:

- `file_path` (string): File path for text-match mode
- `new_text` (string): Replacement text (text-match mode)
- `old_text` (string): Text to find and replace (text-match mode)
- `workspace_edit` (object): WorkspaceEdit object (as returned by rename_symbol or format_document)

### `blast_radius` (~202 tokens)

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.

Input parameters:

- `changed_files` (array, required): List of absolute file paths to analyze for exported symbol impact
- `filter` (string): Filter results: 'untested' returns only symbols with production callers but zero test callers
- `include_transitive` (boolean): If true, include second-order callers (callers of callers) in the results
- `scope` (string): Symbol scope: 'exported' (default) or 'all' (includes unexported symbols for dead code detection)

### `callers` (~174 tokens)

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.

Input parameters:

- `column` (integer, required): 1-indexed column (character offset) in the line
- `cross_concurrent` (boolean): If true\, annotate callers that cross concurrent boundaries (goroutines\, threads\, async tasks). Returns concurrent_callers with the detected pattern.
- `direction` (string): Direction: incoming\, outgoing\, or both (default: both)
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go\, typescript\, python). Optional; auto-detected from file extension
- `line` (integer, required): 1-indexed line number in the file

### `close_document` (~77 tokens)

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.

Input parameters:

- `file_path` (string, required): Absolute path to the file to close

### `commit_session` (~114 tokens)

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.

Input parameters:

- `apply` (boolean): If true, write changes to disk and notify LSP. If false, return diff only
- `session_id` (string, required): Session identifier returned by create_simulation_session
- `target` (string): Commit target: disk (write files) or patch (return unified diff). Default: patch

### `create_simulation_session` (~89 tokens)

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.

Input parameters:

- `language` (string, required): Language identifier for the session (e.g. go, typescript)
- `workspace_root` (string, required): Workspace root directory for the simulation session

### `deactivate_skill` (~47 tokens)

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_session` (~59 tokens)

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.

Input parameters:

- `session_id` (string, required): Session identifier returned by create_simulation_session

### `detect_changes` (~194 tokens)

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.

Input parameters:

- `range` (string): Git range for 'committed' scope. Examples: 'v0.7.0..HEAD', 'abc123..def456', 'main'. If a single ref is given, compares ref~1..ref. Ignored for unstaged/staged scopes.
- `scope` (string): Which changes to analyze: 'unstaged' (default), 'staged', or 'committed'
- `workspace_root` (string): Absolute path to the git repository root. Defaults to the LSP workspace root if omitted

### `detect_lsp_servers` (~97 tokens)

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.

Input parameters:

- `workspace_dir` (string, required): Directory to scan for source languages and LSP server binaries

### `did_change_watched_files` (~112 tokens)

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.

Input parameters:

- `changes` (array, required): Array of file change events: [{uri\, type}] where type is 1=created\, 2=changed\, 3=deleted

### `discard_session` (~51 tokens)

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

Input parameters:

- `session_id` (string, required): Session identifier returned by create_simulation_session

### `evaluate_session` (~118 tokens)

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.

Input parameters:

- `scope` (string): Evaluation scope: file (fast, single file) or workspace (full, all files). Default: file
- `session_id` (string, required): Session identifier returned by create_simulation_session
- `timeout_ms` (integer): Timeout in milliseconds for LSP diagnostics collection. Default: 5000

### `execute_command` (~104 tokens)

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.

Input parameters:

- `arguments` (array): Command arguments as array of JSON objects
- `command` (string, required): LSP command identifier (from code action's command field)

### `explore` (~170 tokens)

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.

Input parameters:

- `column` (integer): 1-indexed column (character offset) in the line. Optional when position_pattern is provided.
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go, typescript, python). Optional; auto-detected from file extension
- `line` (integer): 1-indexed line number in the file. Optional when position_pattern is provided.
- `position_pattern` (string): Alternative to line/column: use @@pattern@@ syntax to match text near the target position

### `explore_symbol` (~186 tokens)

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.

Input parameters:

- `column` (integer): 1-indexed column (character offset) in the line. Optional when position_pattern is provided.
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go\, typescript\, python). Optional; auto-detected from file extension
- `line` (integer): 1-indexed line number in the file. Optional when position_pattern is provided.
- `position_pattern` (string): Alternative to line/column: use @@pattern@@ syntax to match text near the target position

### `export_cache` (~87 tokens)

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.

Input parameters:

- `dest_path` (string, required): Destination path for the compressed cache artifact (e.g. .agent-lsp/cache.db.gz)

### `find_callers` (~197 tokens)

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.

Input parameters:

- `column` (integer, required): 1-indexed column (character offset) in the line
- `cross_concurrent` (boolean): If true\, annotate callers that cross concurrent boundaries (goroutines\, threads\, async tasks). Returns concurrent_callers with the detected pattern.
- `direction` (string): Direction: incoming\, outgoing\, or both (default: both)
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go\, typescript\, python). Optional; auto-detected from file extension
- `line` (integer, required): 1-indexed line number in the file

### `find_references` (~208 tokens)

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.

Input parameters:

- `column` (integer): 1-indexed column (character offset) in the line. Optional when position_pattern is provided.
- `file_path` (string, required): Absolute path to the source file
- `include_declaration` (boolean): Whether to include the declaration site in the results
- `language_id` (string): Language identifier (e.g. go, typescript, python). Optional; auto-detected from file extension
- `line` (integer): 1-indexed line number in the file. Optional when position_pattern is provided.
- `position_pattern` (string): Alternative to line/column: use @@pattern@@ syntax to match text near the target position

### `find_symbol` (~151 tokens)

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.

Input parameters:

- `detail_level` (string): Enrichment level: 'basic' for names/locations only, 'hover' to include type signatures and docs
- `limit` (integer): Maximum number of symbols to enrich with hover info (default 3)
- `offset` (integer): Number of symbols to skip before enriching (default 0), for pagination
- `query` (string): Symbol name or pattern to search for across the workspace

### `format_document` (~119 tokens)

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

Input parameters:

- `file_path` (string, required): Absolute path to the file to format
- `insert_spaces` (boolean): Use spaces instead of tabs. Default: true
- `language_id` (string)
- `tab_size` (integer): Tab size in spaces. Default: 4

### `format_range` (~200 tokens)

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.

Input parameters:

- `end_column` (integer, required): 1-indexed end column of the range to format
- `end_line` (integer, required): 1-indexed end line of the range to format
- `file_path` (string, required): Absolute path to the file to format
- `insert_spaces` (boolean): Use spaces instead of tabs. Default: true
- `language_id` (string)
- `start_column` (integer, required): 1-indexed start column of the range to format
- `start_line` (integer, required): 1-indexed start line of the range to format
- `tab_size` (integer): Tab size in spaces. Default: 4

### `get_completions` (~159 tokens)

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.

Input parameters:

- `column` (integer, required): 1-indexed column (character offset) in the line
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go, typescript, python). Optional; auto-detected from file extension
- `line` (integer, required): 1-indexed line number in the file

### `get_cross_repo_references` (~202 tokens)

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.

Input parameters:

- `column` (integer, required): 1-indexed column (character offset) of the symbol in the line
- `consumer_roots` (array, required): List of absolute paths to consumer repository roots to search for references
- `language_id` (string): Language identifier (e.g. go, typescript, python). Optional; auto-detected from file extension
- `line` (integer, required): 1-indexed line number of the symbol in the file
- `symbol_file` (string, required): Absolute path to the file containing the symbol to search for

### `get_diagnostics` (~125 tokens)

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.

Input parameters:

- `file_path` (string): File path to get diagnostics for. If omitted, returns diagnostics for all open files
- `group_by` (string): Set to 'symbol' to group diagnostics by their owning symbol. Returns symbols with their diagnostics instead of a flat list. Helps understand which function or type is broken.

### `get_document_highlights` (~168 tokens)

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.

Input parameters:

- `column` (integer, required): 1-indexed column (character offset) in the line
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go\, typescript\, python). Optional; auto-detected from file extension
- `line` (integer, required): 1-indexed line number in the file

### `get_inlay_hints` (~250 tokens)

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.

Input parameters:

- `end_column` (integer, required): 1-indexed end column of the range
- `end_line` (integer, required): 1-indexed end line of the range
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go, typescript, python). Optional; auto-detected from file extension
- `start_column` (integer, required): 1-indexed start column of the range
- `start_line` (integer, required): 1-indexed start line of the range

### `get_semantic_tokens` (~201 tokens)

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.

Input parameters:

- `end_column` (integer, required): 1-indexed end column of the range
- `end_line` (integer, required): 1-indexed end line of the range
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go, typescript, python). Optional; auto-detected from file extension
- `start_column` (integer, required): 1-indexed start column of the range
- `start_line` (integer, required): 1-indexed start line of the range

### `get_server_capabilities` (~89 tokens)

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_signature_help` (~133 tokens)

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.

Input parameters:

- `column` (integer, required): 1-indexed column (character offset) in the line
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go, typescript, python). Optional; auto-detected from file extension
- `line` (integer, required): 1-indexed line number in the file

### `get_skill_phase` (~51 tokens)

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.

### `get_symbol_documentation` (~175 tokens)

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.

Input parameters:

- `file_path` (string): Optional file path to establish workspace context for the documentation lookup
- `format` (string): Output format for the documentation (e.g. 'markdown', 'plain')
- `language_id` (string, required): Language identifier (e.g. go, python, rust) to select the correct toolchain doc command
- `symbol` (string, required): Fully qualified symbol name to look up (e.g. 'fmt.Println', 'os.File.Read')

### `get_symbol_source` (~221 tokens)

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.

Input parameters:

- `column` (integer): 1-indexed column (character offset) in the line (defaults to 1)
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go, typescript, python). Optional; auto-detected from file extension
- `line` (integer): 1-indexed line number of the cursor position
- `position_pattern` (string): Alternative to line/column: use @@pattern@@ syntax to match text near the target position

### `get_tests_for_file` (~106 tokens)

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.

Input parameters:

- `file_path` (string, required): Source file path to find associated test files for

### `go_to_declaration` (~162 tokens)

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.

Input parameters:

- `column` (integer, required): 1-indexed column (character offset) in the line
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go\, typescript\, python). Optional; auto-detected from file extension
- `line` (integer, required): 1-indexed line number in the file

### `go_to_definition` (~161 tokens)

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.

Input parameters:

- `column` (integer, required): 1-indexed column (character offset) in the line
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go\, typescript\, python). Optional; auto-detected from file extension
- `line` (integer, required): 1-indexed line number in the file
- `position_pattern` (string): Alternative to line/column: use @@pattern@@ syntax to match text near the target position

### `go_to_implementation` (~138 tokens)

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.

Input parameters:

- `column` (integer, required): 1-indexed column (character offset) in the line
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go\, typescript\, python). Optional; auto-detected from file extension
- `line` (integer, required): 1-indexed line number in the file

### `go_to_symbol` (~122 tokens)

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.

Input parameters:

- `language` (string): Language filter for symbol search. Optional
- `symbol_path` (string, required): Dot-notation symbol path (e.g. MyStruct.MyMethod\, http.Handler)
- `workspace_root` (string): Workspace root directory for symbol search. Optional; uses current workspace

### `go_to_type_definition` (~150 tokens)

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.

Input parameters:

- `column` (integer, required): 1-indexed column (character offset) in the line
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go\, typescript\, python). Optional; auto-detected from file extension
- `line` (integer, required): 1-indexed line number in the file

### `import_cache` (~70 tokens)

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.

Input parameters:

- `src_path` (string, required): Path to the compressed cache artifact to import

### `insert_after_symbol` (~105 tokens)

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.

Input parameters:

- `code` (string, required): Code to insert after the symbol definition
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier. Optional; auto-detected
- `symbol_path` (string, required): Dot-notation symbol path to insert after

### `insert_before_symbol` (~106 tokens)

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.

Input parameters:

- `code` (string, required): Code to insert before the symbol definition
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier. Optional; auto-detected
- `symbol_path` (string, required): Dot-notation symbol path to insert before

### `inspect_symbol` (~180 tokens)

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.

Input parameters:

- `column` (integer): 1-indexed column (character offset) in the line. Optional when position_pattern is provided.
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go, typescript, python). Optional; auto-detected from file extension
- `line` (integer): 1-indexed line number in the file. Optional when position_pattern is provided.
- `position_pattern` (string): Alternative to line/column: use @@pattern@@ syntax to match text near the target position

### `list_symbols` (~141 tokens)

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.

Input parameters:

- `file_path` (string, required): Absolute path to the source file
- `format` (string): Output format: 'outline' for compact markdown, default returns JSON
- `language_id` (string): Language identifier (e.g. go, typescript, python). Optional; auto-detected from file extension

### `list_workspace_folders` (~29 tokens)

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

### `open_document` (~132 tokens)

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.

Input parameters:

- `file_path` (string, required): Absolute path to the file to open in the LSP server
- `language_id` (string)
- `text` (string): Optional file content override. If omitted, reads from disk

### `prepare_rename` (~151 tokens)

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.

Input parameters:

- `column` (integer, required): 1-indexed column (character offset) in the line
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go\, typescript\, python). Optional; auto-detected from file extension
- `line` (integer, required): 1-indexed line number in the file

### `preview_edit` (~293 tokens)

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.

Input parameters:

- `end_column` (integer, required): 1-indexed end column of the range to replace
- `end_line` (integer, required): 1-indexed end line of the range to replace
- `file_path` (string, required): Absolute path to the file to edit within the session
- `language` (string): Language identifier for the session (e.g. go, typescript)
- `new_text` (string, required): Replacement text for the specified range
- `scope` (string): Evaluation scope: file (fast, single file) or workspace (full, all files). Default: file
- `session_id` (string): Session identifier returned by create_simulation_session
- `start_column` (integer, required): 1-indexed start column of the range to replace
- `start_line` (integer, required): 1-indexed start line of the range to replace
- `timeout_ms` (integer): Timeout in milliseconds for LSP diagnostics collection. Default: 5000
- `workspace_root` (string): Workspace root directory for the simulation session

### `remove_workspace_folder` (~43 tokens)

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

Input parameters:

- `path` (string, required): Absolute path to the workspace folder to add/remove

### `rename_symbol` (~237 tokens)

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.

Input parameters:

- `column` (integer): 1-indexed column (character offset) in the line
- `dry_run` (boolean): If true\, return the edit without applying. Always true for this read-only tool
- `exclude_globs` (array): Glob patterns for files to exclude from rename (e.g. vendor/**\, *_gen.go)
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go\, typescript\, python). Optional; auto-detected from file extension
- `line` (integer): 1-indexed line number in the file
- `new_name` (string, required): New name for the symbol
- `position_pattern` (string): Alternative to line/column: use @@pattern@@ syntax to match text near the target position

### `replace_symbol_body` (~168 tokens)

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

Input parameters:

- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier. Optional; auto-detected
- `new_body` (string, required): New body text to replace the symbol's body (signature/declaration preserved)
- `symbol_path` (string, required): Dot-notation symbol path (e.g. MyStruct.Method, Function, Method[0] for overload disambiguation)

### `restart_lsp_server` (~73 tokens)

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.

Input parameters:

- `root_dir` (string): Optional new workspace root. If omitted, restarts with current root

### `run_build` (~132 tokens)

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.

Input parameters:

- `language` (string): Optional language override (go\, rust\, typescript\, python)
- `path` (string): Optional sub-path to narrow build scope
- `workspace_dir` (string, required): Workspace directory to build

### `run_tests` (~143 tokens)

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.

Input parameters:

- `language` (string): Optional language override (go\, rust\, typescript\, python)
- `path` (string): Optional sub-path to narrow test scope
- `workspace_dir` (string, required): Workspace directory to test

### `safe_apply_edit` (~100 tokens)

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.

Input parameters:

- `file_path` (string, required): Absolute path to the file to edit
- `new_text` (string, required): Replacement text
- `old_text` (string, required): Exact text to find and replace

### `safe_delete_symbol` (~102 tokens)

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.

Input parameters:

- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier. Optional; auto-detected
- `symbol_path` (string, required): Dot-notation symbol path of the symbol to delete

### `safe_edit` (~93 tokens)

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.

Input parameters:

- `file_path` (string, required): Absolute path to the file to edit
- `new_text` (string, required): Replacement text
- `old_text` (string, required): Exact text to find and replace

### `set_log_level` (~96 tokens)

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.

Input parameters:

- `level` (string, required): Log level: emergency\, alert\, critical\, error\, warning\, notice\, info\, or debug

### `simulate_chain` (~139 tokens)

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.

Input parameters:

- `edits` (array, required): Array of edit objects, each with file_path, start_line, start_column, end_line, end_column, new_text
- `session_id` (string, required): Session identifier returned by create_simulation_session
- `timeout_ms` (integer): Timeout in milliseconds for LSP diagnostics collection. Default: 5000

### `simulate_edit` (~195 tokens)

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

Input parameters:

- `end_column` (integer, required): 1-indexed end column of the range to replace
- `end_line` (integer, required): 1-indexed end line of the range to replace
- `file_path` (string, required): Absolute path to the file to edit within the session
- `new_text` (string, required): Replacement text for the specified range
- `session_id` (string, required): Session identifier returned by create_simulation_session
- `start_column` (integer, required): 1-indexed start column of the range to replace
- `start_line` (integer, required): 1-indexed start line of the range to replace

### `start_lsp` (~355 tokens)

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.

Input parameters:

- `connect` (string): Connect to an already-running language server at this TCP address (e.g. localhost:9999) instead of spawning a new process. Reuses the existing server's warm index. Supported by gopls (gopls -listen=:…
- `language_id` (string): Language server to start (e.g. go, typescript, rust). Optional; auto-detected
- `ready_timeout_seconds` (number): If > 0, block until all $/progress workspace-indexing tokens complete or this many seconds elapse. Useful for servers like jdtls that index asynchronously after initialize.
- `root_dir` (string, required): Workspace root directory containing the project (e.g. directory with go.mod, package.json)
- `scope` (string): Limit indexing to specific subdirectories. Accepts a path string or array of paths relative to root_dir. Generates a temporary language-server config (pyrightconfig.json, tsconfig.json) that restrict…

### `suggest_fixes` (~180 tokens)

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.

Input parameters:

- `end_column` (integer, required): 1-indexed end column of the range
- `end_line` (integer, required): 1-indexed end line of the range
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go, typescript, python). Optional; auto-detected from file extension
- `start_column` (integer, required): 1-indexed start column of the range
- `start_line` (integer, required): 1-indexed start line of the range

### `type_hierarchy` (~158 tokens)

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.

Input parameters:

- `column` (integer, required): 1-indexed column (character offset) in the line
- `direction` (string): Direction: incoming\, outgoing\, or both (default: both)
- `file_path` (string, required): Absolute path to the source file
- `language_id` (string): Language identifier (e.g. go\, typescript\, python). Optional; auto-detected from file extension
- `line` (integer, required): 1-indexed line number in the file

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/blackwell-systems-agent-lsp/blackwell-systems-agent-lsp#diagnostics

## Score history

- 2026-08-04: 75
- 2026-08-03: 74
- 2026-08-02: 74
- 2026-08-01: 73
- 2026-07-31: 73
- 2026-07-30: 29
- 2026-07-29: 83
- 2026-07-28: 83
- 2026-07-27: 83
- 2026-07-26: 47

## Links

- npm package: https://www.npmjs.com/package/@blackwell-systems/agent-lsp
- Socket report: https://socket.dev/npm/package/@blackwell-systems/agent-lsp
- Repository: https://github.com/blackwell-systems/agent-lsp
- Changelog RSS feed: https://verifymcp.io/servers/blackwell-systems-agent-lsp/blackwell-systems-agent-lsp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/blackwell-systems-agent-lsp/blackwell-systems-agent-lsp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/blackwell-systems-agent-lsp/blackwell-systems-agent-lsp