File Operations

Overview

MCP Filesystem Ultra v4.0.0 provides 7 tools for file management operations, plus consolidated functionality within read_file and search_files that replaces several v3 tools.

What Was Consolidated

v3 Tool	v4 Equivalent
rename_file	move_file — rename is a move within the same directory
soft_delete_file	delete_file — soft-delete is now the default
delete_file (permanent)	delete_file with permanent: true
read_file_range	read_file with start_line + end_line
count_occurrences	search_files with count_only: true
replace_nth_occurrence	edit_file with occurrence: N

---

File Management Tools

copy_file

Copy a file or directory to a new location. Preserves file permissions. For directories, performs a recursive copy (symlinks are skipped for security).

Parameters:

Parameter	Required	Type	Description
source_path	Yes	string	Path of the file or directory to copy
dest_path	Yes	string	Destination path for the copy

Examples:

// Copy a single file
copy_file({ source_path: "config.json", dest_path: "config.backup.json" })

// Copy an entire directory
copy_file({ source_path: "templates/", dest_path: "templates-backup/" })

---

move_file

Move or rename a file or directory. This is an atomic operation — either it completes fully or not at all. In v4, move_file replaces both move_file and rename_file from v3.

Parameters:

Parameter	Required	Type	Description
source_path	Yes	string	Current path of the file or directory
dest_path	Yes	string	New path for the file or directory

Examples:

// Move a file to a different directory
move_file({ source_path: "src/old-module.go", dest_path: "archive/old-module.go" })

// Rename a file (same directory, different name)
move_file({ source_path: "utils.go", dest_path: "helpers.go" })

// Rename a directory
move_file({ source_path: "components", dest_path: "ui-components" })

---

delete_file

Delete a file or directory. By default, performs a soft-delete — the file is moved to a filesdelete/ directory where it can be recovered. Use permanent: true for irreversible deletion.

In v4, delete_file replaces both delete_file and soft_delete_file from v3.

Parameters:

Parameter	Required	Type	Description
path	Yes	string	Path to the file or directory to delete
permanent	No	boolean	Permanently delete instead of soft-delete (default: false)

Examples:

// Soft-delete (recoverable -- moved to filesdelete/)
delete_file({ path: "old-config.json" })

// Permanent delete (irreversible)
delete_file({ path: "temp/build-cache", permanent: true })

Safety features:

• A backup is created automatically before deletion
• Soft-deleted files can be recovered from the filesdelete/ directory
• Access control (--allowed-paths) is enforced — you cannot delete files outside allowed paths

---

get_file_info

Get detailed information about a file or directory, including size, modification time, permissions, and file type.

Parameters:

Parameter	Required	Type	Description
path	Yes	string	Path to the file or directory

Examples:

get_file_info({ path: "main.go" })

Response:

File: main.go
Size: 15.2 KB (15,572 bytes)
Type: text/plain (Go source)
Modified: 2026-03-12 14:30:22
Permissions: -rw-r--r--
Lines: 450

---

create_directory

Create a new directory. Parent directories are created automatically if they do not exist (equivalent to mkdir -p).

Parameters:

Parameter	Required	Type	Description
path	Yes	string	Path to the directory to create

Examples:

// Creates all intermediate directories as needed
create_directory({ path: "src/components/forms/validation" })

---

list_directory

List the contents of a directory. Results are cached for fast repeated access (2-minute cache TTL). Auto-converts WSL/Windows paths.

Parameters:

Parameter	Required	Type	Description
path	Yes	string	Path to the directory (WSL or Windows format)

Examples:

list_directory({ path: "C:\\project\\src" })
list_directory({ path: "/mnt/c/project" })

Response (compact mode):

src: components/, index.ts(2KB), app.tsx(5KB), utils/, config.json

Response (verbose mode):

Directory listing for: C:\project\src

Type    Name                    Size        Modified
----------------------------------------------------
[DIR]   components              -           2026-03-10
[FILE]  index.ts                2.3 KB      2026-03-10
[FILE]  app.tsx                 5.1 KB      2026-03-10
[DIR]   utils                   -           2026-03-09
[FILE]  config.json             0.4 KB      2026-03-08

The maximum number of items returned is controlled by --max-list-items (default: 500).

---

Consolidated Operations

These v3 tools have been absorbed into other v4 tools. The functionality is identical — only the invocation changes.

Reading Line Ranges (replaces read_file_range)

In v3, read_file_range was a separate tool. In v4, use read_file with start_line and end_line:

// v3 (old):
// read_file_range({ path: "main.go", start_line: 100, end_line: 150 })

// v4 (new):
read_file({ path: "main.go", start_line: 100, end_line: 150 })

This is the most token-efficient way to read a specific section of a large file. Instead of reading 3,000 lines (~75,000 tokens), read only the 50 lines you need (~1,250 tokens).

Additional reading modes:

// Read first 50 lines
read_file({ path: "main.go", max_lines: 50, mode: "head" })

