Core Tools

MCP Filesystem Ultra v4.5.29 provides 20 tools (17 core + git + minify_js + help). 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. Risk level never blocks — CRITICAL edits include a VERIFY instruction. The accidental-rewrite guard and --auto-occ=block can block independently. Auto-converts WSL/Windows paths.

Since v4.5.10, an accidental-rewrite guard is active: when new_text is more than 2× the size of old_text, the file has substantial content outside the match (>50%), AND new_text is large (>500 B and >50% of file), the call is BLOCKED with a clear error suggesting write_file. Pass allow_rewrite: true to override (creates a safety backup). The force flag does not bypass the rewrite guard as of v4.5.14 — allow_rewrite is the only override.

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)
expected_hash	No	string	OCC token (FNV-1a from a prior read_file StructuredContent). If the file content hash on disk differs, the edit is rejected with a stale edit: error (v4.5.6+; structured since v4.5.13).
start_line	No	number	For delete_range / replace_range: 1-indexed first line (v4.5.14 / v4.5.16).
end_line	No	number	For delete_range / replace_range: inclusive 1-indexed last line (v4.5.14 / v4.5.16).
tolerant_whitespace	No	boolean	Treat one tab as 4 spaces and CRLF/CR as LF in the matcher (v4.5.7).
diff_format	No	string	"auto", "full", "summary", "stat", "none" (v4.5.14).
allow_rewrite	No	boolean	Bypass the accidental-rewrite guard (v4.5.10, decoupled from force in v4.5.14).

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.
delete_range (v4.5.14)	Removes lines [start_line, end_line] (1-indexed, inclusive). Atomic with backup. No text match needed.
replace_range (v4.5.16)	Line-numbered partner of delete_range: replaces lines [start_line, end_line] with new_text. Reuses the byte-exact splice from delete_range.

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)
output_format	No	string	Response format: "compact" (default, one-liner), "json" (structured {path, total, truncated, entries:[{name,type,size,modified}]}), "tree" (recursive JSON tree, pairs with max_depth). Added in v4.5.25.
max_depth	No	number	Recursion depth for output_format:"tree" (default 2). Added in v4.5.25.

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). Since v4.5.24 it is auto-enabled when path is a regular file or when content-only params are passed.
include	No	string	Alias for file_types (added v4.5.x).
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). Accepts bool too (v4.5.3).
output_format	No	string	"text" (default) or "json" — structured matches with {pattern, path, total_matches, matches:[...]}.
output	No	string	Alias for output_format.

Auto-routing (v4.5.24 false-negative fix): By default search_files is filename-only (SmartSearch). Content search (include_content: true → AdvancedTextSearch) is forced in two cases:

1. path resolves to a regular file (not a directory) — a filename match on a single explicit file is meaningless.
2. Any of these params is passed: output_format, output, context_lines.

When the search returns zero hits and content was not searched, the response says: No filename matches for pattern 'X' in <path> (filename-only search — file contents were NOT searched; pass include_content:true to search inside files).

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. Risk level never blocks — CRITICAL edits include a VERIFY instruction. The accidental-rewrite guard and --auto-occ=block can block independently.

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)
expected_hash	No	string	OCC token (FNV-1a from a prior read_file). Same semantics as edit_file’s expected_hash (v4.5.13).
diff_format	No	string	Diff rendering: "auto" (default — full for small batches, summary for large), "full", "summary", "stat", "none". Aggregate one diff across the batch (v4.5.25).
dry_run	No	boolean	Preview without applying (v4.5.25).
tolerant_whitespace	No	boolean	Treat one tab as 4 spaces and CRLF/CR as LF in the matcher (v4.5.7).

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. project_replace

Project-wide find/replace in a single call. Replaces N calls to multi_edit with 1. Scans directory tree, matches pattern, replaces all occurrences. Creates single consolidated backup.

Annotations:

Annotation	Value
readOnly	false
destructive	true
idempotent	false

Parameters:

Parameter	Required	Type	Description
path	Yes	string	Root directory to scan (WSL or Windows format)
find	Yes	string	Text or regex pattern to find
replace	Yes	string	Replacement text
literal	No	bool	If false, find is regex (default: true)
case_sensitive	No	bool	Case sensitive matching (default: true)
file_types	No	string	Comma-separated extensions (“.php,.html”)
include_paths	No	string	JSON array of glob patterns to include
exclude_paths	No	string	JSON array of glob patterns to exclude
preview	No	bool	Diff without writing (default: false)
create_backup	No	bool	Single consolidated backup (default: true)
parallel	No	bool	Process files concurrently (default: true)
max_files	No	number	Safety cap (default: 1000)

