Migration from v3 to v4

Overview

MCP Filesystem Ultra v4.0.0 consolidates 59 tools down to 16 without losing any functionality. Every feature from v3 is preserved — the tools are just smarter and unified.

Why 16? Claude Desktop triggers lazy tool loading when an MCP server exposes more than roughly 30 tools. When lazy loading is active, Claude must issue a tool_search call before it can invoke any tool, adding latency and token overhead to every interaction. By consolidating to 16 tools — well under the threshold — lazy loading is avoided entirely and every tool is immediately available.

How? Each v4 tool absorbs multiple v3 tools through three patterns:

Pattern	How it works	Example
Auto-routing	A `mode` or `action` parameter selects the behavior	`edit_file` with `mode:"regex"` replaces `regex_transform_file`
Auto-deduction	The tool infers intent from which parameters are present	`backup()` with no params lists backups; with `backup_id` shows details
Intelligent I/O	The tool auto-selects the optimal strategy based on file size	`read_file` replaces `chunked_read_file` and `intelligent_read`

Complete Migration Map

1. `read_file` (replaces 6 tools)

v3 Tool	How to call in v4	Notes
`read_file`	`read_file({ path })`	Same behavior
`chunked_read_file`	`read_file({ path })`	Chunking is now automatic for large files
`intelligent_read`	`read_file({ path })`	Intelligence is built-in (auto-selects I/O strategy)
`read_file_range`	`read_file({ path, start_line: 10, end_line: 50 })`	Use `start_line`/`end_line` params
`read_base64`	`read_file({ path, encoding: "base64" })`	Use `encoding:"base64"` for binary files
`streaming_read_file`	`read_file({ path })`	Streaming is automatic when needed

Additional params: max_lines, mode (“all”, “head”, “tail”).

2. `write_file` (replaces 6 tools)

v3 Tool	How to call in v4	Notes
`write_file`	`write_file({ path, content })`	Same behavior
`create_file`	`write_file({ path, content })`	Creates file if it does not exist
`streaming_write_file`	`write_file({ path, content })`	Streaming is automatic for large content
`intelligent_write`	`write_file({ path, content })`	Intelligence is built-in
`write_base64`	`write_file({ path, content_base64: "..." })`	Use `content_base64` param or `encoding:"base64"`
`write_last_artifact`	`server_info({ action: "artifact", sub_action: "write", path })`	Moved to `server_info`

3. `edit_file` (replaces 8 tools)

v3 Tool	How to call in v4	Notes
`edit_file`	`edit_file({ path, old_text, new_text })`	Same behavior (default mode)
`smart_edit_file`	`edit_file({ path, old_text, new_text })`	Smart editing is built-in
`intelligent_edit`	`edit_file({ path, old_text, new_text })`	Intelligence is built-in
`recovery_edit`	`edit_file({ path, old_text, new_text })`	Recovery logic is built-in
`search_and_replace`	`edit_file({ path, mode: "search_replace", pattern, replacement })`	Use `mode:"search_replace"`
`replace_nth_occurrence`	`edit_file({ path, old_text, new_text, occurrence: N })`	Use `occurrence` param (1=first, -1=last)
`regex_transform_file`	`edit_file({ path, mode: "regex", patterns_json: "[...]" })`	Use `mode:"regex"` with `patterns_json`
`count_occurrences` (edit)	`search_files({ path, pattern, count_only: true })`	Moved to `search_files`

Additional params: force, whole_word, case_sensitive, create_backup, dry_run.

Accepts both old_text/new_text and old_str/new_str for compatibility.

4. `list_directory` (replaces 2 tools)

v3 Tool	How to call in v4	Notes
`list_directory`	`list_directory({ path })`	Same behavior
`mcp_list`	`list_directory({ path })`	Unified name

5. `search_files` (replaces 4 tools)

v3 Tool	How to call in v4	Notes
`smart_search`	`search_files({ path, pattern })`	Default mode (fast search)
`advanced_text_search`	`search_files({ path, pattern, case_sensitive: true })`	Activated by `case_sensitive`, `whole_word`, or `include_context`
`mcp_search`	`search_files({ path, pattern })`	Unified name
`count_occurrences`	`search_files({ path, pattern, count_only: true })`	Use `count_only:true`; add `return_lines:true` for line numbers

Additional params: file_types, context_lines, include_content.

