@j0hanz/filesystem-mcp 1.2.4 → 1.3.1

package/dist/server.d.ts

@@ -1,2 +1,2 @@
-export { createServer, startHttpServer, startServer } from './server/bootstrap.js';
+export { createServer, startHttpServer, startServer, } from './server/bootstrap.js';
 export type { ServerOptions } from './server/types.js';

package/dist/server.js

@@ -1 +1 @@
-export { createServer, startHttpServer, startServer } from './server/bootstrap.js';
+export { createServer, startHttpServer, startServer, } from './server/bootstrap.js';

package/dist/tools/apply-patch.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const APPLY_PATCH_TOOL: ToolContract;
 export declare function registerApplyPatchTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/apply-patch.js

@@ -8,7 +8,8 @@ import { validateExistingPath } from '../lib/path-validation.js';
 import { ApplyPatchInputSchema, ApplyPatchOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const APPLY_PATCH_TOOL = {
+export const APPLY_PATCH_TOOL = {
+    name: 'apply_patch',
     title: 'Apply Patch',
     description: 'Apply a unified diff patch to a file. ' +
         'Generate the patch with `diff_files`, then validate with `dryRun: true` before writing. ' +
@@ -16,6 +17,7 @@ const APPLY_PATCH_TOOL = {
     inputSchema: ApplyPatchInputSchema,
     outputSchema: ApplyPatchOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    gotchas: ['Patch must include valid hunk headers; use `dryRun=true` first.'],
 };
 function assertPatchTargetSizeWithinLimit(filePath, size, maxFileSize) {
     if (size <= maxFileSize)
@@ -69,8 +71,7 @@ export function registerApplyPatchTool(server, options = {}) {
         run: (signal) => handleApplyPatch(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
-    const validatedHandler = withValidatedArgs(ApplyPatchInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name = path.basename(args.path);
@@ -90,7 +91,8 @@ export function registerApplyPatchTool(server, options = {}) {
             return `🛠 apply_patch: ${name} • applied`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'apply_patch', APPLY_PATCH_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(ApplyPatchInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'apply_patch', APPLY_PATCH_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('apply_patch', withDefaultIcons({ ...APPLY_PATCH_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('apply_patch', withDefaultIcons({ ...APPLY_PATCH_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/calculate-hash.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const CALCULATE_HASH_TOOL: ToolContract;
 export declare function registerCalculateHashTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/calculate-hash.js

@@ -12,12 +12,16 @@ import { CalculateHashInputSchema, CalculateHashOutputSchema, } from '../schemas
 import { buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const WINDOWS_PATH_SEPARATOR = /\\/gu;
-const CALCULATE_HASH_TOOL = {
+export const CALCULATE_HASH_TOOL = {
+    name: 'calculate_hash',
     title: 'Calculate Hash',
     description: 'Calculate SHA-256 hash of a file or directory.',
     inputSchema: CalculateHashInputSchema,
     outputSchema: CalculateHashOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: [
+        'Directory hashing respects root `.gitignore` and sorts paths for stable output.',
+    ],
 };
 async function hashFile(filePath, encoding, signal) {
     assertNotAborted(signal);
@@ -204,11 +208,11 @@ export function registerCalculateHashTool(server, options = {}) {
         },
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
-    const validatedHandler = withValidatedArgs(CalculateHashInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
     });
-    if (registerToolTaskIfAvailable(server, 'calculate_hash', CALCULATE_HASH_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(CalculateHashInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'calculate_hash', CALCULATE_HASH_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('calculate_hash', withDefaultIcons({ ...CALCULATE_HASH_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('calculate_hash', withDefaultIcons({ ...CALCULATE_HASH_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/contract.d.ts

@@ -0,0 +1,41 @@
+import type { ZodType } from 'zod';
+export interface ToolContract {
+    /**
+     * The unique name of the tool (e.g., "read", "grep").
+     * This name is used in registration and client calls.
+     */
+    name: string;
+    /**
+     * A short human-readable title for documentation (e.g., "Read File").
+     */
+    title: string;
+    /**
+     * A detailed description of what the tool does.
+     */
+    description: string;
+    /**
+     * Zod schema for the tool's input arguments.
+     */
+    inputSchema: ZodType;
+    /**
+     * Zod schema for the tool's output result (optional).
+     */
+    outputSchema?: ZodType;
+    /**
+     * Optional annotations for tool behavior hints.
+     */
+    annotations?: {
+        readOnlyHint?: boolean;
+        idempotentHint?: boolean;
+        destructiveHint?: boolean;
+        openWorldHint?: boolean;
+    };
+    /**
+     * Specific usage nuances or edge cases for documentation.
+     */
+    nuances?: string[];
+    /**
+     * Common pitfalls or warnings for documentation.
+     */
+    gotchas?: string[];
+}

package/dist/tools/contract.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const CREATE_DIRECTORY_TOOL: ToolContract;
 export declare function registerCreateDirectoryTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/create-directory.js

@@ -6,7 +6,8 @@ import { validatePathForWrite } from '../lib/path-validation.js';
 import { CreateDirectoryInputSchema, CreateDirectoryOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, IDEMPOTENT_WRITE_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const CREATE_DIRECTORY_TOOL = {
+export const CREATE_DIRECTORY_TOOL = {
+    name: 'mkdir',
     title: 'Create Directory',
     description: 'Create a new directory at the specified path (recursive)',
     inputSchema: CreateDirectoryInputSchema,
@@ -30,8 +31,7 @@ export function registerCreateDirectoryTool(server, options = {}) {
         run: (signal) => handleCreateDirectory(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
-    const validatedHandler = withValidatedArgs(CreateDirectoryInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name = path.basename(args.path) || args.path;
@@ -44,7 +44,8 @@ export function registerCreateDirectoryTool(server, options = {}) {
             return `🛠 mkdir: ${name} • created`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'mkdir', CREATE_DIRECTORY_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(CreateDirectoryInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'mkdir', CREATE_DIRECTORY_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('mkdir', withDefaultIcons({ ...CREATE_DIRECTORY_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('mkdir', withDefaultIcons({ ...CREATE_DIRECTORY_TOOL }, options.iconInfo), validatedHandler);
 }

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

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const DELETE_FILE_TOOL: ToolContract;
 export declare function registerDeleteFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/delete-file.js

@@ -6,12 +6,16 @@ import { validatePathForWrite } from '../lib/path-validation.js';
 import { DeleteFileInputSchema, DeleteFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const DELETE_FILE_TOOL = {
+export const DELETE_FILE_TOOL = {
+    name: 'rm',
     title: 'Delete File',
     description: 'Delete a file or directory.',
     inputSchema: DeleteFileInputSchema,
     outputSchema: DeleteFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    gotchas: [
+        'Non-empty directory delete requires `recursive=true`; else returns actionable input error.',
+    ],
 };
 async function handleDeleteFile(args, signal) {
     const validPath = await validatePathForWrite(args.path, signal);
@@ -74,8 +78,7 @@ export function registerDeleteFileTool(server, options = {}) {
             return buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path);
         },
     });
-    const validatedHandler = withValidatedArgs(DeleteFileInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => `🛠 rm: ${path.basename(args.path)}`,
         completionMessage: (args, result) => {
@@ -85,7 +88,8 @@ export function registerDeleteFileTool(server, options = {}) {
             return `🛠 rm: ${name} • deleted`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'rm', DELETE_FILE_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(DeleteFileInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'rm', DELETE_FILE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('rm', withDefaultIcons({ ...DELETE_FILE_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('rm', withDefaultIcons({ ...DELETE_FILE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/diff-files.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const DIFF_FILES_TOOL: ToolContract;
 export declare function registerDiffFilesTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/diff-files.js

@@ -7,7 +7,8 @@ import { withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath } from '../lib/path-validation.js';
 import { DiffFilesInputSchema, DiffFilesOutputSchema } from '../schemas.js';
 import { buildResourceLink, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
-const DIFF_FILES_TOOL = {
+export const DIFF_FILES_TOOL = {
+    name: 'diff_files',
     title: 'Diff Files',
     description: 'Generate a unified diff between two files. ' +
         'Output feeds directly into `apply_patch`. ' +
@@ -15,6 +16,7 @@ const DIFF_FILES_TOOL = {
     inputSchema: DiffFilesInputSchema,
     outputSchema: DiffFilesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    gotchas: ['`isIdentical=true` means no hunks (`@@`) and empty diff.'],
 };
 function assertDiffFileSizeWithinLimit(filePath, size, maxFileSize) {
     if (size <= maxFileSize)
@@ -80,8 +82,7 @@ export function registerDiffFilesTool(server, options = {}) {
         run: (signal) => handleDiffFiles(args, signal, options.resourceStore),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.original),
     });
-    const validatedHandler = withValidatedArgs(DiffFilesInputSchema, handler);
-    server.registerTool('diff_files', withDefaultIcons({ ...DIFF_FILES_TOOL }, options.iconInfo), wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name1 = path.basename(args.original);
@@ -101,5 +102,7 @@ export function registerDiffFilesTool(server, options = {}) {
             const hunks = (sc.diff?.match(/@@/g) ?? []).length;
             return `🕮 diff_files: ${n1} ⟷ ${n2} • ${hunks} hunk${hunks !== 1 ? 's' : ''}`;
         },
-    }));
+    });
+    const validatedHandler = withValidatedArgs(DiffFilesInputSchema, wrappedHandler);
+    server.registerTool('diff_files', withDefaultIcons({ ...DIFF_FILES_TOOL }, options.iconInfo), validatedHandler);
 }

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

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const EDIT_FILE_TOOL: ToolContract;
 export declare function registerEditFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/edit-file.js

@@ -5,7 +5,8 @@ import { atomicWriteFile } from '../lib/fs-helpers.js';
 import { validateExistingPath } from '../lib/path-validation.js';
 import { EditFileInputSchema, EditFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
-const EDIT_FILE_TOOL = {
+export const EDIT_FILE_TOOL = {
+    name: 'edit',
     title: 'Edit File',
     description: 'Edit a file by replacing text. Sequentially applies a list of string replacements. ' +
         'Replaces the first occurrence of each `oldText`. ' +
@@ -14,6 +15,12 @@ const EDIT_FILE_TOOL = {
     inputSchema: EditFileInputSchema,
     outputSchema: EditFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    nuances: [
+        'Apply sequential literal replacements (first occurrence per edit).',
+    ],
+    gotchas: [
+        '`oldText` must match exactly; unmatched items are reported in `unmatchedEdits`.',
+    ],
 };
 function applyEdits(content, edits) {
     let newContent = content;
@@ -65,9 +72,14 @@ async function handleEditFile(args, signal) {
     if (appliedEdits > 0) {
         await atomicWriteFile(validPath, newContent, { encoding: 'utf-8', signal });
     }
+    const unmatchedNote = unmatchedEdits.length > 0
+        ? ` — ${unmatchedEdits.length} unmatched: [${unmatchedEdits
+            .map((s) => JSON.stringify(s.length > 40 ? `${s.slice(0, 40)}\u2026` : s))
+            .join(', ')}]`
+        : '';
     const message = appliedEdits === 0
-        ? `No edits applied to ${args.path}`
-        : `Successfully applied ${appliedEdits} edits to ${args.path}`;
+        ? `No edits applied to ${args.path}${unmatchedNote}`
+        : `Successfully applied ${appliedEdits} edits to ${args.path}${unmatchedNote}`;
     return buildToolResponse(message, structured);
 }
 export function registerEditFileTool(server, options = {}) {
@@ -79,8 +91,7 @@ export function registerEditFileTool(server, options = {}) {
         run: (signal) => handleEditFile(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
-    const validatedHandler = withValidatedArgs(EditFileInputSchema, handler);
-    server.registerTool('edit', withDefaultIcons({ ...EDIT_FILE_TOOL }, options.iconInfo), wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name = path.basename(args.path);
@@ -98,5 +109,7 @@ export function registerEditFileTool(server, options = {}) {
             }
             return `🛠 edit: ${name} • [${sc.appliedEdits ?? 0} edits]`;
         },
-    }));
+    });
+    const validatedHandler = withValidatedArgs(EditFileInputSchema, wrappedHandler);
+    server.registerTool('edit', withDefaultIcons({ ...EDIT_FILE_TOOL }, options.iconInfo), validatedHandler);
 }

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

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const LIST_DIRECTORY_TOOL: ToolContract;
 export declare function registerListDirectoryTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/list-directory.js

@@ -5,7 +5,8 @@ import { ErrorCode } from '../lib/errors.js';
 import { listDirectory } from '../lib/file-operations/list-directory.js';
 import { ListDirectoryInputSchema, ListDirectoryOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
-const LIST_DIRECTORY_TOOL = {
+export const LIST_DIRECTORY_TOOL = {
+    name: 'ls',
     title: 'List Directory',
     description: 'List the immediate contents of a directory (non-recursive). ' +
         'Returns name, relative path, type (file/directory/symlink), size, and modified date. ' +
@@ -15,6 +16,7 @@ const LIST_DIRECTORY_TOOL = {
     inputSchema: ListDirectoryInputSchema,
     outputSchema: ListDirectoryOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: ['`pattern` enables filtered recursive traversal up to `maxDepth`.'],
 };
 function buildListTextResult(result) {
     const { entries, summary, path } = result;
@@ -53,7 +55,7 @@ function buildStructuredListEntry(entry) {
         modified: entry.modified?.toISOString(),
     };
 }
-function buildStructuredListResult(result) {
+function buildStructuredListResult(result, nextCursor) {
     const { entries, summary, path: resultPath } = result;
     const structuredEntries = [];
     for (const entry of entries) {
@@ -71,22 +73,48 @@ function buildStructuredListResult(result) {
         ...(summary.skippedInaccessible
             ? { skippedInaccessible: summary.skippedInaccessible }
             : {}),
+        ...(nextCursor !== undefined ? { nextCursor } : {}),
     };
 }
+function encodeCursor(offset) {
+    return Buffer.from(JSON.stringify({ offset })).toString('base64url');
+}
+function decodeCursor(cursor) {
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            typeof parsed.offset === 'number') {
+            const { offset } = parsed;
+            return Number.isInteger(offset) && offset >= 0 ? offset : 0;
+        }
+    }
+    catch {
+        // ignore malformed cursor
+    }
+    return 0;
+}
 async function handleListDirectory(args, signal) {
     const dirPath = resolvePathOrRoot(args.path);
+    const cursorOffset = args.cursor !== undefined ? decodeCursor(args.cursor) : 0;
+    const pageSize = args.maxEntries ?? 20_000;
     const options = {
         includeHidden: args.includeHidden,
         excludePatterns: args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS,
         sortBy: args.sortBy,
         includeSymlinkTargets: args.includeSymlinkTargets,
         ...(args.maxDepth !== undefined ? { maxDepth: args.maxDepth } : {}),
-        ...(args.maxEntries !== undefined ? { maxEntries: args.maxEntries } : {}),
+        maxEntries: cursorOffset + pageSize,
         ...(args.pattern !== undefined ? { pattern: args.pattern } : {}),
         ...(signal ? { signal } : {}),
     };
     const result = await listDirectory(dirPath, options);
-    return buildToolResponse(buildListTextResult(result), buildStructuredListResult(result));
+    const displayEntries = cursorOffset > 0 ? result.entries.slice(cursorOffset) : result.entries;
+    const nextCursor = result.summary.truncated && displayEntries.length > 0
+        ? encodeCursor(cursorOffset + displayEntries.length)
+        : undefined;
+    const displayResult = { ...result, entries: displayEntries };
+    return buildToolResponse(buildListTextResult(displayResult), buildStructuredListResult(displayResult, nextCursor));
 }
 export function registerListDirectoryTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
@@ -96,8 +124,7 @@ export function registerListDirectoryTool(server, options = {}) {
         run: (signal) => handleListDirectory(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_DIRECTORY, args.path ?? '.'),
     });
-    const validatedHandler = withValidatedArgs(ListDirectoryInputSchema, handler);
-    server.registerTool('ls', withDefaultIcons({ ...LIST_DIRECTORY_TOOL }, options.iconInfo), wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             if (args.path) {
@@ -115,5 +142,7 @@ export function registerListDirectoryTool(server, options = {}) {
             const count = sc.totalEntries ?? 0;
             return `≣ ls: ${base} • ${count} ${count === 1 ? 'entry' : 'entries'}`;
         },
-    }));
+    });
+    const validatedHandler = withValidatedArgs(ListDirectoryInputSchema, wrappedHandler);
+    server.registerTool('ls', withDefaultIcons({ ...LIST_DIRECTORY_TOOL }, options.iconInfo), validatedHandler);
 }

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

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const MOVE_FILE_TOOL: ToolContract;
 export declare function registerMoveFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/move-file.js

@@ -6,12 +6,14 @@ import { validateExistingPath, validatePathForWrite, } from '../lib/path-validat
 import { MoveFileInputSchema, MoveFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const MOVE_FILE_TOOL = {
+export const MOVE_FILE_TOOL = {
+    name: 'mv',
     title: 'Move File',
     description: 'Move or rename a file or directory.',
     inputSchema: MoveFileInputSchema,
     outputSchema: MoveFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    nuances: ['Cross-device moves fall back to copy+delete.'],
 };
 async function handleMoveFile(args, signal) {
     const validSource = await validateExistingPath(args.source, signal);
@@ -46,8 +48,7 @@ export function registerMoveFileTool(server, options = {}) {
         run: (signal) => handleMoveFile(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.source),
     });
-    const validatedHandler = withValidatedArgs(MoveFileInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => `🛠 mv: ${path.basename(args.source)} → ${path.basename(args.destination)}`,
         completionMessage: (args, result) => {
@@ -58,7 +59,8 @@ export function registerMoveFileTool(server, options = {}) {
             return `🛠 mv: ${src} → ${dst} • moved`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'mv', MOVE_FILE_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(MoveFileInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'mv', MOVE_FILE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('mv', withDefaultIcons({ ...MOVE_FILE_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('mv', withDefaultIcons({ ...MOVE_FILE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/read-multiple.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const READ_MULTIPLE_FILES_TOOL: ToolContract;
 export declare function registerReadMultipleFilesTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/read-multiple.js

@@ -5,7 +5,8 @@ import { readMultipleFiles } from '../lib/file-operations/read-multiple-files.js
 import { ReadMultipleFilesInputSchema, ReadMultipleFilesOutputSchema, } from '../schemas.js';
 import { buildResourceLink, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const READ_MULTIPLE_FILES_TOOL = {
+export const READ_MULTIPLE_FILES_TOOL = {
+    name: 'read_many',
     title: 'Read Multiple Files',
     description: 'Read multiple text files in a single request. ' +
         'Returns contents and metadata for each file. ' +
@@ -13,6 +14,10 @@ const READ_MULTIPLE_FILES_TOOL = {
     inputSchema: ReadMultipleFilesInputSchema,
     outputSchema: ReadMultipleFilesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: ['Total read budget is capped by `MAX_READ_MANY_TOTAL_SIZE`.'],
+    gotchas: [
+        'Per-file `truncationReason` can be `head`, `range`, or `externalized`.',
+    ],
 };
 async function handleReadMultipleFiles(args, signal, resourceStore) {
     const options = {
@@ -121,8 +126,7 @@ export function registerReadMultipleFilesTool(server, options = {}) {
             onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FILE, primaryPath),
         });
     };
-    const validatedHandler = withValidatedArgs(ReadMultipleFilesInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const first = path.basename(args.paths[0] ?? '');
@@ -143,7 +147,8 @@ export function registerReadMultipleFilesTool(server, options = {}) {
             return `🕮 read_many: ${total} files read`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'read_many', READ_MULTIPLE_FILES_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(ReadMultipleFilesInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'read_many', READ_MULTIPLE_FILES_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('read_many', withDefaultIcons({ ...READ_MULTIPLE_FILES_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('read_many', withDefaultIcons({ ...READ_MULTIPLE_FILES_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/read.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const READ_FILE_TOOL: ToolContract;
 export declare function registerReadFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/read.js

@@ -5,7 +5,8 @@ import { readFile } from '../lib/fs-helpers.js';
 import { ReadFileInputSchema, ReadFileOutputSchema } from '../schemas.js';
 import { buildResourceLink, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const READ_FILE_TOOL = {
+export const READ_FILE_TOOL = {
+    name: 'read',
     title: 'Read File',
     description: 'Read the text contents of a file. ' +
         'Use head parameter to preview the first N lines of large files. ' +
@@ -13,6 +14,9 @@ const READ_FILE_TOOL = {
     inputSchema: ReadFileInputSchema,
     outputSchema: ReadFileOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: [
+        'Large content is externalized to `filesystem-mcp://result/{id}` and preview is returned inline.',
+    ],
 };
 async function handleReadFile(args, signal, resourceStore) {
     const options = {
@@ -80,8 +84,7 @@ export function registerReadFileTool(server, options = {}) {
         run: (signal) => handleReadFile(args, signal, options.resourceStore),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FILE, args.path),
     });
-    const validatedHandler = withValidatedArgs(ReadFileInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name = path.basename(args.path);
@@ -105,7 +108,8 @@ export function registerReadFileTool(server, options = {}) {
             return `🕮 read: ${name} • ${sc.totalLines ?? '?'} lines`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'read', READ_FILE_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(ReadFileInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'read', READ_FILE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('read', withDefaultIcons({ ...READ_FILE_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('read', withDefaultIcons({ ...READ_FILE_TOOL }, options.iconInfo), validatedHandler);
 }

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

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const SEARCH_AND_REPLACE_TOOL: ToolContract;
 export declare function registerSearchAndReplaceTool(server: McpServer, options?: ToolRegistrationOptions): void;