Code Actions & Quick Fixes

Relevant source files

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

• src/tools/code-actions.ts
• src/schemas/tool-schemas.ts
• src/services/lsp-client.ts
• src/index.ts
• src/constants.ts
• SKILL.md

The Code Actions and Quick Fixes system in lsp-mcp-server provides an interface to apply automated refactorings and corrections suggested by various Language Servers. It enables users to resolve diagnostic errors (Quick Fixes) or perform complex code transformations such as extracting functions or organizing imports. The system bridges the Model Context Protocol (MCP) tool calls to standard Language Server Protocol (LSP) textDocument/codeAction requests.

Sources: src/index.ts:258-278, src/tools/code-actions.ts:140-141, CLAUDE.md:7-10

Architecture and Data Flow

The Code Actions system follows a multi-stage process involving input validation, diagnostic context gathering, LSP communication, and optional file system modification.

Execution Flow

1. Request Validation: The system validates incoming parameters using Zod schemas to ensure absolute paths and 1-indexed positions.
2. Context Preparation: It identifies diagnostics overlapping the specified range to provide the Language Server with necessary context for suggesting fixes.
3. LSP Request: The LSPClient sends a CodeActionRequest to the underlying language server.
4. Action Application: If the apply flag is set, the system translates the suggested WorkspaceEdit into file system writes, applying changes in reverse order to maintain position integrity.

The following diagram illustrates the sequence of operations when a user requests and applies a code action:

Components and Logic

Tool Input Schema

The CodeActionsSchema defines the parameters required to query and apply actions. It supports filtering by specific "kinds" (e.g., quickfix, refactor.extract) and specifies the range within the document.

Parameter	Type	Description
file_path	string	Absolute path to the source file.
start_line	number	1-indexed start line of the range.
start_column	number	1-indexed start column of the range.
kinds	string[]	Optional filter for action types (e.g., source.organizeImports).
apply	boolean	If true, executes the action at action_index.
action_index	number	The index of the action to apply (defaults to 0).

Sources: src/schemas/tool-schemas.ts:192-224, src/index.ts:258-278

Code Action Kinds

The system recognizes standard LSP code action kinds, which are used for filtering and identifying the intent of a transformation.

Kind Constant	Value	Description
QuickFix	quickfix	Resolves diagnostic errors or warnings.
RefactorExtract	refactor.extract	Extracts code into a new method/variable.
SourceOrganizeImports	source.organizeImports	Sorts and cleans up module imports.
SourceFixAll	source.fixAll	Applies all available auto-fixes.

Sources: src/constants.ts:327-347, src/schemas/tool-schemas.ts:208-217

Implementation Details

Workspace Edit Application

When apply is true, the applyWorkspaceEdit function processes the WorkspaceEdit returned by the Language Server. Crucially, it sorts edits in reverse order (bottom-to-top) by line and character before application. This prevents earlier edits from shifting the character offsets of subsequent edits.
Sources: src/tools/code-actions.ts:101-135

Security and Validation

To prevent directory traversal attacks, the system calls validatePathWithinWorkspace before any file write operation. It ensures the file being modified resides within the detected workspace root of the Language Server.
Sources: src/tools/code-actions.ts:109-110, CLAUDE.md:120-123

// From src/tools/code-actions.ts:111-135
// Sorting edits in reverse order is critical for data integrity
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;
});

// Applying changes to content string
for (const edit of sortedEdits) {
  let startOffset = calculateOffset(edit.range.start, lines);
  let endOffset = calculateOffset(edit.range.end, lines);
  currentContent =
    currentContent.substring(0, startOffset) +
    edit.newText +
    currentContent.substring(endOffset);
}

Sources: src/tools/code-actions.ts:111-135

Usage Guidelines

As defined in the project's skill documentation, lsp_code_actions is often part of a multi-step workflow.

1. Context Discovery: Use lsp_diagnostics to find errors at a specific line.
2. Range Identification: If performing refactoring (like extraction), use lsp_selection_range to find the exact semantic boundaries of the expression or statement.
3. Dry Run: Call lsp_code_actions with apply: false to see the available actions and their proposed edit diffs.
4. Execution: Call lsp_code_actions with apply: true and the desired action_index.

Sources: SKILL.md:104-112, SKILL.md:114-118

Summary

The Code Actions and Quick Fixes module provides a robust mechanism for semantic code modification. By leveraging the Language Server's understanding of the codebase, it allows for safe refactoring and error resolution that goes beyond simple text replacement. The system ensures safety through workspace boundary validation and maintains code integrity by carefully ordering text transformations.