io.github.dimitar-grigorov/mcp-file-tools

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

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

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.

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.

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

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

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<tab>\", absolute numbers — use to locate lines reported by grep or encoding errors; STRIP the prefix before using text as edit_file oldText).

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

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.

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.

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

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\").

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.

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

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

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

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

Copy one file byte for byte, keeping its encoding, BOM, line endings, permissions and mtime. Use it to back up a file before an edit or a conversion. Parameters: source (required), destination (required).

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

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.