mcp-fs-shell-windows 0.2.6 → 0.2.18

package/dist/launch_file/handler.js

@@ -0,0 +1,154 @@
+import fs from "fs/promises";
+import path from "path";
+import { spawn } from "child_process";
+import { validatePath, stripLongPath } from "../helpers/path.js";
+/**
+ * Launch a file, directory, or web link in its Windows-associated
+ * application (the OS default: e.g. VLC for .mkv/.mp4, Explorer for
+ * folders, the default browser for http(s) links).
+ *
+ * Windows-only. Mechanism: spawn the shell opener with the target as a
+ * single argv element and stdio ignored:
+ *   %SystemRoot%\explorer.exe <target>
+ *
+ *   - Default association: explorer.exe performs a ShellExecute "open" -
+ *     exactly what a double-click does. Nothing is hardcoded.
+ *   - No pipe inheritance: stdio is "ignore", so the launched process never
+ *     receives the MCP server's stdin/stdout/stderr. The handler resolves
+ *     the moment Windows has spawned the opener - it does NOT stay pending
+ *     until the opened application exits (the exact bug the cmd+start route
+ *     hit: a long-lived GUI child held the pipes open).
+ *   - No intermediary console: the opener is a GUI process and the spawn
+ *     uses windowsHide, so no blank cmd.exe / PowerShell window appears.
+ *   - Verbatim arguments: the target is one argv element, so spaces,
+ *     Unicode, apostrophes, ampersands, parentheses, and every other
+ *     filename character are passed through exactly (no cmd/PowerShell
+ *     quoting to get wrong).
+ *   - Security policy: filesystem targets are routed through validatePath
+ *     (same allowed-roots + symlink resolution as every other tool). Only
+ *     http:// and https:// links are dispatched to the OS directly; every
+ *     other URL scheme (file:, javascript:, ms-*, steam:, vlc:, ...) is
+ *     rejected so the tool cannot reach arbitrary Windows protocol
+ *     handlers or bypass the allowed-roots policy.
+ */
+// Standard-form web links - the ONLY URLs dispatched to the OS opener.
+const WEB_URL = /^https?:\/\//i;
+// A Windows drive path: single letter, ':', then a separator or end of
+// string, e.g. "M:\\...", "C:/...", or a bare "M:".
+const WINDOWS_DRIVE = /^[A-Za-z]:([\\/]|$)/;
+// A URI scheme: 2+ scheme chars then ':'. (A bare drive letter is exactly
+// one char, so "M:foo" is NOT mistaken for a scheme and still resolves as
+// a drive-relative path through validatePath.)
+const URI_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]+:/;
+/**
+ * Windows-only guard; returns the full path to the shell opener.
+ *
+ * The opener defaults to %SystemRoot%\explorer.exe. The host-settable
+ * LAUNCH_FILE_OPENER environment variable overrides it - a test seam that
+ * makes the spawn-failure path testable end-to-end without touching the
+ * real environment (note: faking SystemRoot itself is impossible; Node's
+ * Windows CSPRNG init aborts unless SystemRoot is the real Windows dir).
+ * Only the opener executable changes; the target still passes the full
+ * URL/path policy below.
+ */
+function openerPath() {
+    if (process.platform !== "win32") {
+        throw new Error("launch_file is supported only on Windows");
+    }
+    const override = process.env.LAUNCH_FILE_OPENER;
+    if (override) {
+        return override;
+    }
+    const sysRoot = process.env.SystemRoot || "C:\\Windows";
+    return path.join(sysRoot, "explorer.exe");
+}
+/**
+ * Spawn the opener fully detached and settle the promise only when
+ * Windows has actually created the process ("spawn" event). A failed
+ * process creation ("error" event, e.g. opener executable missing)
+ * REJECTS - it never falsely reports success. Never waits for the opener
+ * to exit.
+ *
+ * Both listeners are removed on settlement, so there is no double
+ * settlement and no listener leak. Exported so tests can exercise both
+ * settlement paths directly.
+ */
+export function launchDetached(opener, target) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(opener, [target], {
+                stdio: "ignore",
+                detached: true,
+                windowsHide: true,
+            });
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
+        const onSpawn = () => {
+            child.removeListener("error", onError);
+            child.unref();
+            resolve();
+        };
+        const onError = (err) => {
+            child.removeListener("spawn", onSpawn);
+            child.unref();
+            reject(err);
+        };
+        child.once("spawn", onSpawn);
+        child.once("error", onError);
+    });
+}
+export async function handleLaunchFile(target, allowedDirectories) {
+    const trimmed = (target ?? "").trim();
+    if (!trimmed) {
+        throw new Error("path must not be empty");
+    }
+    const opener = openerPath();
+    // --- Web link: only http/https; ask the OS to open it (default browser) ---
+    if (WEB_URL.test(trimmed)) {
+        try {
+            await launchDetached(opener, trimmed);
+        }
+        catch (err) {
+            throw new Error(`Failed to launch URL: ${errorMessage(err)}`);
+        }
+        return JSON.stringify({ target: trimmed, kind: "url", dispatched: true });
+    }
+    // --- Other URL schemes: reject. This keeps file: URLs (and any other
+    //     registered protocol handler) from bypassing the filesystem policy. ---
+    if (URI_SCHEME.test(trimmed) && !WINDOWS_DRIVE.test(trimmed)) {
+        throw new Error("Unsupported URL: only http:// and https:// links can be launched. " +
+            'Filesystem targets must be plain paths (e.g. "M:\\..." or "\\\\server\\share"), ' +
+            "not file: URLs or other protocol schemes.");
+    }
+    // --- Filesystem target: enforce the existing path/security policy ---
+    const resolved = await validatePath(trimmed, allowedDirectories);
+    // Useful error for a target that does not exist.
+    let stats;
+    try {
+        stats = await fs.stat(resolved);
+    }
+    catch {
+        throw new Error(`Cannot launch: path does not exist: ${stripLongPath(resolved)}`);
+    }
+    try {
+        // The opener (shell) receives the plain path: Windows shell APIs handle
+        // long paths themselves, while the \\?\ form can break association lookup.
+        await launchDetached(opener, stripLongPath(resolved));
+    }
+    catch (err) {
+        throw new Error(`Failed to launch target: ${errorMessage(err)}`);
+    }
+    return JSON.stringify({
+        target: trimmed,
+        kind: stats.isDirectory() ? "directory" : "file",
+        resolved: stripLongPath(resolved),
+        dispatched: true,
+    });
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/launch_file/schema.js

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export const LaunchFileArgsSchema = z.object({
+    path: z.string(),
+});

package/dist/list_directory/handler.js

@@ -1,25 +1,32 @@
 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 handleListDirectory(directoryPath, allowedDirectories, type = "all", ignore = [], offset = 1, limit = 100, includeSizes = true) {
     const validPath = await validatePath(directoryPath, allowedDirectories);
     const entries = await fs.readdir(validPath, { withFileTypes: true });
     let filtered = entries.filter((entry) => {
-        if (type === "files" && !entry.isFile())
-            return false;
-        if (type === "directories" && !entry.isDirectory())
-            return false;
+        if (entry.isSymbolicLink()) {
+            // Links (junctions/symlinks) are only listed with type "all"
+            if (type !== "all")
+                return false;
+        }
+        else {
+            if (type === "files" && !entry.isFile())
+                return false;
+            if (type === "directories" && !entry.isDirectory())
+                return false;
+        }
         return !ignore.some((pattern) => minimatch(entry.name, pattern, { dot: true }));
     });
     // Stable ordering for pagination
     filtered = filtered.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
     const total = filtered.length;
     if (total === 0) {
-        return `No entries in ${validPath}`;
+        return `No entries in ${stripLongPath(validPath)}`;
     }
     if (offset > total) {
-        return `No entries in ${validPath} (offset ${offset} is beyond ${total} entries)`;
+        return `No entries in ${stripLongPath(validPath)} (offset ${offset} is beyond ${total} entries)`;
     }
     const start = offset - 1;
     const shown = filtered.slice(start, start + limit);
@@ -35,8 +42,8 @@ export async function handleListDirectory(directoryPath, allowedDirectories, typ
                 sizeText = "";
             }
         }
-        lines.push(`${entry.isDirectory() ? "[DIR]" : "[FILE]"} ${entry.name}${sizeText}`);
+        lines.push(`${entry.isSymbolicLink() ? "[LINK]" : entry.isDirectory() ? "[DIR]" : "[FILE]"} ${entry.name}${sizeText}`);
     }
     const end = start + shown.length;
