Tool Selection Guide

This guide helps you choose the right tool from the 20 MCP tools (17 core + git + minify_js + help) available in Filesystem Ultra v4.5.x.

Quick Decision Tree

Reading Files

Do you need to read a file?
├── Full file → read_file
├── Specific line range → read_file with start_line + end_line
└── Binary/base64 → read_file with encoding:"base64"

Writing Files

Need to create or overwrite a file?
├── Text content → write_file
└── Binary/base64 → write_file with encoding:"base64" or content_base64

Editing Files

What kind of edit?
├── Single replacement → edit_file
├── Replace Nth occurrence → edit_file with occurrence:N
├── Regex-based transform → edit_file with mode:"regex"
├── Bulk replace across files → edit_file with mode:"search_replace"
└── Multiple replacements in one file → multi_edit

Searching

What are you looking for?
├── File name or content → search_files
├── Content with regex + context → search_files (with case_sensitive/whole_word/include_context)
├── Count occurrences only → search_files with count_only:true
└── Find and replace across files → edit_file with mode:"search_replace"

By Task Type

Reading and Viewing

Task	Tool	Why
Read any file	`read_file`	Auto-optimizes: direct for small, chunked for large
Read specific lines	`read_file` with `start_line` + `end_line`	Most token-efficient
Read first/last N lines	`read_file` with `mode` + `max_lines`	Tail logs, preview files
Read binary as base64	`read_file` with `encoding:"base64"`	Images, binaries

Editing and Modifying

Task	Tool	Why
Replace specific text	`edit_file`	Auto-backup, risk assessment, smart matching
Replace Nth occurrence	`edit_file` with `occurrence:N`	Precise control
Regex transformation	`edit_file` with `mode:"regex"`	Capture groups, advanced patterns
Bulk replace across files	`edit_file` with `mode:"search_replace"`	Recursive with file pattern filter
Multiple replacements	`multi_edit`	Atomic, single read/write cycle

Creating and Writing

Task	Tool	Why
Create or overwrite file	`write_file`	Auto-streams large content, creates dirs
Write binary from base64	`write_file` with `encoding:"base64"`	Images, binaries

Searching and Finding

Task	Tool	Why
Find files by name	`search_files`	Fast smart search
Find code in files	`search_files` with `include_content`	Content search
Regex with context lines	`search_files` with `include_context`	Advanced text search
Count matches	`search_files` with `count_only:true`	Quick count without reading

File Management

Task	Tool	Why
Rename file	`move_file`	Rename is a move within the same directory
Copy file	`copy_file`	Preserves permissions
Move file	`move_file`	Atomic move
Delete safely	`delete_file`	Soft-delete by default (recoverable)
Delete permanently	`delete_file` with `permanent: true`	Permanent
Get file info	`get_file_info`	Size, date, permissions

Directory Operations

Task	Tool	Why
List contents	`list_directory`	Fast, cached
Create directory	`create_directory`	Creates parents too

Backup and Recovery

Task	Tool	Why
View backups	`backup`	No params = list all
Backup details	`backup` with `backup_id`	Full info
Compare with backup	`backup` with `backup_id` + `file_path`	See differences
Clean old backups	`backup` with `action: "cleanup"`	Free space
Restore file	`backup` with `action:"restore"` + `backup_id`	Preview option with `preview: true`

Analysis and Planning

Task	Tool	Why
Analyze file	`analyze_operation` with `operation: "file"`	Size, type, strategy
Get optimization advice	`analyze_operation` with `operation: "optimize"`	Best approach
Preview edit impact	`analyze_operation` with `operation: "edit"`	Risk level
Preview write impact	`analyze_operation` with `operation: "write"`	Dry-run
Preview delete impact	`analyze_operation` with `operation: "delete"`	Impact analysis

WSL/Windows Integration

Task	Tool	Why
Copy between WSL/Windows	`wsl` with `action:"sync"` + `wsl_path` or `windows_path`	Auto-detects direction
Sync workspace	`wsl` with `action:"sync"` + `direction`	Bidirectional sync
Check status	`wsl` with `action:"status"`	Environment info
Configure auto-sync	`wsl` with `action:"autosync_config"` + `enabled`	Toggle sync

Batch Operations

Task	Tool	Why
Multiple operations	`batch_operations` with `request_json`	Atomic with rollback
Rename many files	`batch_operations` with `rename_json`	8 rename modes
Multi-step pipeline	`batch_operations` with `pipeline_json`	Chained steps with conditions

Server Utilities

Task	Tool	Why
Performance stats	`server_info` with `action:"stats"`	Cache hit rates, throughput
Get help	`server_info` with `action:"help"`	Tool documentation
Capture artifact	`server_info` with `action:"artifact"`	Save/retrieve artifacts

