Claude Instructions

MCP Filesystem Ultra — Instructions for AI Agents

This document is designed to be included in AI agent system prompts or context. Copy this entire content to your AI’s custom instructions or memory.

You can also call get_help() at runtime to retrieve this information dynamically.

---

Important: Ask Before Searching

Before running search_files, ask the user if they know the file location:

Inefficient: "Let me search where X is..." [automatic search]
Efficient:   "Do you know what file/line X is in? If not, I can search for it."

Only search when:

• The user says they don’t know the location
• The user explicitly requests “find X” or “search for X”
• The user clearly does not have the information

Skipping unnecessary searches saves approximately 90% of tokens in cases where the user already knows the location.

For more detail, see guides/PREVENT_UNNECESSARY_SEARCHES.md.

---

Self-Documentation: get_help() Tool

Instead of reading through all documentation, call get_help at runtime:

get_help("overview")  → Quick start guide
get_help("workflow")  → The 4-step efficient workflow
get_help("tools")     → Complete list of tools
get_help("edit")      → Editing files
get_help("errors")    → Common errors and fixes
get_help("examples")  → Practical code examples
get_help("tips")      → Efficiency tips

---

Use MCP Tools, Not Native File Tools

When mcp-filesystem-ultra tools are available, always prefer them over native file operations:

Use MCP tools:

read_file, write_file, edit_file, list_directory, search_files

Avoid native file operations:

• Native file reading tools
• Direct WSL commands for file operations
• Any tool that does not handle /mnt/c/ ↔ C:\ conversion

MCP tools automatically convert paths between WSL and Windows formats.

---

Key Principle: Surgical Edits

Inefficient — avoid this:

read_file(entire_large_file) → write_file(entire_large_file)
5000-line file = 250,000+ tokens

Efficient — prefer this:

search_files(file, pattern) → read_file(file, start_line, end_line) → edit_file(old, new)
5000-line file = approximately 2,000 tokens

---

Complete Tool List (v4 — 16 tools)

Core Tools

Tool	Description
read_file	Read file (auto-optimizes for size, supports start_line/end_line)
write_file	Atomic write with auto path conversion
edit_file	Smart edit with backup, recovery, and path conversion (supports mode:"search_replace")
list_directory	Cached directory listing
search_files	File/content search (supports count_only:true)

Edit Tools

Tool	When to Use
edit_file	Preferred — surgical text replacement
multi_edit	Multiple edits in one atomic operation
regex_transform_file	Advanced regex transformations with capture groups

File Operations

Tool	When to Use
copy_file	Duplicate file/directory
move_file	Move or rename files
delete_file	Delete (soft-delete by default, permanent:true for hard delete)
get_file_info	File metadata (size, date, etc.)
create_directory	Create directory (with parents)

Analysis and Monitoring

Tool	When to Use
analyze_operation	File analysis, dry-run write/edit/delete, optimization suggestions
server_info	Server performance (action: “stats”)

Batch and Backup

Tool	When to Use
batch_operations	Multiple operations atomically (also supports pipeline_json)
backup	List, restore, compare, cleanup backups

WSL Integration

Tool	When to Use
wsl	Copy files between WSL/Windows, check status, configure auto-sync

Utilities

Tool	When to Use
server_info	Help, performance stats, artifact capture

---

Efficient Workflow

For any file edit, follow this sequence:

Step 1: Locate

search_files(file, "function_name")
→ Returns: "Found at lines 45-67"

Step 2: Read Only What You Need

read_file(file, start_line=45, end_line=67)
→ Returns: Only those 22 lines

Step 3: Edit Surgically

edit_file(file, "old_text", "new_text")
→ Returns: "OK: 1 changes"

Step 4: Verify (Optional)

server_info({ action: "stats" })
→ Goal: more than 80% targeted edits

---

File Size Decision Tree

Is file fewer than 1000 lines?
├── YES → read_file() is acceptable
└── NO  → use search_files + read_file(start_line, end_line) + edit_file

Is file more than 5000 lines?
├── NO  → standard workflow is fine
└── YES → never read the entire file

---

Common Errors

”context validation failed”

Cause: File changed since it was last read. Fix: Re-run search_files() + read_file() with start_line/end_line to get current content.

”no match found”

Cause: Text does not exist exactly as specified. Fix:

1. Use search_files() to verify the location.
2. Check for whitespace or indentation differences.
3. Use search_files() with count_only:true to confirm the text exists.

”multiple matches found”

Cause: Same text appears more than once. Fix: Use edit_file with mode:"search_replace" and occurrence parameter

• 1 = first, 2 = second, -1 = last, -2 = second-to-last

”Tool not found: create_file”

Cause: create_file was previously an alias. Fix: Use write_file() — it creates files if they do not exist.

Path errors with /mnt/c/ or C:\

Cause: Path format mismatch. Fix: Use MCP tools — they convert paths automatically. Use read_file, write_file, etc.

---

Quick Reference

Task	Tool
Read a file	read_file
Read specific lines	read_file with start_line/end_line (recommended)
Create a new file	write_file
Edit text in a file	edit_file (recommended)
Make multiple edits	multi_edit (recommended)
Find where code is	search_files
Count occurrences	search_files with count_only:true
List directory	list_directory
Copy or move files	copy_file, move_file
Delete safely	delete_file (soft-delete by default)
Multiple operations	batch_operations
Check efficiency	server_info with action “stats”

---

Token Efficiency Examples

Example 1: Edit a function in a 5000-line file

Inefficient approach (~250,000 tokens):

read_file("large.py")        # 125,000 tokens
# ... process ...
write_file("large.py", all)  # 125,000 tokens

Efficient approach (~2,500 tokens):

search_files("large.py", "def my_function")              # 500 tokens
read_file("large.py", start_line=234, end_line=256)      # 1,000 tokens
edit_file("large.py", "old", "new")                      # 500 tokens

Example 2: Multiple edits in one file

Inefficient — 5 separate edit_file calls:

edit_file(path, old1, new1)  # Read → Edit → Write
edit_file(path, old2, new2)  # Read → Edit → Write (again)
edit_file(path, old3, new3)  # Read → Edit → Write (again)
...

Efficient — 1 multi_edit call:

multi_edit(path, [
  {"old_text": "old1", "new_text": "new1"},
  {"old_text": "old2", "new_text": "new2"},
  {"old_text": "old3", "new_text": "new3"}
])
# File read once, all edits applied, written once

---

Path Handling

All MCP tools handle path conversion automatically:

You provide	Tool converts to
/mnt/c/Users/John/file.txt	C:\Users\John\file.txt (on Windows)
C:\Users\John\file.txt	/mnt/c/Users/John/file.txt (on WSL)

---

Summary

1. Prefer MCP filesystem tools over native file operations.
2. Do not read entire large files — use read_file with start_line/end_line.
3. Use edit_file instead of write_file for modifications.
4. Use multi_edit for multiple changes in one file.
5. Run search_files first to find exact locations.
6. Check server_info with action “stats” to monitor efficiency.

---

Version: 3.13.2 | Last Updated: February 2026