-    return `Showing ${offset}-${end} of ${total} entries in ${validPath}\n` + lines.join("\n");
+    return `Showing ${offset}-${end} of ${total} entries in ${stripLongPath(validPath)}\n` + lines.join("\n");
 }

package/dist/move_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 handleMoveFiles(items, overwrite, allowedDirectories) {
     const results = [];
     const errors = [];
@@ -51,7 +51,7 @@ export async function handleMoveFiles(items, overwrite, allowedDirectories) {
             results.push(`Successfully moved ${item.source} to ${item.destination}`);
         }
         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 move ${item.source} to ${item.destination}: ${errorMessage}`);
         }
     }));

package/dist/patch_files/handler.js

@@ -1,4 +1,4 @@
-import { validatePath } from "../helpers/path.js";
+import { validatePath, stripLongPathAll } from "../helpers/path.js";
 import { applyFilePatches } from "./helpers.js";
 export async function handlePatchFiles(files, dryRun, options, allowedDirectories) {
     const results = [];
@@ -12,7 +12,7 @@ export async function handlePatchFiles(files, dryRun, options, allowedDirectorie
             results.push(`File: ${file.path}\n${result}`);
         }
         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 patch ${file.path}: ${errorMessage}`);
         }
     }));

package/dist/patch_files/helpers.js

