@j0hanz/filesystem-mcp 1.6.1 → 1.7.0

package/dist/tools/calculate-hash.js

@@ -9,7 +9,7 @@ import { globEntries } from '../lib/file-operations/glob-engine.js';
 import { assertNotAborted, withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath } from '../lib/path-validation.js';
 import { CalculateHashInputSchema, CalculateHashOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const WINDOWS_PATH_SEPARATOR = /\\/gu;
 export const CALCULATE_HASH_TOOL = {
@@ -158,17 +158,10 @@ export function registerCalculateHashTool(server, options = {}) {
         context: { path: args.path },
         run: async (signal) => {
             const baseName = path.basename(args.path);
-            let progressCursor = 0;
-            notifyProgress(extra, {
-                current: 0,
-                message: `🕮 calculate_hash: ${baseName}`,
-            });
-            const baseReporter = createProgressReporter(extra);
+            const progress = createToolProgressSession(extra, `🕮 calculate_hash: ${baseName}`);
             const progressWithMessage = ({ current, total, }) => {
-                if (current > progressCursor)
-                    progressCursor = current;
                 const fileWord = current === 1 ? 'file' : 'files';
-                baseReporter({
+                progress.update({
                     current,
                     ...(total !== undefined ? { total } : {}),
                     message: `🕮 calculate_hash: ${baseName} [${current} ${fileWord} hashed]`,
@@ -178,7 +171,7 @@ export function registerCalculateHashTool(server, options = {}) {
                 const result = await handleCalculateHash(args, signal, progressWithMessage);
                 const sc = result.structuredContent;
                 const totalFiles = sc.ok ? (sc.fileCount ?? 1) : 1;
-                const finalCurrent = Math.max(totalFiles + 1, progressCursor + 1);
+                const finalCurrent = Math.max(totalFiles + 1, progress.getCurrent() + 1);
                 let suffix;
                 if (!sc.ok) {
                     suffix = 'failed';
@@ -189,20 +182,11 @@ export function registerCalculateHashTool(server, options = {}) {
                 else {
                     suffix = `${(sc.hash ?? '').slice(0, 8)}...`;
                 }
-                notifyProgress(extra, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `🕮 calculate_hash: ${baseName} • ${suffix}`,
-                });
+                progress.complete(`🕮 calculate_hash: ${baseName} • ${suffix}`, finalCurrent);
                 return result;
             }
             catch (error) {
-                const finalCurrent = Math.max(progressCursor + 1, 1);
-                notifyProgress(extra, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `🕮 calculate_hash: ${baseName} • failed`,
-                });
+                progress.fail(`🕮 calculate_hash: ${baseName} • failed`);
                 throw error;
             }
         },

package/dist/tools/read-multiple.js

@@ -3,7 +3,7 @@ import { DEFAULT_READ_MANY_MAX_TOTAL_SIZE, DEFAULT_SEARCH_TIMEOUT_MS, } from '..
 import { ErrorCode } from '../lib/errors.js';
 import { readMultipleFiles } from '../lib/file-operations/read-multiple-files.js';
 import { ReadMultipleFilesInputSchema, ReadMultipleFilesOutputSchema, } from '../schemas.js';
-import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, maybeExternalizeTextContent, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const READ_MULTIPLE_FILES_TOOL = {
     name: 'read_many',
@@ -20,6 +20,33 @@ export const READ_MULTIPLE_FILES_TOOL = {
         'Per-file `truncationReason` can be `head`, `range`, or `externalized`.',
     ],
 };
+function toStructuredReadManyResult(result) {
+    const structured = {
+        path: result.path,
+    };
+    if (result.content !== undefined)
+        structured.content = result.content;
+    if (result.truncated)
+        structured.truncated = result.truncated;
+    if (result.resourceUri)
+        structured.resourceUri = result.resourceUri;
+    if (result.head !== undefined)
+        structured.head = result.head;
+    if (result.startLine !== undefined)
+        structured.startLine = result.startLine;
+    if (result.endLine !== undefined)
+        structured.endLine = result.endLine;
+    if (result.hasMoreLines)
+        structured.hasMoreLines = result.hasMoreLines;
+    if (result.totalLines !== undefined)
+        structured.totalLines = result.totalLines;
+    if (result.truncationReason) {
+        structured.truncationReason = result.truncationReason;
+    }
+    if (result.error)
+        structured.error = result.error;
+    return structured;
+}
 async function handleReadMultipleFiles(args, signal, resourceStore, onReadComplete) {
     const options = {
         ...(signal ? { signal } : {}),
@@ -70,25 +97,7 @@ async function handleReadMultipleFiles(args, signal, resourceStore, onReadComple
     }
     const structured = {
         ok: true,
-        results: mappedResults.map((result) => ({
-            path: result.path,
-            ...(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 } : {}),
-        })),
+        results: mappedResults.map((result) => toStructuredReadManyResult(result)),
         summary: {
             total: mappedResults.length,
             succeeded,
@@ -130,18 +139,9 @@ export function registerReadMultipleFilesTool(server, options = {}) {
                     ? `, ${path.basename(args.paths[1] ?? '')}${args.paths.length > 2 ? '…' : ''}`
                     : '';
                 const context = `${args.paths.length} files [${first}${extraPaths}]`;
-                let progressCursor = 0;
-                notifyProgress(extra, {
-                    current: 0,
-                    message: `🕮 read_many: ${context}`,
-                });
-                const baseReporter = createProgressReporter(extra);
+                const progress = createToolProgressSession(extra, `🕮 read_many: ${context}`);
                 const onReadComplete = () => {
-                    progressCursor++;
-                    baseReporter({
-                        current: progressCursor,
-                        message: `🕮 read_many: ${context} [${progressCursor}/${args.paths.length} read]`,
-                    });
+                    progress.increment((current) => `🕮 read_many: ${context} [${current}/${args.paths.length} read]`);
                 };
                 try {
                     const result = await handleReadMultipleFiles(args, signal, options.resourceStore, onReadComplete);
@@ -156,21 +156,12 @@ export function registerReadMultipleFilesTool(server, options = {}) {
                     else {
                         suffix = `${total} files read`;
                     }
-                    const finalCurrent = Math.max(total, progressCursor + 1);
-                    notifyProgress(extra, {
-                        current: finalCurrent,
-                        total: finalCurrent,
-                        message: `🕮 read_many: ${context} • ${suffix}`,
-                    });
+                    const finalCurrent = Math.max(total, progress.getCurrent() + 1);
+                    progress.complete(`🕮 read_many: ${context} • ${suffix}`, finalCurrent);
                     return result;
                 }
                 catch (error) {
-                    const finalCurrent = Math.max(progressCursor + 1, 1);
-                    notifyProgress(extra, {
-                        current: finalCurrent,
-                        total: finalCurrent,
-                        message: `🕮 read_many: ${context} • failed`,
-                    });
+                    progress.fail(`🕮 read_many: ${context} • failed`);
                     throw error;
                 }
             },

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

@@ -9,7 +9,7 @@ import { globEntries } from '../lib/file-operations/glob-engine.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, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, notifyProgress, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const SEARCH_AND_REPLACE_TOOL = {
     name: 'search_and_replace',
@@ -56,31 +56,42 @@ function createRegexMatcher(pattern) {
         throw new McpError(ErrorCode.E_INVALID_INPUT, `Invalid regex pattern: ${formatUnknownErrorMessage(error)}`);
     }
 }
-function countRegexMatches(content, regex) {
-    regex.lastIndex = 0;
-    let count = 0;
-    while (regex.exec(content) !== null) {
-        count++;
-        if (regex.lastIndex === 0) {
-            regex.lastIndex++;
+function createRegexReplacementMatcher(regex) {
+    const count = (content) => {
+        regex.lastIndex = 0;
+        let matchCount = 0;
+        while (regex.exec(content) !== null) {
+            matchCount++;
+            if (regex.lastIndex === 0) {
+                regex.lastIndex++;
+            }
         }
-    }
-    return count;
+        return matchCount;
+    };
+    const replace = (content, replacement) => {
+        regex.lastIndex = 0;
+        return content.replace(regex, replacement);
+    };
+    return { count, replace };
 }
-function countLiteralMatches(content, searchPattern) {
-    let count = 0;
-    let pos = content.indexOf(searchPattern);
-    const patternLength = searchPattern.length;
-    while (pos !== -1) {
-        count++;
-        pos = content.indexOf(searchPattern, pos + patternLength);
-    }
-    return count;
+function createLiteralReplacementMatcher(searchPattern) {
+    const count = (content) => {
+        let matchCount = 0;
+        let pos = content.indexOf(searchPattern);
+        const patternLength = searchPattern.length;
+        while (pos !== -1) {
+            matchCount++;
+            pos = content.indexOf(searchPattern, pos + patternLength);
+        }
+        return matchCount;
+    };
+    const replace = (content, replacement) => content.replaceAll(searchPattern, () => replacement);
+    return { count, replace };
 }
 function formatFileTooLargeError(filePath, size, maxFileSize) {
     return `File too large: ${filePath} (${size} bytes > ${maxFileSize} bytes)`;
 }
-async function processEntry(entryPath, args, regex, maxFileSize, signal, summary) {
+async function processEntry(entryPath, options, replacement, matcher, maxFileSize, signal, summary) {
     let validPath;
     try {
         validPath = await validatePathForWrite(entryPath, signal);
@@ -107,22 +118,13 @@ async function processEntry(entryPath, args, regex, maxFileSize, signal, summary
             encoding: 'utf-8',
             signal,
         });
-        const matchCount = args.isRegex && regex
-            ? countRegexMatches(content, regex)
-            : countLiteralMatches(content, args.searchPattern);
+        const matchCount = matcher.count(content);
         if (matchCount > 0) {
             summary.totalMatches += matchCount;
             summary.filesChanged++;
             recordChangedFile(summary, validPath, matchCount);
-            let newContent;
-            if (args.isRegex && regex) {
-                regex.lastIndex = 0;
-                newContent = content.replace(regex, args.replacement);
-            }
-            else {
-                newContent = content.replaceAll(args.searchPattern, () => args.replacement);
-            }
-            if ((args.dryRun || args.returnDiff) &&
+            const newContent = matcher.replace(content, replacement);
+            if ((options.dryRun || options.returnDiff) &&
                 summary.diff.length < MAX_DIFF_SIZE) {
                 const patch = createTwoFilesPatch(path.basename(validPath), path.basename(validPath), content, newContent, 'Original', 'Modified');
                 // Only append if it won't exceed the limit too much
@@ -130,7 +132,7 @@ async function processEntry(entryPath, args, regex, maxFileSize, signal, summary
                     summary.diff += patch;
                 }
             }
-            if (!args.dryRun) {
+            if (!options.dryRun) {
                 await atomicWriteFile(validPath, newContent, {
                     encoding: 'utf-8',
                     signal,
@@ -195,6 +197,13 @@ function createReplacementRegex(args) {
     }
     return createRegexMatcher(args.searchPattern);
 }
+function createReplacementMatcher(args) {
+    const regex = createReplacementRegex(args);
+    if (regex) {
+        return createRegexReplacementMatcher(regex);
+    }
+    return createLiteralReplacementMatcher(args.searchPattern);
+}
 function reportReplaceProgress(onProgress, current, force = false) {
     if (current === 0)
         return;
@@ -205,7 +214,7 @@ function reportReplaceProgress(onProgress, current, force = false) {
 export async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
     const maxFileSize = MAX_TEXT_FILE_SIZE;
     const root = await resolveSearchRoot(args.path, signal);
-    const regex = createReplacementRegex(args);
+    const matcher = createReplacementMatcher(args);
     const entries = globEntries({
         cwd: root,
         pattern: args.filePattern,
@@ -226,7 +235,10 @@ export async function handleSearchAndReplace(args, signal, onProgress = () => {
             summary.processedFiles++;
             reportReplaceProgress(onProgress, summary.processedFiles);
         },
-        runEntry: async (entryPath) => processEntry(entryPath, args, regex, maxFileSize, signal, summary),
+        runEntry: async (entryPath) => processEntry(entryPath, {
+            dryRun: args.dryRun,
+            returnDiff: args.returnDiff ?? false,
+        }, args.replacement, matcher, maxFileSize, signal, summary),
     });
     reportReplaceProgress(onProgress, summary.processedFiles, true);
     const failureSuffix = summary.failedFiles > 0 ? ` (${summary.failedFiles} failed)` : '';
@@ -256,16 +268,9 @@ export function registerSearchAndReplaceTool(server, options = {}) {
         run: async (signal) => {
             const dryLabel = args.dryRun ? ' [dry run]' : '';
             const context = `"${args.searchPattern}" in ${args.filePattern}${dryLabel}`;
-            let progressCursor = 0;
-            notifyProgress(extra, {
-                current: 0,
-                message: `🛠 search_and_replace: ${context}`,
-            });
-            const baseReporter = createProgressReporter(extra);
+            const progress = createToolProgressSession(extra, `🛠 search_and_replace: ${context}`);
             const progressWithMessage = ({ current, total, }) => {
-                if (current > progressCursor)
-                    progressCursor = current;
-                baseReporter({
+                progress.update({
                     current,
                     ...(total !== undefined ? { total } : {}),
                     message: `🛠 search_and_replace: ${args.searchPattern} [${current} files processed]`,
@@ -274,7 +279,7 @@ export function registerSearchAndReplaceTool(server, options = {}) {
             try {
                 const result = await handleSearchAndReplace(args, signal, progressWithMessage);
                 const sc = result.structuredContent;
-                const finalCurrent = Math.max((sc.processedFiles ?? 0) + 1, progressCursor + 1);
+                const finalCurrent = Math.max((sc.processedFiles ?? 0) + 1, progress.getCurrent() + 1);
                 const matchWord = (sc.matches ?? 0) === 1 ? 'match' : 'matches';
                 const fileWord = (sc.filesChanged ?? 0) === 1 ? 'file' : 'files';
                 let endSuffix = `${sc.matches ?? 0} ${matchWord} in ${sc.filesChanged ?? 0} ${fileWord}`;
@@ -282,20 +287,11 @@ export function registerSearchAndReplaceTool(server, options = {}) {
                     endSuffix += `, ${sc.failedFiles} failed`;
                 if (sc.dryRun)
                     endSuffix += ' [dry run]';
-                notifyProgress(extra, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `🛠 search_and_replace: ${context} • ${endSuffix}`,
-                });
+                progress.complete(`🛠 search_and_replace: ${context} • ${endSuffix}`, finalCurrent);
                 return result;
             }
             catch (error) {
-                const finalCurrent = Math.max(progressCursor + 1, 1);
-                notifyProgress(extra, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `🛠 search_and_replace: ${context} • failed`,
-                });
+                progress.fail(`🛠 search_and_replace: ${context} • failed`);
                 throw error;
             }
         },

package/dist/tools/search-content.js

@@ -5,7 +5,7 @@ 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 { SearchContentInputSchema, SearchContentOutputSchema, } from '../schemas.js';
-import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const MAX_INLINE_MATCHES = parseInt(process.env['FS_CONTEXT_MAX_INLINE_MATCHES'] ?? '', 10) || 50;
 export const SEARCH_CONTENT_TOOL = {
@@ -207,28 +207,16 @@ export function registerSearchContentTool(server, options = {}) {
         run: async (signal) => {
             const scope = args.filePattern;
             const { pattern } = args;
-            let progressCursor = 0;
-            notifyProgress(extra, {
-                current: 0,
-                message: `🔎︎ grep: ${pattern} in ${scope}`,
-            });
-            const baseReporter = createProgressReporter(extra);
+            const progress = createToolProgressSession(extra, `🔎︎ grep: ${pattern} in ${scope}`);
             const progressWithMessage = ({ current, total, }) => {
-                if (current > progressCursor)
-                    progressCursor = current;
                 const fileWord = current === 1 ? 'file' : 'files';
-                baseReporter({
+                progress.update({
                     current,
                     ...(total !== undefined ? { total } : {}),
                     message: `🔎︎ grep: ${pattern} [${current} ${fileWord} scanned]`,
                 });
             };
             try {
-                if (signal) {
-                    signal.addEventListener('abort', () => {
-                        console.error('searchContent signal aborted!');
-                    });
-                }
                 const result = await handleSearchContent(args, signal, options.resourceStore, progressWithMessage);
                 const sc = result.structuredContent;
                 const count = sc.ok && sc.totalMatches ? sc.totalMatches : 0;
@@ -254,21 +242,12 @@ export function registerSearchContentTool(server, options = {}) {
                         suffix += ' [truncated — max files]';
                     }
                 }
-                const finalCurrent = Math.max((sc.filesScanned ?? 0) + 1, progressCursor + 1);
-                notifyProgress(extra, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `🔎︎ grep: ${pattern} • ${suffix}`,
-                });
+                const finalCurrent = Math.max((sc.filesScanned ?? 0) + 1, progress.getCurrent() + 1);
+                progress.complete(`🔎︎ grep: ${pattern} • ${suffix}`, finalCurrent);
                 return result;
             }
             catch (error) {
-                const finalCurrent = Math.max(progressCursor + 1, 1);
-                notifyProgress(extra, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `🔎︎ grep: ${pattern} in ${scope} • failed`,
-                });
+                progress.fail(`🔎︎ grep: ${pattern} in ${scope} • failed`);
                 throw error;
             }
         },

package/dist/tools/shared.d.ts

@@ -47,6 +47,7 @@ export type ToolResponse<T> = ReturnType<typeof buildToolResponse<T>> & {
 interface ToolErrorResponse extends Record<string, unknown> {
     content: ContentBlock[];
     isError: true;
+    errorCode?: string;
 }
 export type ToolResult<T> = ToolResponse<T> | ToolErrorResponse;
 export declare function withValidatedArgs<Args, Result>(schema: z.ZodType<Args>, handler: (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>): (args: unknown, extra: ToolExtra) => Promise<ToolResult<Result>>;
@@ -111,9 +112,30 @@ export declare function notifyProgress(extra: ToolExtra, progress: {
     total?: number;
     message?: string;
 }): void;
+export interface ToolProgressSession {
+    update: (progress: {
+        current: number;
+        total?: number;
+        message: string;
+    }) => void;
+    increment: (messageForCurrent: (current: number) => string) => void;
+    complete: (message: string, minimumCurrent?: number) => void;
+    fail: (message: string, minimumCurrent?: number) => void;
+    getCurrent: () => number;
+}
+export declare function createToolProgressSession(extra: ToolExtra, startMessage: string): ToolProgressSession;
 export declare function wrapToolHandler<Args, Result>(handler: (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>, options: {
     guard?: (() => boolean) | undefined;
     progressMessage?: (args: Args) => string;
     completionMessage?: (args: Args, result: ToolResult<Result>) => string | undefined;
 }): (args: Args, extra?: ToolExtra) => Promise<ToolResult<Result>>;
+/**
+ * Returns `pathValue` if non-empty; otherwise resolves to the single allowed
+ * directory from module-level state managed by `RootsManager`. Throws when the
+ * path is ambiguous (multiple roots) or when no roots are configured.
+ *
+ * NOTE: Depends on `getAllowedDirectories()` which reads module-level state
+ * updated by `RootsManager`. Ensure the server is initialized before calling.
+ * See `src/server/roots-manager.ts` for the update lifecycle.
+ */
 export declare function resolvePathOrRoot(pathValue: string | undefined): string;

package/dist/tools/shared.js

@@ -198,6 +198,7 @@ export function buildToolErrorResponse(error, defaultCode, path) {
     return {
         content: [{ type: 'text', text }],
         isError: true,
+        errorCode: detailed.code,
     };
 }
 function buildNotInitializedResult() {
@@ -259,10 +260,11 @@ export function createProgressReporter(extra) {
         // out-of-order progress is undefined in the MCP spec.
         if (current <= lastProgress)
             return;
-        // Enforce rate-limiting to prevent client flooding. Progress updates faster
-        // than PROGRESS_RATE_LIMIT_MS are silently dropped.
+        // Terminal notifications always bypass the rate limit so clients reliably
+        // receive the final state even when updates arrive in quick succession.
+        const isTerminal = total !== undefined && current >= total;
         const now = Date.now();
-        if (now - lastSentMs < PROGRESS_RATE_LIMIT_MS)
+        if (!isTerminal && now - lastSentMs < PROGRESS_RATE_LIMIT_MS)
             return;
         lastProgress = current;
         lastSentMs = now;
@@ -278,16 +280,66 @@ export function notifyProgress(extra, progress) {
         return;
     void reportProgress(extra, progress);
 }
+export function createToolProgressSession(extra, startMessage) {
+    notifyProgress(extra, {
+        current: 0,
+        message: startMessage,
+    });
+    let cursor = 0;
+    const baseReporter = createProgressReporter(extra);
+    const setCursor = (value) => {
+        if (value > cursor)
+            cursor = value;
+        return cursor;
+    };
+    return {
+        update: ({ current, total, message }) => {
+            const normalized = setCursor(current);
+            baseReporter({
+                current: normalized,
+                ...(total !== undefined ? { total } : {}),
+                message,
+            });
+        },
+        increment: (messageForCurrent) => {
+            const next = setCursor(cursor + 1);
+            baseReporter({
+                current: next,
+                message: messageForCurrent(next),
+            });
+        },
+        complete: (message, minimumCurrent) => {
+            const finalCurrent = Math.max(cursor + 1, minimumCurrent ?? 1, 1);
+            notifyProgress(extra, {
+                current: finalCurrent,
+                total: finalCurrent,
+                message,
+            });
+            cursor = finalCurrent;
+        },
+        fail: (message, minimumCurrent) => {
+            const finalCurrent = Math.max(cursor + 1, minimumCurrent ?? 1, 1);
+            notifyProgress(extra, {
+                current: finalCurrent,
+                total: finalCurrent,
+                message,
+            });
+            cursor = finalCurrent;
+        },
+        getCurrent: () => cursor,
+    };
+}
 async function withProgress(message, extra, run, getCompletionMessage) {
     if (!canReportProgress(extra)) {
         return run();
     }
     const total = 1;
-    await reportProgress(extra, {
-        current: 0,
-        total,
-        message,
-    });
+    // Emit the start notification only when a progressToken is present; for
+    // task-only mode the task status is already 'working' — a zero-progress
+    // notification would add unnecessary overhead without client value.
+    if (canSendProgress(extra)) {
+        await reportProgress(extra, { current: 0, total, message });
+    }
     try {
         const result = await run();
         const endMessage = getCompletionMessage?.(result) ?? message;
@@ -326,6 +378,15 @@ export function wrapToolHandler(handler, options) {
         return maybeStripStructuredContentFromResult(result);
     };
 }
+/**
+ * Returns `pathValue` if non-empty; otherwise resolves to the single allowed
+ * directory from module-level state managed by `RootsManager`. Throws when the
+ * path is ambiguous (multiple roots) or when no roots are configured.
+ *
+ * NOTE: Depends on `getAllowedDirectories()` which reads module-level state
+ * updated by `RootsManager`. Ensure the server is initialized before calling.
+ * See `src/server/roots-manager.ts` for the update lifecycle.
+ */
 export function resolvePathOrRoot(pathValue) {
     if (pathValue && pathValue.trim().length > 0)
         return pathValue;

package/dist/tools/stat-many.js

@@ -4,7 +4,7 @@ import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { getMultipleFileInfo } from '../lib/file-operations/file-info.js';
 import { GetMultipleFileInfoInputSchema, GetMultipleFileInfoOutputSchema, } from '../schemas.js';
-import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const GET_MULTIPLE_FILE_INFO_TOOL = {
     name: 'stat_many',
@@ -79,18 +79,9 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
                     ? `, ${path.basename(args.paths[1] ?? '')}${args.paths.length > 2 ? '…' : ''}`
                     : '';
                 const context = `${args.paths.length} paths [${first}${extraPaths}]`;
-                let progressCursor = 0;
-                notifyProgress(extra, {
-                    current: 0,
-                    message: `🕮 stat_many: ${context}`,
-                });
-                const baseReporter = createProgressReporter(extra);
+                const progress = createToolProgressSession(extra, `🕮 stat_many: ${context}`);
                 const onProgress = () => {
-                    progressCursor++;
-                    baseReporter({
-                        current: progressCursor,
-                        message: `🕮 stat_many: ${context} [${progressCursor}/${args.paths.length} scanned]`,
-                    });
+                    progress.increment((current) => `🕮 stat_many: ${context} [${current}/${args.paths.length} scanned]`);
                 };
                 try {
                     const result = await handleGetMultipleFileInfo(args, signal, onProgress);
@@ -105,21 +96,12 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
                     else {
                         suffix = `${total} OK`;
                     }
-                    const finalCurrent = Math.max(total, progressCursor + 1);
-                    notifyProgress(extra, {
-                        current: finalCurrent,
-                        total: finalCurrent,
-                        message: `🕮 stat_many: ${context} • ${suffix}`,
-                    });
+                    const finalCurrent = Math.max(total, progress.getCurrent() + 1);
+                    progress.complete(`🕮 stat_many: ${context} • ${suffix}`, finalCurrent);
                     return result;
                 }
                 catch (error) {
-                    const finalCurrent = Math.max(progressCursor + 1, 1);
-                    notifyProgress(extra, {
-                        current: finalCurrent,
-                        total: finalCurrent,
-                        message: `🕮 stat_many: ${context} • failed`,
-                    });
+                    progress.fail(`🕮 stat_many: ${context} • failed`);
                     throw error;
                 }
             },