6. `analyze_operation` (replaces 5 tools)

v3 Tool	How to call in v4	Notes
`analyze_file`	`analyze_operation({ operation: "file", path })`	Analyze file strategy
`get_optimization_suggestion`	`analyze_operation({ operation: "optimize", path })`	Get optimization advice
`analyze_write`	`analyze_operation({ operation: "write", path, content })`	Preview write impact
`analyze_edit`	`analyze_operation({ operation: "edit", path, old_text, new_text })`	Preview edit impact
`analyze_delete`	`analyze_operation({ operation: "delete", path })`	Preview delete impact

7. `create_directory` (unchanged)

v3 Tool	How to call in v4	Notes
`create_directory`	`create_directory({ path })`	Unchanged

8. `delete_file` (replaces 2 tools)

v3 Tool	How to call in v4	Notes
`delete_file`	`delete_file({ path })`	Now defaults to soft-delete
`soft_delete_file`	`delete_file({ path })`	`permanent: false` is default

Use permanent: true for hard delete.

9. `move_file` (replaces 2 tools)

v3 Tool	How to call in v4	Notes
`move_file`	`move_file({ source_path, dest_path })`	Same behavior
`rename_file`	`move_file({ source_path, dest_path })`	Use `move_file` for renaming

10. `copy_file` (unchanged)

v3 Tool	How to call in v4	Notes
`copy_file`	`copy_file({ source_path, dest_path })`	Unchanged

11. `get_file_info` (unchanged)

v3 Tool	How to call in v4	Notes
`get_file_info`	`get_file_info({ path })`	Unchanged

12. `multi_edit` (unchanged)

v3 Tool	How to call in v4	Notes
`multi_edit`	`multi_edit({ path, edits_json })`	Unchanged — atomic multi-edit on one file

13. `batch_operations` (replaces 4 tools)

v3 Tool	How to call in v4	Notes
`batch_operations`	`batch_operations({ request_json: "{...}" })`	Same behavior (atomic batch ops)
`execute_pipeline`	`batch_operations({ pipeline_json: "{...}" })`	Use `pipeline_json` param
`batch_rename_files`	`batch_operations({ rename_json: "{...}" })`	Use `rename_json` param
`batch_file_operations`	`batch_operations({ request_json: "{...}" })`	Unified batch

Provide exactly one of: request_json, pipeline_json, or rename_json.

14. `backup` (replaces 6 tools)

v3 Tool	How to call in v4	Notes
`list_backups`	`backup()` or `backup({ action: "list" })`	Default action
`get_backup_info`	`backup({ action: "info", backup_id: "..." })`	Show details for one backup
`compare_with_backup`	`backup({ action: "compare", backup_id: "...", file_path: "..." })`	Diff current vs. backup
`cleanup_backups`	`backup({ action: "cleanup" })`	Dry-run by default
`restore_backup`	`backup({ action: "restore", backup_id: "..." })`	Restore is now part of `backup`
`backup_create`	Automatic	Backups are created automatically before destructive operations

Additional params: limit, filter_operation, filter_path, newer_than_hours, older_than_days, dry_run, preview.

15. `wsl` (replaces 6 tools)

v3 Tool	How to call in v4	Notes
`wsl_to_windows_copy`	`wsl({ wsl_path: "/home/..." })`	Direction auto-detected from path
`windows_to_wsl_copy`	`wsl({ windows_path: "C:\\..." })`	Direction auto-detected from path
`sync_claude_workspace`	`wsl({ direction: "wsl_to_windows" })`	Use `direction` param for workspace sync
`wsl_windows_status`	`wsl({ action: "status" })`	Combined integration status
`configure_autosync`	`wsl({ action: "autosync_config", enabled: true })`	Configuration mode
`get_autosync_config` / `autosync_status`	`wsl({ action: "autosync_status" })`	Status check

16. `server_info` (replaces 4 tools)

v3 Tool	How to call in v4	Notes
`get_help`	`server_info()` or `server_info({ action: "help" })`	Default action; use `topic` for specific help
`performance_stats`	`server_info({ action: "stats" })`	Includes edit telemetry
`get_edit_telemetry`	`server_info({ action: "stats" })`	Merged into stats
`capture_last_artifact`	`server_info({ action: "artifact", sub_action: "capture", content: "..." })`	Capture artifact
`artifact_info`	`server_info({ action: "artifact", sub_action: "info" })`	Show stored artifact