@@ -1,8 +1,27 @@
 import fs from "fs/promises";
 import { createUnifiedDiff, normalizeLineEndings } from "../helpers/diff.js";
+import { stripLongPath } from "../helpers/path.js";
+// Detect the dominant line ending of the raw file content so it can be
+// restored on write (mirrors the edit_files approach). CRLF is chosen only
+// when it is the strict majority of the file's newlines; otherwise the file
+// is treated as LF (also the outcome for a CRLF/LF tie, matching the
+// previous LF-normalizing default).
+export function detectDominantEol(text) {
+    const crlf = (text.match(/\r\n/g) || []).length;
+    const others = (text.replace(/\r\n/g, "").match(/[\r\n]/g) || []).length;
+    return crlf > others ? "\r\n" : "\n";
+}
+// Re-apply the dominant line ending to LF-normalized content (no-op for LF).
+export function fromLf(text, eol) {
+    return eol === "\n" ? text : text.replace(/\n/g, eol);
+}
 export async function applyFilePatches(filePath, patches, dryRun = false, options = { preserveIndentation: true }) {
-    // Read file content and normalize line endings
-    const content = normalizeLineEndings(await fs.readFile(filePath, "utf-8"));
+    // Read the raw file, detect its dominant line ending, and normalize to LF
+    // for patching. The dominant ending is restored on write so the file keeps
+    // its original EOL convention.
+    const raw = await fs.readFile(filePath, "utf-8");
+    const eol = detectDominantEol(raw);
+    const content = normalizeLineEndings(raw);
     // Split content into lines
     const contentLines = content.split("\n");
     // Sort patches by line number in descending order so every patch references
@@ -77,7 +96,7 @@ export async function applyFilePatches(filePath, patches, dryRun = false, option
     }
     const modifiedContent = modifiedContentLines.join("\n");
     // Create unified diff
-    const diff = createUnifiedDiff(content, modifiedContent, filePath, filePath);
+    const diff = createUnifiedDiff(content, modifiedContent, stripLongPath(filePath), stripLongPath(filePath));
     // Format diff with appropriate number of backticks
     let numBackticks = 3;
     while (diff.includes("`".repeat(numBackticks))) {
@@ -97,7 +116,8 @@ export async function applyFilePatches(filePath, patches, dryRun = false, option
         }
     });
     if (!dryRun) {
-        await fs.writeFile(filePath, modifiedContent, "utf-8");
+        // Write back with the file's original dominant line ending.
+        await fs.writeFile(filePath, fromLf(modifiedContent, eol), "utf-8");
     }
     return resultText;
 }

package/dist/read_bytes/handler.js

