@j0hanz/filesystem-mcp 1.14.0 → 1.14.1

package/dist/tools/move-file.js

@@ -1,7 +1,8 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
+import { cp, mkdir, rename, rm, stat } from 'node:fs/promises';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { withAbort } from '../lib/abort.js';
 import { ErrorCode, formatUnknownErrorMessage, isNodeError, McpError, } from '../lib/errors.js';
-import { withAbort } from '../lib/fs-helpers.js';
+import { Logger } from '../lib/logger.js';
 import { assertAllowedFileAccess, validateExistingPath, validatePathForWrite, } from '../lib/paths.js';
 import { MoveFileInputSchema, MoveFileOutputSchema } from '../schemas.js';
 import { buildStructuredError, buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
@@ -18,103 +19,119 @@ export const MOVE_FILE_TOOL = {
     ],
     taskSupport: 'forbidden',
 };
-function toMoveFailure(source, error, defaultCode = ErrorCode.E_UNKNOWN) {
+function toMoveFailure(source, error, defaultCode = ErrorCode.UNKNOWN) {
     return {
         source,
         error: buildStructuredError(error, defaultCode, source),
     };
 }
-async function handleMoveFile(args, signal) {
-    const sources = args.sources ?? (args.source ? [args.source] : []);
-    if (sources.length === 0) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'No sources provided.');
+async function handleMoveError(error, src, validSource, targetPath, movedSources, failed, signal) {
+    if (isNodeError(error) && error.code === 'EXDEV') {
+        try {
+            await withAbort(cp(validSource, targetPath, { recursive: true }), signal);
+        }
+        catch (copyError) {
+            failed.push(toMoveFailure(src, copyError));
+            return;
+        }
+        try {
+            await withAbort(rm(validSource, { recursive: true, force: true }), signal);
+            movedSources.push(validSource);
+        }
+        catch (deleteError) {
+            try {
+                await rm(targetPath, { recursive: true, force: true });
+            }
+            catch {
+                failed.push(toMoveFailure(src, new McpError(ErrorCode.UNKNOWN, `Cross-device move partial: data at both source and destination. ${formatUnknownErrorMessage(deleteError)}`, src)));
+                return;
+            }
+            failed.push(toMoveFailure(src, new McpError(ErrorCode.UNKNOWN, `Cross-device move failed: source not removed. ${formatUnknownErrorMessage(deleteError)}`, src)));
+        }
+    }
+    else {
+        failed.push(toMoveFailure(src, error));
+    }
+}
+async function processSingleMove(src, destIsDirectory, validDest, movedSources, failed, signal) {
+    let validSource;
+    try {
+        validSource = await validateExistingPath(src, signal);
+        assertAllowedFileAccess(src, validSource);
+    }
+    catch (error) {
+        failed.push(toMoveFailure(src, error, ErrorCode.ACCESS_DENIED));
+        return;
+    }
+    const targetPath = destIsDirectory
+        ? join(validDest, basename(validSource))
+        : validDest;
+    if (resolve(validSource) === resolve(targetPath)) {
+        return;
+    }
+    if (resolve(targetPath).startsWith(resolve(validSource) + sep)) {
+        failed.push(toMoveFailure(src, new McpError(ErrorCode.INVALID_INPUT, 'Cannot move a directory into its own subdirectory', src), ErrorCode.INVALID_INPUT));
+        return;
     }
-    const validDest = await validatePathForWrite(args.destination, signal);
-    // Check if destination exists and is a directory
-    let destIsDirectory = false;
     try {
-        const stats = await fs.stat(validDest);
-        destIsDirectory = stats.isDirectory();
+        await withAbort(rename(validSource, targetPath), signal);
+        movedSources.push(validSource);
+    }
+    catch (error) {
+        await handleMoveError(error, src, validSource, targetPath, movedSources, failed, signal);
+    }
+}
+async function getDestinationStatus(validDest) {
+    try {
+        const stats = await stat(validDest);
+        return stats.isDirectory();
     }
     catch (error) {
         if (isNodeError(error) && error.code !== 'ENOENT') {
             throw error;
         }
     }
+    return false;
+}
+function formatMoveMessage(moved, failed, destination) {
+    const movedItemStr = `item${moved === 1 ? '' : 's'}`;
+    const failedItemStr = `item${failed === 1 ? '' : 's'}`;
+    if (failed > 0) {
+        return `Moved ${moved} ${movedItemStr}; failed to move ${failed} ${failedItemStr}`;
+    }
+    return `Successfully moved ${moved} ${movedItemStr} to ${destination}`;
+}
+async function handleMoveFile(args, signal) {
+    const sources = args.sources ?? (args.source ? [args.source] : []);
+    if (sources.length === 0) {
+        throw new McpError(ErrorCode.INVALID_INPUT, 'No sources provided.');
+    }
+    const validDest = await validatePathForWrite(args.destination, signal);
+    const destIsDirectory = await getDestinationStatus(validDest);
     if (sources.length > 1 && !destIsDirectory) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Destination must be an existing directory when moving multiple files.');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Destination must be an existing directory for multiple sources.');
     }