Common Scenarios

Scenario 1: Fix a Bug in a Large File

search_files(".", "buggy_function") — Find location
read_file("file.go", start_line: 100, end_line: 120) — Read only that section
edit_file("file.go", "old_code", "fixed_code") — Apply fix

Scenario 2: Rename a Variable Everywhere

search_files("file.go", "oldName", count_only: true) — Check count
analyze_operation("file.go", "edit", old_text: "oldName", new_text: "newName") — Preview
edit_file("file.go", "oldName", "newName") — Apply

Scenario 3: Create Multiple Files Atomically

batch_operations({
  request_json: JSON.stringify({
    operations: [
      { type: "write", path: "file1.go", content: "..." },
      { type: "write", path: "file2.go", content: "..." },
      { type: "create_dir", path: "new_folder" }
    ],
    atomic: true
  })
})

Scenario 4: Recover from Mistake

backup() — List recent backups
backup({ action: "compare", backup_id: "...", file_path: "..." }) — Compare
backup({ action: "restore", backup_id: "...", preview: true }) — Preview
backup({ action: "restore", backup_id: "..." }) — Restore

Scenario 5: Regex Refactor with Capture Groups

edit_file({
  path: "handler.go",
  mode: "regex",
  pattern: "fmt\\.Errorf\\(\"(\\w+): %v\", err\\)",
  replacement: "fmt.Errorf(\"$1: %w\", err)"
})

Scenario 6: Multi-Step Pipeline

batch_operations({
  pipeline_json: JSON.stringify({
    name: "refactor-todos",
    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" } }
    ]
  })
})

Performance Tips

Minimize Token Usage

Use search_files before reading large files — find the exact location first
Use read_file with start_line/end_line when you know the lines
Use edit_file instead of write_file for changes — sends only the diff
Use multi_edit for multiple changes in one file — single read/write cycle
Use batch_operations with pipeline_json for multi-step operations — reduces round-trip overhead

Use Auto-Optimization

The consolidated tools automatically choose the best strategy:

read_file — Direct read or chunked streaming based on file size
write_file — Direct write or streaming write based on content size
edit_file — Direct edit or line-by-line streaming based on file size

Use Caching

Directory listings are cached
Repeated reads of same file use cache
Use server_info with action:"stats" to check cache performance

Migration from v3 (59 tools) to v4 (20 tools)

Old Tool (v3)	New Tool (v4)	How
`mcp_read`	`read_file`	Same params
`mcp_write`	`write_file`	Same params
`mcp_edit`	`edit_file`	Same params
`mcp_search`	`search_files`	Same params
`mcp_list`	`list_directory`	Same params
`read_file_range`	`read_file`	Add `start_line` + `end_line`
`read_base64`	`read_file`	Add `encoding:"base64"`
`write_base64`	`write_file`	Add `encoding:"base64"`
`rename_file`	`move_file`	Same params (rename = move)
`search_and_replace`	`edit_file`	Add `mode:"search_replace"`
`replace_nth_occurrence`	`edit_file`	Add `occurrence:N`
`regex_transform_file`	`edit_file`	Add `mode:"regex"`
`count_occurrences`	`search_files`	Add `count_only:true`
`execute_pipeline`	`batch_operations`	Pass `pipeline_json` instead of `request_json`
`batch_rename_files`	`batch_operations`	Pass `rename_json` instead of `request_json`
`restore_backup`	`backup`	Add `action:"restore"`
`wsl_sync`	`wsl`	Add `action:"sync"`
`wsl_status`	`wsl`	Add `action:"status"`
`stats`	`server_info`	Add `action:"stats"`
`get_help`	`server_info`	Add `action:"help"`
`artifact`	`server_info`	Add `action:"artifact"`

Tool Categories Summary

Category	Count	Tools
Reading	1	`read_file`
Writing	1	`write_file`
Editing	3	`edit_file`, `multi_edit`, `project_replace`
Search	1	`search_files`
File Ops	4	`copy_file`, `move_file`, `delete_file`, `get_file_info`
Directory	2	`list_directory`, `create_directory`
Analysis	1	`analyze_operation`
Backup	1	`backup` (10 actions)
WSL	1	`wsl` (`sync`, `status`, `autosync_config`, `autosync_status`)
Batch / Pipeline	1	`batch_operations`
Utilities	1	`server_info`
Version Control	1	`git` (9 actions — v4.5.25+)
JavaScript	1	`minify_js` (v4.5.7+)
Discovery	1	`help`

Total: 20 tools (17 core + git + minify_js + help)