Core Tools

MCP Filesystem Ultra v4.0.0 provides 16 consolidated tools (down from 59 in v3.x). Each tool is intelligent — it auto-selects the optimal strategy based on file size, context, and parameters provided.

---

1. read_file

Read file contents. Supports full reads, line ranges, head/tail mode, and base64 encoding for binary files. Auto-converts WSL/Windows paths.

Replaces: mcp_read, read_file, read_file_range, read_base64, chunked_read_file, intelligent_read

Annotations:

Annotation	Value
readOnly	true
destructive	false
idempotent	true

Parameters:

Parameter	Required	Type	Description
path	Yes	string	Path to file (WSL or Windows format)
max_lines	No	number	Max lines to return (0 = all)
mode	No	string	Read mode: all, head, tail
start_line	No	number	Starting line number (1-indexed) for range read
end_line	No	number	Ending line number (inclusive) for range read
encoding	No	string	Set to "base64" to read file as base64-encoded binary

Examples:

// Read entire file
read_file({ path: "C:\\project\\main.go" })

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

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

// Read specific line range (most token-efficient)
read_file({ path: "main.go", start_line: 100, end_line: 150 })

// Read binary file as base64
read_file({ path: "image.png", encoding: "base64" })

---

2. write_file

Write file atomically. Supports text content or base64-encoded binary. Auto-creates parent directories. Auto-converts WSL/Windows paths.

Replaces: mcp_write, write_file, create_file, write_base64, streaming_write_file, intelligent_write

Annotations:

Annotation	Value
readOnly	false
destructive	true
idempotent	true

Parameters:

Parameter	Required	Type	Description
path	Yes	string	Path where to write (WSL or Windows format)
content	No	string	Text content to write to the file
content_base64	No	string	Base64-encoded binary content to write
encoding	No	string	Set to "base64" when content is base64-encoded

Examples:

// Write text file
write_file({ path: "config.json", content: "{}" })

// Write binary file from base64
write_file({ path: "image.png", content_base64: "iVBORw0KGgo..." })

// Alternative base64 via encoding flag
write_file({ path: "data.bin", content: "SGVsbG8=", encoding: "base64" })

---

3. edit_file

Edit file with multiple modes. Default mode: smart text replacement with auto-backup and risk validation. Only blocks CRITICAL risk (>=90% content change). Auto-converts WSL/Windows paths.

Replaces: mcp_edit, edit_file, smart_edit_file, intelligent_edit, recovery_edit, search_and_replace, replace_nth_occurrence, regex_transform_file

Annotations:

Annotation	Value
readOnly	false
destructive	true
idempotent	false

Parameters:

Parameter	Required	Type	Description
path	Yes	string	Path to file (WSL or Windows format)
old_text	No	string	Text to be replaced (default mode)
new_text	No	string	New text to replace with (default mode)
old_str	No	string	Alias for old_text
new_str	No	string	Alias for new_text
force	No	boolean	Force operation even if CRITICAL risk (default: false)
mode	No	string	Edit mode: "replace" (default), "search_replace", "regex"
occurrence	No	number	Which occurrence to replace: 1=first, 2=second, -1=last, -2=second-to-last (default: all)
pattern	No	string	Regex or literal pattern (for search_replace and regex modes)
replacement	No	string	Replacement text (for search_replace mode)
patterns_json	No	string	JSON array of patterns for regex mode: [{"pattern": "regex", "replacement": "$1...", "limit": -1}]
case_sensitive	No	boolean	Case sensitive matching (default: true, for regex mode)
create_backup	No	boolean	Create backup before transformation (default: true, for regex mode)
dry_run	No	boolean	Validate without applying changes (default: false, for regex mode)
whole_word	No	boolean	Match whole words only (default: false, for occurrence mode)

Modes:

Mode	When to Use
replace (default)	Simple find-and-replace in a single file. Use old_text/new_text.
search_replace	Recursive search-and-replace across a directory. Use pattern/replacement.
regex	Advanced regex transformations with capture groups. Use patterns_json.

Examples:

// Simple replacement (default mode)
edit_file({ path: "main.go", old_text: "v3.0.0", new_text: "v4.0.0" })

// Replace only the first occurrence
edit_file({ path: "config.ts", old_text: "TODO", new_text: "DONE", occurrence: 1 })

// Replace last occurrence with whole-word matching
edit_file({ path: "app.js", old_text: "count", new_text: "total", occurrence: -1, whole_word: true })

// Recursive search and replace across directory
edit_file({ path: "src/", mode: "search_replace", pattern: "oldFunc", replacement: "newFunc" })

