mcp-fs-shell-windows 0.2.7 → 0.2.19

package/README.md

@@ -12,14 +12,14 @@ Heavily extended fork of [fabienvauchelles/mcp-filesystem-extended](https://gith
 |---|---|
 | Official base | `@modelcontextprotocol/server-filesystem` (Anthropic, PBC; MIT) |
 | Base fork | [fabienvauchelles/mcp-filesystem-extended](https://github.com/fabienvauchelles/mcp-filesystem-extended) @ `b6c317a` (MIT) |
-| This fork | v0.2.1 tool parity + `transfer_files` rename, robustness patches, 8 shell tools (v0.2.2), verbatim argv (v0.2.4), `launch_file` launcher (v0.2.7) — see [Differences](#differences-from-the-base-fork) |
+| This fork | v0.2.1 tool parity + `transfer_files` rename, robustness patches, 8 shell tools (v0.2.2), verbatim argv (v0.2.4), `launch_file` launcher (v0.2.7), raw-byte access + `dir_diff` + text encodings (v0.2.9–v0.2.11), `wait_for_file` (v0.2.12), `replace_regex` (v0.2.14), reparse-point & long-path hardening (v0.2.15–v0.2.16), Recycle-Bin deletes (v0.2.17), `create_link` (v0.2.18) — see [Differences](#differences-from-the-base-fork) |
 
 ## Features
 
-- **23 filesystem tools** — batched read/write/append/delete, move/copy, line-number patching, search (name / glob / regex / fuzzy), tree, counts, checksums, diffs, exact-match text editing. Confined to the allowed directories passed on the command line.
+- **30 filesystem tools** — batched read/write/append/delete (including raw-byte access, per-file text encodings, Recycle-Bin deletes, and link creation), move/copy, line-number patching, search (name / glob / regex / fuzzy / wait-for-file), in-place regex replacement, tree, counts, checksums, file and directory diffs, exact-match text editing. Confined to the allowed directories passed on the command line.
 - **8 shell tools** — synchronous, background, and interactive command execution implemented *inside the MCP server process*: no client-side permission toggles, survives client restarts, works with any MCP client.
 - **1 launcher tool** (`launch_file`, Windows-only) — opens files, folders, and http(s) links in their OS default app, fully detached: returns the moment the opener is spawned (never waits for the app), no console window, no stdio inheritance; filesystem targets are confined to the allowed directories.
-- **Windows-first** — drive roots, UNC roots, `cmd.exe /d /c` with verbatim argv, whole-process-tree kills (`taskkill /T /F`), detached interactive console windows.
+- **Windows-first** — drive roots, UNC roots, long paths beyond the 260-char `MAX_PATH` limit, `cmd.exe /d /c` with verbatim argv, whole-process-tree kills (`taskkill /T /F`), detached interactive console windows.
 - **NAS-safe startup** — an allowed directory that is missing or offline (e.g., a powered-down network share) logs a warning and the server continues instead of exiting.
 
 ## Requirements
@@ -65,22 +65,22 @@ node dist\index.js <allowed-dir> [more-dirs...]
 
 Then point your MCP config at `node <path-to-repo>\dist\index.js` with the allowed directories as the remaining args (same shape as the npx example above).
 
-### Filesystem tools (23)
+### Filesystem tools (30)
 
 | Tool | Purpose |
 |---|---|
-| `read_files` | Read one or more files, line-numbered; `offset`/`limit` paging |
-| `write_new_files` | Create files (per-file `overwrite`, optional `base64` encoding) |
+| `read_files` | Read one or more files, line-numbered; `offset`/`limit` paging; per-file `encoding` (utf8/utf16le/utf16be/cp1252, auto-detected when omitted) |
+| `write_new_files` | Create files (per-file `overwrite`, `textEncoding` utf8/utf16le/utf16be/cp1252, optional `base64` for binary) |
 | `append_files` | Append to files (creates them if missing) |
-| `delete_files` | Delete files/directories (`recursive`) |
+| `delete_files` | Delete files/directories (`recursive`; junctions/symlinks are removed as links, never followed; `toRecycleBin` - Windows: send to Recycle Bin instead of permanent delete) |
 | `copy_file` | Copy files/directories (`recursive`, `overwrite`) |
 | `transfer_files` | Move/rename items (`overwrite`, creates parent dirs) |
 | `patch_files` | Patch by line ranges (`replace`/`insertBefore`/`delete`, `dryRun`, git-diff output) |
 | `create_directories` | Create directory paths (nested chains) |
-| `list_directory` | Single-level listing (sizes, pagination, type filter, ignore globs) |
-| `directory_tree` | Recursive tree view (JSON) with exclusion patterns |
+| `list_directory` | Single-level listing ([FILE]/[DIR]/[LINK] prefixes, sizes, pagination, type filter, ignore globs) |
+| `directory_tree` | Recursive tree view (JSON) with exclusion patterns; includes empty dirs and link nodes |
 | `search_files` | Recursive case-insensitive name-substring search |
-| `search_regex` | Content grep over a single file or directory tree (paged) |
+| `search_regex` | Content grep over a single file or directory tree (paged; total + per-file match counts, `countOnly` mode) |
 | `search_glob` | Glob-based file search (e.g. `**/*.ts`, paged) |
 | `fuzzy_find_files` | Typo-tolerant name/path search (Levenshtein) |
 | `delete_files_by_pattern` | Regex delete within a single directory |
@@ -89,8 +89,15 @@ Then point your MCP config at `node <path-to-repo>\dist\index.js` with the allow
 | `content_diff` | Unified diff of two strings |
 | `checksum_files` | md5/sha1/sha256/sha512 for files |
 | `checksum_files_verif` | Verify files against expected hashes |
-| `get_file_info` | Size, timestamps, type, permissions |
-| `edit_files` | Exact-match text replacement, EOL-tolerant |
+| `get_file_info` | Size, timestamps, type, permissions, `isReparsePoint`, (Windows) NTFS attributes |
+| `edit_files` | Exact-match text replacement, EOL-tolerant (dominant line ending preserved) |
+| `read_bytes` | Read raw bytes at (offset, length) as base64 JSON — any binary file, any size |
+| `write_bytes` | Write raw bytes (base64) into an existing file at an offset — in place, or `extend` past EOF (gap zero-filled) |
+| `replace_regex` | In-place regex replacement across one or more files; `dryRun` defaults to true (unified-diff preview); preserves dominant line endings |
+| `dir_diff` | Recursive two-directory comparison (added/removed/changed/identical; unified diff for changed text files; `ignore` globs, `maxFiles` cap) |
+| `convert_encoding` | Convert a file's text encoding (utf8/utf16le/utf16be/cp1252, source auto-detected) to a new file |
+| `wait_for_file` | Poll until at least one file matching a glob appears under a directory (configurable timeout/interval) |
+| `create_link` | Create a hardlink, directory junction, or file/directory symlink to an existing target (`auto`/`symlink`/`junction`/`hardlink`) |
 | `list_allowed_directories` | List the allowed root directories |
 
 ### Shell tools (8, Windows-only)
@@ -149,6 +156,28 @@ The filesystem tools work in the image; the shell tools require a Windows host w
 
 **v0.2.7 — `launch_file`:** the detached OS launcher (see above). Renamed from a local `open_file` prototype so it cannot collide with other servers' `open_file` tools. Hardened: spawn-failure returns an error (the handler awaits the child's `spawn`/`error` events — it never reports success for a process Windows refused to create), URLs are restricted to http(s) so `file:` URIs cannot bypass the allowed-root policy, and non-Windows platforms fail with a clear error.
 
+**v0.2.8 — line-ending preservation:** `patch_files` and `edit_files` preserve the file's dominant line ending (CRLF or LF) on write.
+
+**v0.2.9 — `read_bytes` / `write_bytes`:** raw binary access at (offset, length) — base64 reads from any part of a file (any size, e.g. GGUFs and blobs) and in-place byte writes into existing files (`extend: true` grows the file past EOF, zero-filling the gap).
+
+**v0.2.10 — `dir_diff`:** recursive comparison of two directory trees — added/removed/changed/identical, unified diffs for changed text files, `ignore` glob patterns, and a `maxFiles` cap.
+
+**v0.2.11 — text encoding support:** per-file `encoding` in `read_files` (utf8/utf16le/utf16be/cp1252, auto-detected from BOMs when omitted), `textEncoding` in `write_new_files`, and `convert_encoding` to transcode a file into a new encoding.
+
+**v0.2.12 — `wait_for_file`:** polling file watcher — waits (up to `timeoutMs`, default 30 s, max 300 s) until at least one file matching a glob appears under a directory.
+
+**v0.2.13 — `search_regex` match totals:** every pattern occurrence is counted (a line matching N times counts N); responses end with the total and per-file counts, and `countOnly: true` returns counts without the matching line text.
+
+**v0.2.14 — `replace_regex`:** in-place regex replacement across one or more files (directories are rejected). `dryRun` defaults to `true` with a unified-diff preview; applied replacements preserve each file's dominant line ending; a missing path or invalid regex errors without writing anything.
+
+**v0.2.15 — reparse-point safety:** junctions/symlinks are never followed. `delete_files` removes them as links (including nested links inside recursive deletes) without touching their targets; `list_directory` shows `[LINK]` entries; `directory_tree` reports link nodes and includes empty directories; `get_file_info` adds `isReparsePoint` and (on Windows) NTFS attributes.
+
+**v0.2.16 — long-path support:** paths beyond the 260-char `MAX_PATH` limit work on Windows via `\\?\` extended-length form (drive and UNC), transparent to callers.
+
+**v0.2.17 — `delete_files` `toRecycleBin`:** send deletes to the Windows Recycle Bin instead of permanent removal. Reparse points are still removed as links (the bin cannot hold them), and any path that cannot be recycled is reported as an error — never silently hard-deleted.
+
+**v0.2.18 — `create_link`:** create hardlinks, directory junctions, and file/directory symlinks (`type: auto | symlink | junction | hardlink`) with strict checks: the target must exist, the link path must not, and the link path's parent must exist.
+
 ## Security
 
 - The filesystem tools are confined to the allowed directories passed at startup (and their subtrees).

package/dist/append_files/handler.js

@@ -1,6 +1,6 @@
 import fs from "fs/promises";
 import path from "path";
-import { validatePath, ensureDirectoryExists } from "../helpers/path.js";
+import { validatePath, ensureDirectoryExists, stripLongPathAll } from "../helpers/path.js";
 export async function handleAppendFiles(files, allowedDirectories) {
     const results = [];
     const errors = [];
@@ -15,7 +15,7 @@ export async function handleAppendFiles(files, allowedDirectories) {
             results.push(`Successfully appended to ${file.path}`);
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorMessage = stripLongPathAll(error instanceof Error ? error.message : String(error));
             errors.push(`Failed to append to file ${file.path}: ${errorMessage}`);
         }
     }));

package/dist/checksum_files/handler.js

@@ -1,4 +1,4 @@
-import { validatePath } from "../helpers/path.js";
+import { validatePath, stripLongPathAll } from "../helpers/path.js";
 import { calculateFileHash } from "../helpers/checksum.js";
 export async function handleChecksumFiles(filePaths, algorithm, allowedDirectories) {
     const results = [];
@@ -12,7 +12,7 @@ export async function handleChecksumFiles(filePaths, algorithm, allowedDirectori
             results.push({ path: filePath, hash });
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorMessage = stripLongPathAll(error instanceof Error ? error.message : String(error));
             errors.push({ path: filePath, error: errorMessage });
         }
     }));

package/dist/checksum_files_verif/handler.js

@@ -1,4 +1,4 @@
-import { validatePath } from "../helpers/path.js";
+import { validatePath, stripLongPathAll } from "../helpers/path.js";
 import { calculateFileHash } from "../helpers/checksum.js";
 import { validateHash } from "./helpers.js";
 export async function handleChecksumFilesVerif(files, algorithm, allowedDirectories) {
@@ -20,7 +20,7 @@ export async function handleChecksumFilesVerif(files, algorithm, allowedDirector
             });
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorMessage = stripLongPathAll(error instanceof Error ? error.message : String(error));
             errors.push({
                 path: file.path,
                 expectedHash: file.expectedHash,

package/dist/convert_encoding/handler.js

@@ -0,0 +1,40 @@
+import fs from "fs/promises";
+import path from "path";
+import { validatePath, ensureDirectoryExists } from "../helpers/path.js";
+import { decodeText, detectEncoding, encodeText, } from "../helpers/encoding.js";
+export async function handleConvertEncoding(filePath, to, from, outPath, overwrite, allowedDirectories) {
+    const validPath = await validatePath(filePath, allowedDirectories);
+    const validOutPath = await validatePath(outPath, allowedDirectories);
+    if (path.normalize(validPath) === path.normalize(validOutPath)) {
+        throw new Error("outPath must differ from path");
+    }
+    // Check that outPath does not already exist (unless overwrite).
+    if (!overwrite) {
+        try {
+            await fs.access(validOutPath);
+            // If we get here, the file exists
+            throw new Error("Output file already exists. Pass overwrite: true to replace it.");
+        }
+        catch (accessError) {
+            if (accessError.code !== "ENOENT") {
+                // Either the "already exists" error above, or some other access error
+                throw accessError;
+            }
+        }
+    }
+    const raw = await fs.readFile(validPath);
+    const sourceEncoding = from ?? detectEncoding(raw);
+    const text = decodeText(raw, sourceEncoding);
+    const out = encodeText(text, to);
+    const directory = path.dirname(validOutPath);
+    await ensureDirectoryExists(directory);
+    await fs.writeFile(validOutPath, out);
+    return JSON.stringify({
+        path: filePath,
+        outPath: outPath,
+        from: sourceEncoding,
+        to,
+        bytesIn: raw.length,
+        bytesOut: out.length,
+    }, null, 2);
+}

package/dist/convert_encoding/schema.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export const ConvertEncodingArgsSchema = z.object({
+    path: z.string().describe("Path to the source file to read"),
+    to: z
+        .enum(["utf8", "utf16le", "utf16be", "cp1252"])
+        .describe("Target encoding (utf16le/utf16be output includes a BOM; utf8/cp1252 do not)"),
+    from: z
+        .enum(["utf8", "utf16le", "utf16be", "cp1252"])
+        .optional()
+        .describe("Source encoding. Omit to auto-detect from the file's bytes (BOM FF FE -> utf16le, FE FF -> utf16be, EF BB BF -> utf8, otherwise strict UTF-8 -> utf8, else cp1252)"),
+    outPath: z
+        .string()
+        .describe("Path of the file to write. Must differ from path and must not already exist unless overwrite=true"),
+    overwrite: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Replace outPath if it already exists. Default: false (fail if it exists)"),
+});

package/dist/copy_files/handler.js

@@ -1,6 +1,6 @@
 import fs from "fs/promises";
 import { copyDir } from "./helpers.js";
-import { validatePath, ensureDirectoryExists } from "../helpers/path.js";
+import { validatePath, ensureDirectoryExists, stripLongPathAll } from "../helpers/path.js";
 export async function handleCopyFile(sourcePath, destinationPath, recursive, overwrite, allowedDirectories) {
     const validSourcePath = await validatePath(sourcePath, allowedDirectories);
     const validDestPath = await validatePath(destinationPath, allowedDirectories);
@@ -37,7 +37,7 @@ export async function handleCopyFile(sourcePath, destinationPath, recursive, ove
         }
     }
     catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorMessage = stripLongPathAll(error instanceof Error ? error.message : String(error));
         throw new Error(`Error copying ${sourcePath} to ${destinationPath}: ${errorMessage}`);
     }
 }

package/dist/count_lines/handler.js

@@ -1,6 +1,6 @@
 import fs from "fs/promises";
 import path from "path";
-import { validatePath } from "../helpers/path.js";
+import { validatePath, stripLongPath } from "../helpers/path.js";
 import { minimatch } from "minimatch";
 export async function handleCountLines(filePath, recursive, pattern, filePattern, excludePatterns, ignoreEmptyLines, allowedDirectories) {
     // Validate the path
@@ -50,10 +50,10 @@ export async function handleCountLines(filePath, recursive, pattern, filePattern
                 totalMatchingLines += file.matchingCount;
             }
             if (pattern) {
-                output += `${file.file}: ${file.count} lines total, ${file.matchingCount} matching lines\n`;
+                output += `${stripLongPath(file.file)}: ${file.count} lines total, ${file.matchingCount} matching lines\n`;
             }
             else {
-                output += `${file.file}: ${file.count} lines\n`;
+                output += `${stripLongPath(file.file)}: ${file.count} lines\n`;
             }
         }
         output += "\n";

package/dist/create_directories/handler.js

@@ -1,5 +1,5 @@
 import fs from "fs/promises";
-import { validatePath } from "../helpers/path.js";
+import { validatePath, stripLongPathAll } from "../helpers/path.js";
 export async function handleCreateDirectories(paths, allowedDirectories) {
     const results = [];
     const errors = [];
@@ -12,7 +12,7 @@ export async function handleCreateDirectories(paths, allowedDirectories) {
             results.push(`Successfully created directory: ${dirPath}`);
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorMessage = stripLongPathAll(error instanceof Error ? error.message : String(error));
             errors.push(`Failed to create directory ${dirPath}: ${errorMessage}`);
         }
     }));

package/dist/create_link/handler.js

@@ -0,0 +1,90 @@
+import fs from "fs/promises";
+import path from "path";
+import { validatePath, stripLongPathAll } from "../helpers/path.js";
+export async function handleCreateLink(target, linkPath, type, allowedDirectories) {
+    // Both paths go through the repo's standard path validation (allow-root
+    // checks, nearest-existing-ancestor handling for not-yet-existing paths,
+    // long-path normalization at the single choke point).
+    const linkAbs = await validatePath(linkPath, allowedDirectories);
+    const targetAbs = await validatePath(target, allowedDirectories);
+    // The target must exist. lstat so a link target is classified as itself.
+    let targetStats;
+    try {
+        targetStats = await fs.lstat(targetAbs);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            throw new Error(`Target does not exist: ${target}`);
+        }
+        throw error;
+    }
+    // The link path must NOT already exist (lstat: an existing reparse point
+    // is caught here too, not followed past).
+    let linkExists = false;
+    try {
+        await fs.lstat(linkAbs);
+        linkExists = true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT") {
+            throw error;
+        }
+    }
+    if (linkExists) {
+        throw new Error(`Link path already exists: ${linkPath}`);
+    }
+    // The link path's parent directory must exist (NOT auto-created).
+    const linkParentAbs = path.dirname(linkAbs);
+    let parentStats;
+    try {
+        parentStats = await fs.stat(linkParentAbs);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            throw new Error(`Parent directory does not exist: ${path.dirname(linkPath)} (create_link does not auto-create parent directories)`);
+        }
+        throw error;
+    }
+    if (!parentStats.isDirectory()) {
+        throw new Error(`Parent path is not a directory: ${path.dirname(linkPath)}`);
+    }
+    let createdKind;
+    if (type === "hardlink") {
+        if (targetStats.isDirectory()) {
+            throw new Error(`hardlink target must be a file, but target is a directory: ${target}`);
+        }
+        // Second name for the same file. Same volume required - a cross-volume
+        // attempt surfaces the natural EXDEV error.
+        await fs.link(targetAbs, linkAbs);
+        createdKind = "hardlink";
+    }
+    else if (type === "junction") {
+        if (process.platform !== "win32") {
+            throw new Error("junction links are only supported on Windows (win32)");
+        }
+        if (!targetStats.isDirectory()) {
+            throw new Error(`junction target must be a directory, but target is a file: ${target}`);
+        }
+        await fs.symlink(targetAbs, linkAbs, "junction");
+        createdKind = "junction";
+    }
+    else {
+        // 'auto' (default) and 'symlink': real symlink, mode chosen by the
+        // target's type. 'auto' NEVER creates a junction - junctions must be
+        // explicit.
+        if (targetStats.isDirectory()) {
+            await fs.symlink(targetAbs, linkAbs, "dir");
+            createdKind = "symlink (directory)";
+        }
+        else {
+            await fs.symlink(targetAbs, linkAbs, "file");
+            createdKind = "symlink (file)";
+        }
+    }
+    // User-supplied strings are echoed back verbatim; stripLongPathAll guards
+    // against any extended-length form leaking into the response.
+    return stripLongPathAll(`Created ${createdKind} link: ${linkPath} -> ${target}`);
+}

package/dist/create_link/schema.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export const CreateLinkArgsSchema = z.object({
+    target: z
+        .string()
+        .describe("Existing file or directory the new link will point to. " +
+        "Must exist (lstat-checked; clear error otherwise). " +
+        "Must be within allowed directories."),
+    linkPath: z
+        .string()
+        .describe("Path at which the link object is created. " +
+        "Must NOT already exist (clear error); its parent directory must already exist " +
+        "(clear error - it is NOT auto-created). " +
+        "Must be within allowed directories."),
+    type: z
+        .enum(["auto", "symlink", "junction", "hardlink"])
+        .optional()
+        .default("auto")
+        .describe("Link type to create. " +
+        "'auto' (default) and 'symlink' create a real symlink based on the target's type: " +
+        "directory target -> directory symlink, file target -> file symlink " +
+        "('auto' never creates a junction - junctions must be explicit). " +
+        "'junction' creates a directory junction (Windows only; target must be a directory). " +
+        "'hardlink' creates a second name for an existing file " +
+        "(target must be a file; same volume - cross-volume errors surface naturally)."),
+});

package/dist/delete_files/handler.js

@@ -1,39 +1,230 @@
 import fs from "fs/promises";
-import { validatePath } from "../helpers/path.js";
-export async function handleDeleteFiles(paths, recursive, allowedDirectories) {
+import { execFile } from "child_process";
+import { promisify } from "util";
+import os from "os";
+import path from "path";
+import { validatePathPreservingLinks, stripLongPath, stripLongPathAll } from "../helpers/path.js";
+const execFileAsync = promisify(execFile);
+// Best-effort unlink that retries after clearing read-only flags, so plain
+// directory trees delete as completely as fs.rm(..., { force: true }) did.
+async function unlinkEntry(fullPath) {
+    try {
+        await fs.unlink(fullPath);
+    }
+    catch (error) {
+        try {
+            await fs.chmod(fullPath, 0o666);
+            await fs.unlink(fullPath);
+        }
+        catch {
+            throw error;
+        }
+    }
+}
+// Recursively delete a real directory without following reparse points
+// (junctions/symlinks): every entry is classified with lstat, links are
+// removed as leaves, real directories are walked, files are unlinked.
+async function rmRealDirectory(dir, errors) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        try {
+            const st = await fs.lstat(fullPath);
+            if (st.isSymbolicLink()) {
+                await fs.unlink(fullPath);
+            }
+            else if (st.isDirectory()) {
+                // The recursive call removes the directory itself
+                await rmRealDirectory(fullPath, errors);
+            }
+            else {
+                await unlinkEntry(fullPath);
+            }
+        }
+        catch (error) {
+            errors.push(stripLongPath(fullPath) +
+                ": " +
+                stripLongPathAll(error instanceof Error ? error.message : String(error)));
+        }
+    }
+    try {
+        await fs.rmdir(dir);
+    }
+    catch (error) {
+        errors.push(stripLongPath(dir) + ": " + stripLongPathAll(error instanceof Error ? error.message : String(error)));
+    }
+}
+async function recycleBatch(items) {
+    const jobDir = path.join(os.tmpdir(), "mcp-fs-shell-windows");
+    await fs.mkdir(jobDir, { recursive: true });
+    const listFile = path.join(jobDir, `delete_files_recycle_${Date.now()}_${process.pid}_${Math.floor(Math.random() * 1e9).toString(36)}.txt`);
+    await fs.writeFile(listFile, items.map((i) => i.resolved).join("\n"), "utf8");
+    try {
+        const ps = [
+            "$ErrorActionPreference='Stop'",
+            `$items = Get-Content -LiteralPath '${listFile}' -Encoding UTF8`,
+            "Add-Type -AssemblyName Microsoft.VisualBasic",
+            "$fileio = [Microsoft.VisualBasic.FileIO.FileSystem]",
+            "foreach ($p in $items) {",
+            "  try {",
+            "    if (Test-Path -LiteralPath $p -PathType Container) {",
+            "      $fileio::DeleteDirectory($p, 'OnlyErrorDialogs', 'SendToRecycleBin')",
+            "      Write-Output ('OK' + [char]9 + $p)",
+            "    } elseif (Test-Path -LiteralPath $p -PathType Leaf) {",
+            "      $fileio::DeleteFile($p, 'OnlyErrorDialogs', 'SendToRecycleBin')",
+            "      Write-Output ('OK' + [char]9 + $p)",
+            "    } else {",
+            "      Write-Output ('MISSING' + [char]9 + $p)",
+            "    }",
+            "  } catch {",
+            "    Write-Output ('ERR' + [char]9 + $p + [char]9 + $_.Exception.Message)",
+            "  }",
+            "}",
+        ].join("\n");
+        const encoded = Buffer.from(ps, "utf16le").toString("base64");
+        const { stdout } = await execFileAsync("powershell", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-EncodedCommand", encoded], { timeout: 300000, maxBuffer: 16 * 1024 * 1024, windowsHide: true });
+        const byResolved = new Map(items.map((i) => [i.resolved, i]));
+        const ok = [];
+        const missing = [];
+        const err = [];
+        const reported = new Set();
+        for (const line of stdout.split(/\r?\n/)) {
+            const parts = line.split("\t");
+            if (parts.length < 2)
+                continue;
+            const [status, resolved, ...msgParts] = parts;
+            const item = byResolved.get(resolved);
+            if (!item || reported.has(item.resolved))
+                continue;
+            reported.add(item.resolved);
+            if (status === "OK") {
+                ok.push(item);
+            }
+            else if (status === "MISSING") {
+                missing.push(item);
+            }
+            else if (status === "ERR") {
+                err.push({ item, message: msgParts.join("\t") });
+            }
+        }
+        // A path with no result line at all is an error - never assume success.
+        for (const item of items) {
+            if (!reported.has(item.resolved)) {
+                err.push({ item, message: "no result from recycle batch" });
+            }
+        }
+        return { ok, missing, err };
+    }
+    finally {
+        await fs.rm(listFile, { force: true }).catch(() => undefined);
+    }
+}
+// Volume roots (drive letters like C:\ or UNC share roots like \\server\share)
+// cannot be sent to the Recycle Bin as a unit; reject them so the shell never
+// starts moving a whole volume's contents.
+function isVolumeRoot(p) {
+    return /^[A-Za-z]:[\\/]?$/.test(p) || /^[\\/][^\\/]+[\\/][^\\/]+$/.test(p) || p === "/";
+}
+export async function handleDeleteFiles(paths, recursive, allowedDirectories, toRecycleBin) {
     const results = [];
     const errors = [];
+    const linkResults = [];
+    const recycleItems = [];
+    const isWin32 = process.platform === "win32";
+    const useRecycle = toRecycleBin && isWin32;
+    if (toRecycleBin && !isWin32) {
+        // Non-Windows: nothing is deleted, each path is reported as an error.
+        for (const filePath of paths) {
+            errors.push(`Failed to delete ${filePath}: toRecycleBin is supported only on Windows`);
+        }
+    }
     await Promise.all(paths.map(async (filePath) => {
+        if (toRecycleBin && !isWin32)
+            return; // already reported above
         try {
-            // Validate path is within allowed directories
-            const validPath = await validatePath(filePath, allowedDirectories);
-            // Get file stats to determine if it's a file or directory
-            const stats = await fs.stat(validPath);
-            if (stats.isDirectory()) {
-                if (recursive) {
-                    await fs.rm(validPath, { recursive: true, force: true });
-                    results.push(`Successfully deleted directory: ${filePath}`);
+            // Validate path is within allowed directories without following
+            // reparse points (the link itself must be what gets classified)
+            const validPath = await validatePathPreservingLinks(filePath, allowedDirectories);
+            // Classify with lstat so reparse points are never followed
+            const stats = await fs.lstat(validPath);
+            if (stats.isSymbolicLink()) {
+                // Junction/symlink: always removed as a leaf, with or without the
+                // recursive flag. The link target is never touched.
+                await fs.unlink(validPath);
+                if (useRecycle) {
+                    results.push(`Successfully deleted link: ${filePath} (link removed permanently; the recycle bin cannot hold links)`);
                 }
                 else {
+                    results.push(`Successfully deleted link: ${filePath} (link removed; target untouched)`);
+                }
+                linkResults.push(filePath);
+            }
+            else if (stats.isDirectory()) {
+                if (!recursive) {
                     throw new Error("Cannot delete directory without recursive flag");
                 }
+                if (useRecycle) {
+                    const plain = stripLongPath(validPath);
+                    if (isVolumeRoot(plain)) {
+                        throw new Error("Cannot send a volume root to the Recycle Bin");
+                    }
+                    recycleItems.push({ requested: filePath, resolved: plain, kind: "directory" });
+                }
+                else {
+                    const dirErrors = [];
+                    await rmRealDirectory(validPath, dirErrors);
+                    if (dirErrors.length > 0) {
+                        throw new Error(dirErrors.join("; "));
+                    }
+                    results.push(`Successfully deleted directory: ${filePath}`);
+                }
             }
             else {
-                // Delete the file
-                await fs.unlink(validPath);
-                results.push(`Successfully deleted file: ${filePath}`);
+                if (useRecycle) {
+                    recycleItems.push({ requested: filePath, resolved: stripLongPath(validPath), kind: "file" });
+                }
+                else {
+                    // Delete the file
+                    await unlinkEntry(validPath);
+                    results.push(`Successfully deleted file: ${filePath}`);
+                }
             }
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorMessage = stripLongPathAll(error instanceof Error ? error.message : String(error));
             errors.push(`Failed to delete ${filePath}: ${errorMessage}`);
         }
     }));
+    if (useRecycle && recycleItems.length > 0) {
+        const { ok, missing, err } = await recycleBatch(recycleItems);
+        for (const item of ok) {
+            const noun = item.kind === "directory" ? "directory" : "file";
+            results.push(`Successfully deleted ${noun}: ${item.requested} (recycled)`);
+        }
+        for (const item of missing) {
+            errors.push(`Failed to delete ${item.requested}: path no longer exists (recycle bin operation not performed)`);
+        }
+        for (const { item, message } of err) {
+            errors.push(`Failed to delete ${item.requested}: ${stripLongPathAll(message)}`);
+        }
+    }
     // Format the results
     const successCount = results.length;
     const errorCount = errors.length;
     let output = `Processed ${successCount + errorCount} paths:\n`;
+    if (useRecycle && results.length > 0) {
+        // Recycle mode: print the per-item success lines so the (recycled) /
+        // link-note suffixes are visible. Default mode keeps the historical
+        // count-only output (byte-identical when the flag is omitted).
+        output += results.join("\n") + "\n";
+    }
     output += `- ${successCount} items deleted successfully\n`;
+    if (linkResults.length > 0) {
+        const linkNote = useRecycle
+            ? "link removed permanently; the recycle bin cannot hold links"
+            : "link removed; target untouched";
+        output += `- ${linkResults.length} reparse point(s) removed (${linkNote}): ${linkResults.join(", ")}\n`;
+    }
     if (errorCount > 0) {
         output += `- ${errorCount} items failed\n\n`;
         output += "Errors:\n" + errors.join("\n");

package/dist/delete_files/schema.js

@@ -2,4 +2,8 @@ import { z } from "zod";
 export const DeleteFilesArgsSchema = z.object({
     paths: z.array(z.string()).describe("Paths to files or directories to delete"),
     recursive: z.boolean().default(false).describe("Whether to recursively delete directories"),
+    toRecycleBin: z.boolean().default(false).describe("Windows only. When true, files and directories are sent to the Recycle Bin instead of being permanently deleted. " +
+        "Reparse points (junctions/symlinks) are still removed as links, because the recycle bin cannot hold links. " +
+        "Any path that cannot be recycled (or no longer exists) is reported as an error and is never permanently deleted as a fallback. " +
+        "On non-Windows platforms this returns a clear error and deletes nothing."),
 });