blackwell-systems / lsp-rename

Requires the agent-lsp MCP server.

lsp-rename: Safe Symbol Rename

Renames a symbol across the workspace in two phases: preview first, then execute
only after explicit confirmation. Never renames without showing impact.

Invocation: User provides old_name (the symbol to rename) and new_name
(the replacement). Optionally provide workspace_root to scope the search.

Prerequisites

If LSP is not yet initialized, call mcp__lsp__start_lsp with the workspace
root first. Auto-inference applies when file paths are provided, but an explicit
start is required when switching workspaces.

Phase 1: Preview

Find the symbol, enumerate all references, and produce a dry-run preview.
Do not apply any edits in this phase.

Step 1 — Locate the symbol

Call mcp__lsp__go_to_symbol with symbol_path set to old_name:

mcp__lsp__go_to_symbol
  symbol_path: "old_name"        # or "Package.OldName" for qualified paths
  workspace_root: "<root>"       # optional; omit to search entire workspace

This returns the definition location (file, line, column). If not found, report
the error and stop.

Step 2 — Validate rename is possible

Call mcp__lsp__prepare_rename at the definition location from Step 1:

mcp__lsp__prepare_rename
  file_path: "<file from Step 1>"
  line: <line from Step 1>
  column: <column from Step 1>

prepare_rename asks the language server whether a rename is valid at this
position. If it returns an error (e.g. the symbol is a keyword, a built-in, or
in a location the server cannot rename), stop immediately and report:

Cannot rename OldName: <server error message>
Common causes: built-in or keyword, imported external package, or position is
not on the symbol name. Try locating the declaration site directly.

Only proceed to Step 3 if prepare_rename succeeds.

Step 3 — Enumerate references

Call mcp__lsp__find_references at the definition location from Step 1:

mcp__lsp__find_references
  file_path: "<file from Step 1>"
  position_pattern: "<symbol>@@"   # @@ immediately after the symbol name
  # fallback: use line/column from Step 1 if position_pattern is unavailable

Collect all returned locations. Note the total count and the distinct files.

Step 4 — Dry-run preview

Call mcp__lsp__rename_symbol with dry_run=true. Do not call apply_edit.

mcp__lsp__rename_symbol
  file_path: "<file from Step 1>"
  line: <line from Step 1>
  column: <column from Step 1>
  new_name: "<new_name>"
  dry_run: true

The response includes a workspace_edit with all proposed changes and a
preview.note describing the scope.

Step 5 — Report impact and hard stop

Display the preview summary to the user:

Rename preview: OldName -> NewName
  Locations to update: N (from find_references count)
  Files affected:      M (distinct files in workspace_edit)
  Language server:     <gopls | typescript-language-server | rust-analyzer | ...>

Changes:
  path/to/file1.go  lines 12, 45, 78
  path/to/file2.go  line 3
  ...

REQUIRED hard stop — do not proceed without explicit user confirmation:

Proceed with rename? [y/n]

Wait for user input. Do not apply any edit until the user answers "y" or "yes".

Edge Case: 0 References

If find_references returns an empty list (the symbol exists but has no external
usages), warn the user before stopping:

Warning: no references found for OldName. The symbol may be unexported,
dead code, or the LSP index may be stale. Renaming will update only the
declaration site.
Proceed anyway? [y/n]

If user answers "n", stop. If "y", continue to Phase 2.

Phase 2: Execute

Only enter this phase after the user answers "y" or "yes" to the confirmation
prompt in Phase 1.

Step 1 — Capture pre-rename diagnostics

Before applying changes, capture the current diagnostic state:

mcp__lsp__get_diagnostics
  file_path: "<one or more files in the workspace_edit>"

Store the result as before_diagnostics.

Step 2 — Execute rename (applies directly)

Call mcp__lsp__rename_symbol without dry_run (or with dry_run=false):

mcp__lsp__rename_symbol
  file_path: "<file from Phase 1 Step 1>"
  line: <line from Phase 1 Step 1>
  column: <column from Phase 1 Step 1>
  new_name: "<new_name>"

Without dry_run, rename_symbol applies the edit to disk itself and returns
a summary (Renamed to "NewName" across N location(s) in M file(s): ...). Do
not call apply_edit afterward and do not reconstruct the edit by hand: the
edit never leaves the server as data you copy back, which is what previously
corrupted files (transposed range offsets, truncated newText). apply_edit
remains for its text-match mode (file_path + old_text + new_text), not for
committing a rename.

Step 3 — Check diagnostics

Call mcp__lsp__get_diagnostics on the affected files and compare against
before_diagnostics:

mcp__lsp__get_diagnostics
  file_path: "<affected files>"

Compute introduced vs. resolved errors and display the Diagnostic Summary (see
[references/patterns.md](references/patterns.md)).

Output Format

After Phase 2 completes, display:

## Rename Summary
- Old name: OldName
- New name: NewName
- Files changed: M
- Locations updated: N
- Post-rename errors: 0

Follow with the Diagnostic Summary if any errors changed (format in
[references/patterns.md](references/patterns.md)).

Only show Diagnostic Summary sections where N > 0. A net change of 0 means the
rename is safe.

Language Support

Tested with gopls, typescript-language-server, and rust-analyzer. Most
LSP-compliant servers support textDocument/rename — agent-lsp works with
any of the 30+ supported language servers that advertise rename capability.
Check your server's capability list via mcp__lsp__get_server_capabilities if
you are unsure.