-    // Ensure destination parent directory exists if it's not an existing directory
     if (!destIsDirectory) {
-        await withAbort(fs.mkdir(path.dirname(validDest), { recursive: true }), signal);
+        await withAbort(mkdir(dirname(validDest), { recursive: true }), signal);
     }
     const movedSources = [];
     const failed = [];
     for (const src of sources) {
-        let validSource;
-        try {
-            validSource = await validateExistingPath(src, signal);
-            assertAllowedFileAccess(src, validSource);
-        }
-        catch (error) {
-            failed.push(toMoveFailure(src, error, ErrorCode.E_ACCESS_DENIED));
-            continue;
-        }
-        const targetPath = destIsDirectory
-            ? path.join(validDest, path.basename(validSource))
-            : validDest;
-        // Prevent moving a file onto itself
-        if (path.resolve(validSource) === path.resolve(targetPath)) {
-            continue;
-        }
-        // Prevent moving a directory into its own subdirectory
-        // Fixes "Missing validation for moving directory into its own subdirectory" finding
-        if (path.resolve(targetPath).startsWith(path.resolve(validSource) + path.sep)) {
-            failed.push(toMoveFailure(src, new McpError(ErrorCode.E_INVALID_INPUT, `Cannot move directory '${src}' into its own subdirectory '${targetPath}'`, src), ErrorCode.E_INVALID_INPUT));
-            continue;
-        }
-        try {
-            await withAbort(fs.rename(validSource, targetPath), signal);
-            movedSources.push(validSource);
-        }
-        catch (error) {
-            if (isNodeError(error) && error.code === 'EXDEV') {
-                // Cross-device link, fallback to copy + delete
-                try {
-                    await withAbort(fs.cp(validSource, targetPath, { recursive: true }), signal);
-                }
-                catch (copyError) {
-                    failed.push(toMoveFailure(src, copyError));
-                    continue;
-                }
-                // Copy succeeded — now remove source
-                try {
-                    await withAbort(fs.rm(validSource, { recursive: true, force: true }), signal);
-                    movedSources.push(validSource);
-                }
-                catch (deleteError) {
-                    // Source delete failed after copy — rollback by removing the copy
-                    try {
-                        await fs.rm(targetPath, { recursive: true, force: true });
-                    }
-                    catch {
-                        // Rollback failed — data exists in both locations
-                        failed.push(toMoveFailure(src, new McpError(ErrorCode.E_UNKNOWN, `Cross-device move partially failed: data exists at both '${validSource}' and '${targetPath}'. ${formatUnknownErrorMessage(deleteError)}`, src)));
-                        continue;
-                    }
-                    failed.push(toMoveFailure(src, new McpError(ErrorCode.E_UNKNOWN, `Cross-device move failed: could not remove source. ${formatUnknownErrorMessage(deleteError)}`, src)));
-                }
-            }
-            else {
-                failed.push(toMoveFailure(src, error));
-            }
+        await processSingleMove(src, destIsDirectory, validDest, movedSources, failed, signal);
+    }
+    const message = formatMoveMessage(movedSources.length, failed.length, args.destination);
+    const movedSource = sources.length === 1 ? movedSources[0] : undefined;
+    const failedSuffix = failed.length > 0 ? ` (${failed.length} failed)` : '';
+    Logger.info(`mv: ${movedSources.length} item(s) → ${args.destination}${failedSuffix}`);
+    if (movedSources.length === 0 && failed.length > 0) {
+        const firstFailure = failed[0];
+        if (firstFailure) {
+            throw new McpError(firstFailure.error.code, message, firstFailure.error.path);
         }
     }
-    const message = failed.length > 0
-        ? `Moved ${movedSources.length} item${movedSources.length === 1 ? '' : 's'}; failed to move ${failed.length} item${failed.length === 1 ? '' : 's'}`
-        : `Successfully moved ${movedSources.length} item${movedSources.length === 1 ? '' : 's'} to ${args.destination}`;
     return buildToolResponse(message, {
         ok: failed.length === 0,
+        ...(movedSource ? { source: movedSource } : {}),
         sources: movedSources,
         destination: validDest,
         ...(failed.length > 0 ? { failed } : {}),
@@ -128,22 +145,22 @@ export function registerMoveFileTool(server, options = {}) {
         timedSignal: {},
         context: { path: args.source ?? args.sources?.[0] },
         run: (signal) => handleMoveFile(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.source ?? args.sources?.[0]),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.source ?? args.sources?.[0]),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
-            const dest = path.basename(args.destination);
+            const dest = basename(args.destination);
             if (args.source && !args.sources?.length) {
-                return `🛠 mv: ${path.basename(args.source)} → ${dest}`;
+                return `🛠 mv: ${basename(args.source)} → ${dest}`;
             }
             const count = (args.source ? 1 : 0) + (args.sources?.length ?? 0);
             return `🛠 mv: ${count} items → ${dest}`;
         },
         completionMessage: (args, result) => {
-            const dest = path.basename(args.destination);
+            const dest = basename(args.destination);
             if (args.source && !args.sources?.length) {
-                const src = path.basename(args.source);
+                const src = basename(args.source);
                 if (result.isError)
                     return `🛠 mv: ${src} → ${dest} • failed`;
                 return `🛠 mv: ${src} → ${dest}`;

package/dist/tools/read-multiple.js

@@ -1,4 +1,4 @@
-import * as path from 'node:path';
+import { basename } from 'node:path';
 import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { readMultipleFiles } from '../lib/file-operations/metadata.js';
@@ -19,7 +19,7 @@ export const READ_MANY_TOOL = {
     taskSupport: 'optional',
 };
 function buildReadManyResourceName(filePath) {
-    return `read:${path.basename(filePath)}`;
+    return `read:${basename(filePath)}`;
 }
 function toStructuredReadManyResult(result) {
     const structuredResult = {
@@ -72,7 +72,7 @@ function maybeExternalizeReadManyResult(result, resourceStore) {
     const baseResult = {
         ...rest,
         ...(error
-            ? { error: buildStructuredError(error, ErrorCode.E_UNKNOWN, result.path) }
+            ? { error: buildStructuredError(error, ErrorCode.UNKNOWN, result.path) }
             : {}),
         ...(truncationReason ? { truncationReason } : {}),
     };
@@ -191,7 +191,7 @@ export function registerReadMultipleFilesTool(server, options = {}) {
                     throw error;
                 }
             },
-            onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FILE, primaryPath),
+            onError: (error) => buildToolErrorResponse(error, ErrorCode.NOT_FILE, primaryPath),
         });
     };
     const wrappedHandler = wrapToolHandler(handler, {

package/dist/tools/read.js

@@ -1,5 +1,5 @@
-import * as path from 'node:path';
 import { createHash } from 'node:crypto';
+import { basename } from 'node:path';
 import { DEFAULT_SEARCH_TIMEOUT_MS, MAX_TEXT_FILE_SIZE, } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { readFile } from '../lib/fs-helpers.js';
@@ -24,7 +24,7 @@ const READ_TOOL_NAME = 'read';
 const READ_TOOL_LABEL = '🕮 read';
 const FULL_FILE_CONTENTS_DESCRIPTION = 'Full file contents';
 function buildReadResourceName(filePath) {
-    return `read:${path.basename(filePath)}`;
+    return `read:${basename(filePath)}`;
 }
 function buildReadOptions(args, signal) {
     const options = {
@@ -99,7 +99,7 @@ function maybeBuildExternalizedReadResponse(filePath, content, structured, resou
     ]);
 }
 function buildReadProgressMessage(args) {
-    const name = path.basename(args.path);
+    const name = basename(args.path);
     if (args.startLine !== undefined) {
         const end = args.endLine ?? '…';
         return `${READ_TOOL_LABEL}: ${name} [lines ${args.startLine}–${end}]`;
@@ -111,7 +111,7 @@ function buildReadProgressMessage(args) {
     return `${READ_TOOL_LABEL}: ${name}`;
 }
 function buildReadCompletionMessage(args, result) {
-    const name = path.basename(args.path);
+    const name = basename(args.path);
     if (result.isError)
         return `${READ_TOOL_LABEL}: ${name} • failed`;
     const structured = result.structuredContent;
@@ -160,7 +160,7 @@ export function registerReadFileTool(server, options = {}) {
         timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
         context: { path: args.path },
         run: (signal) => handleReadFile(args, signal, options.resourceStore),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FILE, args.path),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.NOT_FILE, args.path),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,

package/dist/tools/replace-in-files.js

@@ -1,15 +1,14 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
 import { Buffer } from 'node:buffer';
+import { open } from 'node:fs/promises';
+import { basename, relative } from 'node:path';
 import { createTwoFilesPatch } from 'diff';
 import RE2 from 're2';
-import safeRegex from 'safe-regex2';
 import { DEFAULT_EXCLUDE_PATTERNS, MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY, } from '../lib/constants.js';
 import { ErrorCode, formatUnknownErrorMessage, McpError, } from '../lib/errors.js';
 import { globEntries } from '../lib/file-operations/traversal.js';
 import { atomicWriteFile } from '../lib/fs-helpers.js';
+import { Logger } from '../lib/logger.js';
 import { validateExistingPath, validatePathForWrite } from '../lib/paths.js';
-import { reportPeriodicProgress } from '../lib/utils.js';
 import { SearchAndReplaceInputSchema, SearchAndReplaceOutputSchema, } from '../schemas.js';
 import { buildStructuredError, buildToolErrorResponse, buildToolResponse, createToolProgressSession, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, resolveFinalProgressCurrent, resolvePathOrRoot, truncateProgressPattern, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
@@ -36,7 +35,7 @@ function recordFailure(failures, failure) {
     failures.push(failure);
 }
 function recordChangedFile(summary, filePath, matchCount) {
-    const relativePath = path.relative(summary.root, filePath);
+    const relativePath = relative(summary.root, filePath);
     if (summary.changedFiles.length < MAX_CHANGED_FILES) {
         summary.changedFiles.push({ path: relativePath, matches: matchCount });
         return;
@@ -49,11 +48,14 @@ function createRegexMatcher(pattern, caseSensitive) {
         return new RE2(pattern, flags);
     }
     catch (error) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, `Invalid regex pattern: ${formatUnknownErrorMessage(error)}`);
+        throw new McpError(ErrorCode.INVALID_PATTERN, `Invalid regex pattern: ${formatUnknownErrorMessage(error)} (RE2: no lookahead/lookbehind/backrefs)`);
     }
 }
 function createRegexReplacementMatcher(regex) {
     return {
+        testBuffer(buffer) {
+            return regex.test(buffer);
+        },
         count(content) {
             regex.lastIndex = 0;
             let matchCount = 0;
@@ -120,7 +122,7 @@ async function processEntry(entryPath, ctx) {
         summary.failedFiles++;
         recordFailure(summary.failures, {
             path: entryPath,
-            error: buildStructuredError(error, ErrorCode.E_UNKNOWN, entryPath),
+            error: buildStructuredError(error, ErrorCode.UNKNOWN, entryPath),
         });
         return;
     }
@@ -149,7 +151,7 @@ async function processEntry(entryPath, ctx) {
         summary.failedFiles++;
         recordFailure(summary.failures, {
             path: validPath,
-            error: buildStructuredError(error, ErrorCode.E_UNKNOWN, validPath),
+            error: buildStructuredError(error, ErrorCode.UNKNOWN, validPath),
         });
     }
 }
@@ -157,7 +159,7 @@ async function readReplacementPlan(validPath, ctx) {
     const { matcher, replacement, maxFileSize, signal } = ctx;
     let fileHandle;
     try {
-        const fd = await fs.open(validPath, 'r');
+        const fd = await open(validPath, 'r');
         fileHandle = fd;
         const stats = await fileHandle.stat();
         if (stats.size > maxFileSize) {
@@ -195,7 +197,7 @@ async function maybeAppendPatchDiff(summary, params) {
     const patch = await new Promise((resolve) => {
         // Defer to event loop to avoid blocking on large diffs
         setImmediate(() => {
-            createTwoFilesPatch(path.basename(params.filePath), path.basename(params.filePath), params.originalContent, params.updatedContent, 'Original', 'Modified', {
+            createTwoFilesPatch(basename(params.filePath), basename(params.filePath), params.originalContent, params.updatedContent, 'Original', 'Modified', {
                 callback: (res) => {
                     resolve(res ?? '');
                 },
@@ -262,9 +264,6 @@ async function resolveSearchRoot(pathValue, signal) {
 function createReplacementRegex(args) {
     if (!args.isRegex)
         return undefined;
-    if (!safeRegex(args.searchPattern)) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, `Unsafe regex pattern: ${args.searchPattern}`);
-    }
     return createRegexMatcher(args.searchPattern, args.caseSensitive);
 }
 function createReplacementMatcher(args) {
@@ -287,7 +286,7 @@ async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
         cwd: root,
         pattern: args.filePattern,
         excludePatterns: args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS,
-        includeHidden: args.includeHidden ?? false,
+        includeHidden: args.includeHidden,
         baseNameMatch: false,
         caseSensitiveMatch: true, // Default to sensitive for file paths
         followSymbolicLinks: false,
@@ -300,7 +299,7 @@ async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
     const context = {
         options: {
             dryRun: args.dryRun,
-            returnDiff: args.returnDiff ?? false,
+            returnDiff: args.returnDiff,
         },
         replacement: args.replacement,
         matcher,
@@ -314,9 +313,7 @@ async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
         ...(args.maxFiles !== undefined ? { maxEntries: args.maxFiles } : {}),
         onEntry: () => {
             summary.processedFiles++;
-            reportPeriodicProgress(onProgress, summary.processedFiles, {
-                throttleModulo: 25,
-            });
+            onProgress({ current: summary.processedFiles });
         },
         runEntry: (entryPath) => processEntry(entryPath, context),
     });
@@ -324,10 +321,10 @@ async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
     if (stoppedByLimit) {
         summary.stoppedReason = 'maxFiles';
     }
-    reportPeriodicProgress(onProgress, summary.processedFiles, {
-        throttleModulo: 25,
-        force: true,
-    });
+    onProgress({ current: summary.processedFiles });
+    if (!args.dryRun && summary.totalMatches > 0) {
+        Logger.info(`search_and_replace: ${summary.filesChanged} file(s), ${summary.totalMatches} match(es)`);
+    }
     return buildToolResponse(buildSearchAndReplaceText(summary, args.dryRun), buildSearchAndReplaceStructuredResult(summary, args));
 }
 export function registerSearchAndReplaceTool(server, options = {}) {
@@ -366,7 +363,7 @@ export function registerSearchAndReplaceTool(server, options = {}) {
                 throw error;
             }
         },
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.path),
     });
     const { isInitialized } = options;
     const wrappedHandler = wrapToolHandler(handler, {

package/dist/tools/roots.js

@@ -36,7 +36,7 @@ export function registerListAllowedDirectoriesTool(server, options = {}) {
         extra,
         outputSchema: ListAllowedDirectoriesOutputSchema,
         run: () => handleListAllowedDirectories(),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,

package/dist/tools/search-content.js

@@ -1,8 +1,8 @@
-import * as path from 'node:path';
+import { relative } from 'node:path';
 import RE2 from 're2';
 import { DEFAULT_EXCLUDE_PATTERNS } from '../lib/constants.js';
 import { ErrorCode, formatUnknownErrorMessage, McpError, } from '../lib/errors.js';
-import { searchContent } from '../lib/file-operations/search.js';
+import { searchContent, } from '../lib/file-operations/search.js';
 import { formatOperationSummary } from '../config.js';
 import { SearchContentInputSchema, SearchContentOutputSchema, } from '../schemas.js';
 import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, resolvePathOrRoot, truncateProgressPattern, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
@@ -50,25 +50,15 @@ function buildCompletionSuffix(count, filesMatched, scope, stoppedReason) {
         : '';
     return `${count} ${matchWord} in ${filesMatched} ${fileWord}${reasonSuffix}`;
 }
-function compareNormalizedMatches(left, right) {
-    const fileCompare = left.relativeFile.localeCompare(right.relativeFile);
-    if (fileCompare !== 0)
-        return fileCompare;
-    if (left.line !== right.line)
-        return left.line - right.line;
-    return left.index - right.index;
-}
-function buildSearchPreviewState(matches, payloads) {
-    const needsExternalize = matches.length > CONFIG.MAX_INLINE_MATCHES;
+function buildSearchPreviewState(payloads) {
+    const needsExternalize = payloads.length > CONFIG.MAX_INLINE_MATCHES;
     const visibleCount = needsExternalize
         ? CONFIG.MAX_INLINE_MATCHES
-        : matches.length;
-    const visibleMatches = matches.slice(0, visibleCount);
+        : payloads.length;
     return {
         needsExternalize,
-        visibleMatches,
         visiblePayloads: payloads.slice(0, visibleCount),
-        heading: buildHeading(matches.length, visibleMatches.length),
+        heading: buildHeading(payloads.length, visibleCount),
     };
 }
 export const SEARCH_CONTENT_TOOL = {
@@ -117,29 +107,21 @@ function buildSearchStructured(summary, matches) {
         ...buildStructuredSummaryFields(summary),
     };
 }
-function normalizeMatches(result) {
+function buildSortedPayloads(result, context) {
     const relativeByFile = new Map();
     const getRelativeFile = (file) => {
         const cached = relativeByFile.get(file);
         if (cached !== undefined)
             return cached;
-        const relative = path.relative(result.basePath, file);
-        relativeByFile.set(file, relative);
-        return relative;
+        const rel = relative(result.basePath, file);
+        relativeByFile.set(file, rel);
+        return rel;
     };
-    return result.matches
-        .map((match, index) => ({
-        ...match,
-        relativeFile: getRelativeFile(match.file),
-        index,
-    }))
-        .sort(compareNormalizedMatches);
-}
-function buildMatchPayloads(matches, context) {
-    return matches.map((match) => {
+    const payloads = result.matches.map((match, originalIndex) => {
+        const relFile = getRelativeFile(match.file);
         const column = findColumnOffset(match.content, context);
-        return {
-            file: match.relativeFile,
+        const payload = {
+            file: relFile,
             line: match.line,
             ...(column !== undefined ? { column } : {}),
             content: match.content,
@@ -149,14 +131,24 @@ function buildMatchPayloads(matches, context) {
                 : {}),
             ...(match.contextAfter ? { contextAfter: [...match.contextAfter] } : {}),
         };
+        return { payload, originalIndex };
+    });
+    payloads.sort((left, right) => {
+        const fileCompare = left.payload.file.localeCompare(right.payload.file);
+        if (fileCompare !== 0)
+            return fileCompare;
+        if (left.payload.line !== right.payload.line)
+            return left.payload.line - right.payload.line;
+        return left.originalIndex - right.originalIndex;
     });
+    return payloads.map((p) => p.payload);
 }
 function buildMatchList(heading, matches) {
     if (matches.length === 0)
         return heading;
     const parts = [heading];
     for (const match of matches) {
-        parts.push(`\n  ${match.relativeFile}:${String(match.line).padStart(4)}: ${match.content}`);
+        parts.push(`\n  ${match.file}:${String(match.line).padStart(4)}: ${match.content}`);
     }
     return parts.join('');
 }
@@ -206,7 +198,7 @@ async function executeSearch(args, basePath, signal, onProgress) {
     }
     catch (error) {
         if (error instanceof Error && /regular expression/i.test(error.message)) {
-            throw new McpError(ErrorCode.E_INVALID_PATTERN, error.message);
+            throw new McpError(ErrorCode.INVALID_PATTERN, `Invalid regex pattern: ${formatUnknownErrorMessage(error)} (RE2: no lookahead/lookbehind/backrefs)`);
         }
         throw error;
     }
@@ -219,7 +211,7 @@ function createSearchMatcher(args) {
         return new RE2(args.pattern, flags);
     }
     catch (error) {
-        throw new McpError(ErrorCode.E_INVALID_PATTERN, `Invalid regex pattern: ${formatUnknownErrorMessage(error)}`);
+        throw new McpError(ErrorCode.INVALID_PATTERN, `Invalid regex pattern: ${formatUnknownErrorMessage(error)} (RE2: no lookahead/lookbehind/backrefs)`);
     }
 }
 function createSearchContext(args, matcher) {
@@ -236,11 +228,10 @@ async function handleSearchContent(args, signal, resourceStore, onProgress) {
     const basePath = resolvePathOrRoot(args.path);
     const regexMatcher = createSearchMatcher(args);
     const result = await executeSearch(args, basePath, signal, onProgress);
-    const normalizedMatches = normalizeMatches(result);
     const searchContext = createSearchContext(args, regexMatcher);
-    const matchPayloads = buildMatchPayloads(normalizedMatches, searchContext);
+    const matchPayloads = buildSortedPayloads(result, searchContext);
     const fullStructured = buildSearchStructured(result.summary, matchPayloads);
-    const preview = buildSearchPreviewState(normalizedMatches, matchPayloads);
+    const preview = buildSearchPreviewState(matchPayloads);
     if (resourceStore && preview.needsExternalize) {
         const previewStructured = {
             ...fullStructured,
@@ -253,7 +244,7 @@ async function handleSearchContent(args, signal, resourceStore, onProgress) {
             text: JSON.stringify(fullStructured),
         });
         previewStructured.resourceUri = entry.uri;
-        const text = buildSearchText(preview.heading, preview.visibleMatches);
+        const text = buildSearchText(preview.heading, preview.visiblePayloads);
         return buildToolResponse(text, previewStructured, [
             buildResourceLink({
                 uri: entry.uri,
@@ -264,7 +255,7 @@ async function handleSearchContent(args, signal, resourceStore, onProgress) {
             }),
         ]);
     }
-    const text = buildSearchText(preview.heading, preview.visibleMatches, result.summary);
+    const text = buildSearchText(preview.heading, preview.visiblePayloads, result.summary);
     return buildToolResponse(text, fullStructured);
 }
 export function registerSearchContentTool(server, options = {}) {
@@ -298,7 +289,7 @@ export function registerSearchContentTool(server, options = {}) {
                 throw error;
             }
         },
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path ?? '.'),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.path ?? '.'),
     });
     const { isInitialized } = options;
     const wrappedHandler = wrapToolHandler(handler, {