@j0hanz/filesystem-mcp 1.13.2 → 1.14.1

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,
@@ -157,10 +146,11 @@ export function registerCalculateHashTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'calculate_hash',
         extra,
+        outputSchema: CalculateHashOutputSchema,
         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({
@@ -172,13 +162,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 {
@@ -192,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';
@@ -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) {
@@ -23,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,
     });
 }
@@ -36,23 +37,24 @@ 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),
-        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';
@@ -13,20 +14,17 @@ 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) {
     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) &&
@@ -42,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,
@@ -59,35 +58,36 @@ 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),
         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';
@@ -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) {
@@ -36,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;
@@ -45,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,
@@ -66,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);
@@ -105,26 +104,25 @@ 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),
-        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;
-            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

@@ -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';
@@ -19,7 +21,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 +105,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
@@ -162,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,11 +216,15 @@ 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.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);
 }
@@ -227,10 +232,11 @@ 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),
-        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,8 +1,10 @@
-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';
 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,27 +62,16 @@ 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
     }
-    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)
@@ -170,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;
@@ -201,20 +197,19 @@ 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 ?? '.'),
+        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;
-            if (!sc.ok)
-                return `≣ ls: ${base} • failed`;
             const count = sc.totalEntries ?? 0;
             return `≣ ls: ${base} • ${count} ${count === 1 ? 'entry' : 'entries'}`;
         },