@j0hanz/filesystem-mcp 1.13.2 → 1.14.0

package/dist/tools/apply-patch.js

@@ -2,11 +2,11 @@ import * as path from 'node:path';
 import { readFile, stat } from 'node:fs/promises';
 import { applyPatch, parsePatch } from 'diff';
 import { MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY } from '../lib/constants.js';
-import { ErrorCode, formatUnknownErrorMessage, McpError, } from '../lib/errors.js';
+import { ErrorCode, McpError } from '../lib/errors.js';
 import { atomicWriteFile, processInParallel, withAbort, } from '../lib/fs-helpers.js';
 import { assertAllowedFileAccess, validateExistingPath } from '../lib/paths.js';
 import { ApplyPatchInputSchema, ApplyPatchOutputSchema } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildStructuredError, buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const APPLY_PATCH_TOOL = {
     name: 'apply_patch',
@@ -21,7 +21,6 @@ export const APPLY_PATCH_TOOL = {
     nuances: [
         'Multi-file patches use `path` as base directory; per-file results in `results[]`.',
     ],
-    gotchas: ['Patch must include valid hunk headers; use `dryRun=true` first.'],
     taskSupport: 'forbidden',
 };
 function assertPatchTargetSizeWithinLimit(filePath, size, maxFileSize) {
@@ -68,11 +67,15 @@ async function applyDiff(filePath, diff, options, signal) {
         return {
             path: validPath,
             applied: false,
-            error: 'Patch application failed',
+            error: buildStructuredError(new McpError(ErrorCode.E_INVALID_INPUT, 'Patch application failed', validPath), ErrorCode.E_INVALID_INPUT, validPath),
         };
     }
     if (patched === content) {
-        return { path: validPath, applied: false, error: 'Patch had no effect' };
+        return {
+            path: validPath,
+            applied: false,
+            error: buildStructuredError(new McpError(ErrorCode.E_INVALID_INPUT, 'Patch had no effect', validPath), ErrorCode.E_INVALID_INPUT, validPath),
+        };
     }
     const patchStats = countStructuredPatchStats(diff);
     if (!options.dryRun) {
@@ -88,7 +91,7 @@ async function processMultiFilePatch(basePath, parsed, options, signal) {
             return () => Promise.resolve({
                 path: '<unknown>',
                 applied: false,
-                error: 'Missing file name in patch header',
+                error: buildStructuredError(new McpError(ErrorCode.E_INVALID_INPUT, 'Missing file name in patch header'), ErrorCode.E_INVALID_INPUT),
             });
         }
         const filePath = path.resolve(validBase, fileName);
@@ -101,7 +104,7 @@ async function processMultiFilePatch(basePath, parsed, options, signal) {
                 return {
                     path: fileName,
                     applied: false,
-                    error: formatUnknownErrorMessage(error),
+                    error: buildStructuredError(error, ErrorCode.E_INVALID_INPUT, filePath),
                 };
             }
         };
@@ -117,6 +120,13 @@ async function processMultiFilePatch(basePath, parsed, options, signal) {
         return acc;
     }, { applied: 0, hunks: 0, added: 0, removed: 0 });
     const label = options.dryRun ? ' (dry run)' : '';
+    if (totals.applied === 0) {
+        const failedPaths = results
+            .filter((r) => !r.applied)
+            .map((r) => r.path)
+            .join(', ');
+        throw new McpError(ErrorCode.E_INVALID_INPUT, `All ${parsed.length} file patches failed${label}. Files: ${failedPaths}. Generate fresh patches via diff_files and retry.`);
+    }
     const text = `Applied ${totals.applied}/${parsed.length} file patches${label}`;
     return buildToolResponse(text, {
         ok: totals.applied === parsed.length,
@@ -152,7 +162,7 @@ async function handleApplyPatch(args, signal) {
     }
     const result = await applyDiff(args.path, diff, options, signal);
     if (!result.applied) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, result.error === 'Patch had no effect'
+        throw new McpError(ErrorCode.E_INVALID_INPUT, result.error?.message === 'Patch had no effect'
             ? 'Patch had no effect \u2014 the file content is unchanged after applying. The patch may not match the current file content. Generate a fresh patch via diff_files and retry.'
             : 'Patch application failed. The file content may have changed or patch context is insufficient. Generate a fresh patch via diff_files against the current file, then retry. If differences are minor, enable fuzzy matching with the fuzzFactor parameter.');
     }
@@ -172,6 +182,7 @@ export function registerApplyPatchTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'apply_patch',
         extra,
+        outputSchema: ApplyPatchOutputSchema,
         timedSignal: {},
         context: { path: args.path },
         run: (signal) => handleApplyPatch(args, signal),

package/dist/tools/calculate-hash.js

@@ -157,6 +157,7 @@ export function registerCalculateHashTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'calculate_hash',
         extra,
+        outputSchema: CalculateHashOutputSchema,
         timedSignal: {},
         context: { path: args.path },
         run: async (signal) => {
@@ -172,13 +173,10 @@ export function registerCalculateHashTool(server, options = {}) {
             try {
                 const result = await handleCalculateHash(args, signal, progressWithMessage);
                 const sc = result.structuredContent;
-                const totalFiles = sc.ok ? (sc.fileCount ?? 1) : 1;
+                const totalFiles = sc.fileCount ?? 1;
                 const finalCurrent = resolveFinalProgressCurrent(progress, totalFiles + 1);
                 let suffix;
-                if (!sc.ok) {
-                    suffix = 'failed';
-                }
-                else if (sc.fileCount !== undefined && sc.fileCount > 1) {
+                if (sc.fileCount !== undefined && sc.fileCount > 1) {
                     suffix = `${sc.fileCount} files • ${(sc.hash ?? '').slice(0, 8)}…`;
                 }
                 else {

package/dist/tools/create-directory.js

@@ -13,7 +13,6 @@ export const CREATE_DIRECTORY_TOOL = {
     inputSchema: CreateDirectoryInputSchema,
     outputSchema: CreateDirectoryOutputSchema,
     annotations: IDEMPOTENT_WRITE_TOOL_ANNOTATIONS,
-    nuances: ['Succeeds silently if the directory already exists (idempotent).'],
     taskSupport: 'forbidden',
 };
 async function handleCreateDirectory(args, signal) {
@@ -36,6 +35,7 @@ export function registerCreateDirectoryTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'mkdir',
         extra,
+        outputSchema: CreateDirectoryOutputSchema,
         timedSignal: {},
         context: { path: args.path ?? args.paths?.[0] },
         run: (signal) => handleCreateDirectory(args, signal),

package/dist/tools/delete-file.js

@@ -13,10 +13,7 @@ export const DELETE_FILE_TOOL = {
     inputSchema: DeleteFileInputSchema,
     outputSchema: DeleteFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
-    gotchas: [
-        'No undo — deletion is permanent.',
-        'Non-empty directories require `recursive=true`.',
-    ],
+    gotchas: ['Non-empty directories require `recursive=true`.'],
     taskSupport: 'forbidden',
 };
 async function handleDeleteFile(args, signal) {
@@ -59,6 +56,7 @@ export function registerDeleteFileTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'rm',
         extra,
+        outputSchema: DeleteFileOutputSchema,
         timedSignal: {},
         context: { path: args.path },
         run: (signal) => handleDeleteFile(args, signal),

package/dist/tools/diff-files.js

@@ -17,7 +17,6 @@ export const DIFF_FILES_TOOL = {
     inputSchema: DiffFilesInputSchema,
     outputSchema: DiffFilesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
-    gotchas: ['`isIdentical=true` means no hunks (`@@`) and empty diff.'],
     taskSupport: 'forbidden',
 };
 function computeDiffStats(hunks) {
@@ -105,6 +104,7 @@ export function registerDiffFilesTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'diff_files',
         extra,
+        outputSchema: DiffFilesOutputSchema,
         timedSignal: {},
         context: { path: args.original },
         run: (signal) => handleDiffFiles(args, signal, options.resourceStore),
@@ -123,8 +123,6 @@ export function registerDiffFilesTool(server, options = {}) {
             if (result.isError)
                 return `🕮 diff: ${n1} ⟷ ${n2} • failed`;
             const sc = result.structuredContent;
-            if (!sc.ok)
-                return `🕮 diff: ${n1} ⟷ ${n2} • failed`;
             if (sc.isIdentical)
                 return `🕮 diff: ${n1} ⟷ ${n2} • identical`;
             const added = sc.linesAdded ?? 0;

package/dist/tools/edit-file.js

@@ -19,7 +19,6 @@ export const EDIT_FILE_TOOL = {
     outputSchema: EditFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
     nuances: ['Each edit applies to the output of the previous edit.'],
-    gotchas: ['Unmatched `oldText` entries listed in `unmatchedEdits`.'],
     taskSupport: 'forbidden',
 };
 function escapeRegExp(string) {
@@ -104,7 +103,7 @@ function mergeLineRange(currentRange, content, matchStartIndex, newText) {
 }
 function buildStructuredEditOutput(validPath, result) {
     return {
-        ok: true,
+        ok: result.appliedEdits > 0 || result.unmatchedEdits.length === 0,
         path: validPath,
         appliedEdits: result.appliedEdits,
         ...(result.appliedEdits > 0
@@ -215,6 +214,9 @@ 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);
+    }
     if (editResult.appliedEdits > 0) {
         await atomicWriteFile(validPath, editResult.content, {
             encoding: 'utf-8',
@@ -227,6 +229,7 @@ export function registerEditFileTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'edit',
         extra,
+        outputSchema: EditFileOutputSchema,
         timedSignal: {},
         context: { path: args.path },
         run: (signal) => handleEditFile(args, signal),

package/dist/tools/list-directory.js

@@ -1,8 +1,10 @@
 import * as path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
 import { DEFAULT_EXCLUDE_PATTERNS, MAX_LIST_ENTRIES, } from '../lib/constants.js';
 import { ErrorCode, McpError } from '../lib/errors.js';
 import { listDirectory } from '../lib/file-operations/metadata.js';
+import { createBase64JsonCodec } from '../lib/zod-codecs.js';
 import { formatOperationSummary, joinLines } from '../config.js';
 import { ListDirectoryInputSchema, ListDirectoryOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
@@ -23,6 +25,11 @@ const LIST_CURSOR_TTL_MS = parseInt(process.env['FS_CONTEXT_LIST_CURSOR_TTL_MS']
     5 * 60 * 1000;
 const listSnapshots = new Map();
 const listSnapshotTimers = new Map();
+const ListCursorPayloadSchema = z.strictObject({
+    snapshotId: z.string().min(1),
+    offset: z.int().min(0),
+});
+const ListCursorCodec = createBase64JsonCodec(ListCursorPayloadSchema);
 function buildListFingerprint(args) {
     return JSON.stringify({
         path: resolvePathOrRoot(args.path),
@@ -55,22 +62,11 @@ function storeListSnapshot(snapshot) {
     return snapshotId;
 }
 function encodeListCursor(payload) {
-    return Buffer.from(JSON.stringify(payload)).toString('base64url');
+    return z.encode(ListCursorCodec, payload);
 }
 function decodeListCursor(cursor) {
     try {
-        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
-        if (typeof parsed === 'object' &&
-            parsed !== null &&
-            typeof parsed.snapshotId === 'string' &&
-            typeof parsed.offset === 'number') {
-            const payload = parsed;
-            if (payload.snapshotId.length > 0 &&
-                Number.isInteger(payload.offset) &&
-                payload.offset >= 0) {
-                return payload;
-            }
-        }
+        return ListCursorCodec.parse(cursor);
     }
     catch {
         // fall through to throw
@@ -201,6 +197,7 @@ export function registerListDirectoryTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'ls',
         extra,
+        outputSchema: ListDirectoryOutputSchema,
         context: { path: args.path ?? '.' },
         run: (signal) => handleListDirectory(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_DIRECTORY, args.path ?? '.'),
@@ -213,8 +210,6 @@ export function registerListDirectoryTool(server, options = {}) {
             if (result.isError)
                 return `≣ ls: ${base} • failed`;
             const sc = result.structuredContent;
-            if (!sc.ok)
-                return `≣ ls: ${base} • failed`;
             const count = sc.totalEntries ?? 0;
             return `≣ ls: ${base} • ${count} ${count === 1 ? 'entry' : 'entries'}`;
         },

package/dist/tools/move-file.js

@@ -4,7 +4,7 @@ import { ErrorCode, formatUnknownErrorMessage, isNodeError, McpError, } from '..
 import { withAbort } from '../lib/fs-helpers.js';
 import { assertAllowedFileAccess, validateExistingPath, validatePathForWrite, } from '../lib/paths.js';
 import { MoveFileInputSchema, MoveFileOutputSchema } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildStructuredError, buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const MOVE_FILE_TOOL = {
     name: 'mv',
@@ -13,12 +13,17 @@ export const MOVE_FILE_TOOL = {
     inputSchema: MoveFileInputSchema,
     outputSchema: MoveFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
-    nuances: ['Cross-device moves fall back to copy+delete.'],
     gotchas: [
         'On POSIX, an existing destination is silently overwritten; on Windows, rename fails with EEXIST if destination exists.',
     ],
     taskSupport: 'forbidden',
 };
+function toMoveFailure(source, error, defaultCode = ErrorCode.E_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) {
@@ -52,10 +57,7 @@ async function handleMoveFile(args, signal) {
             assertAllowedFileAccess(src, validSource);
         }
         catch (error) {
-            failed.push({
-                source: src,
-                error: formatUnknownErrorMessage(error),
-            });
+            failed.push(toMoveFailure(src, error, ErrorCode.E_ACCESS_DENIED));
             continue;
         }
         const targetPath = destIsDirectory
@@ -68,10 +70,7 @@ async function handleMoveFile(args, signal) {
         // 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}'`,
-            });
+            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 {
@@ -85,10 +84,7 @@ async function handleMoveFile(args, signal) {
                     await withAbort(fs.cp(validSource, targetPath, { recursive: true }), signal);
                 }
                 catch (copyError) {
-                    failed.push({
-                        source: src,
-                        error: formatUnknownErrorMessage(copyError),
-                    });
+                    failed.push(toMoveFailure(src, copyError));
                     continue;
                 }
                 // Copy succeeded — now remove source
@@ -103,23 +99,14 @@ async function handleMoveFile(args, signal) {
                     }
                     catch {
                         // Rollback failed — data exists in both locations
-                        failed.push({
-                            source: src,
-                            error: `Cross-device move partially failed: data exists at both '${validSource}' and '${targetPath}'. ${formatUnknownErrorMessage(deleteError)}`,
-                        });
+                        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({
-                        source: src,
-                        error: `Cross-device move failed: could not remove source. ${formatUnknownErrorMessage(deleteError)}`,
-                    });
+                    failed.push(toMoveFailure(src, new McpError(ErrorCode.E_UNKNOWN, `Cross-device move failed: could not remove source. ${formatUnknownErrorMessage(deleteError)}`, src)));
                 }
             }
             else {
-                failed.push({
-                    source: src,
-                    error: formatUnknownErrorMessage(error),
-                });
+                failed.push(toMoveFailure(src, error));
             }
         }
     }
@@ -137,6 +124,7 @@ export function registerMoveFileTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'mv',
         extra,
+        outputSchema: MoveFileOutputSchema,
         timedSignal: {},
         context: { path: args.source ?? args.sources?.[0] },
         run: (signal) => handleMoveFile(args, signal),

package/dist/tools/read-multiple.js

@@ -3,7 +3,7 @@ import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { readMultipleFiles } from '../lib/file-operations/metadata.js';
 import { ReadMultipleFilesInputSchema, ReadMultipleFilesOutputSchema, } from '../schemas.js';
-import { buildBatchCompletionSuffix, buildBatchPathContext, buildResourceLink, buildToolErrorResponse, buildToolResponse, createBatchProgressCallbacks, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildBatchCompletionSuffix, buildBatchPathContext, buildResourceLink, buildStructuredError, buildToolErrorResponse, buildToolResponse, createBatchProgressCallbacks, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const READ_MANY_TOOL_NAME = 'read_many';
 const READ_MANY_TOOL_LABEL = '🕮 read_many';
@@ -17,10 +17,6 @@ export const READ_MANY_TOOL = {
     outputSchema: ReadMultipleFilesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
     taskSupport: 'optional',
-    nuances: ['Total read budget is capped by `MAX_READ_MANY_TOTAL_SIZE`.'],
-    gotchas: [
-        'Per-file `truncationReason` can be `head`, `tail`, `range`, or `externalized`.',
-    ],
 };
 function buildReadManyResourceName(filePath) {
     return `read:${path.basename(filePath)}`;
@@ -72,8 +68,12 @@ function resolveReadManyTruncationReason(result) {
 }
 function maybeExternalizeReadManyResult(result, resourceStore) {
     const truncationReason = resolveReadManyTruncationReason(result);
+    const { error, ...rest } = result;
     const baseResult = {
-        ...result,
+        ...rest,
+        ...(error
+            ? { error: buildStructuredError(error, ErrorCode.E_UNKNOWN, result.path) }
+            : {}),
         ...(truncationReason ? { truncationReason } : {}),
     };
     if (!result.content) {
@@ -89,12 +89,13 @@ function maybeExternalizeReadManyResult(result, resourceStore) {
         truncated: true,
         resourceUri: externalized.entry.uri,
         truncationReason: 'externalized',
+        expiresAt: externalized.entry.expiresAt,
     };
 }
 function buildReadManyTextSection(result) {
     const header = `=== ${result.path} ===`;
     if (result.error) {
-        return `${header}\nError: ${result.error}`;
+        return `${header}\nError [${result.error.code}]: ${result.error.message}`;
     }
     return `${header}\n${result.content ?? ''}`;
 }
@@ -128,6 +129,9 @@ function buildReadManyResponsePayload(results, resourceStore) {
                 uri: mappedResult.resourceUri,
                 name: buildReadManyResourceName(mappedResult.path),
                 description: FULL_FILE_CONTENTS_DESCRIPTION,
+                ...(mappedResult.expiresAt
+                    ? { expiresAt: mappedResult.expiresAt }
+                    : {}),
             }));
         }
         if (mappedResult.error === undefined)
@@ -162,6 +166,7 @@ export function registerReadMultipleFilesTool(server, options = {}) {
         return executeToolWithDiagnostics({
             toolName: READ_MANY_TOOL_NAME,
             extra,
+            outputSchema: ReadMultipleFilesOutputSchema,
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: primaryPath },
             run: async (signal) => {

package/dist/tools/read.js

@@ -115,8 +115,6 @@ function buildReadCompletionMessage(args, result) {
     if (result.isError)
         return `${READ_TOOL_LABEL}: ${name} • failed`;
     const structured = result.structuredContent;
-    if (!structured.ok)
-        return `${READ_TOOL_LABEL}: ${name} • failed`;
     const lines = structured.linesRead ?? structured.totalLines;
     if (structured.startLine !== undefined) {
         const end = structured.linesRead
@@ -158,6 +156,7 @@ export function registerReadFileTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: READ_TOOL_NAME,
         extra,
+        outputSchema: ReadFileOutputSchema,
         timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
         context: { path: args.path },
         run: (signal) => handleReadFile(args, signal, options.resourceStore),