mcp-fs-shell-windows 0.2.6 → 0.2.18

package/README.md

@@ -12,12 +12,13 @@ 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) — 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) — 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.
 - **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.
 - **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.
 
@@ -71,7 +72,7 @@ Then point your MCP config at `node <path-to-repo>\dist\index.js` with the allow
 | `read_files` | Read one or more files, line-numbered; `offset`/`limit` paging |
 | `write_new_files` | Create files (per-file `overwrite`, optional `base64` encoding) |
 | `append_files` | Append to files (creates them if missing) |
-| `delete_files` | Delete files/directories (`recursive`) |
+| `delete_files` | Delete files/directories (`recursive`, `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) |
@@ -113,6 +114,12 @@ Practical notes:
 - `timeout /t` can fail when stdin is not an interactive console — use `ping -n N 127.0.0.1 >nul` for sleeps.
 - Synchronous calls are bounded (max 28 s) so they cannot wedge the MCP request channel; anything longer should go through `shell_start`.
 
+### Launcher tool (1, Windows-only)
+
+| Tool | Purpose |
+|---|---|
+| `launch_file` | Launch a file, folder, or http(s) link via the Windows shell opener (`explorer.exe` — the OS default association: VLC for .mkv, Explorer for folders, default browser for web links). The target is passed as a single argv element (spaces, Unicode, `&`, apostrophes, parentheses all safe) and the call returns as soon as the opener process is actually spawned — it never waits for the opened app, creates no console window, and inherits no stdio pipes. Filesystem paths are subject to the allowed-root policy and checked for existence; only `http://`/`https://` links are launched, every other URL scheme (`file:`, `javascript:`, `ms-*`, `steam:`, …) is rejected, so no `file:` URI can bypass the filesystem policy. A failed opener spawn errors instead of reporting success. The response reports `dispatched: true` (the opener process was created) — not that the app handled the target. A host-settable `LAUNCH_FILE_OPENER` env var overrides the opener executable (test seam). |
+
 ## Docker
 
 ```bat
@@ -140,10 +147,13 @@ The filesystem tools work in the image; the shell tools require a Windows host w
 
 **v0.2.4 — verbatim argv:** `windowsVerbatimArguments` + `/d` on all user-command spawns (run/test/start and the terminal launcher).
 
+**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.
+
 ## Security
 
 - The filesystem tools are confined to the allowed directories passed at startup (and their subtrees).
 - The shell tools are **not** confined: anything the server process's user can execute will run, including against reachable network shares. Grant this server the same trust you would grant an unsandboxed shell.
+- `launch_file` targets are confined to the allowed directories (for paths), but the opened application runs with the full rights of the server user — like anything you double-click.
 - The server communicates over stdio and opens no network endpoints of its own.
 
 ## License

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

package/dist/delete_files_by_pattern/handler.js

@@ -1,6 +1,6 @@
 import fs from "fs/promises";
 import path from "path";
-import { validatePath } from "../helpers/path.js";
+import { validatePath, stripLongPath, stripLongPathAll } from "../helpers/path.js";
 export async function handleDeleteFilesByPattern(directory, pattern, includeDirectories, allowedDirectories) {
     const validPath = await validatePath(directory, allowedDirectories);
     let regex;
@@ -21,23 +21,23 @@ export async function handleDeleteFilesByPattern(directory, pattern, includeDire
             if (entry.isDirectory()) {
                 if (includeDirectories) {
                     await fs.rm(fullPath, { recursive: true, force: true });
-                    deleted.push(`${fullPath} (directory)`);
+                    deleted.push(`${stripLongPath(fullPath)} (directory)`);
                 }
                 else {
-                    skipped.push(`${fullPath} (directory; set includeDirectories: true to delete)`);
+                    skipped.push(`${stripLongPath(fullPath)} (directory; set includeDirectories: true to delete)`);
                 }
             }
             else {
                 await fs.unlink(fullPath);
-                deleted.push(fullPath);
+                deleted.push(stripLongPath(fullPath));
             }
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            skipped.push(`${fullPath} (${errorMessage})`);
+            const errorMessage = stripLongPathAll(error instanceof Error ? error.message : String(error));
+            skipped.push(`${stripLongPath(fullPath)} (${errorMessage})`);
         }
     }
-    let output = `Pattern "${pattern}" in ${validPath}:\n`;
+    let output = `Pattern "${pattern}" in ${stripLongPath(validPath)}:\n`;
     output += `- ${deleted.length} deleted\n`;
     if (skipped.length > 0) {
         output += `- ${skipped.length} skipped:\n` + skipped.map((s) => `  ${s}`).join("\n");