@@ -0,0 +1,43 @@
+import fs from "fs/promises";
+import { validatePath } from "../helpers/path.js";
+export async function handleReadBytes(filePath, offset, length, allowedDirectories) {
+    const validPath = await validatePath(filePath, allowedDirectories);
+    let stats;
+    try {
+        stats = await fs.stat(validPath);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            throw new Error(`File does not exist: ${filePath}`);
+        }
+        throw error;
+    }
+    if (!stats.isFile()) {
+        throw new Error(`Not a file: ${filePath}`);
+    }
+    const size = stats.size;
+    if (offset >= size) {
+        throw new Error(`offset beyond EOF: offset ${offset} >= file size ${size}`);
+    }
+    const actualLength = Math.min(length, size - offset);
+    const buffer = Buffer.alloc(actualLength);
+    const handle = await fs.open(validPath, "r");
+    try {
+        const { bytesRead } = await handle.read(buffer, 0, actualLength, offset);
+        if (bytesRead !== actualLength) {
+            throw new Error(`Short read: expected ${actualLength} bytes at offset ${offset}, got ${bytesRead}`);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return JSON.stringify({
+        path: filePath,
+        offset,
+        length,
+        actualLength,
+        size,
+        dataBase64: buffer.toString("base64"),
+    });
+}

package/dist/read_bytes/schema.js

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export const ReadBytesArgsSchema = z.object({
+    path: z.string().describe("Path to the file to read"),
+    offset: z.number().int().min(0).describe("Byte offset to start reading from (0-indexed). Must be less than the file size."),
+    length: z.number().int().min(1).describe("Number of bytes to read. If offset+length exceeds the file size, the read is clamped to EOF."),
+});

package/dist/read_files/handler.js

@@ -1,34 +1,43 @@
 import fs from "fs/promises";
-import { validatePath } from "../helpers/path.js";
-export async function handleReadFiles(filePaths, allowedDirectories, offset, limit) {
-    const results = await Promise.all(filePaths.map(async (filePath) => {
+import { validatePath, stripLongPathAll } from "../helpers/path.js";
+import { decodeText, detectEncoding, } from "../helpers/encoding.js";
+export async function handleReadFiles(fileItems, allowedDirectories, offset, limit) {
+    const results = await Promise.all(fileItems.map(async (item) => {
+        const filePath = typeof item === "string" ? item : item.path;
         try {
             const validPath = await validatePath(filePath, allowedDirectories);
-            const content = await fs.readFile(validPath, "utf-8");
+            const raw = await fs.readFile(validPath);
+            // Decode with the file's explicit encoding when given, otherwise
+            // auto-detect from the raw bytes (BOM, then strict UTF-8, else cp1252).
+            const encoding = (typeof item !== "string" && item.encoding) || detectEncoding(raw);
+            const content = decodeText(raw, encoding);
+            // Per-file offset/limit (object form) fall back to the global ones.
+            const effOffset = (typeof item !== "string" && item.offset) || offset;
+            const effLimit = (typeof item !== "string" && item.limit) || limit;
             // Split into lines, keeping original line numbers
             const lines = content.split("\n");
             const total = lines.length;
             let startLine = 1;
             let endLine = total;
-            if (offset !== undefined || limit !== undefined) {
-                startLine = offset ?? 1;
+            if (effOffset !== undefined || effLimit !== undefined) {
+                startLine = effOffset ?? 1;
                 if (startLine > total) {
                     throw new Error(`offset ${startLine} is beyond end of file (${total} lines)`);
                 }
-                endLine = limit !== undefined ? Math.min(total, startLine + limit - 1) : total;
+                endLine = effLimit !== undefined ? Math.min(total, startLine + effLimit - 1) : total;
             }
             // Format content with line numbers
             const numberedContent = lines
                 .slice(startLine - 1, endLine)
                 .map((line, idx) => `${startLine + idx}: ${line}`)
                 .join("\n");
-            const header = offset !== undefined || limit !== undefined
+            const header = effOffset !== undefined || effLimit !== undefined
                 ? `${filePath}: [lines ${startLine}-${endLine} of ${total}]\n`
                 : `${filePath}:\n`;
             return `${header}${numberedContent}\n`;
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorMessage = stripLongPathAll(error instanceof Error ? error.message : String(error));
             return `${filePath}: Error - ${errorMessage}`;
         }
     }));

package/dist/read_files/schema.js

@@ -1,6 +1,40 @@
 import { z } from "zod";
+export const ReadFileItemSchema = z.union([
+    z.string().describe("Path to the file to read"),
+    z.object({
+        path: z.string().describe("Path to the file to read"),
+        encoding: z
+            .enum(["utf8", "utf16le", "utf16be", "cp1252"])
+            .optional()
+            .describe("Decoding to use for this file (a matching BOM is stripped). 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)"),
+        offset: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe("Start reading from this line number (1-indexed). Overrides the global offset for this file."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe("Maximum number of lines to read for this file. Overrides the global limit."),
+    }),
+]);
 export const ReadFilesArgsSchema = z.object({
-    paths: z.array(z.string()),
-    offset: z.number().int().min(1).optional().describe("Start reading from this line number (1-indexed). Omit to read from the beginning."),
-    limit: z.number().int().min(1).optional().describe("Maximum number of lines to read per file. Omit to read to the end."),
+    paths: z
+        .array(ReadFileItemSchema)
+        .describe("Files to read. Each item is a plain path string, or an object {path, encoding?, offset?, limit?}."),
+    offset: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Start reading from this line number (1-indexed). Omit to read from the beginning."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Maximum number of lines to read per file. Omit to read to the end."),
 });

package/dist/replace_regex/handler.js

@@ -0,0 +1,105 @@
+import fs from "fs/promises";
+import { validatePath } from "../helpers/path.js";
+import { createUnifiedDiff, normalizeLineEndings } from "../helpers/diff.js";
+import { detectDominantEol, fromLf } from "../patch_files/helpers.js";
+// Ensure the 'g' (global) flag is present in the flag set (deduplicated) and
+// add it if the caller omitted it, so that every match is replaced. Caller
+// flags such as 'i' are preserved.
+function withGlobalFlag(flags) {
+    const set = new Set();
+    for (const ch of flags || "")
+        set.add(ch);
+    set.add("g");
+    return Array.from(set).join("");
+}
+export async function handleReplaceRegex(paths, pattern, replacement, flags, dryRun, allowedDirectories) {
+    const effectiveFlags = withGlobalFlag(flags || "");
+    // Validate the regex up front. If it is invalid (bad pattern or bad flags),
+    // throw so that NOTHING is written for this call.
+    try {
+        new RegExp(pattern, effectiveFlags);
+    }
+    catch (error) {
+        throw new Error(`Invalid regular expression "${pattern}" (flags "${effectiveFlags}"): ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Phase 1: validate every path and compute all results WITHOUT writing.
+    // Any missing path, directory, or unreadable file throws, so NOTHING is
+    // written for the whole call (all-or-nothing). Writes happen only in Phase 2,
+    // after this loop completes successfully.
+    const computed = [];
+    let totalReplacements = 0;
+    for (const requestedPath of paths) {
+        const resolvedPath = await validatePath(requestedPath, allowedDirectories);
+        let stat;
+        try {
+            stat = await fs.stat(resolvedPath);
+        }
+        catch {
+            throw new Error(`Path not found: ${requestedPath}`);
+        }
+        if (stat.isDirectory()) {
+            throw new Error(`Directory not accepted: ${requestedPath}. replace_regex operates on files only - list the specific file path(s) to change.`);
+        }
+        if (!stat.isFile()) {
+            throw new Error(`Not a regular file: ${requestedPath}`);
+        }
+        const raw = await fs.readFile(resolvedPath, "utf-8");
+        const eol = detectDominantEol(raw);
+        // Run the replacement in LF-normalized space, then restore the file's
+        // dominant line ending on write so a pure-CRLF file stays fully CRLF
+        // (byte-level; no mixed endings). Same approach as patch_files.
+        const content = normalizeLineEndings(raw);
+        // Count matches (fresh global regex; advance on zero-length matches to
+        // avoid an infinite loop, mirroring search_regex).
+        const countRegex = new RegExp(pattern, effectiveFlags);
+        let matches = 0;
+        let m;
+        while ((m = countRegex.exec(content)) !== null) {
+            matches++;
+            if (m[0].length === 0)
+                countRegex.lastIndex++;
+        }
+        // Perform the replacement (fresh global regex; $1/${name}/$&/$' etc. are
+        // handled by the engine). The count of matches equals the number of
+        // replacements for a global pattern.
+        const replaceRegex = new RegExp(pattern, effectiveFlags);
+        const newContent = content.replace(replaceRegex, replacement);
+        totalReplacements += matches;
+        const entry = {
+            requestedPath,
+            resolvedPath,
+            matches,
+            writeText: fromLf(newContent, eol),
+        };
+        if (dryRun) {
+            entry.preview =
+                matches === 0
+                    ? "(no matches - no change)"
+                    : createUnifiedDiff(content, newContent, requestedPath, requestedPath);
+        }
+        computed.push(entry);
+    }
+    // Phase 2: apply writes (only when not a dry run). All Phase-1 computation
+    // above has already succeeded, so every file can be written safely.
+    if (!dryRun) {
+        for (const entry of computed) {
+            await fs.writeFile(entry.resolvedPath, entry.writeText, "utf-8");
+        }
+    }
+    // Build the text output.
+    const mode = dryRun
+        ? "Dry run (preview only - NO files were written)"
+        : "Applied (files written in place)";
+    let output = `${mode}: ${computed.length} file(s), ${totalReplacements} replacement(s) total.\n`;
+    for (const entry of computed) {
+        output += `\nFile: ${entry.requestedPath}\n`;
+        output += `  matches: ${entry.matches}\n`;
+        if (dryRun && entry.preview !== undefined) {
+            output += `  preview:\n${entry.preview}\n`;
+        }
+    }
+    if (dryRun) {
+        output += `\n(No changes were written. Re-run with dryRun=false to apply.)`;
+    }
+    return output;
+}

package/dist/replace_regex/schema.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export const ReplaceRegexArgsSchema = z.object({
+    paths: z
+        .array(z.string())
+        .min(1)
+        .describe("Paths to the files to replace regex matches in. One or many FILES may be listed; directories are NOT accepted (a directory path is an error and nothing is written)."),
+    pattern: z
+        .string()
+        .describe("Regular expression pattern to match in each file (JavaScript regex syntax)."),
+    replacement: z
+        .string()
+        .describe("Replacement text for each match. Standard regex replacement syntax is supported (e.g. $1, ${name}, $&, $')."),
+    flags: z
+        .string()
+        .optional()
+        .default("")
+        .describe("Additional regex flags (e.g. 'i' case-insensitive, 'm', 's', 'u'). The 'g' (global) flag is ALWAYS applied so every match is replaced; if you omit 'g' it is forced on."),
+    dryRun: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("When true (default), preview the WOULD-BE change per file (unified diff) without writing anything. When false, apply the replacements in place and report per-file match counts plus a total."),
+});

package/dist/search_files/handler.js

@@ -1,4 +1,4 @@
-import { validatePath } from "../helpers/path.js";
+import { validatePath, stripLongPath } from "../helpers/path.js";
 import { searchFiles } from "./helpers.js";
 export async function handleSearchFiles(directoryPath, pattern, excludePatterns, maxResults, offset, allowedDirectories) {
     const validPath = await validatePath(directoryPath, allowedDirectories);
@@ -11,5 +11,5 @@ export async function handleSearchFiles(directoryPath, pattern, excludePatterns,
     }
     const end = offset + shown.length - 1;
     const totalText = stopped ? `at least ${results.length}` : `${results.length}`;
-    return `Found ${totalText} files matching "${pattern}" (showing ${offset}-${end})\n\n` + shown.join("\n");
+    return `Found ${totalText} files matching "${pattern}" (showing ${offset}-${end})\n\n` + shown.map(stripLongPath).join("\n");
 }

package/dist/search_glob/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 handleSearchGlob(searchPath, pattern, excludePatterns, maxResults, offset, allowedDirectories) {
     // Validate root path
@@ -70,7 +70,7 @@ export async function handleSearchGlob(searchPath, pattern, excludePatterns, max
         }
         output += "\n\n";
         for (const result of shown) {
-            output += `${result}\n`;
+            output += `${stripLongPath(result)}\n`;
         }
     }
     return output;