@j0hanz/filesystem-mcp 1.7.2 → 1.8.0

package/dist/schemas.js

@@ -18,6 +18,9 @@ function isSafeGlobPattern(value) {
 const MAX_PATH_LENGTH = 4096;
 const DESC_PATH_ROOT = 'Base directory (default: root). Absolute path required if multiple roots exist. Examples: "src", "src/components"';
 const DESC_PATH_REQUIRED = 'Absolute path to file or directory. Examples: "src/index.ts", "README.md"';
+function defaultFalseBoolean(description) {
+    return z.boolean().optional().default(false).describe(description);
+}
 const PathSchemaBase = z
     .string()
     .max(MAX_PATH_LENGTH, `Path too long (max ${MAX_PATH_LENGTH} chars)`);
@@ -109,16 +112,8 @@ const OperationSummarySchema = z.strictObject({
 });
 export const ListDirectoryInputSchema = z.strictObject({
     path: OptionalPathSchema.describe(DESC_PATH_ROOT),
-    includeHidden: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include hidden items (starting with .)'),
-    includeIgnored: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include ignored items (node_modules, .git, etc).'),
+    includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
+    includeIgnored: defaultFalseBoolean('Include ignored items (node_modules, .git, etc).'),
     maxDepth: z
         .number()
         .int({ error: 'Must be integer' })
@@ -143,11 +138,7 @@ export const ListDirectoryInputSchema = z.strictObject({
         .max(1000, 'Max 1000 chars')
         .optional()
         .describe('Optional glob pattern filter (e.g. "**/*.ts")'),
-    includeSymlinkTargets: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Resolve and include symlink targets in results'),
+    includeSymlinkTargets: defaultFalseBoolean('Resolve and include symlink targets in results'),
     cursor: z
         .string()
         .optional()
@@ -174,16 +165,8 @@ export const SearchFilesInputSchema = z.strictObject({
         .optional()
         .default(DEFAULT_SEARCH_RESULTS)
         .describe(`Max results (1-${MAX_SEARCH_RESULTS}). Default: ${DEFAULT_SEARCH_RESULTS}`),
-    includeIgnored: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include ignored items (node_modules, etc).'),
-    includeHidden: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include hidden items (starting with .)'),
+    includeIgnored: defaultFalseBoolean('Include ignored items (node_modules, etc).'),
+    includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
     sortBy: SearchFilesSortSchema.optional()
         .default('path')
         .describe('Sort by path, name, size, or modified'),
@@ -217,16 +200,8 @@ export const TreeInputSchema = z.strictObject({
         .optional()
         .default(DEFAULT_TREE_ENTRIES)
         .describe(`Max entries. Default: ${DEFAULT_TREE_ENTRIES}`),
-    includeHidden: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include hidden items (starting with .)'),
-    includeIgnored: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include ignored items. Disables .gitignore.'),
+    includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
+    includeIgnored: defaultFalseBoolean('Include ignored items. Disables .gitignore.'),
 });
 export const SearchContentInputSchema = z.strictObject({
     path: OptionalPathSchema.describe(DESC_PATH_ROOT),
@@ -235,21 +210,9 @@ export const SearchContentInputSchema = z.strictObject({
         .min(1, 'Pattern required')
         .max(1000, 'Max 1000 chars')
         .describe('Literal text to search for by default; treated as RE2 regex when isRegex is true.'),
-    isRegex: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Treat pattern as a RE2 regular expression. RE2 does not support lookahead, lookbehind, or backreferences.'),
-    caseSensitive: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Case-sensitive matching (default: false — searches are case-insensitive).'),
-    wholeWord: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Match whole words only'),
+    isRegex: defaultFalseBoolean('Treat pattern as a RE2 regular expression. RE2 does not support lookahead, lookbehind, or backreferences.'),
+    caseSensitive: defaultFalseBoolean('Case-sensitive matching (default: false — searches are case-insensitive).'),
+    wholeWord: defaultFalseBoolean('Match whole words only'),
     contextLines: z
         .number()
         .int({ error: 'Must be integer' })
@@ -273,16 +236,8 @@ export const SearchContentInputSchema = z.strictObject({
         .optional()
         .default('**/*')
         .describe('Glob for candidate files (e.g. "**/*.ts")'),
-    includeHidden: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include hidden items (starting with .)'),
-    includeIgnored: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include ignored items (node_modules, etc).'),
+    includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
+    includeIgnored: defaultFalseBoolean('Include ignored items (node_modules, etc).'),
 });
 export const ReadFileInputSchema = z
     .strictObject({
@@ -511,16 +466,8 @@ export const EditFileInputSchema = z.strictObject({
     }))
         .min(1, 'Min 1 edit required')
         .describe('List of replacements to apply sequentially. Each edit replaces the first occurrence of oldText.'),
-    dryRun: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Preview edits without writing. Check unmatchedEdits in the response to verify all oldText values were found.'),
-    ignoreWhitespace: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Ignore leading/trailing whitespace and treat all whitespace sequences as equivalent when matching oldText.'),
+    dryRun: defaultFalseBoolean('Preview edits without writing. Check unmatchedEdits in the response to verify all oldText values were found.'),
+    ignoreWhitespace: defaultFalseBoolean('Ignore leading/trailing whitespace and treat all whitespace sequences as equivalent when matching oldText.'),
 });
 export const EditFileOutputSchema = z.strictObject({
     ok: z.boolean(),
@@ -562,16 +509,8 @@ export const MoveFileOutputSchema = z.strictObject({
 });
 export const DeleteFileInputSchema = z.strictObject({
     path: RequiredPathSchema.describe(DESC_PATH_REQUIRED),
-    recursive: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Delete non-empty directories'),
-    ignoreIfNotExists: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('No error if missing'),
+    recursive: defaultFalseBoolean('Delete non-empty directories'),
+    ignoreIfNotExists: defaultFalseBoolean('No error if missing'),
 });
 export const DeleteFileOutputSchema = z.strictObject({
     ok: z.boolean(),
@@ -665,16 +604,8 @@ export const SearchAndReplaceInputSchema = z.strictObject({
         .min(1, 'Search pattern required')
         .describe('Text to search for. Matched literally by default; treated as RE2 regex when isRegex is true.'),
     replacement: z.string().describe('Replacement text'),
-    isRegex: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Treat searchPattern as a RE2 regular expression. Supports capture group references ($1, $2) in replacement.'),
-    dryRun: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Preview matches without writing. Check changedFiles and matches in the response before committing.'),
+    isRegex: defaultFalseBoolean('Treat searchPattern as a RE2 regular expression. Supports capture group references ($1, $2) in replacement.'),
+    dryRun: defaultFalseBoolean('Preview matches without writing. Check changedFiles and matches in the response before committing.'),
     includeHidden: z
         .boolean()
         .optional()

package/dist/server/bootstrap.js

@@ -66,8 +66,8 @@ export async function createServer(options = {}) {
     if (serverInstructions) {
         serverConfig.instructions =
             'filesystem-mcp: Secure local filesystem MCP server. ' +
-                'Always begin with: roots → ls/find → stat → read. Never guess paths. ' +
-                'Full reference: read the internal://instructions resource or invoke the get-help prompt.';
+                'Start with: roots -> ls/find -> stat -> read. Never guess paths. ' +
+                'For full guidance, read internal://instructions or run the get-help prompt.';
     }
     const server = new McpServer(withDefaultIcons({
         name: 'filesystem-mcp',

package/dist/tools/apply-patch.js

@@ -48,6 +48,9 @@ async function handleApplyPatch(args, signal) {
     if (patched === false) {
         throw new McpError(ErrorCode.E_INVALID_INPUT, 'Patch application failed. The file content may have changed or patch context is insufficient. Generate a fresh patch via diff_files against the current file, then retry. If differences are minor, enable fuzzy matching with the fuzzFactor parameter.');
     }
+    if (patched === content) {
+        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Patch had no effect — the file content is unchanged after applying. The patch may not match the current file content. Generate a fresh patch via diff_files and retry.');
+    }
     if (args.dryRun) {
         return buildToolResponse('Dry run successful. Patch can be applied.', {
             ok: true,

package/dist/tools/calculate-hash.js

@@ -8,8 +8,9 @@ import { isIgnoredByGitignore, loadRootGitignore, } from '../lib/file-operations
 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 { reportPeriodicProgress } from '../lib/progress-reporting.js';
 import { CalculateHashInputSchema, CalculateHashOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const WINDOWS_PATH_SEPARATOR = /\\/gu;
 export const CALCULATE_HASH_TOOL = {
@@ -54,13 +55,6 @@ function updateCompositeHash(hasher, pathLengthBytes, relativePath, fileHash) {
     hasher.update(relativePathBytes);
     hasher.update(fileHash);
 }
-function reportHashProgress(onProgress, current, force = false) {
-    if (!onProgress || current === 0)
-        return;
-    if (!force && current % 25 !== 0)
-        return;
-    onProgress({ current });
-}
 async function hashDirectory(dirPath, options = {}) {
     const { signal, onProgress } = options;
     const gitignoreMatcher = await loadRootGitignore(dirPath, signal);
@@ -102,9 +96,12 @@ async function hashDirectory(dirPath, options = {}) {
         }));
         entries.push(...batchResults);
         filesHashed += batchResults.length;
-        reportHashProgress(onProgress, filesHashed);
+        reportPeriodicProgress(onProgress, filesHashed, { throttleModulo: 25 });
     }
-    reportHashProgress(onProgress, filesHashed, true);
+    reportPeriodicProgress(onProgress, filesHashed, {
+        throttleModulo: 25,
+        force: true,
+    });
     assertNotAborted(signal);
     // Sort by path with byte-wise semantics for deterministic ordering.
     entries.sort(comparePaths);
@@ -141,7 +138,10 @@ async function handleCalculateHash(args, signal, onProgress) {
     else {
         // Hash single file
         const hash = await hashFile(validPath, 'hex', signal);
-        reportHashProgress(onProgress, 1, true);
+        reportPeriodicProgress(onProgress, 1, {
+            throttleModulo: 25,
+            force: true,
+        });
         return buildToolResponse(hash, {
             ok: true,
             path: validPath,
@@ -171,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, progress.getCurrent() + 1);
+                const finalCurrent = resolveFinalProgressCurrent(progress, totalFiles + 1);
                 let suffix;
                 if (!sc.ok) {
                     suffix = 'failed';

package/dist/tools/delete-file.js

@@ -1,8 +1,8 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { ErrorCode, isNodeError } from '../lib/errors.js';
+import { ErrorCode, isNodeError, McpError } from '../lib/errors.js';
 import { withAbort } from '../lib/fs-helpers.js';
-import { validatePathForWrite } from '../lib/path-validation.js';
+import { isAllowedDirectoryRoot, validatePathForWrite, } from '../lib/path-validation.js';
 import { DeleteFileInputSchema, DeleteFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
@@ -20,6 +20,9 @@ export const DELETE_FILE_TOOL = {
 };
 async function handleDeleteFile(args, signal) {
     const validPath = await validatePathForWrite(args.path, signal);
+    if (isAllowedDirectoryRoot(validPath)) {
+        throw new McpError(ErrorCode.E_ACCESS_DENIED, `Deleting a workspace root directory is not allowed: ${args.path}`);
+    }
     let stats;
     try {
         stats = await withAbort(fs.lstat(validPath), signal);

package/dist/tools/list-directory.js

@@ -4,7 +4,7 @@ import { DEFAULT_EXCLUDE_PATTERNS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { listDirectory } from '../lib/file-operations/list-directory.js';
 import { ListDirectoryInputSchema, ListDirectoryOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, decodeOffsetCursor, encodeOffsetCursor, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const LIST_DIRECTORY_TOOL = {
     name: 'ls',
@@ -82,27 +82,9 @@ function buildStructuredListResult(result, nextCursor) {
         ...(nextCursor !== undefined ? { nextCursor } : {}),
     };
 }
-function encodeCursor(offset) {
-    return Buffer.from(JSON.stringify({ offset })).toString('base64url');
-}
-function decodeCursor(cursor) {
-    try {
-        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
-        if (typeof parsed === 'object' &&
-            parsed !== null &&
-            typeof parsed.offset === 'number') {
-            const { offset } = parsed;
-            return Number.isInteger(offset) && offset >= 0 ? offset : 0;
-        }
-    }
-    catch {
-        // ignore malformed cursor
-    }
-    return 0;
-}
 async function handleListDirectory(args, signal) {
     const dirPath = resolvePathOrRoot(args.path);
-    const cursorOffset = args.cursor !== undefined ? decodeCursor(args.cursor) : 0;
+    const cursorOffset = args.cursor !== undefined ? decodeOffsetCursor(args.cursor) : 0;
     const pageSize = args.maxEntries;
     const options = {
         includeHidden: args.includeHidden,
@@ -117,7 +99,7 @@ async function handleListDirectory(args, signal) {
     const result = await listDirectory(dirPath, options);
     const displayEntries = cursorOffset > 0 ? result.entries.slice(cursorOffset) : result.entries;
     const nextCursor = result.summary.truncated && displayEntries.length > 0
-        ? encodeCursor(cursorOffset + displayEntries.length)
+        ? encodeOffsetCursor(cursorOffset + displayEntries.length)
         : undefined;
     const displayResult = { ...result, entries: displayEntries };
     return buildToolResponse(buildListTextResult(displayResult, nextCursor), buildStructuredListResult(displayResult, nextCursor));

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, createToolProgressSession, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildBatchCompletionSuffix, buildBatchPathContext, buildResourceLink, buildToolErrorResponse, buildToolResponse, createBatchProgressCallbacks, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const READ_MULTIPLE_FILES_TOOL = {
     name: 'read_many',
@@ -134,29 +134,19 @@ export function registerReadMultipleFilesTool(server, options = {}) {
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: primaryPath },
             run: async (signal) => {
-                const first = path.basename(args.paths[0] ?? '');
-                const extraPaths = args.paths.length > 1
-                    ? `, ${path.basename(args.paths[1] ?? '')}${args.paths.length > 2 ? '…' : ''}`
-                    : '';
-                const context = `${args.paths.length} files [${first}${extraPaths}]`;
-                const progress = createToolProgressSession(extra, `🕮 read_many: ${context}`);
-                const onReadComplete = () => {
-                    progress.increment((current) => `🕮 read_many: ${context} [${current}/${args.paths.length} read]`);
-                };
+                const context = buildBatchPathContext(args.paths, 'files');
+                const { progress, onItemComplete } = createBatchProgressCallbacks(extra, {
+                    toolLabel: '🕮 read_many',
+                    context,
+                    totalItems: args.paths.length,
+                    itemVerb: 'read',
+                });
                 try {
-                    const result = await handleReadMultipleFiles(args, signal, options.resourceStore, onReadComplete);
+                    const result = await handleReadMultipleFiles(args, signal, options.resourceStore, onItemComplete);
                     const sc = result.structuredContent;
+                    const suffix = buildBatchCompletionSuffix(sc.summary, 'files read', 'file read');
                     const total = sc.summary?.total ?? 0;
-                    const failed = sc.summary?.failed ?? 0;
-                    const succeeded = sc.summary?.succeeded ?? 0;
-                    let suffix;
-                    if (failed) {
-                        suffix = `${succeeded}/${total} read, ${failed} failed`;
-                    }
-                    else {
-                        suffix = `${total} files read`;
-                    }
-                    const finalCurrent = Math.max(total, progress.getCurrent() + 1);
+                    const finalCurrent = resolveFinalProgressCurrent(progress, total);
                     progress.complete(`🕮 read_many: ${context} • ${suffix}`, finalCurrent);
                     return result;
                 }

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

@@ -8,8 +8,9 @@ import { ErrorCode, formatUnknownErrorMessage, McpError, } from '../lib/errors.j
 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 { reportPeriodicProgress } from '../lib/progress-reporting.js';
 import { SearchAndReplaceInputSchema, SearchAndReplaceOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, resolveFinalProgressCurrent, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const SEARCH_AND_REPLACE_TOOL = {
     name: 'search_and_replace',
@@ -204,13 +205,6 @@ function createReplacementMatcher(args) {
     }
     return createLiteralReplacementMatcher(args.searchPattern);
 }
-function reportReplaceProgress(onProgress, current, force = false) {
-    if (current === 0)
-        return;
-    if (!force && current % 25 !== 0)
-        return;
-    onProgress({ current });
-}
 export async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
     const maxFileSize = MAX_TEXT_FILE_SIZE;
     const root = await resolveSearchRoot(args.path, signal);
@@ -233,14 +227,19 @@ export async function handleSearchAndReplace(args, signal, onProgress = () => {
         concurrency: REPLACE_CONCURRENCY,
         onEntry: () => {
             summary.processedFiles++;
-            reportReplaceProgress(onProgress, summary.processedFiles);
+            reportPeriodicProgress(onProgress, summary.processedFiles, {
+                throttleModulo: 25,
+            });
         },
         runEntry: async (entryPath) => processEntry(entryPath, {
             dryRun: args.dryRun,
             returnDiff: args.returnDiff ?? false,
         }, args.replacement, matcher, maxFileSize, signal, summary),
     });
-    reportReplaceProgress(onProgress, summary.processedFiles, true);
+    reportPeriodicProgress(onProgress, summary.processedFiles, {
+        throttleModulo: 25,
+        force: true,
+    });
     const failureSuffix = summary.failedFiles > 0 ? ` (${summary.failedFiles} failed)` : '';
     return buildToolResponse(`Found ${summary.totalMatches} matches in ${summary.filesChanged} files${failureSuffix}.${args.dryRun ? ' (Dry run)' : ''}`, {
         ok: true,
@@ -279,7 +278,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, progress.getCurrent() + 1);
+                const finalCurrent = resolveFinalProgressCurrent(progress, (sc.processedFiles ?? 0) + 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}`;

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, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, 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 = {
@@ -242,7 +242,7 @@ export function registerSearchContentTool(server, options = {}) {
                         suffix += ' [truncated — max files]';
                     }
                 }
-                const finalCurrent = Math.max((sc.filesScanned ?? 0) + 1, progress.getCurrent() + 1);
+                const finalCurrent = resolveFinalProgressCurrent(progress, (sc.filesScanned ?? 0) + 1);
                 progress.complete(`🔎︎ grep: ${pattern} • ${suffix}`, finalCurrent);
                 return result;
             }

package/dist/tools/search-files.js

@@ -4,26 +4,8 @@ import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_SEARCH_TIMEOUT_MS, } from '../lib/con
 import { ErrorCode } from '../lib/errors.js';
 import { searchFiles } from '../lib/file-operations/search-files.js';
 import { SearchFilesInputSchema, SearchFilesOutputSchema } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createProgressReporter, decodeOffsetCursor, encodeOffsetCursor, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-function encodeCursor(offset) {
-    return Buffer.from(JSON.stringify({ offset })).toString('base64url');
-}
-function decodeCursor(cursor) {
-    try {
-        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
-        if (typeof parsed === 'object' &&
-            parsed !== null &&
-            typeof parsed.offset === 'number') {
-            const { offset } = parsed;
-            return Number.isInteger(offset) && offset >= 0 ? offset : 0;
-        }
-    }
-    catch {
-        // ignore malformed cursor
-    }
-    return 0;
-}
 export const SEARCH_FILES_TOOL = {
     name: 'find',
     title: 'Find Files',
@@ -43,7 +25,7 @@ export const SEARCH_FILES_TOOL = {
 async function handleSearchFiles(args, signal, onProgress) {
     const basePath = resolvePathOrRoot(args.path);
     const excludePatterns = args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS;
-    const cursorOffset = args.cursor !== undefined ? decodeCursor(args.cursor) : 0;
+    const cursorOffset = args.cursor !== undefined ? decodeOffsetCursor(args.cursor) : 0;
     const pageSize = args.maxResults;
     const fetchMax = cursorOffset + pageSize;
     const searchOptions = {
@@ -59,7 +41,7 @@ async function handleSearchFiles(args, signal, onProgress) {
     const allResults = result.results;
     const displayResults = cursorOffset > 0 ? allResults.slice(cursorOffset) : allResults;
     const nextCursor = result.summary.truncated && displayResults.length > 0
-        ? encodeCursor(cursorOffset + displayResults.length)
+        ? encodeOffsetCursor(cursorOffset + displayResults.length)
         : undefined;
     const relativeResults = [];
     for (const entry of displayResults) {

package/dist/tools/shared.d.ts

@@ -123,7 +123,18 @@ export interface ToolProgressSession {
     fail: (message: string, minimumCurrent?: number) => void;
     getCurrent: () => number;
 }
+export interface BatchProgressCallbacks {
+    progress: ToolProgressSession;
+    onItemComplete: () => void;
+}
 export declare function createToolProgressSession(extra: ToolExtra, startMessage: string): ToolProgressSession;
+export declare function createBatchProgressCallbacks(extra: ToolExtra, params: {
+    toolLabel: string;
+    context: string;
+    totalItems: number;
+    itemVerb: string;
+}): BatchProgressCallbacks;
+export declare function resolveFinalProgressCurrent(progress: ToolProgressSession, ...candidates: number[]): number;
 export declare function wrapToolHandler<Args, Result>(handler: (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>, options: {
     guard?: (() => boolean) | undefined;
     progressMessage?: (args: Args) => string;
@@ -139,3 +150,11 @@ export declare function wrapToolHandler<Args, Result>(handler: (args: Args, extr
  * See `src/server/roots-manager.ts` for the update lifecycle.
  */
 export declare function resolvePathOrRoot(pathValue: string | undefined): string;
+export declare function encodeOffsetCursor(offset: number): string;
+export declare function decodeOffsetCursor(cursor: string): number;
+export declare function buildBatchPathContext(paths: readonly string[], unitLabel?: string): string;
+export declare function buildBatchCompletionSuffix(summary: {
+    total?: number;
+    failed?: number;
+    succeeded?: number;
+} | undefined, successWord: string, singularWord?: string): string;

package/dist/tools/shared.js

@@ -1,3 +1,4 @@
+import * as path from 'node:path';
 import { channel } from 'node:diagnostics_channel';
 import { z } from 'zod';
 import { parseTrueEnvFlag } from '../lib/constants.js';
@@ -292,6 +293,15 @@ export function createToolProgressSession(extra, startMessage) {
             cursor = value;
         return cursor;
     };
+    const finishProgress = (message, minimumCurrent) => {
+        const finalCurrent = Math.max(cursor + 1, minimumCurrent ?? 1, 1);
+        notifyProgress(extra, {
+            current: finalCurrent,
+            total: finalCurrent,
+            ...(message !== undefined ? { message } : {}),
+        });
+        cursor = finalCurrent;
+    };
     return {
         update: ({ current, total, message }) => {
             const normalized = setCursor(current);
@@ -308,27 +318,27 @@ export function createToolProgressSession(extra, startMessage) {
                 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;
-        },
+        complete: finishProgress,
+        fail: finishProgress,
         getCurrent: () => cursor,
     };
 }
+export function createBatchProgressCallbacks(extra, params) {
+    const progress = createToolProgressSession(extra, `${params.toolLabel}: ${params.context}`);
+    const onItemComplete = () => {
+        progress.increment((current) => `${params.toolLabel}: ${params.context} [${current}/${params.totalItems} ${params.itemVerb}]`);
+    };
+    return { progress, onItemComplete };
+}
+export function resolveFinalProgressCurrent(progress, ...candidates) {
+    let finalCurrent = progress.getCurrent() + 1;
+    for (const candidate of candidates) {
+        if (candidate > finalCurrent) {
+            finalCurrent = candidate;
+        }
+    }
+    return finalCurrent;
+}
 async function withProgress(message, extra, run, getCompletionMessage) {
     if (!canReportProgress(extra)) {
         return run();
@@ -403,3 +413,39 @@ export function resolvePathOrRoot(pathValue) {
     }
     return root;
 }
+export function encodeOffsetCursor(offset) {
+    return Buffer.from(JSON.stringify({ offset })).toString('base64url');
+}
+export function decodeOffsetCursor(cursor) {
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            typeof parsed.offset === 'number') {
+            const { offset } = parsed;
+            return Number.isInteger(offset) && offset >= 0 ? offset : 0;
+        }
+    }
+    catch {
+        // ignore malformed cursor
+    }
+    return 0;
+}
+export function buildBatchPathContext(paths, unitLabel = 'paths') {
+    const normalizedLabel = paths.length === 1 ? unitLabel.replace(/s$/i, '') : unitLabel;
+    const first = path.basename(paths[0] ?? '');
+    const extraPaths = paths.length > 1
+        ? `, ${path.basename(paths[1] ?? '')}${paths.length > 2 ? '…' : ''}`
+        : '';
+    return `${paths.length} ${normalizedLabel} [${first}${extraPaths}]`;
+}
+export function buildBatchCompletionSuffix(summary, successWord, singularWord) {
+    const total = summary?.total ?? 0;
+    const failed = summary?.failed ?? 0;
+    const succeeded = summary?.succeeded ?? 0;
+    if (failed) {
+        return `${succeeded}/${total} ${successWord}, ${failed} failed`;
+    }
+    const word = total === 1 && singularWord ? singularWord : successWord;
+    return `${total} ${word}`;
+}