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

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

This returns a workspace_edit with the full set of changes.

Step 3 — Apply the edit

Call mcp__lsp__apply_edit with the workspace_edit from Step 2:

mcp__lsp__apply_edit
  workspace_edit: <workspace_edit from rename_symbol>

Step 4 — 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).

---

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

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.