@j0hanz/filesystem-mcp 1.3.1 → 1.4.0

package/dist/completions.js

@@ -7,6 +7,7 @@ import { isRecord } from './lib/type-guards.js';
 const MAX_COMPLETION_ITEMS = 100;
 const COMPLETION_RATE_LIMIT_MS = 100;
 const completionLastCallMs = new Map();
+const completionLastResult = new Map();
 function extractTopicCompletions(instructions) {
     const headers = [];
     for (const line of instructions.split('\n')) {
@@ -394,6 +395,16 @@ export function registerCompletions(server, instructions = '') {
         const now = Date.now();
         const lastCallMs = completionLastCallMs.get(argName) ?? 0;
         if (now - lastCallMs < COMPLETION_RATE_LIMIT_MS) {
+            const lastResult = completionLastResult.get(argName);
+            if (lastResult) {
+                return {
+                    completion: {
+                        values: lastResult.values,
+                        total: lastResult.total,
+                        hasMore: lastResult.hasMore,
+                    },
+                };
+            }
             return { completion: { values: [], total: 0, hasMore: false } };
         }
         completionLastCallMs.set(argName, now);
@@ -403,6 +414,7 @@ export function registerCompletions(server, instructions = '') {
             argumentName: argName,
             ...(contextArguments ? { contextArguments } : {}),
         });
+        completionLastResult.set(argName, completions);
         return {
             completion: {
                 values: completions.values,

package/dist/lib/constants.d.ts

@@ -1,3 +1,6 @@
+declare const VALID_LOG_LEVELS: readonly ["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"];
+export type ValidLogLevel = (typeof VALID_LOG_LEVELS)[number];
+export declare const DEFAULT_LOG_LEVEL: "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency";
 export declare const PARALLEL_CONCURRENCY: number;
 export declare const MAX_SEARCHABLE_FILE_SIZE: number;
 export declare const MAX_TEXT_FILE_SIZE: number;
@@ -19,3 +22,4 @@ export declare const SENSITIVE_FILE_ALLOWLIST: string[];
 export declare const KNOWN_BINARY_EXTENSIONS: Set<string>;
 export declare const DEFAULT_EXCLUDE_PATTERNS: string[];
 export declare function getMimeType(ext: string): string;
+export {};

package/dist/lib/constants.js

@@ -43,6 +43,28 @@ function parseEnvList(envVar) {
     }
     return entries;
 }
+const VALID_LOG_LEVELS = [
+    'debug',
+    'info',
+    'notice',
+    'warning',
+    'error',
+    'critical',
+    'alert',
+    'emergency',
+];
+function parseEnvLogLevel(envVar, defaultValue) {
+    const value = process.env[envVar];
+    if (!value)
+        return defaultValue;
+    const normalized = value.trim().toLowerCase();
+    if (VALID_LOG_LEVELS.includes(normalized)) {
+        return normalized;
+    }
+    console.error(`[WARNING] Invalid ${envVar} value: ${value} (must be ${VALID_LOG_LEVELS.join('|')}). Using default: ${defaultValue}`);
+    return defaultValue;
+}
+export const DEFAULT_LOG_LEVEL = parseEnvLogLevel('FILESYSTEM_MCP_LOG_LEVEL', 'debug');
 // Auto-tuned parallelism based on CPU cores (no env override)
 const BYTES_PER_PARALLEL_TASK = 64 * MIB;
 const BYTES_PER_SEARCH_WORKER = 128 * MIB;

package/dist/lib/file-operations/file-info.d.ts

@@ -2,6 +2,7 @@ import type { FileInfo, GetMultipleFileInfoResult } from '../../config.js';
 interface FileInfoOptions {
     includeMimeType?: boolean | undefined;
     signal?: AbortSignal | undefined;
+    onProgress?: () => void;
 }
 export declare function getFileInfo(filePath: string, options?: FileInfoOptions): Promise<FileInfo>;
 type GetMultipleFileInfoOptions = FileInfoOptions;

package/dist/lib/file-operations/file-info.js

@@ -89,10 +89,11 @@ function buildIndexedPathTasks(paths) {
     return tasks;
 }
 async function readFileInfoInParallel(paths, options) {
-    return processInParallel(buildIndexedPathTasks(paths), async ({ filePath, index }) => ({
-        index,
-        value: await processFileInfo(filePath, options),
-    }), PARALLEL_CONCURRENCY, options.signal);
+    return processInParallel(buildIndexedPathTasks(paths), async ({ filePath, index }) => {
+        const value = await processFileInfo(filePath, options);
+        options.onProgress?.();
+        return { index, value };
+    }, PARALLEL_CONCURRENCY, options.signal);
 }
 function applyResults(output, results) {
     for (const result of results) {

package/dist/lib/file-operations/read-multiple-files.d.ts

@@ -19,6 +19,7 @@ interface ReadMultipleOptions {
     startLine?: number;
     endLine?: number;
     signal?: AbortSignal;
+    onReadComplete?: () => void;
 }
 export declare function readMultipleFiles(filePaths: readonly string[], options?: ReadMultipleOptions): Promise<ReadMultipleResult[]>;
 export {};

package/dist/lib/file-operations/read-multiple-files.js

@@ -48,12 +48,16 @@ async function readSingleFile(task, readOptions) {
         value: buildReadMultipleResult(filePath, result),
     };
 }
-async function readFilesInParallel(filesToProcess, options, signal) {
+async function readFilesInParallel(filesToProcess, options, signal, onReadComplete) {
     const readOptions = buildReadOptions(options);
     if (signal) {
         readOptions.signal = signal;
     }
-    return processInParallel(filesToProcess, async (task) => readSingleFile(task, readOptions), PARALLEL_CONCURRENCY, signal);
+    return processInParallel(filesToProcess, async (task) => {
+        const result = await readSingleFile(task, readOptions);
+        onReadComplete?.();
+        return result;
+    }, PARALLEL_CONCURRENCY, signal);
 }
 function normalizeReadMultipleOptions(options) {
     const normalized = {
@@ -248,7 +252,7 @@ export async function readMultipleFiles(filePaths, options = {}) {
     const output = buildOutput(filePaths);
     const { skippedBudget, validated } = await collectFileBudget(filePaths, normalized.maxTotalSize, normalized.maxSize, signal);
     const filesToProcess = buildFilesToProcess(filePaths, validated, skippedBudget);
-    const { results, errors } = await readFilesInParallel(filesToProcess, normalized, signal);
+    const { results, errors } = await readFilesInParallel(filesToProcess, normalized, signal, options.onReadComplete);
     applyResults(output, results);
     applyErrors(output, errors, filesToProcess, filePaths);
     applySkippedBudget(output, skippedBudget, filePaths, normalized.maxTotalSize);

package/dist/lib/file-operations/tree.d.ts

@@ -12,6 +12,10 @@ interface TreeOptions {
     includeIgnored?: boolean;
     timeoutMs?: number;
     signal?: AbortSignal;
+    onProgress?: (progress: {
+        total?: number;
+        current: number;
+    }) => void;
 }
 interface TreeResult {
     root: string;

package/dist/lib/file-operations/tree.js

@@ -265,6 +265,7 @@ export async function treeDirectory(dirPath, options = {}) {
             const parent = ensureParentNodes(rootNode, nodeByPath, resolved.relativePosix);
             upsertChildNode(parent, nodeByPath, resolved, childPathIndexByParent);
             totalEntries += 1;
+            options.onProgress?.({ current: totalEntries });
         }
         sortTree(rootNode);
         return {

package/dist/lib/resource-store.d.ts

@@ -15,6 +15,7 @@ export interface ResourceStore {
     }): TextResourceEntry;
     getText(uri: string): TextResourceEntry;
     clear(): void;
+    keys(): string[];
 }
 interface ResourceStoreOptions {
     maxEntries: number;

package/dist/lib/resource-store.js

@@ -147,5 +147,8 @@ export function createInMemoryResourceStore(options = {}) {
             bytes: bytesBeforeClear,
         });
     }
-    return { putText, getText, clear };
+    function keys() {
+        return Array.from(byUri.keys());
+    }
+    return { putText, getText, clear, keys };
 }

package/dist/schemas.d.ts

@@ -733,6 +733,7 @@ export declare const SearchAndReplaceOutputSchema: z.ZodObject<{
         matches: z.ZodNumber;
     }, z.core.$strict>>>;
     changedFilesTruncated: z.ZodOptional<z.ZodBoolean>;
+    diff: z.ZodOptional<z.ZodString>;
     dryRun: z.ZodOptional<z.ZodBoolean>;
     error: z.ZodOptional<z.ZodObject<{
         code: z.ZodEnum<{

package/dist/schemas.js

@@ -662,6 +662,7 @@ export const SearchAndReplaceOutputSchema = z.strictObject({
         .boolean()
         .optional()
         .describe('Changed file list truncated'),
+    diff: z.string().optional().describe('Unified diff of changes (dryRun only)'),
     dryRun: z.boolean().optional(),
     error: ErrorSchema.optional(),
 });

package/dist/server/bootstrap.js

@@ -7,6 +7,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest, SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { registerCompletions } from '../completions.js';
+import { DEFAULT_LOG_LEVEL } from '../lib/constants.js';
 import { formatUnknownErrorMessage } from '../lib/errors.js';
 import { createInMemoryResourceStore } from '../lib/resource-store.js';
 import { pkgInfo } from '../pkg-info.js';
@@ -77,7 +78,7 @@ export async function createServer(options = {}) {
         ...(SERVER_DESCRIPTION ? { description: SERVER_DESCRIPTION } : {}),
         ...(SERVER_HOMEPAGE ? { websiteUrl: SERVER_HOMEPAGE } : {}),
     }, localIcon), serverConfig);
-    const loggingState = createLoggingState('debug');
+    const loggingState = createLoggingState(DEFAULT_LOG_LEVEL);
     const rootsManager = new RootsManager(options, loggingState);
     rootsManagers.set(server, rootsManager);
     server.server.setRequestHandler(SetLevelRequestSchema, (req) => {
@@ -160,6 +161,14 @@ async function createHttpSession(options, sessions) {
     await mcpServer.connect(transport);
     return { server: mcpServer, transport };
 }
+function sendJsonRpcError(res, status, code, message) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+        jsonrpc: '2.0',
+        error: { code, message },
+        id: null,
+    }));
+}
 export async function startHttpServer(port, options) {
     const sessions = new Map();
     async function handleMcpRequest(req, res) {
@@ -198,91 +207,27 @@ export async function startHttpServer(port, options) {
                     if (session) {
                         await session.transport.handleRequest(req, res, body);
                     }
-                    else {
-                        res.writeHead(400, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({
-                            jsonrpc: '2.0',
-                            error: {
-                                code: -32000,
-                                message: 'Bad Request: Session not found',
-                            },
-                            id: null,
-                        }));
-                    }
                 }
                 else if (!sessionId && isInitializeRequest(body)) {
                     const { transport } = await createHttpSession(options, sessions);
                     await transport.handleRequest(req, res, body);
                 }
-                else {
-                    res.writeHead(400, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({
-                        jsonrpc: '2.0',
-                        error: {
-                            code: -32000,
-                            message: 'Bad Request: No valid session ID provided',
-                        },
-                        id: null,
-                    }));
-                }
-            }
-            else if (method === 'GET') {
-                if (!sessionId || !sessions.has(sessionId)) {
-                    res.writeHead(400, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({
-                        jsonrpc: '2.0',
-                        error: {
-                            code: -32000,
-                            message: 'Bad Request: Invalid or missing session ID',
-                        },
-                        id: null,
-                    }));
-                    return;
-                }
-                const session = sessions.get(sessionId);
-                if (session) {
-                    await session.transport.handleRequest(req, res);
+                else if (sessionId) {
+                    sendJsonRpcError(res, 400, -32000, 'Bad Request: Session not found');
                 }
                 else {
-                    res.writeHead(400, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({
-                        jsonrpc: '2.0',
-                        error: {
-                            code: -32000,
-                            message: 'Bad Request: Session not found',
-                        },
-                        id: null,
-                    }));
+                    sendJsonRpcError(res, 400, -32000, 'Bad Request: No valid session ID provided');
                 }
             }
-            else if (method === 'DELETE') {
+            else if (method === 'GET' || method === 'DELETE') {
                 if (!sessionId || !sessions.has(sessionId)) {
-                    res.writeHead(400, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({
-                        jsonrpc: '2.0',
-                        error: {
-                            code: -32000,
-                            message: 'Bad Request: Invalid or missing session ID',
-                        },
-                        id: null,
-                    }));
+                    sendJsonRpcError(res, 400, -32000, 'Bad Request: Invalid or missing session ID');
                     return;
                 }
                 const session = sessions.get(sessionId);
                 if (session) {
                     await session.transport.handleRequest(req, res);
                 }
-                else {
-                    res.writeHead(400, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({
-                        jsonrpc: '2.0',
-                        error: {
-                            code: -32000,
-                            message: 'Bad Request: Session not found',
-                        },
-                        id: null,
-                    }));
-                }
             }
             else {
                 res.writeHead(405, { Allow: 'GET, POST, DELETE' });
@@ -292,12 +237,7 @@ export async function startHttpServer(port, options) {
         catch (error) {
             console.error('[HTTP] Error handling request:', formatUnknownErrorMessage(error));
             if (!res.headersSent) {
-                res.writeHead(500, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({
-                    jsonrpc: '2.0',
-                    error: { code: -32603, message: 'Internal Server Error' },
-                    id: null,
-                }));
+                sendJsonRpcError(res, 500, -32603, 'Internal Server Error');
             }
         }
     }

package/dist/tools/contract.d.ts

@@ -38,4 +38,8 @@ export interface ToolContract {
      * Common pitfalls or warnings for documentation.
      */
     gotchas?: string[];
+    /**
+     * Task support level for the tool. Defaults to 'optional'.
+     */
+    taskSupport?: 'optional' | 'required' | 'forbidden';
 }

package/dist/tools/diff-files.js

@@ -7,6 +7,7 @@ import { withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath } from '../lib/path-validation.js';
 import { DiffFilesInputSchema, DiffFilesOutputSchema } from '../schemas.js';
 import { buildResourceLink, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { registerToolTaskIfAvailable } from './task-support.js';
 export const DIFF_FILES_TOOL = {
     name: 'diff_files',
     title: 'Diff Files',
@@ -104,5 +105,7 @@ export function registerDiffFilesTool(server, options = {}) {
         },
     });
     const validatedHandler = withValidatedArgs(DiffFilesInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'diff_files', DIFF_FILES_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
+        return;
     server.registerTool('diff_files', withDefaultIcons({ ...DIFF_FILES_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/edit-file.js

@@ -5,6 +5,7 @@ import { atomicWriteFile } from '../lib/fs-helpers.js';
 import { validateExistingPath } from '../lib/path-validation.js';
 import { EditFileInputSchema, EditFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { registerToolTaskIfAvailable } from './task-support.js';
 export const EDIT_FILE_TOOL = {
     name: 'edit',
     title: 'Edit File',
@@ -111,5 +112,7 @@ export function registerEditFileTool(server, options = {}) {
         },
     });
     const validatedHandler = withValidatedArgs(EditFileInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'edit', EDIT_FILE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
+        return;
     server.registerTool('edit', withDefaultIcons({ ...EDIT_FILE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/list-directory.js

@@ -5,6 +5,7 @@ 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 { registerToolTaskIfAvailable } from './task-support.js';
 export const LIST_DIRECTORY_TOOL = {
     name: 'ls',
     title: 'List Directory',
@@ -144,5 +145,7 @@ export function registerListDirectoryTool(server, options = {}) {
         },
     });
     const validatedHandler = withValidatedArgs(ListDirectoryInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'ls', LIST_DIRECTORY_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
+        return;
     server.registerTool('ls', withDefaultIcons({ ...LIST_DIRECTORY_TOOL }, options.iconInfo), validatedHandler);
 }

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, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, maybeExternalizeTextContent, notifyProgress, 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',
@@ -14,17 +14,19 @@ export const READ_MULTIPLE_FILES_TOOL = {
     inputSchema: ReadMultipleFilesInputSchema,
     outputSchema: ReadMultipleFilesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    taskSupport: 'required',
     nuances: ['Total read budget is capped by `MAX_READ_MANY_TOTAL_SIZE`.'],
     gotchas: [
         'Per-file `truncationReason` can be `head`, `range`, or `externalized`.',
     ],
 };
-async function handleReadMultipleFiles(args, signal, resourceStore) {
+async function handleReadMultipleFiles(args, signal, resourceStore, onReadComplete) {
     const options = {
         ...(signal ? { signal } : {}),
         ...(args.head !== undefined ? { head: args.head } : {}),
         ...(args.startLine !== undefined ? { startLine: args.startLine } : {}),
         ...(args.endLine !== undefined ? { endLine: args.endLine } : {}),
+        ...(onReadComplete ? { onReadComplete } : {}),
     };
     const results = await readMultipleFiles(args.paths, options);
     const maxTotalSize = DEFAULT_READ_MANY_MAX_TOTAL_SIZE;
@@ -122,30 +124,61 @@ export function registerReadMultipleFilesTool(server, options = {}) {
             extra,
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: primaryPath },
-            run: (signal) => handleReadMultipleFiles(args, signal, options.resourceStore),
+            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}]`;
+                let progressCursor = 0;
+                notifyProgress(extra, {
+                    current: 0,
+                    message: `🕮 read_many: ${context}`,
+                });
+                const baseReporter = createProgressReporter(extra);
+                const onReadComplete = () => {
+                    progressCursor++;
+                    baseReporter({
+                        current: progressCursor,
+                        message: `🕮 read_many: ${context} [${progressCursor}/${args.paths.length} read]`,
+                    });
+                };
+                try {
+                    const result = await handleReadMultipleFiles(args, signal, options.resourceStore, onReadComplete);
+                    const sc = result.structuredContent;
+                    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, progressCursor + 1);
+                    notifyProgress(extra, {
+                        current: finalCurrent,
+                        total: finalCurrent,
+                        message: `🕮 read_many: ${context} • ${suffix}`,
+                    });
+                    return result;
+                }
+                catch (error) {
+                    const finalCurrent = Math.max(progressCursor + 1, 1);
+                    notifyProgress(extra, {
+                        current: finalCurrent,
+                        total: finalCurrent,
+                        message: `🕮 read_many: ${context} • failed`,
+                    });
+                    throw error;
+                }
+            },
             onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FILE, primaryPath),
         });
     };
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => {
-            const first = path.basename(args.paths[0] ?? '');
-            const extra = args.paths.length > 1 ? `, ${path.basename(args.paths[1] ?? '')}…` : '';
-            return `🕮 read_many: ${args.paths.length} files [${first}${extra}]`;
-        },
-        completionMessage: (args, result) => {
-            if (result.isError)
-                return `🕮 read_many: ${args.paths.length} files • failed`;
-            const sc = result.structuredContent;
-            if (!sc.ok)
-                return `🕮 read_many: ${args.paths.length} files • failed`;
-            const total = sc.summary?.total ?? 0;
-            const succeeded = sc.summary?.succeeded ?? 0;
-            const failed = sc.summary?.failed ?? 0;
-            if (failed)
-                return `🕮 read_many: ${succeeded}/${total} read, ${failed} failed`;
-            return `🕮 read_many: ${total} files read`;
-        },
     });
     const validatedHandler = withValidatedArgs(ReadMultipleFilesInputSchema, wrappedHandler);
     if (registerToolTaskIfAvailable(server, 'read_many', READ_MULTIPLE_FILES_TOOL, validatedHandler, options.iconInfo, options.isInitialized))

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

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import { createTwoFilesPatch } from 'diff';
 import RE2 from 're2';
 import safeRegex from 'safe-regex2';
 import { DEFAULT_EXCLUDE_PATTERNS, MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY, } from '../lib/constants.js';
@@ -17,10 +18,12 @@ export const SEARCH_AND_REPLACE_TOOL = {
         '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. ' +
+        'Returns a unified diff of changes in `dryRun` mode. ' +
         'Literal mode (default) matches exact text; `isRegex: true` enables RE2 regex with capture groups ($1, $2).',
     inputSchema: SearchAndReplaceInputSchema,
     outputSchema: SearchAndReplaceOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    taskSupport: 'required',
     gotchas: [
         'Literal mode is default; `isRegex=true` enables RE2 + capture replacements (`$1`, `$2`).',
     ],
@@ -31,6 +34,7 @@ export const SEARCH_AND_REPLACE_TOOL = {
 const MAX_FAILURES = 20;
 const REPLACE_CONCURRENCY = Math.min(PARALLEL_CONCURRENCY, 8);
 const MAX_CHANGED_FILES = 100;
+const MAX_DIFF_SIZE = 20 * 1024; // 20KB limit for diff output
 function recordFailure(failures, failure) {
     if (failures.length >= MAX_FAILURES)
         return;
@@ -110,15 +114,22 @@ async function processEntry(entryPath, args, regex, maxFileSize, signal, summary
             summary.totalMatches += matchCount;
             summary.filesChanged++;
             recordChangedFile(summary, validPath, matchCount);
-            if (!args.dryRun) {
-                let newContent;
-                if (args.isRegex && regex) {
-                    regex.lastIndex = 0;
-                    newContent = content.replace(regex, args.replacement);
-                }
-                else {
-                    newContent = content.replaceAll(args.searchPattern, () => args.replacement);
+            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 && 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
+                if (summary.diff.length + patch.length <= MAX_DIFF_SIZE + 1024) {
+                    summary.diff += patch;
                 }
+            }
+            if (!args.dryRun) {
                 await atomicWriteFile(validPath, newContent, {
                     encoding: 'utf-8',
                     signal,
@@ -167,6 +178,7 @@ function createReplaceSummary(root) {
         failures: [],
         changedFiles: [],
         changedFilesTruncated: false,
+        diff: '',
     };
 }
 async function resolveSearchRoot(pathValue, signal) {
@@ -228,6 +240,7 @@ async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
             ? { changedFiles: summary.changedFiles }
             : {}),
         ...(summary.changedFilesTruncated ? { changedFilesTruncated: true } : {}),
+        ...(args.dryRun && summary.diff ? { diff: summary.diff } : {}),
         dryRun: args.dryRun,
     });
 }

package/dist/tools/roots.js

@@ -3,6 +3,7 @@ import { ErrorCode } from '../lib/errors.js';
 import { getAllowedDirectories } from '../lib/path-validation.js';
 import { ListAllowedDirectoriesInputSchema, ListAllowedDirectoriesOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { registerToolTaskIfAvailable } from './task-support.js';
 export const LIST_ALLOWED_DIRECTORIES_TOOL = {
     name: 'roots',
     title: 'Workspace Roots',
@@ -54,5 +55,7 @@ export function registerListAllowedDirectoriesTool(server, options = {}) {
         },
     });
     const validatedHandler = withValidatedArgs(ListAllowedDirectoriesInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'roots', LIST_ALLOWED_DIRECTORIES_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
+        return;
     server.registerTool('roots', withDefaultIcons({ ...LIST_ALLOWED_DIRECTORIES_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/search-content.js

@@ -26,6 +26,7 @@ export const SEARCH_CONTENT_TOOL = {
     gotchas: [
         'Inline match rows are capped (first 50); full structured results are externalized via `resourceUri`.',
     ],
+    taskSupport: 'required',
 };
 function assertValidRegexPattern(pattern) {
     try {

package/dist/tools/search-files.js

@@ -38,6 +38,7 @@ export const SEARCH_FILES_TOOL = {
         'Respects `.gitignore` unless `includeIgnored=true`.',
         'Returns relative paths plus metadata; may truncate.',
     ],
+    taskSupport: 'required',
 };
 async function handleSearchFiles(args, signal, onProgress) {
     const basePath = resolvePathOrRoot(args.path);

package/dist/tools/shared.js

@@ -125,6 +125,11 @@ function canSendProgress(extra) {
     return (extra._meta?.progressToken !== undefined &&
         extra.sendNotification !== undefined);
 }
+function canReportProgress(extra) {
+    const taskExtra = extra;
+    const hasTask = taskExtra.taskId !== undefined && taskExtra.taskStore !== undefined;
+    return canSendProgress(extra) || hasTask;
+}
 export function withDefaultIcons(tool, iconInfo) {
     if (!iconInfo) {
         return maybeStripOutputSchema(tool);
@@ -216,25 +221,53 @@ export function buildToolErrorResponse(error, defaultCode, path) {
 function buildNotInitializedResult() {
     return buildToolErrorResponse(NOT_INITIALIZED_ERROR, ErrorCode.E_INVALID_INPUT);
 }
-async function sendProgressNotification(extra, params) {
-    if (!canSendProgress(extra))
-        return;
-    try {
-        await extra.sendNotification({
-            method: 'notifications/progress',
-            params,
-        });
+async function reportProgress(extra, progress) {
+    const taskExtra = extra;
+    if (typeof taskExtra.taskId === 'string' &&
+        taskExtra.taskStore !== undefined &&
+        taskExtra.taskStore !== null) {
+        const store = taskExtra.taskStore;
+        if (typeof store.updateTaskStatus === 'function') {
+            try {
+                let statusMessage = progress.message;
+                if (progress.total !== undefined) {
+                    statusMessage = statusMessage
+                        ? `${statusMessage} (${progress.current}/${progress.total})`
+                        : `${progress.current}/${progress.total}`;
+                }
+                else {
+                    statusMessage ??= `${progress.current}`;
+                }
+                await store.updateTaskStatus(taskExtra.taskId, 'working', statusMessage);
+            }
+            catch (error) {
+                console.error('Failed to update task status message:', error);
+            }
+        }
     }
-    catch (error) {
-        // Ignore progress notification failures to avoid breaking tool execution.
-        console.error('Failed to send progress notification:', error);
+    if (canSendProgress(extra)) {
+        try {
+            await extra.sendNotification({
+                method: 'notifications/progress',
+                params: {
+                    progressToken: extra._meta.progressToken,
+                    progress: progress.current,
+                    ...(progress.total !== undefined ? { total: progress.total } : {}),
+                    ...(progress.message !== undefined
+                        ? { message: progress.message }
+                        : {}),
+                },
+            });
+        }
+        catch (error) {
+            console.error('Failed to send progress notification:', error);
+        }
     }
 }
 export function createProgressReporter(extra) {
-    if (!canSendProgress(extra)) {
+    if (!canReportProgress(extra)) {
         return () => { };
     }
-    const token = extra._meta.progressToken;
     // State for monotonic enforcement and rate-limiting.
     let lastProgress = -1;
     let lastSentMs = 0;
@@ -251,52 +284,41 @@ export function createProgressReporter(extra) {
             return;
         lastProgress = current;
         lastSentMs = now;
-        void sendProgressNotification(extra, {
-            progressToken: token,
-            progress: current,
+        void reportProgress(extra, {
+            current,
             ...(total !== undefined ? { total } : {}),
             ...(message !== undefined ? { message } : {}),
         });
     };
 }
 export function notifyProgress(extra, progress) {
-    if (!canSendProgress(extra))
+    if (!canReportProgress(extra))
         return;
-    const token = extra._meta.progressToken;
-    void sendProgressNotification(extra, {
-        progressToken: token,
-        progress: progress.current,
-        ...(progress.total !== undefined ? { total: progress.total } : {}),
-        ...(progress.message !== undefined ? { message: progress.message } : {}),
-    });
+    void reportProgress(extra, progress);
 }
 async function withProgress(message, extra, run, getCompletionMessage) {
-    if (!canSendProgress(extra)) {
+    if (!canReportProgress(extra)) {
         return run();
     }
-    const token = extra._meta.progressToken;
     const total = 1;
-    await sendProgressNotification(extra, {
-        progressToken: token,
-        progress: 0,
+    await reportProgress(extra, {
+        current: 0,
         total,
         message,
     });
     try {
         const result = await run();
         const endMessage = getCompletionMessage?.(result) ?? message;
-        await sendProgressNotification(extra, {
-            progressToken: token,
-            progress: total,
+        await reportProgress(extra, {
+            current: total,
             total,
             message: endMessage,
         });
         return result;
     }
     catch (error) {
-        void sendProgressNotification(extra, {
-            progressToken: token,
-            progress: total,
+        void reportProgress(extra, {
+            current: total,
             total,
             message: `${message} • failed`,
         });

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, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, 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',
@@ -13,6 +13,7 @@ export const GET_MULTIPLE_FILE_INFO_TOOL = {
     inputSchema: GetMultipleFileInfoInputSchema,
     outputSchema: GetMultipleFileInfoOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    taskSupport: 'required',
     nuances: ['Use before read/search when file size/type uncertainty exists.'],
 };
 function formatFileInfoDetail(info) {
@@ -28,10 +29,11 @@ function formatFileInfoDetail(info) {
         lines.push(`  Target: ${info.symlinkTarget}`);
     return joinLines(lines);
 }
-async function handleGetMultipleFileInfo(args, signal) {
+async function handleGetMultipleFileInfo(args, signal, onProgress) {
     const result = await getMultipleFileInfo(args.paths, {
         includeMimeType: true,
         ...(signal ? { signal } : {}),
+        ...(onProgress ? { onProgress } : {}),
     });
     const structuredResults = [];
     const textBlocks = [];
@@ -71,30 +73,61 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
             extra,
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: primaryPath },
-            run: (signal) => handleGetMultipleFileInfo(args, signal),
+            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} paths [${first}${extraPaths}]`;
+                let progressCursor = 0;
+                notifyProgress(extra, {
+                    current: 0,
+                    message: `🕮 stat_many: ${context}`,
+                });
+                const baseReporter = createProgressReporter(extra);
+                const onProgress = () => {
+                    progressCursor++;
+                    baseReporter({
+                        current: progressCursor,
+                        message: `🕮 stat_many: ${context} [${progressCursor}/${args.paths.length} scanned]`,
+                    });
+                };
+                try {
+                    const result = await handleGetMultipleFileInfo(args, signal, onProgress);
+                    const sc = result.structuredContent;
+                    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} OK, ${failed} failed`;
+                    }
+                    else {
+                        suffix = `${total} OK`;
+                    }
+                    const finalCurrent = Math.max(total, progressCursor + 1);
+                    notifyProgress(extra, {
+                        current: finalCurrent,
+                        total: finalCurrent,
+                        message: `🕮 stat_many: ${context} • ${suffix}`,
+                    });
+                    return result;
+                }
+                catch (error) {
+                    const finalCurrent = Math.max(progressCursor + 1, 1);
+                    notifyProgress(extra, {
+                        current: finalCurrent,
+                        total: finalCurrent,
+                        message: `🕮 stat_many: ${context} • failed`,
+                    });
+                    throw error;
+                }
+            },
             onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, primaryPath),
         });
     };
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => {
-            const first = path.basename(args.paths[0] ?? '');
-            const extra = args.paths.length > 1 ? `, ${path.basename(args.paths[1] ?? '')}…` : '';
-            return `🕮 stat_many: ${args.paths.length} paths [${first}${extra}]`;
-        },
-        completionMessage: (args, result) => {
-            if (result.isError)
-                return `🕮 stat_many: ${args.paths.length} paths • failed`;
-            const sc = result.structuredContent;
-            if (!sc.ok)
-                return `🕮 stat_many: ${args.paths.length} paths • failed`;
-            const total = sc.summary?.total ?? 0;
-            const succeeded = sc.summary?.succeeded ?? 0;
-            const failed = sc.summary?.failed ?? 0;
-            if (failed)
-                return `🕮 stat_many: ${succeeded}/${total} OK, ${failed} failed`;
-            return `🕮 stat_many: ${total} OK`;
-        },
     });
     const validatedHandler = withValidatedArgs(GetMultipleFileInfoInputSchema, wrappedHandler);
     if (registerToolTaskIfAvailable(server, 'stat_many', GET_MULTIPLE_FILE_INFO_TOOL, validatedHandler, options.iconInfo, options.isInitialized))

package/dist/tools/task-support.js

@@ -304,7 +304,12 @@ export function tryRegisterToolTask(server, toolName, toolDef, taskHandler, icon
     const tasks = getExperimentalTaskRegistration(server);
     if (!tasks?.registerToolTask)
         return false;
-    tasks.registerToolTask(toolName, withDefaultIcons({ ...toolDef, execution: { taskSupport: 'optional' } }, iconInfo), taskHandler);
+    const def = toolDef;
+    const existingExecution = def.execution ?? {};
+    const taskSupport = def.taskSupport ??
+        existingExecution.taskSupport ??
+        'optional';
+    tasks.registerToolTask(toolName, withDefaultIcons({ ...toolDef, execution: { ...existingExecution, taskSupport } }, iconInfo), taskHandler);
     return true;
 }
 export function registerToolTaskIfAvailable(server, toolName, toolDef, run, iconInfo, guard) {

package/dist/tools/tree.js

@@ -3,7 +3,7 @@ import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { formatTreeAscii, treeDirectory } from '../lib/file-operations/tree.js';
 import { TreeInputSchema, TreeOutputSchema } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const TREE_TOOL = {
     name: 'tree',
@@ -14,9 +14,10 @@ export const TREE_TOOL = {
     inputSchema: TreeInputSchema,
     outputSchema: TreeOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    taskSupport: 'required',
     gotchas: ['`maxDepth=0` returns only the root node.'],
 };
-async function handleTree(args, signal) {
+async function handleTree(args, signal, onProgress) {
     const basePath = resolvePathOrRoot(args.path);
     const result = await treeDirectory(basePath, {
         maxDepth: args.maxDepth,
@@ -24,6 +25,7 @@ async function handleTree(args, signal) {
         includeHidden: args.includeHidden,
         includeIgnored: args.includeIgnored,
         ...(signal ? { signal } : {}),
+        ...(onProgress ? { onProgress } : {}),
     });
     const ascii = formatTreeAscii(result.tree);
     const structured = {
@@ -45,30 +47,54 @@ export function registerTreeTool(server, options = {}) {
             extra,
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: targetPath },
-            run: (signal) => handleTree(args, signal),
+            run: async (signal) => {
+                const context = args.path ? path.basename(args.path) : '.';
+                let progressCursor = 0;
+                notifyProgress(extra, {
+                    current: 0,
+                    message: `≣ tree: ${context}`,
+                });
+                const baseReporter = createProgressReporter(extra);
+                const onProgress = (progress) => {
+                    const { current } = progress;
+                    if (current > progressCursor)
+                        progressCursor = current;
+                    baseReporter({
+                        current,
+                        message: `≣ tree: ${context} [${current} entries]`,
+                    });
+                };
+                try {
+                    const result = await handleTree(args, signal, onProgress);
+                    const sc = result.structuredContent;
+                    const count = sc.totalEntries ?? 0;
+                    const { truncated } = sc;
+                    let suffix = `${count} ${count === 1 ? 'entry' : 'entries'}`;
+                    if (truncated)
+                        suffix += ' [truncated]';
+                    const finalCurrent = Math.max(count, progressCursor + 1);
+                    notifyProgress(extra, {
+                        current: finalCurrent,
+                        total: finalCurrent,
+                        message: `≣ tree: ${context} • ${suffix}`,
+                    });
+                    return result;
+                }
+                catch (error) {
+                    const finalCurrent = Math.max(progressCursor + 1, 1);
+                    notifyProgress(extra, {
+                        current: finalCurrent,
+                        total: finalCurrent,
+                        message: `≣ tree: ${context} • failed`,
+                    });
+                    throw error;
+                }
+            },
             onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_DIRECTORY, targetPath),
         });
     };
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => {
-            if (args.path) {
-                return `≣ tree: ${path.basename(args.path)}`;
-            }
-            return '≣ tree';
-        },
-        completionMessage: (args, result) => {
-            const base = args.path ? path.basename(args.path) : '.';
-            if (result.isError)
-                return `≣ tree: ${base} • failed`;
-            const sc = result.structuredContent;
-            if (!sc.ok)
-                return `≣ tree: ${base} • failed`;
-            const count = sc.totalEntries ?? 0;
-            if (sc.truncated)
-                return `≣ tree: ${base} • ${count} entries [truncated]`;
-            return `≣ tree: ${base} • ${count} ${count === 1 ? 'entry' : 'entries'}`;
-        },
     });
     const validatedHandler = withValidatedArgs(TreeInputSchema, wrappedHandler);
     if (registerToolTaskIfAvailable(server, 'tree', TREE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/filesystem-mcp",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "mcpName": "io.github.j0hanz/filesystem-mcp",
   "description": "MCP Server that enables LLMs to interact with the local filesystem.",
   "type": "module",