mcp-fs-shell-windows 0.2.7 → 0.2.19

package/dist/launch_file/handler.js

@@ -1,7 +1,7 @@
 import fs from "fs/promises";
 import path from "path";
 import { spawn } from "child_process";
-import { validatePath } from "../helpers/path.js";
+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
@@ -132,10 +132,12 @@ export async function handleLaunchFile(target, allowedDirectories) {
         stats = await fs.stat(resolved);
     }
     catch {
-        throw new Error(`Cannot launch: path does not exist: ${resolved}`);
+        throw new Error(`Cannot launch: path does not exist: ${stripLongPath(resolved)}`);
     }
     try {
-        await launchDetached(opener, resolved);
+        // 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)}`);
@@ -143,7 +145,7 @@ export async function handleLaunchFile(target, allowedDirectories) {
     return JSON.stringify({
         target: trimmed,
         kind: stats.isDirectory() ? "directory" : "file",
-        resolved,
+        resolved: stripLongPath(resolved),
         dispatched: true,
     });
 }

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;

package/dist/search_regex/handler.js

@@ -1,14 +1,15 @@
 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 handleSearchRegex(searchPath, pattern, filePatterns, excludePatterns, maxResults, caseSensitive, offset, allowedDirectories) {
+export async function handleSearchRegex(searchPath, pattern, filePatterns, excludePatterns, maxResults, caseSensitive, offset, allowedDirectories, countOnly) {
     // Validate root path (may be a directory or a single file)
     const validRootPath = await validatePath(searchPath, allowedDirectories);
     const results = [];
+    const perFileCounts = new Map();
+    const filesSearchedList = [];
     let filesSearched = 0;
-    let matchesFound = 0;
-    let searchAborted = false;
+    let totalMatches = 0;
     const effectiveCap = offset - 1 + maxResults;
     // Create regex pattern
     const regexFlags = caseSensitive ? "mg" : "img";
@@ -20,38 +21,40 @@ export async function handleSearchRegex(searchPath, pattern, filePatterns, exclu
         throw new Error(`Invalid regular expression: ${pattern}`);
     }
     async function scanFile(fullPath) {
-        if (searchAborted)
-            return;
         try {
             filesSearched++;
+            filesSearchedList.push(fullPath);
             const content = await fs.readFile(fullPath, "utf-8");
             const lines = content.split("\n");
             regex.lastIndex = 0;
             let match;
+            // Every occurrence is counted (a line containing the pattern 4 times
+            // counts as 4 matches). Line results are collected only while under the
+            // pagination cap; counting always runs to completion so the reported
+            // total is exact.
             while ((match = regex.exec(content)) !== null) {
-                matchesFound++;
-                // Find the line number for this match
-                const matchPosition = match.index;
-                let lineNumber = 0;
-                let charCount = 0;
-                for (let i = 0; i < lines.length; i++) {
-                    charCount += lines[i].length + 1; // +1 for the newline
-                    if (charCount > matchPosition) {
-                        lineNumber = i + 1;
-                        break;
+                totalMatches++;
+                perFileCounts.set(fullPath, (perFileCounts.get(fullPath) ?? 0) + 1);
+                if (!countOnly && results.length < effectiveCap) {
+                    // Find the line number for this match
+                    const matchPosition = match.index;
+                    let lineNumber = 0;
+                    let charCount = 0;
+                    for (let i = 0; i < lines.length; i++) {
+                        charCount += lines[i].length + 1; // +1 for the newline
+                        if (charCount > matchPosition) {
+                            lineNumber = i + 1;
+                            break;
+                        }
                     }
-                }
-                // Get the line content
-                const lineContent = lines[lineNumber - 1]?.trim() || "";
-                results.push({
-                    file: fullPath,
-                    line: lineNumber,
-                    content: lineContent,
-                    match: match[0],
-                });
-                if (results.length >= effectiveCap) {
-                    searchAborted = true;
-                    break;
+                    // Get the line content
+                    const lineContent = lines[lineNumber - 1]?.trim() || "";
+                    results.push({
+                        file: fullPath,
+                        line: lineNumber,
+                        content: lineContent,
+                        match: match[0],
+                    });
                 }
                 // Guard against zero-length matches (e.g. pattern "a*") looping forever
                 if (match[0].length === 0) {
@@ -64,13 +67,9 @@ export async function handleSearchRegex(searchPath, pattern, filePatterns, exclu
         }
     }
     async function searchDirectory(dirPath) {
-        if (searchAborted)
-            return;
         try {
             const entries = await fs.readdir(dirPath, { withFileTypes: true });
             for (const entry of entries) {
-                if (searchAborted)
-                    break;
                 const fullPath = path.join(dirPath, entry.name);
                 try {
                     // Validate each path before processing
@@ -122,22 +121,44 @@ export async function handleSearchRegex(searchPath, pattern, filePatterns, exclu
     else {
         await searchDirectory(validRootPath);
     }
+    // Total-match summary (always included), with per-file counts for the
+    // files that contain at least one match, in first-match (walk) order.
+    const matchedFileEntries = [...perFileCounts.entries()];
+    const matchedFilesCount = matchedFileEntries.length;
+    let matchedFilesList = "";
+    for (const [file, count] of matchedFileEntries) {
+        matchedFilesList += `  ${stripLongPath(file)}: ${count}\n`;
+    }
+    const totalLine = `Total matches: ${totalMatches} (${matchedFilesCount} files)\n`;
     // Format the results
     let output = "";
-    const shown = results.slice(offset - 1);
-    if (matchesFound === 0) {
+    const shown = countOnly ? [] : results.slice(offset - 1);
+    if (countOnly) {
+        // Counts only: total header, files searched, then a per-file count line
+        // for EVERY searched file (0 for files with no matches).
+        output = totalLine;
+        output += `Searched ${filesSearched} files\n`;
+        if (totalMatches > 0) {
+            output += "\n";
+            for (const file of filesSearchedList) {
+                output += `  ${stripLongPath(file)}: ${perFileCounts.get(file) ?? 0}\n`;
+            }
+        }
+    }
+    else if (totalMatches === 0) {
         output = `No matches found for regex: ${pattern}\n`;
         output += `Searched ${filesSearched} files\n`;
+        output += totalLine;
     }
     else if (shown.length === 0) {
-        output = `Found ${matchesFound} matches in ${results.length} locations (offset ${offset} is beyond the collected range)\n`;
+        output = `Found ${totalMatches} matches in ${results.length} locations (offset ${offset} is beyond the collected range)\n`;
+        output += "\n";
+        output += totalLine;
+        output += matchedFilesList;
     }
     else {
         const end = offset + shown.length - 1;
-        output = `Found ${matchesFound} matches in ${results.length} locations (showing ${offset}-${end})`;
-        if (searchAborted) {
-            output += ` (search stopped at ${effectiveCap} collected matches)`;
-        }
+        output = `Found ${totalMatches} matches in ${results.length} locations (showing ${offset}-${end})`;
         output += "\n\n";
         // Group by file for more readable output
         const fileGroups = new Map();
@@ -148,12 +169,14 @@ export async function handleSearchRegex(searchPath, pattern, filePatterns, exclu
             fileGroups.get(result.file)?.push(result);
         }
         for (const [file, fileResults] of fileGroups.entries()) {
-            output += `File: ${file}\n`;
+            output += `File: ${stripLongPath(file)}\n`;
             for (const result of fileResults) {
                 output += `  Line ${result.line}: ${result.content}\n`;
             }
             output += "\n";
         }
+        output += totalLine;
+        output += matchedFilesList;
     }
     return output;
 }

package/dist/search_regex/schema.js

@@ -7,4 +7,5 @@ export const SearchRegexArgsSchema = z.object({
     maxResults: z.number().optional().default(100).describe("Maximum number of results to return"),
     offset: z.number().int().min(1).optional().default(1).describe("1-indexed match number to start from. Default: 1."),
     caseSensitive: z.boolean().optional().default(false).describe("Whether the search should be case-sensitive"),
+    countOnly: z.boolean().optional().default(false).describe("When true, return only per-file match counts and the total (no matching line text). Default: false."),
 });