Key Concepts in v4

Auto-Deduction Pattern

Many unified tools auto-detect the intended action from which parameters you provide:

// backup examples:
backup()                                              // -> list all
backup({ action: "info", backup_id: "..." })          // -> show details
backup({ action: "compare", backup_id, file_path })   // -> compare
backup({ action: "cleanup" })                         // -> cleanup (dry-run)
backup({ action: "restore", backup_id: "..." })       // -> restore

// server_info examples:
server_info()                                         // -> help
server_info({ action: "stats" })                      // -> performance stats
server_info({ action: "artifact", sub_action: "capture", content: "code" })
server_info({ action: "artifact", sub_action: "write", path: "file.go" })

Auto-Routing Pattern

Tools with a mode or action parameter route to different engine functions:

// edit_file routing:
edit_file({ path, old_text, new_text })                           // -> default replace
edit_file({ path, old_text, new_text, occurrence: 1 })            // -> replace Nth
edit_file({ path, mode: "search_replace", pattern, replacement }) // -> recursive search & replace
edit_file({ path, mode: "regex", patterns_json: "[...]" })        // -> regex transform

// search_files routing:
search_files({ path, pattern })                                   // -> fast search (SmartSearch)
search_files({ path, pattern, case_sensitive: true })              // -> advanced text search
search_files({ path, pattern, count_only: true })                 // -> count occurrences

Intelligent I/O

read_file and write_file auto-select the optimal I/O strategy based on file size:

File Size	Strategy Selected
< 100 KB	Direct I/O (fastest)
100 KB — 500 KB	Streaming I/O
500 KB — 5 MB	Chunked processing
> 5 MB	Special handling with progress

You never need to choose between read_file and chunked_read_file — v4 handles it transparently.

Final Tool Inventory (v4.0.0)

#	Tool	Category	v3 tools absorbed
1	`read_file`	Core	`read_file`, `chunked_read_file`, `intelligent_read`, `read_file_range`, `read_base64`, `streaming_read_file`
2	`write_file`	Core	`write_file`, `create_file`, `streaming_write_file`, `intelligent_write`, `write_base64`
3	`edit_file`	Core	`edit_file`, `smart_edit_file`, `intelligent_edit`, `recovery_edit`, `search_and_replace`, `replace_nth_occurrence`, `regex_transform_file`
4	`list_directory`	Core	`list_directory`, `mcp_list`
5	`search_files`	Core	`smart_search`, `advanced_text_search`, `mcp_search`, `count_occurrences`
6	`analyze_operation`	Analysis	`analyze_file`, `get_optimization_suggestion`, `analyze_write`, `analyze_edit`, `analyze_delete`
7	`create_directory`	Files	`create_directory`
8	`delete_file`	Files	`delete_file`, `soft_delete_file`
9	`move_file`	Files	`move_file`, `rename_file`
10	`copy_file`	Files	`copy_file`
11	`get_file_info`	Files	`get_file_info`
12	`multi_edit`	Edit	`multi_edit`
13	`batch_operations`	Batch	`batch_operations`, `execute_pipeline`, `batch_rename_files`, `batch_file_operations`
14	`backup`	Recovery	`list_backups`, `get_backup_info`, `compare_with_backup`, `cleanup_backups`, `restore_backup`, `backup_create`
15	`wsl`	Integration	`wsl_to_windows_copy`, `windows_to_wsl_copy`, `sync_claude_workspace`, `wsl_windows_status`, `configure_autosync`, `autosync_status`
16	`server_info`	Utilities	`get_help`, `performance_stats`, `get_edit_telemetry`, `capture_last_artifact`, `artifact_info`

Migration from v3 to v4

Overview

Complete Migration Map

1. read_file (replaces 6 tools)

2. write_file (replaces 6 tools)

3. edit_file (replaces 8 tools)

4. list_directory (replaces 2 tools)

5. search_files (replaces 4 tools)

6. analyze_operation (replaces 5 tools)

7. create_directory (unchanged)

8. delete_file (replaces 2 tools)

9. move_file (replaces 2 tools)

10. copy_file (unchanged)

11. get_file_info (unchanged)

12. multi_edit (unchanged)

13. batch_operations (replaces 4 tools)

14. backup (replaces 6 tools)

15. wsl (replaces 6 tools)

16. server_info (replaces 4 tools)