@j0hanz/filesystem-mcp 1.1.2 → 1.2.0

package/dist/tools/read-multiple.js

@@ -2,37 +2,24 @@ import * as path from 'node:path';
 import { DEFAULT_READ_MANY_MAX_TOTAL_SIZE, DEFAULT_SEARCH_TIMEOUT_MS, } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { readMultipleFiles } from '../lib/file-operations/read-multiple-files.js';
-import { createTimedAbortSignal } from '../lib/fs-helpers.js';
-import { withToolDiagnostics } from '../lib/observability.js';
-import { ReadMultipleFilesInputSchema, ReadMultipleFilesOutputSchema, } from '../schemas.js';
-import { buildResourceLink, buildToolErrorResponse, buildToolResponse, getExperimentalTaskRegistration, maybeExternalizeTextContent, withDefaultIcons, withToolErrorHandling, wrapToolHandler, } from './shared.js';
-import { createToolTaskHandler } from './task-support.js';
+import { ReadMultipleFilesInputSchema, } from '../schemas.js';
+import { buildResourceLink, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, wrapToolHandler, } from './shared.js';
+import { registerToolTaskIfAvailable } from './task-support.js';
 const READ_MULTIPLE_FILES_TOOL = {
     title: 'Read Multiple Files',
     description: 'Read multiple text files in a single request. ' +
         'Returns contents and metadata for each file. ' +
         'For single file, use read for simpler output.',
     inputSchema: ReadMultipleFilesInputSchema,
-    outputSchema: ReadMultipleFilesOutputSchema,
-    annotations: {
-        readOnlyHint: true,
-        idempotentHint: true,
-        openWorldHint: false,
-    },
+    annotations: READ_ONLY_TOOL_ANNOTATIONS,
 };
 async function handleReadMultipleFiles(args, signal, resourceStore) {
     const options = {
         ...(signal ? { signal } : {}),
+        ...(args.head !== undefined ? { head: args.head } : {}),
+        ...(args.startLine !== undefined ? { startLine: args.startLine } : {}),
+        ...(args.endLine !== undefined ? { endLine: args.endLine } : {}),
     };
-    if (args.head !== undefined) {
-        options.head = args.head;
-    }
-    if (args.startLine !== undefined) {
-        options.startLine = args.startLine;
-    }
-    if (args.endLine !== undefined) {
-        options.endLine = args.endLine;
-    }
     const results = await readMultipleFiles(args.paths, options);
     const maxTotalSize = DEFAULT_READ_MANY_MAX_TOTAL_SIZE;
     const mappedResults = results.map((result) => {
@@ -65,78 +52,79 @@ async function handleReadMultipleFiles(args, signal, resourceStore) {
             truncationReason: 'externalized',
         };
     });
+    let succeeded = 0;
+    let failed = 0;
+    for (const result of mappedResults) {
+        if (result.error === undefined)
+            succeeded += 1;
+        else
+            failed += 1;
+    }
     const structured = {
         ok: true,
         results: mappedResults.map((result) => ({
             path: result.path,
-            content: result.content,
-            truncated: result.truncated,
-            resourceUri: result.resourceUri,
-            readMode: result.readMode,
-            head: result.head,
-            startLine: result.startLine,
-            endLine: result.endLine,
-            linesRead: result.linesRead,
-            hasMoreLines: result.hasMoreLines,
-            totalLines: result.totalLines,
-            truncationReason: result.truncationReason,
-            maxTotalSize: result.maxTotalSize,
-            error: result.error,
+            ...(result.content !== undefined ? { content: result.content } : {}),
+            ...(result.truncated ? { truncated: result.truncated } : {}),
+            ...(result.resourceUri ? { resourceUri: result.resourceUri } : {}),
+            ...(result.head !== undefined ? { head: result.head } : {}),
+            ...(result.startLine !== undefined
+                ? { startLine: result.startLine }
+                : {}),
+            ...(result.endLine !== undefined ? { endLine: result.endLine } : {}),
+            ...(result.hasMoreLines ? { hasMoreLines: result.hasMoreLines } : {}),
+            ...(result.totalLines !== undefined
+                ? { totalLines: result.totalLines }
+                : {}),
+            ...(result.truncationReason
+                ? { truncationReason: result.truncationReason }
+                : {}),
+            ...(result.error ? { error: result.error } : {}),
         })),
         summary: {
             total: mappedResults.length,
-            succeeded: mappedResults.filter((r) => r.error === undefined).length,
-            failed: mappedResults.filter((r) => r.error !== undefined).length,
+            succeeded,
+            failed,
         },
     };
-    const resourceLinks = mappedResults.flatMap((result) => {
+    const resourceLinks = [];
+    for (const result of mappedResults) {
         if (!result.resourceUri)
-            return [];
-        return [
-            buildResourceLink({
-                uri: result.resourceUri,
-                name: `read:${path.basename(result.path)}`,
-                description: 'Full file contents',
-            }),
-        ];
-    });
+            continue;
+        resourceLinks.push(buildResourceLink({
+            uri: result.resourceUri,
+            name: `read:${path.basename(result.path)}`,
+            description: 'Full file contents',
+        }));
+    }
     const text = mappedResults
         .map((result) => {
+        const header = `=== ${result.path} ===`;
         if (result.error) {
-            return `${result.path}: ${result.error}`;
+            return `${header}\nError: ${result.error}`;
         }
-        return result.path;
+        return `${header}\n${result.content ?? ''}`;
     })
-        .join('\n');
-    return buildToolResponse(text, structured, resourceLinks, resourceStore);
+        .join('\n\n');
+    return buildToolResponse(text, structured, resourceLinks);
 }
 export function registerReadMultipleFilesTool(server, options = {}) {
     const handler = (args, extra) => {
         const primaryPath = args.paths[0] ?? '';
-        return withToolDiagnostics('read_many', () => withToolErrorHandling(async () => {
-            const { signal, cleanup } = createTimedAbortSignal(extra.signal, DEFAULT_SEARCH_TIMEOUT_MS);
-            try {
-                return await handleReadMultipleFiles(args, signal, options.resourceStore);
-            }
-            finally {
-                cleanup();
-            }
-        }, (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FILE, primaryPath)), { path: primaryPath });
+        return executeToolWithDiagnostics({
+            toolName: 'read_many',
+            extra,
+            timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
+            context: { path: primaryPath },
+            run: (signal) => handleReadMultipleFiles(args, signal, options.resourceStore),
+            onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FILE, primaryPath),
+        });
     };
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => `🕮 read_many: ${args.paths.length} files`,
     });
