@j0hanz/filesystem-mcp 1.14.0 → 1.15.0

package/dist/tools/calculate-hash.js

@@ -1,15 +1,14 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
 import { createHash } from 'node:crypto';
 import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { basename, relative, win32 } from 'node:path';
 import { pipeline } from 'node:stream/promises';
+import { assertNotAborted, withAbort } from '../lib/abort.js';
 import { PARALLEL_CONCURRENCY } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { isIgnoredByGitignore, loadRootGitignore, } from '../lib/file-operations/core.js';
 import { globEntries } from '../lib/file-operations/traversal.js';
-import { assertNotAborted, withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath } from '../lib/paths.js';
-import { reportPeriodicProgress } from '../lib/utils.js';
 import { CalculateHashInputSchema, CalculateHashOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
@@ -32,8 +31,8 @@ async function hashFile(filePath, encoding, signal) {
     return encoding ? hasher.digest(encoding) : hasher.digest();
 }
 function toStableRelativePath(root, entryPath) {
-    const relativePath = path.relative(root, entryPath);
-    return relativePath.includes(path.win32.sep)
+    const relativePath = relative(root, entryPath);
+    return relativePath.includes(win32.sep)
         ? relativePath.replace(WINDOWS_PATH_SEPARATOR, '/')
         : relativePath;
 }
@@ -93,18 +92,11 @@ async function hashDirectory(dirPath, options = {}) {
             const fileHash = await hashFile(task.filePath, undefined, signal);
             entries.push({ path: task.relativePath, hash: fileHash });
             filesHashed++;
-            reportPeriodicProgress(onProgress, filesHashed, {
-                throttleModulo: 25,
-                total: totalFiles,
-            });
+            onProgress?.({ current: filesHashed, total: totalFiles });
         }
     };
     await Promise.all(Array.from({ length: concurrency }, () => worker()));
-    reportPeriodicProgress(onProgress, filesHashed, {
-        throttleModulo: 25,
-        total: totalFiles,
-        force: true,
-    });
+    onProgress?.({ current: filesHashed, total: totalFiles });
     assertNotAborted(signal);
     // Sort by path with byte-wise semantics for deterministic ordering.
     entries.sort(comparePaths);
