lsp-rename

name	lsp-rename
description	Two-phase safe rename across the entire workspace. Use when renaming any symbol, function, method, variable, type, or identifier — shows all affected sites before executing atomically via LSP. Never renames without confirmation.
argument-hint	[old-name] [new-name]
user-invocable	true
allowed-tools	mcp__lsp__go_to_symbol mcp__lsp__prepare_rename mcp__lsp__find_references mcp__lsp__rename_symbol mcp__lsp__apply_edit mcp__lsp__get_diagnostics
license	MIT
compatibility	Requires the agent-lsp MCP server (github.com/blackwell-systems/agent-lsp)
metadata	{"required-capabilities":"referencesProvider renameProvider workspaceSymbolProvider","tool_permissions":{"phases":{"prerequisites":"[Truncated]","preview":"[Truncated]","execute":"[Truncated]"},"global_forbidden":["mcp__lsp__format_document","mcp__lsp__run_tests"]}}

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