edit_file
Apply multiple text replacements to files and view unified diffs of changes made. Specify file path and edit operations to modify UTF-8 text files within allowed directories.
Instructions
Apply multiple text replacements to a file and return a unified diff.
Args: path (str): File path to edit (absolute or relative to allowed directories) edits (List[Dict[str, str]]): List of edit operations, each with 'oldText' and 'newText' keys
Returns: str: Unified diff showing changes made, or error message if failed
Note: - Path must be within allowed directory roots - File must be a UTF-8 text file - Edits are applied sequentially in the order provided - Each 'oldText' must match exactly (first occurrence is replaced) - Returns unified diff format showing before/after changes - File is atomically updated using temporary file - If no changes made, returns 'No changes made.'
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| edits | Yes |
Implementation Reference
- main.py:569-622 (handler)The core handler implementation for the 'edit_file' MCP tool. It is registered via @mcp.tool decorator (conditionally if not in read-only mode). Applies sequential string replacements specified in the 'edits' list to the target file, generates and returns a unified diff, and atomically updates the file using a temporary file.@mcp.tool def edit_file(path: str, edits: List[Dict[str, str]]) -> str: """Apply multiple text replacements to a file and return a unified diff. Args: path (str): File path to edit (absolute or relative to allowed directories) edits (List[Dict[str, str]]): List of edit operations, each with 'oldText' and 'newText' keys Returns: str: Unified diff showing changes made, or error message if failed Note: - Path must be within allowed directory roots - File must be a UTF-8 text file - Edits are applied sequentially in the order provided - Each 'oldText' must match exactly (first occurrence is replaced) - Returns unified diff format showing before/after changes - File is atomically updated using temporary file - If no changes made, returns 'No changes made.' """ try: rp = _resolve(path) if not _is_text(rp): return ( f"Error editing file: '{rp}' is not a UTF-8 text file or is binary" ) original = rp.read_text(encoding="utf-8") modified = original for i, edit in enumerate(edits): old = edit.get("oldText", "") new = edit.get("newText", "") if old not in modified: return f"Error editing file: could not find text to replace in edit {i + 1}. Make sure the text matches exactly:\n{old}" modified = modified.replace(old, new, 1) if modified == original: return "No changes made." diff = "\n".join( difflib.unified_diff( original.splitlines(), modified.splitlines(), fromfile=str(rp), tofile=str(rp), lineterm="", ) ) tmp = rp.with_suffix(rp.suffix + ".tmp") tmp.write_text(modified, encoding="utf-8") tmp.replace(rp) return diff except Exception as e: return _human_error(e, "editing file")
- main.py:569-569 (registration)The @mcp.tool decorator registers the edit_file function with the FastMCP server, making it available as an MCP tool.@mcp.tool
- main.py:570-588 (schema)The function signature and docstring define the input schema: path (str), edits (List[Dict with 'oldText' and 'newText']), and output as str (diff or error message). FastMCP uses this for tool schema.def edit_file(path: str, edits: List[Dict[str, str]]) -> str: """Apply multiple text replacements to a file and return a unified diff. Args: path (str): File path to edit (absolute or relative to allowed directories) edits (List[Dict[str, str]]): List of edit operations, each with 'oldText' and 'newText' keys Returns: str: Unified diff showing changes made, or error message if failed Note: - Path must be within allowed directory roots - File must be a UTF-8 text file - Edits are applied sequentially in the order provided - Each 'oldText' must match exactly (first occurrence is replaced) - Returns unified diff format showing before/after changes - File is atomically updated using temporary file - If no changes made, returns 'No changes made.' """