Check if a newer version of mcp-file-tools is available. Returns current version, latest version, and update instructions if outdated. Uses a cached result (max 1 GitHub API call per 30 min); force=true bypasses the cache. Call once at the start of each session.

Convert files between encodings. Parameters: path (one file) OR paths (a batch — never both), to (required), from (omit to auto-detect), backup (write .bak first), dryRun (report only), allowLowConfidence, bom ("auto" default, "always", "never", "preserve"). Refuses rather than corrupting: a narrowing conversion (utf-8 to cp1251) names the characters the target lacks with line and column, and an untrusted detection names its best guess — confirm it with from, or pass allowLowConfidence=true. A source BOM is stripped before decoding; one contradicting an explicit from is an error. No-op if the file already holds the target bytes. In a batch one bad file does not stop the rest. Run dryRun over a project first. Examples: {"path": "D:\legacy\data.txt", "to": "utf-8", "backup": true} leaves data.txt.bak; {"paths": ["a.pas", "b.pas"], "to": "utf-8", "dryRun": true} previews a migration.

Copy a file. Fails if destination exists. Parameters: source (required), destination (required).

Create a directory recursively (mkdir -p). Succeeds silently if already exists. Parameter: path (required).

Delete a file. Does not delete directories. Parameter: path (required).

Auto-detect file encoding with confidence score (0-100) and BOM detection. ALWAYS use this first when encountering garbled text or � characters. Use before read_text_file to determine the correct encoding. Parameters: path (required), mode (sample=fast default, chunked=thorough, full=entire file). When the answer is in doubt — low confidence, or a charset this server cannot read — the result also ranks candidates; retry the read with a supported one and ask the user if two are plausible.

Edit one file with replacements or a unified diff. Returns a unified diff and keeps the file's encoding and line endings. PREFER THIS over read+write to modify a file. In 'ask before edits' mode call dryRun=true first, show the diff, then dryRun=false once the user confirms; with auto-edit permissions go straight to dryRun=false. On no match, prefer fixing oldText from the closest-content hint. Alternatively retry that edit with similarity (0.0-1.0) for whitespace/comment drift, not different code. Do NOT re-read the file afterwards to verify: a success with a diff means the edit is on disk, a failed edit changes nothing. Parameters: path; exactly one of edits [{oldText, newText, similarity?, replaceAll?}] or patch (---/+++/@@ unified diff for one file); dryRun (default false); encoding (auto). oldText must match ONE place: several matches fail with their line numbers and change nothing — add surrounding lines to pick one, or set replaceAll: true to change them all and report the count to the user. Edits apply in order. Matching ignores per-line leading/trailing whitespace and CRLF/LF, but interior spacing must match; newText is re-indented. Example: {"path": "D:\src\unit1.pas", "edits": [{"oldText": "i: Integer;", "newText": "i: NativeInt;"}, {"oldText": "for i := 0 to 10 do", "newText": "for i := 0 to 20 do"}], "dryRun": true}

Get file/directory metadata: size, timestamps, permissions, type. Use this to check file size before reading large files with read_text_file. Parameter: path (required).

Regex search in file contents with encoding support. PREFER THIS over built-in Grep for non-UTF-8 files. Skips .gitignore'd files (respectGitignore=false to include). Parameters: pattern (regex) or patterns (array), paths (array of files, or dirs searched recursively), caseSensitive (default true), contextBefore/After, maxMatches (default 1000), offset, include/includes, exclude/excludes, encoding. patterns finds ANY of several regexes in ONE pass — sweeping a codebase for a list of names is one call, not one per name. outputMode: "content" (default, matching lines), "files_with_matches" (paths only, far cheaper when you just need WHICH files), "count" (matching lines per file). contextBefore/After apply to content mode only. matchesOnly=true returns the matched substring instead of the whole line, for extracting values — with patterns it also tells you which one hit. offset skips the first N results, so you can page past maxMatches; the response echoes nextOffset when truncated. Include and exclude patterns are basename-only globs; {a,b} alternatives work and a leading **/ is ignored. Includes match any pattern and excludes reject any match. Do not combine a singular field with its plural. Example: {"patterns": ["TCustomer", "TOrder"], "paths": ["D:\proj\src"], "includes": [".pas", ".dfm"], "outputMode": "files_with_matches"}