// Regex transformation with capture groups
edit_file({
  path: "types.go",
  mode: "regex",
  patterns_json: JSON.stringify([
    { pattern: "func (\\w+)\\(\\)", replacement: "func $1(ctx context.Context)", limit: -1 }
  ]),
  dry_run: true
})

---

4. list_directory

List directory contents with caching. Auto-converts WSL/Windows paths.

Replaces: mcp_list, list_directory

Annotations:

Annotation	Value
readOnly	true
destructive	false
idempotent	true

Parameters:

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

Examples:

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

---

5. search_files

Search files by name or content. Supports regex and literal patterns. Auto-routes between fast search and advanced text search based on parameters. Auto-converts WSL/Windows paths.

Replaces: mcp_search, smart_search, advanced_text_search, count_occurrences

Annotations:

Annotation	Value
readOnly	true
destructive	false
idempotent	true

Parameters:

Parameter	Required	Type	Description
path	Yes	string	Base directory or file (WSL or Windows format)
pattern	Yes	string	Regex or literal pattern
include_content	No	boolean	Include file content search (default: false)
file_types	No	string	Comma-separated file extensions (e.g., .go,.txt)
case_sensitive	No	boolean	Case sensitive search (default: false)
whole_word	No	boolean	Match whole words only (default: false)
include_context	No	boolean	Include surrounding context lines (default: false)
context_lines	No	number	Number of context lines (default: 3)
count_only	No	boolean	Count pattern occurrences without full search (default: false)
return_lines	No	string	Return line numbers of count matches ("true"/"false", for count_only mode)

Auto-routing: When case_sensitive, whole_word, or include_context are provided, the tool automatically routes to the advanced text search engine. When count_only is true, it dispatches to the occurrence counter. Otherwise, it uses the fast smart search path.

Examples:

// Fast file name search
search_files({ path: "C:\\project", pattern: "main.go" })

// Content search with file type filter
search_files({ path: ".", pattern: "TODO", include_content: true, file_types: ".go,.ts" })

// Advanced search with context
search_files({ path: ".", pattern: "func.*Error", case_sensitive: true, include_context: true })

// Count occurrences in a file
search_files({ path: "main.go", pattern: "fmt\\.Sprintf", count_only: true })

// Count with line numbers
search_files({ path: "main.go", pattern: "TODO", count_only: true, return_lines: "true" })

---

6. analyze_operation

Analyze a file operation without executing (Plan Mode / dry-run). Useful for previewing the impact of writes, edits, and deletes before committing.

Annotations:

Annotation	Value
readOnly	true
destructive	false
idempotent	true

Parameters:

Parameter	Required	Type	Description
operation	Yes	string	Operation to analyze: file, optimize, write, edit, delete
path	Yes	string	Path to the file
content	No	string	Content for write analysis
old_text	No	string	Text to be replaced (for edit analysis)
new_text	No	string	Replacement text (for edit analysis)

Operations:

Operation	Purpose
file	Analyze file size, type, recommendations
optimize	Get optimization strategy suggestion
write	Dry-run write analysis
edit	Dry-run edit with risk assessment
delete	Dry-run delete impact analysis

Examples:

// Analyze a file
analyze_operation({ operation: "file", path: "large-data.json" })

// Preview edit risk
analyze_operation({ operation: "edit", path: "config.go", old_text: "v3", new_text: "v4" })

// Preview delete impact
analyze_operation({ operation: "delete", path: "old-module/" })

---

7. create_directory

Create a new directory (and parent directories if needed).

Annotations:

Annotation	Value
readOnly	false
destructive	false
idempotent	true

Parameters:

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

Examples:

create_directory({ path: "src/components/ui" })

---

8. delete_file

Delete a file or directory. Default: soft-delete (moves to trash). Use permanent: true for hard delete.

Annotations:

Annotation	Value
readOnly	false
destructive	true
idempotent	false

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)
delete_file({ path: "old-config.json" })

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

---

9. move_file

Move or rename a file or directory to a new location.

Replaces: move_file, rename_file

Annotations:

Annotation	Value
readOnly	false
destructive	true
idempotent	false

Parameters:

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

Examples:

// Move file
move_file({ source_path: "src/old.go", dest_path: "src/new.go" })

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

---

10. copy_file

Copy a file or directory to a new location. Preserves permissions.

Annotations:

Annotation	Value
readOnly	false
destructive	false
idempotent	true

Parameters:

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

Examples:

copy_file({ source_path: "config.json", dest_path: "config.backup.json" })
copy_file({ source_path: "templates/", dest_path: "templates-backup/" })

---

11. get_file_info

Get detailed information about a file or directory (size, modification time, permissions, type).

