Tool Selection Guide

This guide helps you choose the right tool from the 17 core MCP tools available in Filesystem Ultra.

Claude Code Compatibility

For Claude Code compatibility, these aliases work identically to the core tools:

Alias	→ Core	Also Available
View	read_file	read_text_file
Edit	edit_file	edit
Write	write_file	write, create_file
Replace	write_file	write
LS	list_directory	directory_tree
GlobTool	search_files	search
GrepTool	search_files	search

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 cleanup: true	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" + source_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:"status" + 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

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

Scenario 2: Rename a Variable Everywhere

1. search_files("file.go", "oldName", count_only: true) — Check count
2. analyze_operation("file.go", "edit", old_text: "oldName", new_text: "newName") — Preview
3. 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

1. backup() — List recent backups
2. backup({ backup_id: "...", file_path: "..." }) — Compare
3. backup({ action: "restore", backup_id: "...", preview: true }) — Preview
4. 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

1. Use search_files before reading large files — find the exact location first
2. Use read_file with start_line/end_line when you know the lines
3. Use edit_file instead of write_file for changes — sends only the diff
4. Use multi_edit for multiple changes in one file — single read/write cycle
5. Use batch_operations with pipeline_json for multi-step operations — 4x token reduction

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 (98%+ hit rate)
• Repeated reads of same file use cache
• Use server_info with action:"stats" to check cache performance

---

Migration from v3 (59 tools) to v4 (16 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	2	edit_file, multi_edit
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
WSL	1	wsl
Batch	1	batch_operations
Utilities	1	server_info

Total: 17 core tools