Returns the list of directories this server is allowed to access. Subdirectories are also accessible. If empty, user needs to add directory paths as args in .mcp.json.

List files and directories with optional glob pattern filtering (e.g., *.pas, *.dfm). Parameters: path (required), pattern (optional, default: *), sortBy ("name" default, "mtime" newest first, "size" largest first), reverse (bool, flips the order).

List all 25 supported encodings with name, aliases, and description. Use this to find the correct encoding name for read/write/convert operations.

Detect, strip, or add Unicode BOM (Byte Order Mark). UTF-8 BOM breaks PHP/shell scripts; UTF-16 files need BOMs. Parameters: path (required), action (required: "detect"|"strip"|"add"), encoding (required for "add": utf-8, utf-16-le, utf-16-be, utf-32-le, utf-32-be).

Detect or fix line endings. action="detect" reports the dominant style (crlf/lf/mixed/none), total lines, and the line numbers that disagree — use it when a file looks inconsistent. action="convert" rewrites the file to style, per code unit for UTF-16 and preserving its BOM; no-op if the file already matches. Parameters: path, action ("detect"|"convert"), style ("lf"|"crlf", required for convert), encoding (auto-detected, including most BOM-less UTF-16 — pass utf-16-le/utf-16-be if a very short or unusual file is misread). Example: {"path": "D:\src\unit1.pas", "action": "convert", "style": "crlf"}

Move or rename files/directories. Fails if destination exists. Parameters: source (required), destination (required).

Read multiple files concurrently with encoding support. PREFER THIS when reading several non-UTF-8 files at once. Individual failures don't stop the batch — partial results are returned. Parameters: paths (required array), encoding (optional, auto-detected per file).

Read file with encoding auto-detection, converts to UTF-8. PREFER THIS over built-in Read for non-UTF-8 files (Cyrillic, legacy codebases). Returns totalLines and fileSizeBytes for planning the next read. Parameters: path, encoding (auto-detected), offset (1-indexed start line), limit (max lines), maxCharacters (caps output to avoid token overflow), lineNumbers (default false: prefix lines with "N", absolute numbers — use to locate lines reported by grep or encoding errors; STRIP the prefix before using text as edit_file oldText). Page files >2000 lines: {"path": "D:\src\app.pas", "offset": 1, "limit": 2000}, then offset 2001, until offset exceeds totalLines.

Recursively search for files matching a glob pattern (*.ext at any depth, /*.ext, several ** and {a,b} alternatives allowed). Returns full paths. Skips .gitignore'd files (respectGitignore=false to include). Parameters: path (required), pattern (required), excludePatterns, maxResults (default 10000), sortBy, reverse. sortBy: "name" (default, lexical), "mtime" (newest first) or "size" (largest first); reverse flips the order. Unlike the built-in Glob there is no mtime default — pass sortBy "mtime" for newest first. With mtime or size the whole tree is ranked before the cap, so a truncated result really is the newest/largest maxResults files. Example: {"path": "D:\proj", "pattern": "/*.pas", "sortBy": "mtime"}

Compact indented tree view of directory structure. PREFER THIS for directory visualization. Skips .gitignore'd files and .git (respectGitignore=false to include). Set showEncoding=true to detect and display file encodings (e.g., for auditing legacy codebases). Parameters: path (required), maxDepth (0=unlimited), maxFiles (default 1000), dirsOnly (bool), exclude (array of patterns), showEncoding (bool, shows detected encoding per file).

Write file with encoding conversion from UTF-8. PREFER THIS over built-in Write for non-UTF-8 files. Use after read_text_file to keep the original encoding. Parameters: path, content, encoding (default: the existing file's detected encoding, else utf-8), bom, lineEndings. bom: "auto" (default) writes a BOM for utf-16-* targets, else keeps one only if the file already had a BOM of the same encoding; "preserve" keeps it even when the encoding changed; "never" strips it; "always" fails on encodings with no BOM (e.g. cp1251). lineEndings: "preserve" (default) converts content to the file's existing style, so sending LF into a CRLF file will NOT leave it mixed; also "crlf", "lf", "asis" (byte for byte). Example — strip a UTF-8 BOM that breaks PHP: {"path": "D:\www\index.php", "content": "<?php ...", "bom": "never"}