// Read last 20 lines (useful for log files)
read_file({ path: "server.log", max_lines: 20, mode: "tail" })

Counting Occurrences (replaces count_occurrences)

In v3, count_occurrences was a separate tool. In v4, use search_files with count_only: true:

// v3 (old):
// count_occurrences({ path: "main.go", pattern: "TODO" })

// v4 (new):
search_files({ path: "main.go", pattern: "TODO", count_only: true })

To also get line numbers of each match:

search_files({ path: "main.go", pattern: "TODO", count_only: true, return_lines: "true" })

Response:

Count: 5 occurrences in main.go
Lines: 23, 45, 78, 112, 156

Replacing Nth Occurrence (replaces replace_nth_occurrence)

In v3, replace_nth_occurrence was a separate tool. In v4, use edit_file with the occurrence parameter:

// v3 (old):
// replace_nth_occurrence({ path: "config.go", old_text: "TODO", new_text: "DONE", n: 1 })

// v4 (new) -- replace first occurrence
edit_file({ path: "config.go", old_text: "TODO", new_text: "DONE", occurrence: 1 })

// Replace second occurrence
edit_file({ path: "config.go", old_text: "TODO", new_text: "DONE", occurrence: 2 })

// Replace last occurrence
edit_file({ path: "config.go", old_text: "TODO", new_text: "DONE", occurrence: -1 })

// Replace second-to-last occurrence
edit_file({ path: "config.go", old_text: "TODO", new_text: "DONE", occurrence: -2 })

Combine with whole_word: true to avoid partial matches:

edit_file({
  path: "app.js",
  old_text: "count",
  new_text: "total",
  occurrence: -1,
  whole_word: true
})

---

Safety Features

Automatic Backups

All destructive operations (edit_file, delete_file, multi_edit) automatically create a backup before executing. You can restore any backup using:

backup({ action: "restore", backup_id: "20260313-143022-abc123" })

Risk Assessment

Edit operations are assessed for risk before execution:

Risk Level	Condition	Behavior
LOW	< 20% of file changed, < 50 occurrences	Proceeds silently
MEDIUM	20-74% change, or 50-100 occurrences	Auto-proceeds with backup and risk notice
HIGH	75-89% change, or > 100 occurrences	Auto-proceeds with backup and prominent warning
CRITICAL	>= 90% change	Blocked — requires force: true

Access Control

When --allowed-paths is configured, all file operations verify that the target path is within an allowed directory. Symlinks are resolved before checking containment, preventing path traversal attacks.

Atomic Operations

Move and write operations are atomic — they either complete fully or leave the filesystem unchanged. Writes use a temporary file + rename strategy to prevent partial writes on failure.

---

Batch File Operations

For operating on multiple files at once, use batch_operations:

Batch CRUD Operations

batch_operations({
  request_json: JSON.stringify({
    operations: [
      { type: "write", path: "file1.go", content: "package main" },
      { type: "copy", source: "template.json", destination: "config.json" },
      { type: "create_dir", path: "output/" },
      { type: "delete", path: "temp.log" }
    ],
    atomic: true,
    create_backup: true
  })
})

Batch Rename

Rename multiple files using patterns:

batch_operations({
  rename_json: JSON.stringify({
    path: "src/",
    mode: "find_replace",
    find: "old_prefix_",
    replace: "new_prefix_",
    recursive: true,
    preview: true
  })
})

Available rename modes: find_replace, add_prefix, add_suffix, number_files, regex_rename, change_extension, to_lowercase, to_uppercase.

See Batch Operations and Pipeline System for more details.

---

Common Workflows

Workflow 1: Safely Rename a Module

// 1. Check what files reference the old name
search_files({ path: "src/", pattern: "oldModule", include_content: true })

// 2. Rename the file
move_file({ source_path: "src/oldModule.go", dest_path: "src/newModule.go" })

// 3. Update references in other files
edit_file({
  path: "src/",
  mode: "search_replace",
  pattern: "oldModule",
  replacement: "newModule"
})

Workflow 2: Create a New Feature Directory

// 1. Create the directory structure
create_directory({ path: "src/features/authentication" })

// 2. Write initial files
write_file({ path: "src/features/authentication/handler.go", content: "package authentication\n" })
write_file({ path: "src/features/authentication/handler_test.go", content: "package authentication\n" })

// 3. Verify
list_directory({ path: "src/features/authentication" })

Workflow 3: Clean Up Temporary Files

// 1. Find temporary files
search_files({ path: ".", pattern: "\\.tmp$", include_content: false })

// 2. Review before deleting
get_file_info({ path: "build/output.tmp" })

// 3. Delete (soft-delete by default)
delete_file({ path: "build/output.tmp" })

---

See Also

• Core Tools API Reference — Complete parameters for all 16 tools
• Search Operations — Unified search and pattern matching
• Backups and Recovery — Backup system details
• Batch Operations — Multi-file atomic operations
• Migration from v3 — Complete v3-to-v4 mapping

---

Last updated: March 2026 Version: 4.0.0