@@ -123,7 +115,7 @@ async function hashDirectory(dirPath, options = {}) {
 async function handleCalculateHash(args, signal, onProgress) {
     const validPath = await validateExistingPath(args.path, signal);
     // Check if path is a directory or file
-    const stats = await withAbort(fs.stat(validPath), signal);
+    const stats = await withAbort(stat(validPath), signal);
     if (stats.isDirectory()) {
         // Hash directory: composite hash of all files
         const { hash, fileCount } = await hashDirectory(validPath, {
@@ -141,10 +133,7 @@ async function handleCalculateHash(args, signal, onProgress) {
     else {
         // Hash single file
         const hash = await hashFile(validPath, 'hex', signal);
-        reportPeriodicProgress(onProgress, 1, {
-            throttleModulo: 25,
-            force: true,
-        });
+        onProgress?.({ current: 1 });
         return buildToolResponse(hash, {
             ok: true,
             path: validPath,
@@ -161,7 +150,7 @@ export function registerCalculateHashTool(server, options = {}) {
         timedSignal: {},
         context: { path: args.path },
         run: async (signal) => {
-            const baseName = path.basename(args.path);
+            const baseName = basename(args.path);
             const progress = createToolProgressSession(extra, `🕮 hash: ${baseName}`);
             const progressWithMessage = ({ current, total, }) => {
                 progress.update({
@@ -190,7 +179,7 @@ export function registerCalculateHashTool(server, options = {}) {
                 throw error;
             }
         },
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.path),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,

package/dist/tools/create-directory.js

@@ -1,7 +1,7 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { withAbort } from '../lib/abort.js';
 import { ErrorCode, McpError } from '../lib/errors.js';
-import { withAbort } from '../lib/fs-helpers.js';
 import { validatePathForWrite } from '../lib/paths.js';
 import { CreateDirectoryInputSchema, CreateDirectoryOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, IDEMPOTENT_WRITE_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
@@ -22,12 +22,14 @@ async function handleCreateDirectory(args, signal) {
     if (args.paths)
         allPaths.push(...args.paths);
     if (allPaths.length === 0) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'No paths provided to create.');
+        throw new McpError(ErrorCode.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)));
+    await Promise.all(validPaths.map((p) => withAbort(mkdir(p, { recursive: true }), signal)));
+    const createdPath = validPaths.length === 1 ? validPaths[0] : undefined;
     return buildToolResponse(`Successfully created ${validPaths.length} director${validPaths.length === 1 ? 'y' : 'ies'}`, {
         ok: true,
+        ...(createdPath ? { path: createdPath } : {}),
         paths: validPaths,
     });
 }
@@ -39,20 +41,20 @@ export function registerCreateDirectoryTool(server, options = {}) {
         timedSignal: {},
         context: { path: args.path ?? args.paths?.[0] },
         run: (signal) => handleCreateDirectory(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path ?? args.paths?.[0]),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.path ?? args.paths?.[0]),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             if (args.path && !args.paths?.length) {
-                return `🛠 mkdir: ${path.basename(args.path)}`;
+                return `🛠 mkdir: ${basename(args.path)}`;
             }
             const count = (args.path ? 1 : 0) + (args.paths?.length ?? 0);
             return `🛠 mkdir: ${count} directories`;
         },
         completionMessage: (args, result) => {
             if (args.path && !args.paths?.length) {
-                const name = path.basename(args.path);
+                const name = basename(args.path);
                 if (result.isError)
                     return `🛠 mkdir: ${name} • failed`;
                 return `🛠 mkdir: ${name}`;

package/dist/tools/delete-file.js

@@ -1,7 +1,8 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
+import { lstat, rm, rmdir } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { withAbort } from '../lib/abort.js';
 import { ErrorCode, isNodeError, McpError } from '../lib/errors.js';
-import { withAbort } from '../lib/fs-helpers.js';
+import { Logger } from '../lib/logger.js';
 import { isAllowedDirectoryRoot, validatePathForWrite } from '../lib/paths.js';
 import { DeleteFileInputSchema, DeleteFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
@@ -19,11 +20,11 @@ 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}`);
+        throw new McpError(ErrorCode.ACCESS_DENIED, 'Deleting a workspace root directory is not allowed');
     }
     let stats;
     try {
-        stats = await withAbort(fs.lstat(validPath), signal);
+        stats = await withAbort(lstat(validPath), signal);
     }
     catch (error) {
         if (isNodeError(error) &&
@@ -39,14 +40,15 @@ async function handleDeleteFile(args, signal) {
     if (stats.isDirectory() && !args.recursive) {
         // Use rmdir for non-recursive directory deletes so non-empty directories
         // consistently return ENOTEMPTY-style errors with actionable guidance.
-        await withAbort(fs.rmdir(validPath), signal);
+        await withAbort(rmdir(validPath), signal);
     }
     else {
-        await withAbort(fs.rm(validPath, {
+        await withAbort(rm(validPath, {
             recursive: args.recursive,
             force: args.ignoreIfNotExists,
         }), signal);
     }
+    Logger.info(`rm: ${args.path}`);
     return buildToolResponse(`Successfully deleted: ${args.path}`, {
         ok: true,
         path: validPath,
@@ -63,29 +65,29 @@ export function registerDeleteFileTool(server, options = {}) {
         onError: (error) => {
             if (isNodeError(error)) {
                 if (error.code === 'ENOENT') {
-                    return buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, args.path);
+                    return buildToolErrorResponse(error, ErrorCode.NOT_FOUND, args.path);
                 }
                 if (error.code === 'ENOTEMPTY') {
-                    return buildToolErrorResponse(new Error(`Directory is not empty: ${args.path}. Use recursive: true to delete non-empty directories.`), ErrorCode.E_INVALID_INPUT, args.path);
+                    return buildToolErrorResponse(new Error('Directory not empty. Set recursive: true.'), ErrorCode.INVALID_INPUT, args.path);
                 }
                 if (error.code === 'EISDIR') {
-                    return buildToolErrorResponse(new Error(`Path is a directory: ${args.path}. Use recursive: true to delete directories.`), ErrorCode.E_INVALID_INPUT, args.path);
+                    return buildToolErrorResponse(new Error('Path is a directory. Set recursive: true.'), ErrorCode.INVALID_INPUT, args.path);
                 }
                 if (error.code === 'EEXIST') {
-                    return buildToolErrorResponse(new Error(`Directory is not empty: ${args.path}. Use recursive: true to delete non-empty directories.`), ErrorCode.E_INVALID_INPUT, args.path);
+                    return buildToolErrorResponse(new Error('Directory not empty. Set recursive: true.'), ErrorCode.INVALID_INPUT, args.path);
                 }
                 if (error.code === 'EPERM' || error.code === 'EACCES') {
-                    return buildToolErrorResponse(error, ErrorCode.E_PERMISSION_DENIED, args.path);
+                    return buildToolErrorResponse(error, ErrorCode.PERMISSION_DENIED, args.path);
                 }
             }
-            return buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path);
+            return buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.path);
         },
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => `🛠 rm: ${path.basename(args.path)}`,
+        progressMessage: (args) => `🛠 rm: ${basename(args.path)}`,
         completionMessage: (args, result) => {
-            const name = path.basename(args.path);
+            const name = basename(args.path);
             if (result.isError)
                 return `🛠 rm: ${name} • failed`;
             return `🛠 rm: ${name}`;

package/dist/tools/diff-files.js

@@ -1,9 +1,9 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
+import { readFile, stat } from 'node:fs/promises';
+import { basename } from 'node:path';
 import { formatPatch, structuredPatch } from 'diff';
+import { withAbort } from '../lib/abort.js';
 import { MAX_TEXT_FILE_SIZE } from '../lib/constants.js';
 import { ErrorCode, McpError } from '../lib/errors.js';
-import { withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath } from '../lib/paths.js';
 import { DiffFilesInputSchema, DiffFilesOutputSchema } from '../schemas.js';
 import { buildResourceLink, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
@@ -35,7 +35,7 @@ function computeDiffStats(hunks) {
 function assertDiffFileSizeWithinLimit(filePath, size, maxFileSize) {
     if (size <= maxFileSize)
         return;
-    throw new McpError(ErrorCode.E_TOO_LARGE, `File too large for diff: ${filePath} (${size} bytes > ${maxFileSize} bytes).`, filePath, { size, maxFileSize });
+    throw new McpError(ErrorCode.TOO_LARGE, `File too large for diff (${size} bytes > ${maxFileSize} bytes).`, filePath, { size, maxFileSize });
 }
 async function handleDiffFiles(args, signal, resourceStore) {
     const maxFileSize = MAX_TEXT_FILE_SIZE;
@@ -44,17 +44,17 @@ async function handleDiffFiles(args, signal, resourceStore) {
         validateExistingPath(args.modified, signal),
     ]);
     const [originalStats, modifiedStats] = await Promise.all([
-        withAbort(fs.stat(originalPath), signal),
-        withAbort(fs.stat(modifiedPath), signal),
+        withAbort(stat(originalPath), signal),
+        withAbort(stat(modifiedPath), signal),
     ]);
     assertDiffFileSizeWithinLimit(originalPath, originalStats.size, maxFileSize);
     assertDiffFileSizeWithinLimit(modifiedPath, modifiedStats.size, maxFileSize);
     const [originalContent, modifiedContent] = await Promise.all([
-        fs.readFile(originalPath, { encoding: 'utf-8', signal }),
-        fs.readFile(modifiedPath, { encoding: 'utf-8', signal }),
+        readFile(originalPath, { encoding: 'utf-8', signal }),
+        readFile(modifiedPath, { encoding: 'utf-8', signal }),
     ]);
     const patchObj = await new Promise((resolve) => {
-        structuredPatch(path.basename(originalPath), path.basename(modifiedPath), originalContent, modifiedContent, undefined, undefined, {
+        structuredPatch(basename(originalPath), basename(modifiedPath), originalContent, modifiedContent, undefined, undefined, {
             ...(args.context !== undefined ? { context: args.context } : {}),
             ignoreWhitespace: args.ignoreWhitespace,
             stripTrailingCr: args.stripTrailingCr,
@@ -65,7 +65,7 @@ async function handleDiffFiles(args, signal, resourceStore) {
         });
     });
     if (!patchObj) {
-        throw new McpError(ErrorCode.E_TIMEOUT, `Diff computation timed out or failed due to complexity.`, originalPath);
+        throw new McpError(ErrorCode.TIMEOUT, `Diff timed out or too complex.`, originalPath);
     }
     const isIdentical = patchObj.hunks.length === 0;
     const diffText = isIdentical ? '' : formatPatch(patchObj);
@@ -108,18 +108,18 @@ export function registerDiffFilesTool(server, options = {}) {
         timedSignal: {},
         context: { path: args.original },
         run: (signal) => handleDiffFiles(args, signal, options.resourceStore),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.original),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.original),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
-            const n1 = path.basename(args.original);
-            const n2 = path.basename(args.modified);
+            const n1 = basename(args.original);
+            const n2 = basename(args.modified);
             return `🕮 diff: ${n1} ⟷ ${n2}`;
         },
         completionMessage: (args, result) => {
-            const n1 = path.basename(args.original);
-            const n2 = path.basename(args.modified);
+            const n1 = basename(args.original);
+            const n2 = basename(args.modified);
             if (result.isError)
                 return `🕮 diff: ${n1} ⟷ ${n2} • failed`;
             const sc = result.structuredContent;

package/dist/tools/edit-file.js

@@ -2,9 +2,11 @@ import { readFile, stat } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { createTwoFilesPatch, diffLines } from 'diff';
 import RE2 from 're2';
+import { withAbort } from '../lib/abort.js';
 import { MAX_TEXT_FILE_SIZE } from '../lib/constants.js';
 import { ErrorCode, McpError } from '../lib/errors.js';
-import { atomicWriteFile, withAbort } from '../lib/fs-helpers.js';
+import { atomicWriteFile } from '../lib/fs-helpers.js';
+import { Logger } from '../lib/logger.js';
 import { assertAllowedFileAccess, validateExistingPath } from '../lib/paths.js';
 import { EditFileInputSchema, EditFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
@@ -161,7 +163,7 @@ async function loadEditableFile(requestedPath, signal) {
     assertAllowedFileAccess(requestedPath, validPath);
     const stats = await withAbort(stat(validPath), signal);
     if (stats.size > MAX_TEXT_FILE_SIZE) {
-        throw new McpError(ErrorCode.E_TOO_LARGE, `File too large for edit: ${requestedPath} (${stats.size} bytes > ${MAX_TEXT_FILE_SIZE} bytes)`, requestedPath, { size: stats.size, maxFileSize: MAX_TEXT_FILE_SIZE });
+        throw new McpError(ErrorCode.TOO_LARGE, `File too large for edit (${stats.size} bytes > ${MAX_TEXT_FILE_SIZE} bytes)`, requestedPath, { size: stats.size, maxFileSize: MAX_TEXT_FILE_SIZE });
     }
     const content = await readFile(validPath, { encoding: 'utf-8', signal });
     return { validPath, content };
@@ -215,13 +217,14 @@ async function handleEditFile(args, signal) {
         return buildToolResponse(`Dry run complete. ${editResult.appliedEdits} edits would be applied.`, structured);
     }
     if (editResult.appliedEdits === 0 && editResult.unmatchedEdits.length > 0) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, `All ${editResult.unmatchedEdits.length} edits failed to match. Verify oldText includes exact content with surrounding context.`, args.path);
+        throw new McpError(ErrorCode.INVALID_INPUT, `All ${editResult.unmatchedEdits.length} edits failed. Verify oldText matches exact file content.`, args.path);
     }
     if (editResult.appliedEdits > 0) {
         await atomicWriteFile(validPath, editResult.content, {
             encoding: 'utf-8',
             signal,
         });
+        Logger.info(`edit: ${args.path} (${editResult.appliedEdits} edits, +${editResult.linesAdded}/-${editResult.linesRemoved})`);
     }
     return buildToolResponse(buildEditMessage(args.path, editResult), structured);
 }
@@ -233,7 +236,7 @@ export function registerEditFileTool(server, options = {}) {
         timedSignal: {},
         context: { path: args.path },
         run: (signal) => handleEditFile(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.path),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,

package/dist/tools/list-directory.js

@@ -1,5 +1,5 @@
-import * as path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { basename } from 'node:path';
 import { z } from 'zod';
 import { DEFAULT_EXCLUDE_PATTERNS, MAX_LIST_ENTRIES, } from '../lib/constants.js';
 import { ErrorCode, McpError } from '../lib/errors.js';
@@ -71,7 +71,7 @@ function decodeListCursor(cursor) {
     catch {
         // fall through to throw
     }
-    throw new McpError(ErrorCode.E_INVALID_INPUT, 'Invalid cursor: the cursor value is malformed or expired.');
+    throw new McpError(ErrorCode.INVALID_INPUT, 'Invalid or expired cursor.');
 }
 function resolveNextListCursor(snapshotId, offset, pageSize, totalEntries) {
     if (!snapshotId)
@@ -166,7 +166,7 @@ async function handleListDirectory(args, signal) {
         const cursor = decodeListCursor(args.cursor);
         const snapshot = listSnapshots.get(cursor.snapshotId);
         if (snapshot?.fingerprint !== fingerprint) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, 'Invalid cursor: the cursor value is malformed or expired.');
+            throw new McpError(ErrorCode.INVALID_INPUT, 'Invalid or expired cursor.');
         }
         const { offset, snapshotId: storedSnapshotId } = cursor;
         cursorOffset = offset;
@@ -200,13 +200,13 @@ export function registerListDirectoryTool(server, options = {}) {
         outputSchema: ListDirectoryOutputSchema,
         context: { path: args.path ?? '.' },
         run: (signal) => handleListDirectory(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_DIRECTORY, args.path ?? '.'),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.NOT_DIRECTORY, args.path ?? '.'),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => `≣ ls: ${args.path ? path.basename(args.path) : '.'}`,
+        progressMessage: (args) => `≣ ls: ${args.path ? basename(args.path) : '.'}`,
         completionMessage: (args, result) => {
-            const base = args.path ? path.basename(args.path) : '.';
+            const base = args.path ? basename(args.path) : '.';
             if (result.isError)
                 return `≣ ls: ${base} • failed`;
             const sc = result.structuredContent;

package/dist/tools/move-file.js

@@ -1,7 +1,8 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
+import { cp, mkdir, rename, rm, stat } from 'node:fs/promises';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { withAbort } from '../lib/abort.js';
 import { ErrorCode, formatUnknownErrorMessage, isNodeError, McpError, } from '../lib/errors.js';
-import { withAbort } from '../lib/fs-helpers.js';
+import { Logger } from '../lib/logger.js';
 import { assertAllowedFileAccess, validateExistingPath, validatePathForWrite, } from '../lib/paths.js';
 import { MoveFileInputSchema, MoveFileOutputSchema } from '../schemas.js';
 import { buildStructuredError, buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
@@ -18,103 +19,119 @@ export const MOVE_FILE_TOOL = {
     ],
     taskSupport: 'forbidden',
 };
-function toMoveFailure(source, error, defaultCode = ErrorCode.E_UNKNOWN) {
+function toMoveFailure(source, error, defaultCode = ErrorCode.UNKNOWN) {
     return {
         source,
         error: buildStructuredError(error, defaultCode, source),
     };
 }
-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.');
+async function handleMoveError(error, src, validSource, targetPath, movedSources, failed, signal) {
+    if (isNodeError(error) && error.code === 'EXDEV') {
+        try {
+            await withAbort(cp(validSource, targetPath, { recursive: true }), signal);
+        }
+        catch (copyError) {
+            failed.push(toMoveFailure(src, copyError));
+            return;
+        }
+        try {
+            await withAbort(rm(validSource, { recursive: true, force: true }), signal);
+            movedSources.push(validSource);
+        }
+        catch (deleteError) {
+            try {
+                await rm(targetPath, { recursive: true, force: true });
+            }
+            catch {
+                failed.push(toMoveFailure(src, new McpError(ErrorCode.UNKNOWN, `Cross-device move partial: data at both source and destination. ${formatUnknownErrorMessage(deleteError)}`, src)));
+                return;
+            }
+            failed.push(toMoveFailure(src, new McpError(ErrorCode.UNKNOWN, `Cross-device move failed: source not removed. ${formatUnknownErrorMessage(deleteError)}`, src)));
+        }
+    }
+    else {
+        failed.push(toMoveFailure(src, error));
+    }
+}
+async function processSingleMove(src, destIsDirectory, validDest, movedSources, failed, signal) {
+    let validSource;
+    try {
+        validSource = await validateExistingPath(src, signal);
+        assertAllowedFileAccess(src, validSource);
+    }
+    catch (error) {
+        failed.push(toMoveFailure(src, error, ErrorCode.ACCESS_DENIED));
+        return;
+    }
+    const targetPath = destIsDirectory
+        ? join(validDest, basename(validSource))
+        : validDest;
+    if (resolve(validSource) === resolve(targetPath)) {
+        return;
+    }
+    if (resolve(targetPath).startsWith(resolve(validSource) + sep)) {
+        failed.push(toMoveFailure(src, new McpError(ErrorCode.INVALID_INPUT, 'Cannot move a directory into its own subdirectory', src), ErrorCode.INVALID_INPUT));
+        return;
     }
-    const validDest = await validatePathForWrite(args.destination, signal);
-    // Check if destination exists and is a directory
-    let destIsDirectory = false;
     try {
-        const stats = await fs.stat(validDest);
-        destIsDirectory = stats.isDirectory();
+        await withAbort(rename(validSource, targetPath), signal);
+        movedSources.push(validSource);
+    }
+    catch (error) {
+        await handleMoveError(error, src, validSource, targetPath, movedSources, failed, signal);
+    }
+}
+async function getDestinationStatus(validDest) {
+    try {
+        const stats = await stat(validDest);
+        return stats.isDirectory();
     }
     catch (error) {
         if (isNodeError(error) && error.code !== 'ENOENT') {
             throw error;
         }
     }
+    return false;
+}
+function formatMoveMessage(moved, failed, destination) {
+    const movedItemStr = `item${moved === 1 ? '' : 's'}`;
+    const failedItemStr = `item${failed === 1 ? '' : 's'}`;
+    if (failed > 0) {
+        return `Moved ${moved} ${movedItemStr}; failed to move ${failed} ${failedItemStr}`;
+    }
+    return `Successfully moved ${moved} ${movedItemStr} to ${destination}`;
+}
+async function handleMoveFile(args, signal) {
+    const sources = args.sources ?? (args.source ? [args.source] : []);
+    if (sources.length === 0) {
+        throw new McpError(ErrorCode.INVALID_INPUT, 'No sources provided.');
+    }
+    const validDest = await validatePathForWrite(args.destination, signal);
+    const destIsDirectory = await getDestinationStatus(validDest);
     if (sources.length > 1 && !destIsDirectory) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Destination must be an existing directory when moving multiple files.');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Destination must be an existing directory for multiple sources.');
     }
-    // Ensure destination parent directory exists if it's not an existing directory
     if (!destIsDirectory) {
-        await withAbort(fs.mkdir(path.dirname(validDest), { recursive: true }), signal);
+        await withAbort(mkdir(dirname(validDest), { recursive: true }), signal);
     }
     const movedSources = [];
     const failed = [];
     for (const src of sources) {
-        let validSource;
-        try {
-            validSource = await validateExistingPath(src, signal);
-            assertAllowedFileAccess(src, validSource);
-        }
-        catch (error) {
-            failed.push(toMoveFailure(src, error, ErrorCode.E_ACCESS_DENIED));
-            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(toMoveFailure(src, new McpError(ErrorCode.E_INVALID_INPUT, `Cannot move directory '${src}' into its own subdirectory '${targetPath}'`, src), ErrorCode.E_INVALID_INPUT));
-            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);
-                }
-                catch (copyError) {
-                    failed.push(toMoveFailure(src, copyError));
-                    continue;
-                }
-                // Copy succeeded — now remove source
-                try {
-                    await withAbort(fs.rm(validSource, { recursive: true, force: true }), signal);
-                    movedSources.push(validSource);
-                }
-                catch (deleteError) {
-                    // Source delete failed after copy — rollback by removing the copy
-                    try {
-                        await fs.rm(targetPath, { recursive: true, force: true });
-                    }
-                    catch {
-                        // Rollback failed — data exists in both locations
-                        failed.push(toMoveFailure(src, new McpError(ErrorCode.E_UNKNOWN, `Cross-device move partially failed: data exists at both '${validSource}' and '${targetPath}'. ${formatUnknownErrorMessage(deleteError)}`, src)));
-                        continue;
-                    }
-                    failed.push(toMoveFailure(src, new McpError(ErrorCode.E_UNKNOWN, `Cross-device move failed: could not remove source. ${formatUnknownErrorMessage(deleteError)}`, src)));
-                }
-            }
-            else {
-                failed.push(toMoveFailure(src, error));
-            }
+        await processSingleMove(src, destIsDirectory, validDest, movedSources, failed, signal);
+    }
+    const message = formatMoveMessage(movedSources.length, failed.length, args.destination);
+    const movedSource = sources.length === 1 ? movedSources[0] : undefined;
+    const failedSuffix = failed.length > 0 ? ` (${failed.length} failed)` : '';
+    Logger.info(`mv: ${movedSources.length} item(s) → ${args.destination}${failedSuffix}`);
+    if (movedSources.length === 0 && failed.length > 0) {
+        const firstFailure = failed[0];
+        if (firstFailure) {
+            throw new McpError(firstFailure.error.code, message, firstFailure.error.path);
         }
     }
-    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,
+        ...(movedSource ? { source: movedSource } : {}),
         sources: movedSources,
         destination: validDest,
         ...(failed.length > 0 ? { failed } : {}),
@@ -128,22 +145,22 @@ export function registerMoveFileTool(server, options = {}) {
         timedSignal: {},
         context: { path: args.source ?? args.sources?.[0] },
         run: (signal) => handleMoveFile(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.source ?? args.sources?.[0]),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.source ?? args.sources?.[0]),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
-            const dest = path.basename(args.destination);
+            const dest = basename(args.destination);
             if (args.source && !args.sources?.length) {
-                return `🛠 mv: ${path.basename(args.source)} → ${dest}`;
+                return `🛠 mv: ${basename(args.source)} → ${dest}`;
             }
             const count = (args.source ? 1 : 0) + (args.sources?.length ?? 0);
             return `🛠 mv: ${count} items → ${dest}`;
         },
         completionMessage: (args, result) => {
-            const dest = path.basename(args.destination);
+            const dest = basename(args.destination);
             if (args.source && !args.sources?.length) {
-                const src = path.basename(args.source);
+                const src = basename(args.source);
                 if (result.isError)
                     return `🛠 mv: ${src} → ${dest} • failed`;
                 return `🛠 mv: ${src} → ${dest}`;