Annotations:

Annotation	Value
readOnly	true
destructive	false
idempotent	true

Parameters:

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

Examples:

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

---

12. multi_edit

Apply multiple edits to a single file atomically. Much faster than calling edit_file multiple times. Only blocks CRITICAL risk (>=90% change).

Annotations:

Annotation	Value
readOnly	false
destructive	true
idempotent	false

Parameters:

Parameter	Required	Type	Description
path	Yes	string	Path to the file to edit
edits_json	Yes	string	JSON array of edits: [{"old_text": "...", "new_text": "..."}, ...]
force	No	boolean	Force operation even if CRITICAL risk (default: false)

Examples:

// Rename a variable across a file
multi_edit({
  path: "main.go",
  edits_json: JSON.stringify([
    { old_text: "oldVarName", new_text: "newVarName" },
    { old_text: "OldFuncName", new_text: "NewFuncName" }
  ])
})

// Apply multiple fixes atomically
multi_edit({
  path: "config.ts",
  edits_json: JSON.stringify([
    { old_text: "port: 3000", new_text: "port: 8080" },
    { old_text: "debug: true", new_text: "debug: false" },
    { old_text: "v1.0.0", new_text: "v2.0.0" }
  ])
})

---

13. batch_operations

Execute multiple file operations atomically, run multi-step pipelines, or batch rename files. Provide exactly one of: request_json, pipeline_json, or rename_json.

Replaces: batch_operations, execute_pipeline, batch_rename_files

Annotations:

Annotation	Value
readOnly	false
destructive	true
idempotent	false

Parameters:

Parameter	Required	Type	Description
request_json	No	string	JSON with operations array and options. Fields: operations (array), atomic (bool), create_backup (bool), validate_only (bool)
pipeline_json	No	string	JSON pipeline definition with name, steps, and optional flags (dry_run, force, stop_on_error, create_backup, verbose, parallel)
rename_json	No	string	JSON with batch rename parameters. Fields: path, mode, find, replace, prefix, suffix, pattern, extension, start_number, padding, recursive, file_pattern, preview, case_sensitive

Batch Operations Mode (request_json)

Supported operations: write, edit, copy, move, delete, create_dir

batch_operations({
  request_json: JSON.stringify({
    operations: [
      { type: "write", path: "file1.go", content: "package main" },
      { type: "copy", source: "a.txt", destination: "b.txt" },
      { type: "create_dir", path: "new_folder" }
    ],
    atomic: true,
    create_backup: true
  })
})

Pipeline Mode (pipeline_json)

Multi-step file transformation pipeline with 12 actions, conditional logic, template variables, and parallel execution. See Pipeline Tools for full reference.

Supported steps: search, read_ranges, edit, multi_edit, count_occurrences, regex_transform, copy, rename, delete, aggregate, diff, merge

batch_operations({
  pipeline_json: JSON.stringify({
    name: "refactor-todos",
    parallel: true,
    stop_on_error: true,
    create_backup: true,
    steps: [
      { id: "find", action: "search", params: { path: ".", pattern: "TODO", file_types: [".go"] } },
      { id: "count", action: "count_occurrences", input_from: "find", params: { pattern: "TODO" } },
      { id: "fix", action: "edit", input_from: "find",
        condition: { type: "count_gt", step_ref: "count", value: "0" },
        params: { old_text: "TODO", new_text: "DONE" } }
    ]
  })
})

Batch Rename Mode (rename_json)

Modes: find_replace, add_prefix, add_suffix, number_files, regex_rename, change_extension, to_lowercase, to_uppercase

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

---

14. backup

Manage file backups. Backups are created automatically before destructive operations. Use this tool to list, inspect, compare, clean up, or restore backups.

Replaces: backup, restore_backup, list_backups, get_backup_info, compare_with_backup, cleanup_backups

Annotations:

Annotation	Value
readOnly	false
destructive	false
idempotent	false

Parameters:

Parameter	Required	Type	Description
action	No	string	Action: list (default), info, compare, cleanup, restore
backup_id	No	string	Backup ID (required for info, compare, restore)
file_path	No	string	File path for compare or selective restore
limit	No	number	Max backups to return for list (default: 20)
filter_operation	No	string	Filter by operation: edit, delete, batch, all
filter_path	No	string	Filter by file path (substring match)
newer_than_hours	No	number	Only backups newer than N hours
older_than_days	No	number	For cleanup: delete backups older than N days (default: 7)
dry_run	No	boolean	For cleanup/restore: preview without executing (default: true for cleanup, false for restore)
preview	No	boolean	For restore: show diff without restoring (default: false)

Action routing:

Action	Required Params	Description
list	(none)	List all backups with optional filters
info	backup_id	Show detailed backup information
compare	backup_id, file_path	Compare current file with backup version
cleanup	(none)	Clean up old backups
restore	backup_id	Restore file(s) from a backup

Examples:

// List recent backups
backup({})
backup({ action: "list", newer_than_hours: 24 })

// Get backup details
backup({ action: "info", backup_id: "20260313-143022-abc123" })

// Compare file with backup
backup({ action: "compare", backup_id: "20260313-143022-abc123", file_path: "main.go" })

// Preview restore
backup({ action: "restore", backup_id: "20260313-143022-abc123", preview: true, file_path: "main.go" })

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

// Clean up old backups (dry run)
backup({ action: "cleanup", older_than_days: 30, dry_run: true })

---

15. wsl

WSL/Windows file integration. Sync files between WSL and Windows, check integration status, or configure auto-sync.

Replaces: wsl_sync, wsl_status, configure_autosync, autosync_status

Annotations:

Annotation	Value
readOnly	false
destructive	false
idempotent	true

Parameters:

Parameter	Required	Type	Description
action	No	string	Action: sync (default), status, autosync_config, autosync_status
wsl_path	No	string	Source WSL path for sync
windows_path	No	string	Destination or source Windows path for sync
direction	No	string	Sync direction: wsl_to_windows, windows_to_wsl, bidirectional
create_dirs	No	boolean	Create destination directories (default: true)
filter_pattern	No	string	File filter pattern for workspace sync
dry_run	No	boolean	Preview changes without executing (default: false)
enabled	No	boolean	Enable/disable auto-sync (for autosync_config)
sync_on_write	No	boolean	Auto-sync on write operations (default: true)
sync_on_edit	No	boolean	Auto-sync on edit operations (default: true)
silent	No	boolean	Silent mode for auto-sync (default: false)

Action routing:

Action	Description
sync (default)	Copy files between WSL and Windows. Auto-detects direction from path format.
status	Show WSL/Windows integration status
autosync_config	Configure automatic sync (requires enabled param)
autosync_status	Show current auto-sync configuration and status

Examples:

// Check WSL status
wsl({ action: "status" })

// Copy file from WSL to Windows
wsl({ wsl_path: "/home/user/project/main.go" })

// Copy file from Windows to WSL
wsl({ windows_path: "C:\\project\\config.json" })

// Workspace sync with filter
wsl({ direction: "wsl_to_windows", filter_pattern: "*.go", dry_run: true })

// Enable auto-sync
wsl({ action: "autosync_config", enabled: true, sync_on_write: true })

// Check auto-sync status
wsl({ action: "autosync_status" })

---

16. server_info

Get server information, help, performance stats, and manage code artifacts.

Replaces: stats, get_help, artifact, performance_stats, get_edit_telemetry, capture_last_artifact, write_last_artifact, artifact_info

Annotations:

Annotation	Value
readOnly	true
destructive	false
idempotent	true

Parameters:

Parameter	Required	Type	Description
action	No	string	Action: help (default), stats, artifact
topic	No	string	Help topic: overview, workflow, tools, read, write, edit, search, batch, errors, examples, tips, all
sub_action	No	string	For artifact: capture, write, info
content	No	string	Artifact content to capture
path	No	string	Path for writing artifact

Action routing:

Action	Description
help (default)	Show usage instructions. Use topic to narrow.
stats	Show performance metrics and edit telemetry
artifact	Manage code artifacts via sub_action

Examples:

// Get help
server_info({})
server_info({ action: "help", topic: "edit" })

// Performance stats
server_info({ action: "stats" })

// Capture artifact in memory
server_info({ action: "artifact", sub_action: "capture", content: "function hello() {}" })

// Write artifact to file
server_info({ action: "artifact", sub_action: "write", path: "output.js" })

// Check artifact info
server_info({ action: "artifact", sub_action: "info" })

---

Tool Count Summary

Category	Count	Tools
Reading	1	read_file
Writing	1	write_file
Editing	2	edit_file, multi_edit
Search	1	search_files
File Management	4	delete_file, move_file, copy_file, get_file_info
Directory	2	list_directory, create_directory
Analysis	1	analyze_operation
Batch / Pipeline	1	batch_operations
Backup	1	backup
WSL	1	wsl
Server	1	server_info

Total: 16 tools (consolidated from 59 in v3.x)

---

See Also

• Tool Selection Guide — Which tool for your task
• Backup Tools — Detailed backup usage
• WSL Tools — WSL integration details
• Pipeline Tools — Pipeline reference
• Migration from v3 — Upgrading from 59 to 16 tools