-    const taskOptions = options.isInitialized
-        ? { guard: options.isInitialized }
-        : undefined;
-    const tasks = getExperimentalTaskRegistration(server);
-    if (tasks?.registerToolTask) {
-        tasks.registerToolTask('read_many', withDefaultIcons({
-            ...READ_MULTIPLE_FILES_TOOL,
-            execution: { taskSupport: 'optional' },
-        }, options.iconInfo), createToolTaskHandler(wrappedHandler, taskOptions));
+    if (registerToolTaskIfAvailable(server, 'read_many', READ_MULTIPLE_FILES_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
         return;
-    }
     server.registerTool('read_many', withDefaultIcons({ ...READ_MULTIPLE_FILES_TOOL }, options.iconInfo), wrappedHandler);
 }

package/dist/tools/read.js

@@ -2,22 +2,16 @@ import * as path 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';
-import { createTimedAbortSignal } from '../lib/fs-helpers.js';
-import { withToolDiagnostics } from '../lib/observability.js';
-import { ReadFileInputSchema, ReadFileOutputSchema } from '../schemas.js';
-import { buildResourceLink, buildToolErrorResponse, buildToolResponse, maybeExternalizeTextContent, withDefaultIcons, withToolErrorHandling, wrapToolHandler, } from './shared.js';
+import { ReadFileInputSchema } from '../schemas.js';
+import { buildResourceLink, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, wrapToolHandler, } from './shared.js';
+import { registerToolTaskIfAvailable } from './task-support.js';
 const READ_FILE_TOOL = {
     title: 'Read File',
     description: 'Read the text contents of a file. ' +
         'Use head parameter to preview the first N lines of large files. ' +
         'For multiple files, use read_many for efficiency.',
     inputSchema: ReadFileInputSchema,
-    outputSchema: ReadFileOutputSchema,
-    annotations: {
-        readOnlyHint: true,
-        idempotentHint: true,
-        openWorldHint: false,
-    },
+    annotations: READ_ONLY_TOOL_ANNOTATIONS,
 };
 async function handleReadFile(args, signal, resourceStore) {
     const options = {
@@ -42,19 +36,18 @@ async function handleReadFile(args, signal, resourceStore) {
         ok: true,
         path: args.path,
         content: result.content,
-        truncated: result.truncated,
-        resourceUri: undefined,
-        totalLines: result.totalLines,
-        readMode: result.readMode,
-        head: result.head,
-        startLine: result.startLine,
-        endLine: result.endLine,
-        linesRead: result.linesRead,
-        hasMoreLines: result.hasMoreLines,
+        ...(result.truncated ? { truncated: result.truncated } : {}),
+        ...(result.totalLines !== undefined
+            ? { totalLines: result.totalLines }
+            : {}),
+        ...(result.head !== undefined ? { head: result.head } : {}),
+        ...(result.startLine !== undefined ? { startLine: result.startLine } : {}),
+        ...(result.endLine !== undefined ? { endLine: result.endLine } : {}),
+        ...(result.hasMoreLines ? { hasMoreLines: result.hasMoreLines } : {}),
     };
     const externalized = maybeExternalizeTextContent(resourceStore, result.content, { name: `read:${path.basename(args.path)}`, mimeType: 'text/plain' });
     if (!externalized) {
-        return buildToolResponse(result.content, structured, [], resourceStore);
+        return buildToolResponse(result.content, structured);
     }
     const { entry, preview } = externalized;
     const structuredWithResource = {
@@ -75,19 +68,18 @@ async function handleReadFile(args, signal, resourceStore) {
             mimeType: entry.mimeType,
             description: 'Full file contents',
         }),
-    ], resourceStore);
+    ]);
 }
 export function registerReadFileTool(server, options = {}) {
-    const handler = (args, extra) => withToolDiagnostics('read', () => withToolErrorHandling(async () => {
-        const { signal, cleanup } = createTimedAbortSignal(extra.signal, DEFAULT_SEARCH_TIMEOUT_MS);
-        try {
-            return await handleReadFile(args, signal, options.resourceStore);
-        }
-        finally {
-            cleanup();
-        }
-    }, (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FILE, args.path)), { path: args.path });
-    server.registerTool('read', withDefaultIcons({ ...READ_FILE_TOOL }, options.iconInfo), wrapToolHandler(handler, {
+    const handler = (args, extra) => executeToolWithDiagnostics({
+        toolName: 'read',
+        extra,
+        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),
+    });
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name = path.basename(args.path);
@@ -97,5 +89,8 @@ export function registerReadFileTool(server, options = {}) {
             }
             return `🕮 read: ${name}`;
         },
-    }));
+    });
+    if (registerToolTaskIfAvailable(server, 'read', READ_FILE_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+        return;
+    server.registerTool('read', withDefaultIcons({ ...READ_FILE_TOOL }, options.iconInfo), wrappedHandler);
 }

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

@@ -2,24 +2,23 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import RE2 from 're2';
 import safeRegex from 'safe-regex2';
-import { MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY } from '../lib/constants.js';
+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/glob-engine.js';
-import { atomicWriteFile, createTimedAbortSignal, withAbort, } from '../lib/fs-helpers.js';
-import { withToolDiagnostics } from '../lib/observability.js';
+import { atomicWriteFile, withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath, validatePathForWrite, } from '../lib/path-validation.js';
-import { SearchAndReplaceInputSchema, SearchAndReplaceOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, createProgressReporter, getExperimentalTaskRegistration, notifyProgress, resolvePathOrRoot, withDefaultIcons, withToolErrorHandling, wrapToolHandler, } from './shared.js';
-import { createToolTaskHandler } from './task-support.js';
+import { SearchAndReplaceInputSchema, } from '../schemas.js';
+import { buildToolErrorResponse, buildToolResponse, createProgressReporter, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, notifyProgress, resolvePathOrRoot, withDefaultIcons, wrapToolHandler, } from './shared.js';
+import { registerToolTaskIfAvailable } from './task-support.js';
 const SEARCH_AND_REPLACE_TOOL = {
     title: 'Search and Replace',
-    description: 'Search and replace text across multiple files.',
+    description: 'Search and replace text across multiple files matching a glob pattern. ' +
+        'Replaces ALL occurrences in each file (unlike `edit` which replaces only the first). ' +
+        'Use `filePattern` to scope which files are touched. ' +
+        'Always run with `dryRun: true` first to verify matches before writing. ' +
+        'Literal mode (default) matches exact text; `isRegex: true` enables RE2 regex with capture groups ($1, $2).',
     inputSchema: SearchAndReplaceInputSchema,
-    outputSchema: SearchAndReplaceOutputSchema,
-    annotations: {
-        readOnlyHint: false,
-        openWorldHint: false,
-    },
+    annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
 };
 const MAX_FAILURES = 20;
 const REPLACE_CONCURRENCY = Math.min(PARALLEL_CONCURRENCY, 8);
@@ -110,7 +109,7 @@ async function processEntry(entryPath, args, regex, maxFileSize, signal, summary
                     newContent = content.replace(regex, args.replacement);
                 }
                 else {
-                    newContent = content.replaceAll(args.searchPattern, args.replacement);
+                    newContent = content.replaceAll(args.searchPattern, () => args.replacement);
                 }
                 await atomicWriteFile(validPath, newContent, {
                     encoding: 'utf-8',
@@ -183,13 +182,13 @@ function reportReplaceProgress(onProgress, current, force = false) {
     onProgress({ current });
 }
 async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
-    const maxFileSize = args.maxFileSize ?? MAX_TEXT_FILE_SIZE;
+    const maxFileSize = MAX_TEXT_FILE_SIZE;
     const root = await resolveSearchRoot(args.path, signal);
     const regex = createReplacementRegex(args);
     const entries = globEntries({
         cwd: root,
         pattern: args.filePattern,
-        excludePatterns: args.excludePatterns,
+        excludePatterns: DEFAULT_EXCLUDE_PATTERNS,
         includeHidden: false,
         baseNameMatch: false,
         caseSensitiveMatch: true, // Default to sensitive for file paths
@@ -225,13 +224,16 @@ async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
     });
 }
 export function registerSearchAndReplaceTool(server, options = {}) {
-    const handler = (args, extra) => withToolDiagnostics('search_and_replace', () => withToolErrorHandling(async () => {
-        notifyProgress(extra, {
-            current: 0,
-            message: `🛠 search_and_replace: ${args.filePattern}`,
-        });
-        const { signal, cleanup } = createTimedAbortSignal(extra.signal);
-        try {
+    const handler = (args, extra) => executeToolWithDiagnostics({
+        toolName: 'search_and_replace',
+        extra,
+        timedSignal: {},
+        ...(args.path ? { context: { path: args.path } } : {}),
+        run: async (signal) => {
+            notifyProgress(extra, {
+                current: 0,
+                message: `🛠 search_and_replace: ${args.filePattern}`,
+            });
             const result = await handleSearchAndReplace(args, signal, createProgressReporter(extra));
             const sc = result.structuredContent;
             const finalCurrent = (sc.processedFiles ?? 0) + 1;
@@ -240,23 +242,14 @@ export function registerSearchAndReplaceTool(server, options = {}) {
                 message: `🛠 search_and_replace: ${args.filePattern} ➟ ${String(sc.filesChanged ?? 0)} files`,
             });
             return result;
-        }
-        finally {
-            cleanup();
-        }
-    }, (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path)), args.path ? { path: args.path } : {});
+        },
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
+    });
     const { isInitialized } = options;
     const wrappedHandler = wrapToolHandler(handler, {
         guard: isInitialized,
     });
-    const taskOptions = isInitialized ? { guard: isInitialized } : undefined;
-    const tasks = getExperimentalTaskRegistration(server);
-    if (tasks?.registerToolTask) {
-        tasks.registerToolTask('search_and_replace', withDefaultIcons({
-            ...SEARCH_AND_REPLACE_TOOL,
-            execution: { taskSupport: 'optional' },
-        }, options.iconInfo), createToolTaskHandler(wrappedHandler, taskOptions));
+    if (registerToolTaskIfAvailable(server, 'search_and_replace', SEARCH_AND_REPLACE_TOOL, wrappedHandler, options.iconInfo, isInitialized))
         return;
-    }
     server.registerTool('search_and_replace', withDefaultIcons({ ...SEARCH_AND_REPLACE_TOOL }, options.iconInfo), wrappedHandler);
 }

package/dist/tools/roots.js

@@ -1,21 +1,15 @@
 import { joinLines } from '../config.js';
 import { ErrorCode } from '../lib/errors.js';
-import { withToolDiagnostics } from '../lib/observability.js';
 import { getAllowedDirectories } from '../lib/path-validation.js';
-import { ListAllowedDirectoriesInputSchema, ListAllowedDirectoriesOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, withDefaultIcons, withToolErrorHandling, wrapToolHandler, } from './shared.js';
+import { ListAllowedDirectoriesInputSchema, } from '../schemas.js';
+import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, wrapToolHandler, } from './shared.js';
 const LIST_ALLOWED_DIRECTORIES_TOOL = {
     title: 'Workspace Roots',
     description: 'List the workspace roots this server can access. ' +
         'Call this first to see available directories. ' +
         'All other tools only work within these directories.',
     inputSchema: ListAllowedDirectoriesInputSchema,
-    outputSchema: ListAllowedDirectoriesOutputSchema,
-    annotations: {
-        readOnlyHint: true,
-        idempotentHint: true,
-        openWorldHint: false,
-    },
+    annotations: READ_ONLY_TOOL_ANNOTATIONS,
 };
 function buildTextRoots(dirs) {
     if (dirs.length === 0) {
@@ -37,7 +31,12 @@ function handleListAllowedDirectories() {
     return buildToolResponse(buildTextRoots(dirs), structured);
 }
 export function registerListAllowedDirectoriesTool(server, options = {}) {
-    const handler = () => withToolErrorHandling(() => withToolDiagnostics('roots', () => Promise.resolve(handleListAllowedDirectories())), (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN));
+    const handler = (_args, extra) => executeToolWithDiagnostics({
+        toolName: 'roots',
+        extra,
+        run: () => handleListAllowedDirectories(),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN),
+    });
     server.registerTool('roots', withDefaultIcons({ ...LIST_ALLOWED_DIRECTORIES_TOOL }, options.iconInfo), wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: () => '≣ roots',

package/dist/tools/search-content.js

@@ -4,24 +4,19 @@ import { formatOperationSummary, joinLines } from '../config.js';
 import { DEFAULT_EXCLUDE_PATTERNS } from '../lib/constants.js';
 import { ErrorCode, formatUnknownErrorMessage, McpError, } from '../lib/errors.js';
 import { searchContent } from '../lib/file-operations/search-content.js';
-import { withToolDiagnostics } from '../lib/observability.js';
-import { SearchContentInputSchema, SearchContentOutputSchema, } from '../schemas.js';
-import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createProgressReporter, getExperimentalTaskRegistration, notifyProgress, resolvePathOrRoot, withDefaultIcons, withToolErrorHandling, wrapToolHandler, } from './shared.js';
-import { createToolTaskHandler } from './task-support.js';
+import { SearchContentInputSchema, } from '../schemas.js';
+import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, wrapToolHandler, } from './shared.js';
+import { registerToolTaskIfAvailable } from './task-support.js';
 const MAX_INLINE_MATCHES = 50;
 const SEARCH_CONTENT_TOOL = {
     title: 'Search Content',
     description: 'Search for text within file contents (grep-like). ' +
         'Returns matching lines. ' +
         'Path may be a directory or a single file. ' +
+        'Use `filePattern` to scope by file type (e.g. `**/*.ts`) and avoid noisy results. ' +
         'Use includeHidden=true to include hidden files and directories.',
     inputSchema: SearchContentInputSchema,
-    outputSchema: SearchContentOutputSchema,
-    annotations: {
-        readOnlyHint: true,
-        idempotentHint: true,
-        openWorldHint: false,
-    },
+    annotations: READ_ONLY_TOOL_ANNOTATIONS,
 };
 function assertValidRegexPattern(pattern) {
     try {
@@ -73,35 +68,47 @@ function formatSearchMatchLine(match) {
 }
 function buildStructuredSearchResult(result, normalizedMatches, options) {
     const { summary } = result;
+    const matches = [];
+    for (const match of normalizedMatches) {
+        matches.push(buildSearchMatchPayload(match));
+    }
     return {
         ok: true,
         patternType: options.patternType,
         caseSensitive: options.caseSensitive,
-        matches: normalizedMatches.map(buildSearchMatchPayload),
+        matches,
         totalMatches: summary.matches,
-        truncated: summary.truncated,
-        filesScanned: summary.filesScanned,
-        filesMatched: summary.filesMatched,
-        skippedTooLarge: summary.skippedTooLarge,
-        skippedBinary: summary.skippedBinary,
-        skippedInaccessible: summary.skippedInaccessible,
-        linesSkippedDueToRegexTimeout: summary.linesSkippedDueToRegexTimeout,
+        ...(summary.truncated ? { truncated: summary.truncated } : {}),
+        ...(summary.filesMatched ? { filesMatched: summary.filesMatched } : {}),
+        ...(summary.skippedTooLarge
+            ? { skippedTooLarge: summary.skippedTooLarge }
+            : {}),
+        ...(summary.skippedBinary ? { skippedBinary: summary.skippedBinary } : {}),
+        ...(summary.skippedInaccessible
+            ? { skippedInaccessible: summary.skippedInaccessible }
+            : {}),
+        ...(summary.linesSkippedDueToRegexTimeout
+            ? { linesSkippedDueToRegexTimeout: summary.linesSkippedDueToRegexTimeout }
+            : {}),
         ...(summary.stoppedReason ? { stoppedReason: summary.stoppedReason } : {}),
     };
 }
 function normalizeSearchMatches(result) {
     const relativeByFile = new Map();
-    const normalized = result.matches.map((match, index) => {
+    const normalized = [];
+    let index = 0;
+    for (const match of result.matches) {
         const cached = relativeByFile.get(match.file);
         const relative = cached ?? path.relative(result.basePath, match.file);
         if (!cached)
             relativeByFile.set(match.file, relative);
-        return {
+        normalized.push({
             ...match,
             relativeFile: relative,
             index,
-        };
-    });
+        });
+        index += 1;
+    }
     normalized.sort((a, b) => {
         const fileCompare = a.relativeFile.localeCompare(b.relativeFile);
         if (fileCompare !== 0)
@@ -127,7 +134,6 @@ async function handleSearchContent(args, signal, resourceStore, onProgress) {
         wholeWord: args.wholeWord,
         contextLines: args.contextLines,
         maxResults: args.maxResults,
-        maxFilesScanned: args.maxFilesScanned,
         isLiteral: !args.isRegex,
     };
     if (signal) {
@@ -156,22 +162,14 @@ async function handleSearchContent(args, signal, resourceStore, onProgress) {
         return buildToolResponse(buildSearchTextResult(result, normalizedMatches), structuredFull);
     }
     const previewMatches = normalizedMatches.slice(0, MAX_INLINE_MATCHES);
+    const previewPayload = [];
+    for (const match of previewMatches) {
+        previewPayload.push(buildSearchMatchPayload(match));
+    }
     const previewStructured = {
-        ok: true,
-        patternType,
-        caseSensitive: args.caseSensitive,
-        matches: previewMatches.map(buildSearchMatchPayload),
-        totalMatches: structuredFull.totalMatches,
+        ...structuredFull,
+        matches: previewPayload,
         truncated: true,
-        filesScanned: structuredFull.filesScanned,
-        filesMatched: structuredFull.filesMatched,
-        skippedTooLarge: structuredFull.skippedTooLarge,
-        skippedBinary: structuredFull.skippedBinary,
-        skippedInaccessible: structuredFull.skippedInaccessible,
-        linesSkippedDueToRegexTimeout: structuredFull.linesSkippedDueToRegexTimeout,
-        ...(structuredFull.stoppedReason
-            ? { stoppedReason: structuredFull.stoppedReason }
-            : {}),
         resourceUri: undefined,
     };
     const entry = resourceStore.putText({
@@ -180,10 +178,13 @@ async function handleSearchContent(args, signal, resourceStore, onProgress) {
         text: JSON.stringify(structuredFull),
     });
     previewStructured.resourceUri = entry.uri;
-    const text = joinLines([
+    const textLines = [
         `Found ${normalizedMatches.length} (showing first ${MAX_INLINE_MATCHES}):`,
-        ...previewMatches.map(formatSearchMatchLine),
-    ]);
+    ];
+    for (const match of previewMatches) {
+        textLines.push(formatSearchMatchLine(match));
+    }
+    const text = joinLines(textLines);
     return buildToolResponse(text, previewStructured, [
         buildResourceLink({
             uri: entry.uri,
@@ -194,44 +195,43 @@ async function handleSearchContent(args, signal, resourceStore, onProgress) {
     ]);
 }
 export function registerSearchContentTool(server, options = {}) {
-    const handler = (args, extra) => withToolDiagnostics('grep', () => withToolErrorHandling(async () => {
-        const normalizedArgs = SearchContentInputSchema.parse(args);
-        notifyProgress(extra, {
-            current: 0,
-            message: `🔎︎ grep: ${normalizedArgs.pattern}`,
-        });
-        const result = await handleSearchContent(normalizedArgs, extra.signal, options.resourceStore, createProgressReporter(extra));
-        const sc = result.structuredContent;
-        const count = sc.ok && sc.totalMatches ? sc.totalMatches : 0;
-        let suffix;
-        if (count === 0) {
-            suffix = 'No matches';
-        }
-        else if (count === 1) {
-            suffix = '1 match';
-        }
-        else {
-            suffix = `${count} matches`;
-        }
-        const finalCurrent = (sc.filesScanned ?? 0) + 1;
-        notifyProgress(extra, {
-            current: finalCurrent,
-            message: `🔎︎ grep: ${normalizedArgs.pattern} ➟ ${suffix}`,
-        });
-        return result;
-    }, (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path ?? '.')), { path: args.path ?? '.' });
+    const handler = (args, extra) => executeToolWithDiagnostics({
+        toolName: 'grep',
+        extra,
+        context: { path: args.path ?? '.' },
+        run: async (signal) => {
+            const normalizedArgs = SearchContentInputSchema.parse(args);
+            notifyProgress(extra, {
+                current: 0,
+                message: `🔎︎ grep: ${normalizedArgs.pattern}`,
+            });
+            const result = await handleSearchContent(normalizedArgs, signal, options.resourceStore, createProgressReporter(extra));
+            const sc = result.structuredContent;
+            const count = sc.ok && sc.totalMatches ? sc.totalMatches : 0;
+            let suffix;
+            if (count === 0) {
+                suffix = 'No matches';
+            }
+            else if (count === 1) {
+                suffix = '1 match';
+            }
+            else {
+                suffix = `${count} matches`;
+            }
+            const finalCurrent = (sc.filesScanned ?? 0) + 1;
+            notifyProgress(extra, {
+                current: finalCurrent,
+                message: `🔎︎ grep: ${normalizedArgs.pattern} ➟ ${suffix}`,
+            });
+            return result;
+        },
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path ?? '.'),
+    });
     const { isInitialized } = options;
     const wrappedHandler = wrapToolHandler(handler, {
         guard: isInitialized,
     });
-    const taskOptions = isInitialized ? { guard: isInitialized } : undefined;
-    const tasks = getExperimentalTaskRegistration(server);
-    if (tasks?.registerToolTask) {
-        tasks.registerToolTask('grep', withDefaultIcons({
-            ...SEARCH_CONTENT_TOOL,
-            execution: { taskSupport: 'optional' },
-        }, options.iconInfo), createToolTaskHandler(wrappedHandler, taskOptions));
+    if (registerToolTaskIfAvailable(server, 'grep', SEARCH_CONTENT_TOOL, wrappedHandler, options.iconInfo, isInitialized))
         return;
-    }
     server.registerTool('grep', withDefaultIcons({ ...SEARCH_CONTENT_TOOL }, options.iconInfo), wrappedHandler);
 }