Response:

{
  "files_changed": 45,
  "total_replacements": 230,
  "backup_id": "20260520-...",
  "risk_level": "MEDIUM",
  "per_file": [
    {"path": "src/main.php", "replacements": 12},
    {"path": "src/utils.php", "replacements": 5}
  ]
}

Example — Replace across PHP files, excluding vendor:

project_replace({
  path: "C:\\project\\public_html",
  find: "utf8_encode(",
  replace: "utf8e(",
  file_types: ".php",
  exclude_paths: JSON.stringify(["jotajotape/**", "vendor/**"]),
  preview: false
})

Example — Regex find/replace:

project_replace({
  path: "src/",
  find: "item_(\\d+)",
  replace: "obj_$1",
  literal: false,
  file_types: ".go,.ts"
})

Example — Preview only (dry-run):

project_replace({
  path: "src/",
  find: "TODO",
  replace: "DONE",
  preview: true
})

---

14. 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, search_and_replace, copy, move, delete, create_dir, extract

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
  })
})

---

15. 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: see Action routing below (10 values).
backup_id	No	string	Backup ID (required for info, compare, restore)
sd_id	No	string	SD-ID for trash actions (restore_trash, purge_trash) (v4.5.11).
file_path	No	string	File path for compare, selective restore, or undo_last step-through (v4.3.8).
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 / purge_trash: age threshold in days
dry_run	No	boolean	Preview without executing (cleanup, restore, purge_trash)
preview	No	boolean	For undo_last: show what would be undone without applying

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	older_than_days?	Delete old backups; pass dry_run:true for preview (default dry_run:true)
restore	backup_id	Restore file(s) from a backup (atomic). Pass dry_run:true / preview:true.
undo_last	(optional file_path)	Step-through one backup in the chain. Without file_path, undoes the most recent. With file_path, walks the chain for that file; pass preview:true to peek. (v4.3.8)
undo_chain	file_path	Show the full chain of backups for a file (v4.3.8)
list_trash	(none)	List soft-deleted files (sd_id, original path). Added v4.5.11.
restore_trash	sd_id	Move a soft-deleted file back to its original path. Added v4.5.11.
purge_trash	(none; optional older_than_days / sd_id)	Permanently delete trash entries. Added v4.5.11.

Soft-delete integration (v4.5.11+): delete_file without permanent:true stores files under <backup-dir>/filesdelete/<sd-id>/<basename> with a metadata.json sidecar when --backup-dir is configured. The SD-ID is returned in the delete_file response so the trash actions above can find it. Requires --backup-dir.

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" })

// Step-through undo (file_path is the chain key)
backup({ action: "undo_last", file_path: "main.go", preview: true })
backup({ action: "undo_last", file_path: "main.go" })

// Show the entire undo chain for a file
backup({ action: "undo_chain", file_path: "main.go" })

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

// Trash workflows (v4.5.11)
backup({ action: "list_trash" })
backup({ action: "restore_trash", sd_id: "sd-..." })
backup({ action: "purge_trash", older_than_days: 30, dry_run: true })

---

16. wsl

WSL/Windows file integration. Sync files between WSL and Windows, or check integration status.

Auto-sync (write/edit-time syncing) is configured via the MCP_WSL_AUTOSYNC environment variable or the deprecated autosync_config/autosync_status params — not as wsl actions. The wsl tool itself only exposes sync and status.

Replaces: wsl_sync, wsl_status (configure_autosync/autosync_status were v3 tools — now env-var driven).

Annotations:

Annotation	Value
readOnly	false
destructive	false
idempotent	true

Parameters:

Parameter	Required	Type	Description
action	No	string	Action: sync (default) or status. The legacy autosync_config / autosync_status actions are not dispatched.
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	(Legacy auto-sync param — no longer dispatched. Use the MCP_WSL_AUTOSYNC env var.)
sync_on_write	No	boolean	(Legacy auto-sync param)
sync_on_edit	No	boolean	(Legacy auto-sync param)
silent	No	boolean	(Legacy auto-sync param)

Action routing:

Action	Description
sync (default)	Copy files between WSL and Windows. Auto-detects direction from path format.
status	Show WSL/Windows integration 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 })

---

17. 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" })

---

18. git

Built-in git version control inside repositories. Calls git directly via a hardened command constructor (no shell). 9 actions since v4.5.25: init, status, diff, log, show, add, commit, restore, branch. paths is a native array; rev is the revision/range parameter; output is an action-specific enum. See Git Tools for the full reference.

Annotations:

Annotation	Value
readOnly	false
destructive	true (restore, branch delete)
idempotent	false

---

19. minify_js

Pure-Go JavaScript minifier — no Node, no external tools, no API calls. Strips // and /* */ comments, collapses whitespace, optionally joins onto a single line, while preserving string / template / regex literals.

Annotations:

Annotation	Value
readOnly	false
destructive	true (overwrites the file; auto-creates a backup before destructive mode by default)
idempotent	true (idempotent on already-minified content)

Parameters:

Parameter	Required	Type	Description
path	Yes	string	Path to the JS file to minify (overwritten in place)
output_path	No	string	Write to a different file instead of overwriting
remove_comments	No	boolean	Strip // and /* */ comments (default: true)
collapse_whitespace	No	boolean	Collapse runs of whitespace (default: true)
single_line	No	boolean	Join everything onto a single line (default: true)
dry_run	No	boolean	Preview reductions without writing (default: false)
create_backup	No	boolean	Backup before overwriting (default: true when not dry_run)

Examples:

// Dry run
minify_js({ path: "app.js", dry_run: true })
// → "MINIFY (dry-run) app.js | 87342→31045B (-56297, 64.4%) | comments:42"

// Live minify
minify_js({ path: "app.js" })
// → file overwritten; UNDO:20260607-xxxxx is the backup ID

See the dedicated page under Minify JS.

---

20. help

Discovery tool — call first to list all 20 tools (17 core + git + minify_js + help) with their parameters and short descriptions. No parameters.

Annotations:

Annotation	Value
readOnly	true
destructive	false
idempotent	true

For topic-specific help (e.g. recovery workflow, hooks example), call server_info({action: "help", topic: "..."}) — see Server Info help topics.

---

Structured Output (v4.5.26+)

Since v4.5.26, read_file, write_file, edit_file, and multi_edit publish an MCP outputSchema and return a typed structuredContent payload alongside the byte-identical text fallback. The text response is unchanged — Claude and other agents that read Content[0].Text keep working. New clients that read structuredContent get a JSON object instead of having to parse the human-readable text.

Quick reference (full schemas and worked example: Structured Output):

Tool	structuredContent shape
read_file	{content, content_hash?} (content_hash absent on multi-file reads)
write_file	{path, bytes_written, content_hash, message, [backup_id], [feedback]}
edit_file	{path, replacements, lines_added, lines_removed, total_lines, content_hash, message, [backup_id], [parent_backup_id], [risk_warning], [structure_warning], [integrity], [external_change]}
multi_edit	{path, successful_edits, total_edits, lines_added, lines_removed, total_lines, content_hash, message, [backup_id], [parent_backup_id], [risk_warning], [structure_warning], [integrity]}

Two practical consequences:

• content_hash from write_file can now be chained directly into edit_file.expected_hash without re-reading — fixes a long-standing false-positive external_change warning in the write→edit pattern (the session was missing RecordWriteHash until v4.5.26).
• parent_backup_id on edit_file / multi_edit lets an agent walk the undo chain (backup(action:"undo_last", file_path:...)) without scraping the chain: segment from the text.

---

Tool Count 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 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 (10 actions: list, info, compare, cleanup, restore, undo_last, undo_chain, list_trash, restore_trash, purge_trash)
WSL	1	wsl (sync, status, autosync_config, autosync_status)
Server	1	server_info
Version Control	1	git (9 actions)
JavaScript	1	minify_js
Discovery	1	help

Total: 20 tools (17 core + git + minify_js + help, consolidated from 59 in v3.x)

---

See Also

• Structured Output — outputSchema + structuredContent on the 4 I/O core tools (v4.5.26+)
• Tool Selection Guide — Which tool for your task
• Backup Tools — Detailed backup usage
• WSL Tools — WSL integration details
• Git Tools — Git version control reference
• Pipeline Tools — Pipeline reference
• Migration from v3 — Upgrading from 59 to 17 core tools (20 tools today)