Rename & Document Formatting

Relevant source files

The following files were used as context for generating this wiki page:

• src/tools/rename.ts
• src/tools/formatting.ts
• src/schemas/tool-schemas.ts
• src/services/lsp-client.ts
• src/tools/utils.ts
• src/utils/uri.ts
• src/utils/position.ts

Rename and Document Formatting are core refactoring and code maintenance features provided by the lsp-mcp-server. These features leverage the Language Server Protocol (LSP) to perform semantically aware symbol renames across a codebase and to apply consistent code styles according to project configurations.

The system ensures safety by validating file paths within the workspace boundary and providing "dry run" or "preview" capabilities before committing changes to the filesystem. Sources: CLAUDE.md:120-125, SKILL.md:162-165

Symbol Renaming

The renaming system facilitates the global modification of identifiers (variables, functions, classes, etc.). Unlike simple text search-and-replace, it uses the LSP server's semantic model to identify all true references, including those in different files or under aliases. Sources: SKILL.md:5-9, src/tools/rename.ts:106-110

Renaming Logic and Workflow

The renaming process is divided into validation, calculation, and application phases.

1. Preparation/Validation: The server first calls prepareRename on the LSP client to determine if a symbol at the specific position is renameable. Sources: src/tools/rename.ts:114-118, src/services/lsp-client.ts:468-482
2. Edit Calculation: If valid, the client requests a WorkspaceEdit from the LSP server. This object contains all necessary TextEdit operations mapped to their respective file URIs. Sources: src/tools/rename.ts:133-138, src/services/lsp-client.ts:484-496
3. Application: Edits are applied to the filesystem only if the dry_run flag is set to false. Sources: src/tools/rename.ts:175-184

The following sequence diagram illustrates the renaming flow:

The diagram shows the multi-step communication between the MCP handler, the underlying LSP client, and the filesystem. Sources: src/tools/rename.ts:106-200

Handling Text Edits

To maintain document integrity, edits are applied in reverse order (from the end of the file to the start). This prevents earlier edits from shifting the offsets required for subsequent changes in the same file. Sources: src/tools/rename.ts:63-68, src/tools/formatting.ts:60-65

// Example of sorting edits in reverse order
const sortedEdits = [...edits].sort((a, b) => {
  if (a.range.start.line !== b.range.start.line) {
    return b.range.start.line - a.range.start.line;
  }
  return b.range.start.character - a.range.start.character;
});

Sources: src/tools/rename.ts:68-73

Document Formatting

The Document Formatting tool allows for the automatic adjustment of code layout based on defined rules (e.g., tab size, space insertion). Sources: src/tools/formatting.ts:98-103

Architecture of Formatting

The formatting system handles a single document at a time. It uses the FormattingOptions structure to pass configuration preferences to the LSP server.

Parameter	Type	Description	Default
file_path	string	Absolute path to the file	(Required)
tab_size	number	Number of spaces per tab	2
insert_spaces	boolean	Use spaces instead of tabs	true
apply	boolean	Whether to write changes to disk	false

Sources: src/schemas/tool-schemas.ts:250-264, src/tools/formatting.ts:101-115

Implementation Details

When the apply parameter is true, the tool reads the current file content, applies the returned TextEdit array using an offset-based calculation, and writes the result back to the same path. Sources: src/tools/formatting.ts:128-135

This flowchart describes the decision logic within the formatting handler. Sources: src/tools/formatting.ts:98-140

Security and Validation

Both Rename and Formatting tools implement strict security measures to prevent unauthorized filesystem access:

• Absolute Paths: All file_path inputs are validated by Zod to be absolute paths. Sources: src/schemas/tool-schemas.ts:38-43
• Workspace Anchoring: Before any write operation, the system calls validatePathWithinWorkspace(filePath, workspaceRoot). This ensures the server cannot modify files outside of its designated project directory. Sources: src/tools/rename.ts:180-181, src/tools/formatting.ts:129-130, CLAUDE.md:120-125
• 1-Indexed Positions: Tools accept 1-indexed line and column numbers for human-readability, which are internally converted to LSP's 0-indexed format before transmission. Sources: src/utils/position.ts, SKILL.md:25-27

Data Structures

RenameResponse

The response returned by the lsp_rename tool.

• changes: A map where keys are file paths and values are arrays of RenameEdit.
• files_affected: Total number of unique files modified.
• edits_count: Total number of text replacements.
• applied: Boolean indicating if changes were written to disk.
• original_name: The identifier name before the rename (if provided by LSP).

Sources: src/tools/rename.ts:187-200

FormatEdit

A simplified representation of a TextEdit for formatting.

• range: The 1-indexed start and end coordinates.
• new_text: The string to be inserted/replaced.

Sources: src/tools/formatting.ts:45-53

Summary

The Rename and Document Formatting modules provide a robust interface for semantically aware code modifications. By leveraging the LSPClient and implementing safety checks through workspace path validation, the server allows for reliable cross-file refactoring and consistent code styling. The use of reverse-order edit application and 1-indexed position conversion ensures both technical correctness and developer-friendly interaction. Sources: src/tools/rename.ts:106, src/tools/formatting.ts:98, CLAUDE.md:120