@j0hanz/filesystem-mcp 1.5.3 → 1.6.0

package/dist/lib/errors.d.ts

@@ -9,6 +9,7 @@ interface DetailedError {
 }
 export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;
 export declare function formatUnknownErrorMessage(error: unknown): string;
+export declare function normalizeUnknownError(error: unknown): Error;
 export declare function isAbortError(error: unknown): boolean;
 export declare function isTimeoutLikeError(error: unknown): boolean;
 export declare class McpError extends Error {

package/dist/lib/errors.js

@@ -94,6 +94,11 @@ export function formatUnknownErrorMessage(error) {
         return String(error);
     }
 }
+export function normalizeUnknownError(error) {
+    return error instanceof Error
+        ? error
+        : new Error(formatUnknownErrorMessage(error));
+}
 const NODE_ERROR_CODE_MAP = {
     ENOENT: ErrorCode.E_NOT_FOUND,
     EACCES: ErrorCode.E_PERMISSION_DENIED,

package/dist/lib/fs-helpers.js

@@ -5,7 +5,7 @@ import { randomUUID } from 'node:crypto';
 import { Writable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { BINARY_CHECK_BUFFER_SIZE, KNOWN_BINARY_EXTENSIONS, MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY, } from './constants.js';
-import { ErrorCode, formatUnknownErrorMessage, McpError } from './errors.js';
+import { ErrorCode, McpError, normalizeUnknownError } from './errors.js';
 import { assertAllowedFileAccess } from './path-policy.js';
 import { validateExistingPath } from './path-validation.js';
 function createAbortError(message = 'Operation aborted') {
@@ -20,11 +20,6 @@ function normalizeAbortReason(reason, message) {
 function isFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value);
 }
-function normalizeUnknownError(error) {
-    return error instanceof Error
-        ? error
-        : new Error(formatUnknownErrorMessage(error));
-}
 export function assertNotAborted(signal, message) {
     if (!signal)
         return;

package/dist/schemas.d.ts

@@ -33,6 +33,8 @@ export declare const ToolErrorResponseSchema: z.ZodObject<{
         suggestion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
 }, z.core.$strict>;
+declare const HeadLinesSchema: z.ZodOptional<z.ZodInt>;
+declare const LineNumberSchema: z.ZodNumber;
 export declare const ListDirectoryInputSchema: z.ZodObject<{
     path: z.ZodOptional<z.ZodString>;
     includeHidden: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
@@ -85,16 +87,16 @@ export declare const SearchContentInputSchema: z.ZodObject<{
     includeIgnored: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strict>;
 export declare const ReadFileInputSchema: z.ZodObject<{
+    head: typeof HeadLinesSchema;
+    startLine: z.ZodOptional<typeof LineNumberSchema>;
+    endLine: z.ZodOptional<typeof LineNumberSchema>;
     path: z.ZodString;
-    head: z.ZodOptional<z.ZodInt>;
-    startLine: z.ZodOptional<z.ZodNumber>;
-    endLine: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export declare const ReadMultipleFilesInputSchema: z.ZodObject<{
+    head: typeof HeadLinesSchema;
+    startLine: z.ZodOptional<typeof LineNumberSchema>;
+    endLine: z.ZodOptional<typeof LineNumberSchema>;
     paths: z.ZodArray<z.ZodString>;
-    head: z.ZodOptional<z.ZodInt>;
-    startLine: z.ZodOptional<z.ZodNumber>;
-    endLine: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export declare const GetFileInfoInputSchema: z.ZodObject<{
     path: z.ZodString;
@@ -472,11 +474,13 @@ export declare const GetMultipleFileInfoOutputSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const CreateDirectoryInputSchema: z.ZodObject<{
-    path: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export declare const CreateDirectoryOutputSchema: z.ZodObject<{
     ok: z.ZodBoolean;
     path: z.ZodOptional<z.ZodString>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
     error: z.ZodOptional<z.ZodObject<{
         code: z.ZodEnum<{
             readonly E_ACCESS_DENIED: "E_ACCESS_DENIED";
@@ -532,6 +536,7 @@ export declare const EditFileInputSchema: z.ZodObject<{
         newText: z.ZodString;
     }, z.core.$strict>>;
     dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    ignoreWhitespace: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strict>;
 export declare const EditFileOutputSchema: z.ZodObject<{
     ok: z.ZodBoolean;
@@ -560,13 +565,19 @@ export declare const EditFileOutputSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const MoveFileInputSchema: z.ZodObject<{
-    source: z.ZodString;
+    source: z.ZodOptional<z.ZodString>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodString>>;
     destination: z.ZodString;
 }, z.core.$strict>;
 export declare const MoveFileOutputSchema: z.ZodObject<{
     ok: z.ZodBoolean;
     source: z.ZodOptional<z.ZodString>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodString>>;
     destination: z.ZodOptional<z.ZodString>;
+    failed: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        error: z.ZodString;
+    }, z.core.$strict>>>;
     error: z.ZodOptional<z.ZodObject<{
         code: z.ZodEnum<{
             readonly E_ACCESS_DENIED: "E_ACCESS_DENIED";
@@ -717,6 +728,7 @@ export declare const SearchAndReplaceInputSchema: z.ZodObject<{
     dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     includeHidden: z.ZodOptional<z.ZodBoolean>;
     includeIgnored: z.ZodOptional<z.ZodBoolean>;
+    returnDiff: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const SearchAndReplaceOutputSchema: z.ZodObject<{
     ok: z.ZodBoolean;

package/dist/schemas.js

@@ -81,6 +81,13 @@ const validateReadRange = (value, ctx) => {
         addReadRangeIssue(ctx, 'endLine', "'endLine' must be >= 'startLine'");
     }
 };
+function createReadRangeInputFields(descriptions) {
+    return {
+        head: HeadLinesSchema.describe(descriptions.head),
+        startLine: LineNumberSchema.optional().describe(descriptions.startLine),
+        endLine: LineNumberSchema.optional().describe(descriptions.endLine),
+    };
+}
 const FileInfoSchema = z.strictObject({
     name: z.string().describe('Name'),
     path: z.string().describe('Absolute path'),
@@ -280,9 +287,11 @@ export const SearchContentInputSchema = z.strictObject({
 export const ReadFileInputSchema = z
     .strictObject({
     path: RequiredPathSchema.describe(DESC_PATH_REQUIRED),
-    head: HeadLinesSchema.describe('Read first N lines (preview)'),
-    startLine: LineNumberSchema.optional().describe('Start line (1-based, inclusive)'),
-    endLine: LineNumberSchema.optional().describe('End line (1-based, inclusive). Requires startLine.'),
+    ...createReadRangeInputFields({
+        head: 'Read first N lines (preview)',
+        startLine: 'Start line (1-based, inclusive)',
+        endLine: 'End line (1-based, inclusive). Requires startLine.',
+    }),
 })
     .superRefine(validateReadRange);
 export const ReadMultipleFilesInputSchema = z
@@ -292,9 +301,11 @@ export const ReadMultipleFilesInputSchema = z
         .min(1, 'Min 1 path required')
         .max(100, 'Max 100 files')
         .describe('Files to read. e.g. ["src/index.ts"]'),
-    head: HeadLinesSchema.describe('Read first N lines of each file'),
-    startLine: LineNumberSchema.optional().describe('Start line (1-based, inclusive) per file'),
-    endLine: LineNumberSchema.optional().describe('End line (1-based, inclusive) per file. Requires startLine.'),
+    ...createReadRangeInputFields({
+        head: 'Read first N lines of each file',
+        startLine: 'Start line (1-based, inclusive) per file',
+        endLine: 'End line (1-based, inclusive) per file. Requires startLine.',
+    }),
 })
     .superRefine(validateReadRange);
 export const GetFileInfoInputSchema = z.strictObject({
@@ -459,12 +470,22 @@ export const GetMultipleFileInfoOutputSchema = z.strictObject({
     summary: OperationSummarySchema.optional(),
     error: ErrorSchema.optional(),
 });
-export const CreateDirectoryInputSchema = z.strictObject({
-    path: RequiredPathSchema.describe(DESC_PATH_REQUIRED),
+export const CreateDirectoryInputSchema = z
+    .strictObject({
+    path: RequiredPathSchema.optional().describe(DESC_PATH_REQUIRED),
+    paths: z
+        .array(RequiredPathSchema)
+        .optional()
+        .describe('Absolute paths to directories to create'),
+})
+    .refine((data) => data.path !== undefined || data.paths !== undefined, {
+    message: "Either 'path' or 'paths' must be provided",
+    path: ['path'],
 });
 export const CreateDirectoryOutputSchema = z.strictObject({
     ok: z.boolean(),
     path: z.string().optional(),
+    paths: z.array(z.string()).optional(),
     error: ErrorSchema.optional(),
 });
 export const WriteFileInputSchema = z.strictObject({
@@ -495,6 +516,11 @@ export const EditFileInputSchema = z.strictObject({
         .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.'),
 });
 export const EditFileOutputSchema = z.strictObject({
     ok: z.boolean(),
@@ -510,14 +536,28 @@ export const EditFileOutputSchema = z.strictObject({
         .describe('Edits that could not be applied'),
     error: ErrorSchema.optional(),
 });
-export const MoveFileInputSchema = z.strictObject({
-    source: RequiredPathSchema.describe('Path to move'),
+export const MoveFileInputSchema = z
+    .strictObject({
+    source: RequiredPathSchema.optional().describe('Path to move (deprecated: use sources)'),
+    sources: z.array(RequiredPathSchema).optional().describe('Paths to move'),
     destination: RequiredPathSchema.describe('New path'),
+})
+    .refine((data) => (data.source ?? data.sources) !== undefined, {
+    message: "Either 'source' or 'sources' must be provided",
+    path: ['source'],
 });
 export const MoveFileOutputSchema = z.strictObject({
     ok: z.boolean(),
     source: z.string().optional(),
+    sources: z.array(z.string()).optional(),
     destination: z.string().optional(),
+    failed: z
+        .array(z.strictObject({
+        source: z.string().describe('Source path'),
+        error: z.string().describe('Error message'),
+    }))
+        .optional()
+        .describe('List of files that failed to move'),
     error: ErrorSchema.optional(),
 });
 export const DeleteFileInputSchema = z.strictObject({
@@ -643,6 +683,10 @@ export const SearchAndReplaceInputSchema = z.strictObject({
         .boolean()
         .optional()
         .describe('Include files and directories ignored by .gitignore rules (e.g. node_modules, dist). Default: false.'),
+    returnDiff: z
+        .boolean()
+        .optional()
+        .describe('Return unified diff of changes even if dryRun is false. Default: false.'),
 });
 export const SearchAndReplaceOutputSchema = z.strictObject({
     ok: z.boolean(),

package/dist/tools/create-directory.d.ts

@@ -1,4 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+import type { z } from 'zod';
+import { CreateDirectoryInputSchema, CreateDirectoryOutputSchema } from '../schemas.js';
+import { type ToolContract, type ToolRegistrationOptions, type ToolResponse } from './shared.js';
 export declare const CREATE_DIRECTORY_TOOL: ToolContract;
+export declare function handleCreateDirectory(args: z.infer<typeof CreateDirectoryInputSchema>, signal?: AbortSignal): Promise<ToolResponse<z.infer<typeof CreateDirectoryOutputSchema>>>;
 export declare function registerCreateDirectoryTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/create-directory.js

@@ -1,6 +1,5 @@
 import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { ErrorCode } from '../lib/errors.js';
+import { ErrorCode, McpError } from '../lib/errors.js';
 import { withAbort } from '../lib/fs-helpers.js';
 import { validatePathForWrite } from '../lib/path-validation.js';
 import { CreateDirectoryInputSchema, CreateDirectoryOutputSchema, } from '../schemas.js';
@@ -15,12 +14,20 @@ export const CREATE_DIRECTORY_TOOL = {
     annotations: IDEMPOTENT_WRITE_TOOL_ANNOTATIONS,
     nuances: ['Succeeds silently if the directory already exists (idempotent).'],
 };
-async function handleCreateDirectory(args, signal) {
-    const validPath = await validatePathForWrite(args.path, signal);
-    await withAbort(fs.mkdir(validPath, { recursive: true }), signal);
-    return buildToolResponse(`Successfully created directory: ${args.path}`, {
+export async function handleCreateDirectory(args, signal) {
+    const allPaths = [];
+    if (args.path)
+        allPaths.push(args.path);
+    if (args.paths)
+        allPaths.push(...args.paths);
+    if (allPaths.length === 0) {
+        throw new McpError(ErrorCode.E_INVALID_INPUT, 'No paths provided to create.');
+    }
+    const validPaths = await Promise.all(allPaths.map((p) => validatePathForWrite(p, signal)));
+    await Promise.all(validPaths.map((p) => withAbort(fs.mkdir(p, { recursive: true }), signal)));
+    return buildToolResponse(`Successfully created ${validPaths.length} director${validPaths.length === 1 ? 'y' : 'ies'}`, {
         ok: true,
-        path: validPath,
+        paths: validPaths,
     });
 }
 export function registerCreateDirectoryTool(server, options = {}) {
@@ -28,21 +35,21 @@ export function registerCreateDirectoryTool(server, options = {}) {
         toolName: 'mkdir',
         extra,
         timedSignal: {},
-        context: { path: args.path },
+        context: { path: args.path ?? args.paths?.[0] },
         run: (signal) => handleCreateDirectory(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path ?? args.paths?.[0]),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
-            const name = path.basename(args.path) || '.';
-            return `🛠 mkdir: ${name}`;
+            const count = (args.path ? 1 : 0) + (args.paths?.length ?? 0);
+            return `🛠 mkdir: ${count} director${count === 1 ? 'y' : 'ies'}`;
         },
         completionMessage: (args, result) => {
-            const name = path.basename(args.path) || '.';
+            const count = (args.path ? 1 : 0) + (args.paths?.length ?? 0);
             if (result.isError)
-                return `🛠 mkdir: ${name} • failed`;
-            return `🛠 mkdir: ${name} • created`;
+                return `🛠 mkdir: ${count} • failed`;
+            return `🛠 mkdir: ${count} • created`;
         },
     });
     const validatedHandler = withValidatedArgs(CreateDirectoryInputSchema, wrappedHandler);

package/dist/tools/edit-file.d.ts

@@ -1,4 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+import type { z } from 'zod';
+import { EditFileInputSchema, EditFileOutputSchema } from '../schemas.js';
+import { type ToolContract, type ToolRegistrationOptions, type ToolResponse } from './shared.js';
 export declare const EDIT_FILE_TOOL: ToolContract;
+export declare function handleEditFile(args: z.infer<typeof EditFileInputSchema>, signal?: AbortSignal): Promise<ToolResponse<z.infer<typeof EditFileOutputSchema>>>;
 export declare function registerEditFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/edit-file.js

@@ -23,28 +23,57 @@ export const EDIT_FILE_TOOL = {
         '`oldText` must match exactly; unmatched items are reported in `unmatchedEdits`.',
     ],
 };
-function applyEdits(content, edits) {
+function escapeRegExp(string) {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function applyEdits(content, edits, ignoreWhitespace) {
     let newContent = content;
     let appliedEdits = 0;
     const unmatchedEdits = [];
     let minLine;
     let maxLine;
     for (const edit of edits) {
-        if (!newContent.includes(edit.oldText)) {
-            unmatchedEdits.push(edit.oldText);
-            continue;
+        if (ignoreWhitespace) {
+            const pattern = escapeRegExp(edit.oldText).replace(/\s+/g, '\\s+');
+            const regex = new RegExp(pattern);
+            const match = regex.exec(newContent);
+            if (!match) {
+                unmatchedEdits.push(edit.oldText);
+                continue;
+            }
+            const { index } = match;
+            const matchLength = match[0].length;
+            const linesBefore = newContent.slice(0, index).split('\n').length;
+            const newTextLines = edit.newText.split('\n').length;
+            const startLine = linesBefore;
+            const endLine = linesBefore + newTextLines - 1;
+            if (minLine === undefined || startLine < minLine)
+                minLine = startLine;
+            if (maxLine === undefined || endLine > maxLine)
+                maxLine = endLine;
+            newContent =
+                newContent.slice(0, index) +
+                    edit.newText +
+                    newContent.slice(index + matchLength);
+            appliedEdits += 1;
+        }
+        else {
+            if (!newContent.includes(edit.oldText)) {
+                unmatchedEdits.push(edit.oldText);
+                continue;
+            }
+            const index = newContent.indexOf(edit.oldText);
+            const linesBefore = newContent.slice(0, index).split('\n').length;
+            const newTextLines = edit.newText.split('\n').length;
+            const startLine = linesBefore;
+            const endLine = linesBefore + newTextLines - 1;
+            if (minLine === undefined || startLine < minLine)
+                minLine = startLine;
+            if (maxLine === undefined || endLine > maxLine)
+                maxLine = endLine;
+            newContent = newContent.replace(edit.oldText, () => edit.newText);
+            appliedEdits += 1;
         }
-        const index = newContent.indexOf(edit.oldText);
-        const linesBefore = newContent.slice(0, index).split('\n').length;
-        const newTextLines = edit.newText.split('\n').length;
-        const startLine = linesBefore;
-        const endLine = linesBefore + newTextLines - 1;
-        if (minLine === undefined || startLine < minLine)
-            minLine = startLine;
-        if (maxLine === undefined || endLine > maxLine)
-            maxLine = endLine;
-        newContent = newContent.replace(edit.oldText, () => edit.newText);
-        appliedEdits += 1;
     }
     const result = {
         content: newContent,
@@ -56,10 +85,10 @@ function applyEdits(content, edits) {
     }
     return result;
 }
-async function handleEditFile(args, signal) {
+export async function handleEditFile(args, signal) {
     const validPath = await validateExistingPath(args.path, signal);
     const content = await fs.readFile(validPath, { encoding: 'utf-8', signal });
-    const { content: newContent, appliedEdits, unmatchedEdits, lineRange, } = applyEdits(content, args.edits);
+    const { content: newContent, appliedEdits, unmatchedEdits, lineRange, } = applyEdits(content, args.edits, args.ignoreWhitespace);
     const structured = {
         ok: true,
         path: validPath,

package/dist/tools/move-file.d.ts

@@ -1,4 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+import type { z } from 'zod';
+import { MoveFileInputSchema, MoveFileOutputSchema } from '../schemas.js';
+import { type ToolContract, type ToolRegistrationOptions, type ToolResponse } from './shared.js';
 export declare const MOVE_FILE_TOOL: ToolContract;
+export declare function handleMoveFile(args: z.infer<typeof MoveFileInputSchema>, signal?: AbortSignal): Promise<ToolResponse<z.infer<typeof MoveFileOutputSchema>>>;
 export declare function registerMoveFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/move-file.js

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { ErrorCode, isNodeError } from '../lib/errors.js';
+import { ErrorCode, formatUnknownErrorMessage, isNodeError, McpError, } from '../lib/errors.js';
 import { withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath, validatePathForWrite, } from '../lib/path-validation.js';
 import { MoveFileInputSchema, MoveFileOutputSchema } from '../schemas.js';
@@ -18,28 +18,95 @@ export const MOVE_FILE_TOOL = {
         'On POSIX, an existing destination is silently overwritten; on Windows, rename fails with EEXIST if destination exists.',
     ],
 };
-async function handleMoveFile(args, signal) {
-    const validSource = await validateExistingPath(args.source, signal);
+export async function handleMoveFile(args, signal) {
+    const sources = args.sources ?? (args.source ? [args.source] : []);
+    if (sources.length === 0) {
+        throw new McpError(ErrorCode.E_INVALID_INPUT, 'No sources provided.');
+    }
     const validDest = await validatePathForWrite(args.destination, signal);
-    // Ensure destination parent directory exists
-    await withAbort(fs.mkdir(path.dirname(validDest), { recursive: true }), signal);
+    // Check if destination exists and is a directory
+    let destIsDirectory = false;
     try {
-        await withAbort(fs.rename(validSource, validDest), signal);
+        const stats = await fs.stat(validDest);
+        destIsDirectory = stats.isDirectory();
     }
     catch (error) {
-        if (isNodeError(error) && error.code === 'EXDEV') {
-            // Cross-device link, fallback to copy + delete
-            await withAbort(fs.cp(validSource, validDest, { recursive: true }), signal);
-            await withAbort(fs.rm(validSource, { recursive: true, force: true }), signal);
-        }
-        else {
+        if (isNodeError(error) && error.code !== 'ENOENT') {
             throw error;
         }
     }
-    return buildToolResponse(`Successfully moved ${args.source} to ${args.destination}`, {
-        ok: true,
-        source: validSource,
+    if (sources.length > 1 && !destIsDirectory) {
+        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Destination must be an existing directory when moving multiple files.');
+    }
+    // Ensure destination parent directory exists if it's not an existing directory
+    if (!destIsDirectory) {
+        await withAbort(fs.mkdir(path.dirname(validDest), { recursive: true }), signal);
+    }
+    const movedSources = [];
+    const failed = [];
+    for (const src of sources) {
+        let validSource;
+        try {
+            validSource = await validateExistingPath(src, signal);
+        }
+        catch (error) {
+            failed.push({
+                source: src,
+                error: formatUnknownErrorMessage(error),
+            });
+            continue;
+        }
+        const targetPath = destIsDirectory
+            ? path.join(validDest, path.basename(validSource))
+            : validDest;
+        // Prevent moving a file onto itself
+        if (path.resolve(validSource) === path.resolve(targetPath)) {
+            continue;
+        }
+        // Prevent moving a directory into its own subdirectory
+        // Fixes "Missing validation for moving directory into its own subdirectory" finding
+        if (path.resolve(targetPath).startsWith(path.resolve(validSource) + path.sep)) {
+            failed.push({
+                source: src,
+                error: `Cannot move directory '${src}' into its own subdirectory '${targetPath}'`,
+            });
+            continue;
+        }
+        try {
+            await withAbort(fs.rename(validSource, targetPath), signal);
+            movedSources.push(validSource);
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === 'EXDEV') {
+                // Cross-device link, fallback to copy + delete
+                try {
+                    await withAbort(fs.cp(validSource, targetPath, { recursive: true }), signal);
+                    await withAbort(fs.rm(validSource, { recursive: true, force: true }), signal);
+                    movedSources.push(validSource);
+                }
+                catch (copyError) {
+                    failed.push({
+                        source: src,
+                        error: formatUnknownErrorMessage(copyError),
+                    });
+                }
+            }
+            else {
+                failed.push({
+                    source: src,
+                    error: formatUnknownErrorMessage(error),
+                });
+            }
+        }
+    }
+    const message = failed.length > 0
+        ? `Moved ${movedSources.length} item${movedSources.length === 1 ? '' : 's'}; failed to move ${failed.length} item${failed.length === 1 ? '' : 's'}`
+        : `Successfully moved ${movedSources.length} item${movedSources.length === 1 ? '' : 's'} to ${args.destination}`;
+    return buildToolResponse(message, {
+        ok: failed.length === 0,
+        sources: movedSources,
         destination: validDest,
+        ...(failed.length > 0 ? { failed } : {}),
     });
 }
 export function registerMoveFileTool(server, options = {}) {
@@ -47,19 +114,23 @@ export function registerMoveFileTool(server, options = {}) {
         toolName: 'mv',
         extra,
         timedSignal: {},
-        context: { path: args.source },
+        context: { path: args.source ?? args.sources?.[0] },
         run: (signal) => handleMoveFile(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.source),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.source ?? args.sources?.[0]),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => `🛠 mv: ${path.basename(args.source)} → ${path.basename(args.destination)}`,
+        progressMessage: (args) => {
+            const count = (args.source ? 1 : 0) + (args.sources?.length ?? 0);
+            const dest = path.basename(args.destination);
+            return `🛠 mv: ${count} item${count === 1 ? '' : 's'} → ${dest}`;
+        },
         completionMessage: (args, result) => {
-            const src = path.basename(args.source);
-            const dst = path.basename(args.destination);
+            const count = (args.source ? 1 : 0) + (args.sources?.length ?? 0);
+            const dest = path.basename(args.destination);
             if (result.isError)
-                return `🛠 mv: ${src} → ${dst} • failed`;
-            return `🛠 mv: ${src} → ${dst} • moved`;
+                return `🛠 mv: ${count} → ${dest} • failed`;
+            return `🛠 mv: ${count} → ${dest} • moved`;
         },
     });
     const validatedHandler = withValidatedArgs(MoveFileInputSchema, wrappedHandler);

package/dist/tools/read-multiple.js

@@ -14,7 +14,7 @@ export const READ_MULTIPLE_FILES_TOOL = {
     inputSchema: ReadMultipleFilesInputSchema,
     outputSchema: ReadMultipleFilesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
-    taskSupport: 'required',
+    taskSupport: 'optional',
     nuances: ['Total read budget is capped by `MAX_READ_MANY_TOTAL_SIZE`.'],
     gotchas: [
         'Per-file `truncationReason` can be `head`, `range`, or `externalized`.',

package/dist/tools/replace-in-files.d.ts

@@ -1,4 +1,10 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+import type { z } from 'zod';
+import { SearchAndReplaceInputSchema, SearchAndReplaceOutputSchema } from '../schemas.js';
+import { type ToolContract, type ToolRegistrationOptions, type ToolResponse } from './shared.js';
 export declare const SEARCH_AND_REPLACE_TOOL: ToolContract;
+export declare function handleSearchAndReplace(args: z.infer<typeof SearchAndReplaceInputSchema>, signal?: AbortSignal, onProgress?: (progress: {
+    total?: number;
+    current: number;
+}) => void): Promise<ToolResponse<z.infer<typeof SearchAndReplaceOutputSchema>>>;
 export declare function registerSearchAndReplaceTool(server: McpServer, options?: ToolRegistrationOptions): void;

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

@@ -23,7 +23,7 @@ export const SEARCH_AND_REPLACE_TOOL = {
     inputSchema: SearchAndReplaceInputSchema,
     outputSchema: SearchAndReplaceOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
-    taskSupport: 'required',
+    taskSupport: 'optional',
     gotchas: [
         'Literal mode is default; `isRegex=true` enables RE2 + capture replacements (`$1`, `$2`).',
     ],
@@ -122,7 +122,8 @@ async function processEntry(entryPath, args, regex, maxFileSize, signal, summary
             else {
                 newContent = content.replaceAll(args.searchPattern, () => args.replacement);
             }
-            if (args.dryRun && summary.diff.length < MAX_DIFF_SIZE) {
+            if ((args.dryRun || args.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
                 if (summary.diff.length + patch.length <= MAX_DIFF_SIZE + 1024) {
@@ -201,7 +202,7 @@ function reportReplaceProgress(onProgress, current, force = false) {
         return;
     onProgress({ current });
 }
-async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
+export async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
     const maxFileSize = MAX_TEXT_FILE_SIZE;
     const root = await resolveSearchRoot(args.path, signal);
     const regex = createReplacementRegex(args);
@@ -240,7 +241,9 @@ async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
             ? { changedFiles: summary.changedFiles }
             : {}),
         ...(summary.changedFilesTruncated ? { changedFilesTruncated: true } : {}),
-        ...(args.dryRun && summary.diff ? { diff: summary.diff } : {}),
+        ...((args.dryRun || args.returnDiff) && summary.diff
+            ? { diff: summary.diff }
+            : {}),
         dryRun: args.dryRun,
     });
 }

package/dist/tools/search-content.js

@@ -26,7 +26,7 @@ export const SEARCH_CONTENT_TOOL = {
     gotchas: [
         'Skips binary and oversized files silently — check file type with `stat` if no matches appear.',
     ],
-    taskSupport: 'required',
+    taskSupport: 'optional',
 };
 function assertValidRegexPattern(pattern) {
     try {

package/dist/tools/search-files.js

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

package/dist/tools/shared.js

@@ -89,12 +89,6 @@ export function buildResourceLink(params) {
         ...(params.mimeType ? { mimeType: params.mimeType } : {}),
     };
 }
-function buildContentBlock(text, structuredContent, extraContent = []) {
-    return {
-        content: [{ type: 'text', text }, ...extraContent],
-        structuredContent,
-    };
-}
 function resolveDetailedError(error, defaultCode, path) {
     const detailed = createDetailedError(error, path);
     if (detailed.code === ErrorCode.E_UNKNOWN) {
@@ -104,7 +98,10 @@ function resolveDetailedError(error, defaultCode, path) {
     return detailed;
 }
 export function buildToolResponse(text, structuredContent, extraContent = []) {
-    return buildContentBlock(text, structuredContent, extraContent);
+    return {
+        content: [{ type: 'text', text }, ...extraContent],
+        structuredContent,
+    };
 }
 function parseToolArgs(schema, args) {
     const candidate = args === undefined ? {} : args;
@@ -213,7 +210,8 @@ export function buildToolErrorResponse(error, defaultCode, path) {
         error: errorContent,
     };
     return {
-        ...buildContentBlock(text, structuredContent),
+        content: [{ type: 'text', text }],
+        structuredContent,
         isError: true,
     };
 }

package/dist/tools/stat-many.js

@@ -13,7 +13,7 @@ export const GET_MULTIPLE_FILE_INFO_TOOL = {
     inputSchema: GetMultipleFileInfoInputSchema,
     outputSchema: GetMultipleFileInfoOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
-    taskSupport: 'required',
+    taskSupport: 'optional',
     nuances: ['Use before read/search when file size/type uncertainty exists.'],
 };
 function formatFileInfoDetail(info) {

package/dist/tools/tree.js

@@ -14,7 +14,7 @@ export const TREE_TOOL = {
     inputSchema: TreeInputSchema,
     outputSchema: TreeOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
-    taskSupport: 'required',
+    taskSupport: 'optional',
     gotchas: ['`maxDepth=0` returns only the root node.'],
 };
 async function handleTree(args, signal, onProgress) {

package/package.json

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