Understanding the edit_block Search and Replace Syntax in Desktop Commander MCP

The Desktop Commander MCP edit_block tool uses a four-part search-and-replace block format marked by <<<<<<< SEARCH, =======, and >>>>>>> REPLACE delimiters to perform precise file modifications.

Desktop Commander MCP is a Model Context Protocol server that enables AI assistants to read, write, and modify files on your local machine. The edit_block search and replace syntax provides a standardized way to define exact text substitutions, allowing for surgical edits without rewriting entire files. This format is documented in the repository's README.md and implemented across multiple source files including src/tools/edit.ts.

The Four-Part Edit Block Structure

The canonical edit_block syntax requires exactly four components placed after the target file path:

filepath.ext
<<<<<<< SEARCH
content to find
=======
new content
>>>>>>> REPLACE

• File path: The relative or absolute path to the file you want to modify
• Search marker: <<<<<<< SEARCH initiates the search section
• Separator: ======= divides the search content from the replacement content
• Replace marker: >>>>>>> REPLACE terminates the edit block

According to the source code in src/tools/edit.ts, the server performs an exact-match search by default, falling back to fuzzy matching if the exact string is not found.

Practical Code Examples

Simple JavaScript Modification

src/main.js
<<<<<<< SEARCH
console.log("old message");
=======
console.log("new message");
>>>>>>> REPLACE

Updating Markdown Headers

docs/guide.md
<<<<<<< SEARCH

# Introduction

=======

# Getting Started

>>>>>>> REPLACE

Programmatic API Usage

When calling the tool programmatically, you use old_string and new_string parameters instead of the block format:

await callTool('edit_block', {
  path: 'src/main.js',
  old_string: 'console.log("old message");',
  new_string: 'console.log("new message");'
});

Excel Cell Editing

The tool also supports spreadsheet manipulation through the range parameter as implemented in src/utils/files/excel.ts:

await callTool('edit_block', {
  path: 'data/report.xlsx',
  range: 'Sheet1!B2',
  content: [['42']]
});

Implementation Across the Codebase

The edit_block search and replace functionality spans several key files in the wonderwhy-er/DesktopCommanderMCP repository:

• src/tools/edit.ts: Contains the core implementation of the edit_block tool, including exact-match and fuzzy-search logic
• src/ui/file-preview/src/markdown/editor.ts: Handles UI parsing of the edit-block syntax from Markdown files
• src/utils/files/excel.ts: Manages the range argument handling for Excel-specific edits
• README.md: Documents the four-line block layout and usage patterns

Summary

• The edit_block syntax uses <<<<<<< SEARCH, =======, and >>>>>>> REPLACE delimiters to define search and replace operations
• Place the file path on the line immediately preceding the search marker
• The tool supports both the block format for UI/Markdown usage and programmatic parameters (old_string/new_string) for API calls
• Excel files receive special handling through the range parameter in src/utils/files/excel.ts
• The server attempts exact matching first, then falls back to fuzzy search if needed

Frequently Asked Questions

What happens if the search text is not found exactly?

The edit_block tool first attempts an exact match of the search content. If the exact string is not found in the target file, the implementation in src/tools/edit.ts falls back to fuzzy matching to locate similar content before returning an error.

Can I use edit_block for binary files like Excel spreadsheets?

Yes. While text files use the standard search/replace syntax, Excel files utilize the range parameter as shown in src/utils/files/excel.ts. You specify the cell range (e.g., Sheet1!B2) and provide the new content as a 2D array.

Is the file path required in the block format?

Yes. The file path must appear on the line immediately before the <<<<<<< SEARCH marker. This tells the Desktop Commander MCP server which file to modify, and can be either a relative path from the working directory or an absolute path.

How does the programmatic API differ from the block syntax?

The programmatic API uses discrete parameters (path, old_string, new_string) rather than the visual delimiter format. Both methods execute the same underlying logic in src/tools/edit.ts, but the block format is designed for human readability in Markdown or UI contexts, while the parameter format suits direct function calls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}