Desktop Commander MCP

Instructions

Implementation Reference

• src/tools/edit.ts:370-440 (handler)

  The main handler function for the 'edit_block' tool. It parses arguments using EditBlockArgsSchema and dispatches to either structured file range editing (for Excel etc.) or text file search/replace editing.
  export async function handleEditBlock(args: unknown): Promise<ServerResult> { const parsed = EditBlockArgsSchema.parse(args); // Structured files: Range rewrite if (parsed.range !== undefined && parsed.content !== undefined) { try { // Validate path before any filesystem operations const validatedPath = await validatePath(parsed.file_path); const { getFileHandler } = await import('../utils/files/factory.js'); const handler = await getFileHandler(validatedPath); // Parse content if it's a JSON string (AI often sends arrays as JSON strings) let content = parsed.content; if (typeof content === 'string') { try { content = JSON.parse(content); } catch { // Leave as-is if not valid JSON - let handler decide } } // Check if handler supports range editing if ('editRange' in handler && typeof handler.editRange === 'function') { await handler.editRange(validatedPath, parsed.range, content, parsed.options); return { content: [{ type: "text", text: `Successfully updated range ${parsed.range} in ${parsed.file_path}` }], }; } else { return { content: [{ type: "text", text: `Error: Range-based editing not supported for ${parsed.file_path}` }], isError: true }; } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [{ type: "text", text: `Error: ${errorMessage}` }], isError: true }; } } // Text files: String replacement // Validate required parameters for text replacement if (parsed.old_string === undefined || parsed.new_string === undefined) { return { content: [{ type: "text", text: `Error: Text replacement requires both old_string and new_string parameters` }], isError: true }; } const searchReplace = { search: parsed.old_string, replace: parsed.new_string }; return performSearchReplace(parsed.file_path, searchReplace, parsed.expected_replacements); }
• src/tools/schemas.ts:129-143 (schema)

  Zod schema defining input parameters for edit_block tool, supporting both text replacement (old_string, new_string, expected_replacements) and structured range edits (range, content).
  export const EditBlockArgsSchema = z.object({ file_path: z.string(), // Text file string replacement old_string: z.string().optional(), new_string: z.string().optional(), expected_replacements: z.number().optional().default(1), // Structured file range rewrite (Excel, etc.) range: z.string().optional(), content: z.any().optional(), options: z.record(z.any()).optional() }).refine( data => (data.old_string !== undefined && data.new_string !== undefined) || (data.range !== undefined && data.content !== undefined), { message: "Must provide either (old_string + new_string) or (range + content)" } );
• src/server.ts:674-724 (registration)

  Registration of 'edit_block' tool in the list_tools handler, defining name, description, input schema, and annotations.
  name: "edit_block", description: ` Apply surgical edits to files. BEST PRACTICE: Make multiple small, focused edits rather than one large edit. Each edit_block call should change only what needs to be changed - include just enough context to uniquely identify the text being modified. FORMAT HANDLING (by extension): EXCEL FILES (.xlsx, .xls, .xlsm) - Range Update mode: Takes: - file_path: Path to the Excel file - range: ALWAYS use FROM:TO format - "SheetName!A1:C10" or "SheetName!C1:C1" - content: 2D array, e.g., [["H1","H2"],["R1","R2"]] TEXT FILES - Find/Replace mode: Takes: - file_path: Path to the file to edit - old_string: Text to replace - new_string: Replacement text - expected_replacements: Optional number of replacements (default: 1) By default, replaces only ONE occurrence of the search text. To replace multiple occurrences, provide expected_replacements with the exact number of matches expected. UNIQUENESS REQUIREMENT: When expected_replacements=1 (default), include the minimal amount of context necessary (typically 1-3 lines) before and after the change point, with exact whitespace and indentation. When editing multiple sections, make separate edit_block calls for each distinct change rather than one large replacement. When a close but non-exact match is found, a character-level diff is shown in the format: common_prefix{-removed-}{+added+}common_suffix to help you identify what's different. Similar to write_file, there is a configurable line limit (fileWriteLineLimit) that warns if the edited file exceeds this limit. If this happens, consider breaking your edits into smaller, more focused changes. ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(EditBlockArgsSchema), annotations: { title: "Edit Block", readOnlyHint: false, destructiveHint: true, openWorldHint: false, }, },
• src/server.ts:1322-1324 (registration)

  Dispatch in CallToolRequestSchema handler that routes 'edit_block' calls to handlers.handleEditBlock.
  case "edit_block": result = await handlers.handleEditBlock(args); break;
• src/tools/edit.ts:113-317 (helper)

  Core helper function implementing text file editing logic: exact search/replace, fuzzy matching fallback, line ending handling, occurrence counting, and warnings for large edits.
  export async function performSearchReplace(filePath: string, block: SearchReplace, expectedReplacements: number = 1): Promise<ServerResult> { // Get file extension for telemetry using path module const fileExtension = path.extname(filePath).toLowerCase(); // Capture file extension and string sizes in telemetry without capturing the file path capture('server_edit_block', { fileExtension: fileExtension, oldStringLength: block.search.length, oldStringLines: block.search.split('\n').length, newStringLength: block.replace.length, newStringLines: block.replace.split('\n').length, expectedReplacements: expectedReplacements }); // Check for empty search string to prevent infinite loops if (block.search === "") { // Capture file extension in telemetry without capturing the file path capture('server_edit_block_empty_search', {fileExtension: fileExtension, expectedReplacements}); return { content: [{ type: "text", text: "Empty search strings are not allowed. Please provide a non-empty string to search for." }], }; } // Read file directly to preserve line endings - critical for edit operations const validPath = await validatePath(filePath); const content = await readFileInternal(validPath, 0, Number.MAX_SAFE_INTEGER); // Make sure content is a string if (typeof content !== 'string') { capture('server_edit_block_content_not_string', {fileExtension: fileExtension, expectedReplacements}); throw new Error('Wrong content for file ' + filePath); } // Get the line limit from configuration const config = await configManager.getConfig(); const MAX_LINES = config.fileWriteLineLimit ?? 50; // Default to 50 if not set // Detect file's line ending style const fileLineEnding = detectLineEnding(content); // Normalize search string to match file's line endings const normalizedSearch = normalizeLineEndings(block.search, fileLineEnding); // First try exact match let tempContent = content; let count = 0; let pos = tempContent.indexOf(normalizedSearch); while (pos !== -1) { count++; pos = tempContent.indexOf(normalizedSearch, pos + 1); } // If exact match found and count matches expected replacements, proceed with exact replacement if (count > 0 && count === expectedReplacements) { // Replace all occurrences let newContent = content; // If we're only replacing one occurrence, replace it directly if (expectedReplacements === 1) { const searchIndex = newContent.indexOf(normalizedSearch); newContent = newContent.substring(0, searchIndex) + normalizeLineEndings(block.replace, fileLineEnding) + newContent.substring(searchIndex + normalizedSearch.length); } else { // Replace all occurrences using split and join for multiple replacements newContent = newContent.split(normalizedSearch).join(normalizeLineEndings(block.replace, fileLineEnding)); } // Check if search or replace text has too many lines const searchLines = block.search.split('\n').length; const replaceLines = block.replace.split('\n').length; const maxLines = Math.max(searchLines, replaceLines); let warningMessage = ""; if (maxLines > MAX_LINES) { const problemText = searchLines > replaceLines ? 'search text' : 'replacement text'; warningMessage = `\n\nWARNING: The ${problemText} has ${maxLines} lines (maximum: ${MAX_LINES}). RECOMMENDATION: For large search/replace operations, consider breaking them into smaller chunks with fewer lines.`; } await writeFile(filePath, newContent); capture('server_edit_block_exact_success', {fileExtension: fileExtension, expectedReplacements, hasWarning: warningMessage !== ""}); return { content: [{ type: "text", text: `Successfully applied ${expectedReplacements} edit${expectedReplacements > 1 ? 's' : ''} to ${filePath}${warningMessage}` }], }; } // If exact match found but count doesn't match expected, inform the user if (count > 0 && count !== expectedReplacements) { capture('server_edit_block_unexpected_count', {fileExtension: fileExtension, expectedReplacements, expectedReplacementsCount: count}); return { content: [{ type: "text", text: `Expected ${expectedReplacements} occurrences but found ${count} in ${filePath}. ` + `Double check and make sure you understand all occurencies and if you want to replace all ${count} occurrences, set expected_replacements to ${count}. ` + `If there are many occurrancies and you want to change some of them and keep the rest. Do it one by one, by adding more lines around each occurrence.` + `If you want to replace a specific occurrence, make your search string more unique by adding more lines around search string.` }], }; } // If exact match not found, try fuzzy search if (count === 0) { // Track fuzzy search time const startTime = performance.now(); // Perform fuzzy search const fuzzyResult = recursiveFuzzyIndexOf(content, block.search); const similarity = getSimilarityRatio(block.search, fuzzyResult.value); // Calculate execution time in milliseconds const executionTime = performance.now() - startTime; // Generate diff and gather character code data const diff = highlightDifferences(block.search, fuzzyResult.value); // Count character codes in diff const characterCodeData = getCharacterCodeData(block.search, fuzzyResult.value); // Create comprehensive log entry const logEntry: FuzzySearchLogEntry = { timestamp: new Date(), searchText: block.search, foundText: fuzzyResult.value, similarity: similarity, executionTime: executionTime, exactMatchCount: count, expectedReplacements: expectedReplacements, fuzzyThreshold: FUZZY_THRESHOLD, belowThreshold: similarity < FUZZY_THRESHOLD, diff: diff, searchLength: block.search.length, foundLength: fuzzyResult.value.length, fileExtension: fileExtension, characterCodes: characterCodeData.report, uniqueCharacterCount: characterCodeData.uniqueCount, diffLength: characterCodeData.diffLength }; // Log to file await fuzzySearchLogger.log(logEntry); // Combine all fuzzy search data for single capture const fuzzySearchData = { similarity: similarity, execution_time_ms: executionTime, search_length: block.search.length, file_size: content.length, threshold: FUZZY_THRESHOLD, found_text_length: fuzzyResult.value.length, character_codes: characterCodeData.report, unique_character_count: characterCodeData.uniqueCount, total_diff_length: characterCodeData.diffLength }; // Check if the fuzzy match is "close enough" if (similarity >= FUZZY_THRESHOLD) { // Capture the fuzzy search event with all data capture('server_fuzzy_search_performed', fuzzySearchData); // If we allow fuzzy matches, we would make the replacement here // For now, we'll return a detailed message about the fuzzy match return { content: [{ type: "text", text: `Exact match not found, but found a similar text with ${Math.round(similarity * 100)}% similarity (found in ${executionTime.toFixed(2)}ms):\n\n` + `Differences:\n${diff}\n\n` + `To replace this text, use the exact text found in the file.\n\n` + `Log entry saved for analysis. Use the following command to check the log:\n` + `Check log: ${await fuzzySearchLogger.getLogPath()}` }],// TODO }; } else { // If the fuzzy match isn't close enough // Still capture the fuzzy search event with all data capture('server_fuzzy_search_performed', { ...fuzzySearchData, below_threshold: true }); return { content: [{ type: "text", text: `Search content not found in ${filePath}. The closest match was "${fuzzyResult.value}" ` + `with only ${Math.round(similarity * 100)}% similarity, which is below the ${Math.round(FUZZY_THRESHOLD * 100)}% threshold. ` + `(Fuzzy search completed in ${executionTime.toFixed(2)}ms)\n\n` + `Log entry saved for analysis. Use the following command to check the log:\n` + `Check log: ${await fuzzySearchLogger.getLogPath()}` }], }; } } throw new Error("Unexpected error during search and replace operation."); }