@j0hanz/filesystem-mcp 1.2.1 → 1.2.3

package/dist/tools/read-multiple.js

@@ -3,7 +3,7 @@ import { DEFAULT_READ_MANY_MAX_TOTAL_SIZE, DEFAULT_SEARCH_TIMEOUT_MS, } from '..
 import { ErrorCode } from '../lib/errors.js';
 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, wrapToolHandler, } from './shared.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 = {
     title: 'Read Multiple Files',
@@ -121,9 +121,27 @@ export function registerReadMultipleFilesTool(server, options = {}) {
             onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FILE, primaryPath),
         });
     };
-    const wrappedHandler = wrapToolHandler(handler, {
+    const validatedHandler = withValidatedArgs(ReadMultipleFilesInputSchema, handler);
+    const wrappedHandler = wrapToolHandler(validatedHandler, {
         guard: options.isInitialized,
-        progressMessage: (args) => `🕮 read_many: ${args.paths.length} files`,
+        progressMessage: (args) => {
+            const first = path.basename(args.paths[0] ?? '');
+            const extra = args.paths.length > 1 ? `, ${path.basename(args.paths[1] ?? '')}…` : '';
+            return `🕮 read_many: ${args.paths.length} files [${first}${extra}]`;
+        },
+        completionMessage: (args, result) => {
+            if (result.isError)
+                return `🕮 read_many: ${args.paths.length} files • failed`;
+            const sc = result.structuredContent;
+            if (!sc.ok)
+                return `🕮 read_many: ${args.paths.length} files • failed`;
+            const total = sc.summary?.total ?? 0;
+            const succeeded = sc.summary?.succeeded ?? 0;
+            const failed = sc.summary?.failed ?? 0;
+            if (failed)
+                return `🕮 read_many: ${succeeded}/${total} read, ${failed} failed`;
+            return `🕮 read_many: ${total} files read`;
+        },
     });
     if (registerToolTaskIfAvailable(server, 'read_many', READ_MULTIPLE_FILES_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
         return;

package/dist/tools/read.js

@@ -3,7 +3,7 @@ import { DEFAULT_SEARCH_TIMEOUT_MS, MAX_TEXT_FILE_SIZE, } from '../lib/constants
 import { ErrorCode } from '../lib/errors.js';
 import { readFile } from '../lib/fs-helpers.js';
 import { ReadFileInputSchema, ReadFileOutputSchema } from '../schemas.js';
-import { buildResourceLink, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, wrapToolHandler, } from './shared.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 = {
     title: 'Read File',
@@ -80,7 +80,8 @@ export function registerReadFileTool(server, options = {}) {
         run: (signal) => handleReadFile(args, signal, options.resourceStore),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FILE, args.path),
     });
-    const wrappedHandler = wrapToolHandler(handler, {
+    const validatedHandler = withValidatedArgs(ReadFileInputSchema, handler);
+    const wrappedHandler = wrapToolHandler(validatedHandler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name = path.basename(args.path);
@@ -90,6 +91,19 @@ export function registerReadFileTool(server, options = {}) {
             }
             return `🕮 read: ${name}`;
         },
+        completionMessage: (args, result) => {
+            const name = path.basename(args.path);
+            if (result.isError)
+                return `🕮 read: ${name} • failed`;
+            const sc = result.structuredContent;
+            if (!sc.ok)
+                return `🕮 read: ${name} • failed`;
+            if (sc.hasMoreLines)
+                return `🕮 read: ${name} • truncated [${sc.totalLines ?? '?'} lines]`;
+            if (sc.startLine !== undefined)
+                return `🕮 read: ${name} • lines ${sc.startLine}–${sc.endLine ?? '?'}`;
+            return `🕮 read: ${name} • ${sc.totalLines ?? '?'} lines`;
+        },
     });
     if (registerToolTaskIfAvailable(server, 'read', READ_FILE_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
         return;

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

@@ -8,7 +8,7 @@ import { globEntries } from '../lib/file-operations/glob-engine.js';
 import { atomicWriteFile, withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath, validatePathForWrite, } from '../lib/path-validation.js';
 import { SearchAndReplaceInputSchema, SearchAndReplaceOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, createProgressReporter, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, notifyProgress, resolvePathOrRoot, withDefaultIcons, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createProgressReporter, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, notifyProgress, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const SEARCH_AND_REPLACE_TOOL = {
     title: 'Search and Replace',
@@ -231,23 +231,56 @@ export function registerSearchAndReplaceTool(server, options = {}) {
         timedSignal: {},
         ...(args.path ? { context: { path: args.path } } : {}),
         run: async (signal) => {
+            const dryLabel = args.dryRun ? ' [dry run]' : '';
+            const context = `"${args.searchPattern}" in ${args.filePattern}${dryLabel}`;
+            let progressCursor = 0;
             notifyProgress(extra, {
                 current: 0,
-                message: `🛠 search_and_replace: ${args.filePattern}`,
+                message: `🛠 search_and_replace: ${context}`,
             });
-            const result = await handleSearchAndReplace(args, signal, createProgressReporter(extra));
-            const sc = result.structuredContent;
-            const finalCurrent = (sc.processedFiles ?? 0) + 1;
-            notifyProgress(extra, {
-                current: finalCurrent,
-                message: `🛠 search_and_replace: ${args.filePattern} ➟ ${String(sc.filesChanged ?? 0)} files`,
-            });
-            return result;
+            const baseReporter = createProgressReporter(extra);
+            const progressWithMessage = ({ current, total, }) => {
+                if (current > progressCursor)
+                    progressCursor = current;
+                baseReporter({
+                    current,
+                    ...(total !== undefined ? { total } : {}),
+                    message: `🛠 search_and_replace: "${args.searchPattern}" — ${current} files processed`,
+                });
+            };
+            try {
+                const result = await handleSearchAndReplace(args, signal, progressWithMessage);
+                const sc = result.structuredContent;
+                const finalCurrent = Math.max((sc.processedFiles ?? 0) + 1, progressCursor + 1);
+                const matchWord = (sc.matches ?? 0) === 1 ? 'match' : 'matches';
+                const fileWord = (sc.filesChanged ?? 0) === 1 ? 'file' : 'files';
+                let endSuffix = `${sc.matches ?? 0} ${matchWord} in ${sc.filesChanged ?? 0} ${fileWord}`;
+                if (sc.failedFiles)
+                    endSuffix += `, ${sc.failedFiles} failed`;
+                if (sc.dryRun)
+                    endSuffix += ' [dry run]';
+                notifyProgress(extra, {
+                    current: finalCurrent,
+                    total: finalCurrent,
+                    message: `🛠 search_and_replace: ${context} • ${endSuffix}`,
+                });
+                return result;
+            }
+            catch (error) {
+                const finalCurrent = Math.max(progressCursor + 1, 1);
+                notifyProgress(extra, {
+                    current: finalCurrent,
+                    total: finalCurrent,
+                    message: `🛠 search_and_replace: ${context} • failed`,
+                });
+                throw error;
+            }
         },
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
     const { isInitialized } = options;
-    const wrappedHandler = wrapToolHandler(handler, {
+    const validatedHandler = withValidatedArgs(SearchAndReplaceInputSchema, handler);
+    const wrappedHandler = wrapToolHandler(validatedHandler, {
         guard: isInitialized,
     });
     if (registerToolTaskIfAvailable(server, 'search_and_replace', SEARCH_AND_REPLACE_TOOL, wrappedHandler, options.iconInfo, isInitialized))

package/dist/tools/roots.js

@@ -2,7 +2,7 @@ import { joinLines } from '../config.js';
 import { ErrorCode } from '../lib/errors.js';
 import { getAllowedDirectories } from '../lib/path-validation.js';
 import { ListAllowedDirectoriesInputSchema, ListAllowedDirectoriesOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 const LIST_ALLOWED_DIRECTORIES_TOOL = {
     title: 'Workspace Roots',
     description: 'List the workspace roots this server can access. ' +
@@ -38,8 +38,18 @@ export function registerListAllowedDirectoriesTool(server, options = {}) {
         run: () => handleListAllowedDirectories(),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN),
     });
-    server.registerTool('roots', withDefaultIcons({ ...LIST_ALLOWED_DIRECTORIES_TOOL }, options.iconInfo), wrapToolHandler(handler, {
+    const validatedHandler = withValidatedArgs(ListAllowedDirectoriesInputSchema, handler);
+    server.registerTool('roots', withDefaultIcons({ ...LIST_ALLOWED_DIRECTORIES_TOOL }, options.iconInfo), wrapToolHandler(validatedHandler, {
         guard: options.isInitialized,
         progressMessage: () => '≣ roots',
+        completionMessage: (_args, result) => {
+            if (result.isError)
+                return `≣ roots • failed`;
+            const sc = result.structuredContent;
+            if (!sc.ok)
+                return `≣ roots • failed`;
+            const count = sc.rootsCount ?? 0;
+            return `≣ roots • ${count} ${count === 1 ? 'root' : 'roots'}`;
+        },
     }));
 }

package/dist/tools/search-content.js

@@ -5,7 +5,7 @@ import { DEFAULT_EXCLUDE_PATTERNS } from '../lib/constants.js';
 import { ErrorCode, formatUnknownErrorMessage, McpError, } from '../lib/errors.js';
 import { searchContent } from '../lib/file-operations/search-content.js';
 import { SearchContentInputSchema, SearchContentOutputSchema, } from '../schemas.js';
-import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, wrapToolHandler, } from './shared.js';
+import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const MAX_INLINE_MATCHES = 50;
 const SEARCH_CONTENT_TOOL = {
@@ -69,16 +69,14 @@ function formatSearchMatchLine(match) {
 }
 function buildStructuredSearchResult(result, normalizedMatches, options) {
     const { summary } = result;
-    const matches = [];
-    for (const match of normalizedMatches) {
-        matches.push(buildSearchMatchPayload(match));
-    }
+    const matches = normalizedMatches.map((match) => buildSearchMatchPayload(match));
     return {
         ok: true,
         patternType: options.patternType,
         caseSensitive: options.caseSensitive,
         matches,
         totalMatches: summary.matches,
+        filesScanned: summary.filesScanned,
         ...(summary.truncated ? { truncated: summary.truncated } : {}),
         ...(summary.filesMatched ? { filesMatched: summary.filesMatched } : {}),
         ...(summary.skippedTooLarge
@@ -163,10 +161,7 @@ async function handleSearchContent(args, signal, resourceStore, onProgress) {
         return buildToolResponse(buildSearchTextResult(result, normalizedMatches), structuredFull);
     }
     const previewMatches = normalizedMatches.slice(0, MAX_INLINE_MATCHES);
-    const previewPayload = [];
-    for (const match of previewMatches) {
-        previewPayload.push(buildSearchMatchPayload(match));
-    }
+    const previewPayload = previewMatches.map((match) => buildSearchMatchPayload(match));
     const previewStructured = {
         ...structuredFull,
         matches: previewPayload,
@@ -201,35 +196,73 @@ export function registerSearchContentTool(server, options = {}) {
         extra,
         context: { path: args.path ?? '.' },
         run: async (signal) => {
-            const normalizedArgs = SearchContentInputSchema.parse(args);
+            const scope = args.filePattern;
+            const { pattern } = args;
+            let progressCursor = 0;
             notifyProgress(extra, {
                 current: 0,
-                message: `🔎︎ grep: ${normalizedArgs.pattern}`,
+                message: `🔎︎ grep: ${pattern} in ${scope}`,
             });
-            const result = await handleSearchContent(normalizedArgs, signal, options.resourceStore, createProgressReporter(extra));
-            const sc = result.structuredContent;
-            const count = sc.ok && sc.totalMatches ? sc.totalMatches : 0;
-            let suffix;
-            if (count === 0) {
-                suffix = 'No matches';
+            const baseReporter = createProgressReporter(extra);
+            const progressWithMessage = ({ current, total, }) => {
+                if (current > progressCursor)
+                    progressCursor = current;
+                const fileWord = current === 1 ? 'file' : 'files';
+                baseReporter({
+                    current,
+                    ...(total !== undefined ? { total } : {}),
+                    message: `🔎︎ grep: ${pattern} — ${current} ${fileWord} scanned`,
+                });
+            };
+            try {
+                const result = await handleSearchContent(args, signal, options.resourceStore, progressWithMessage);
+                const sc = result.structuredContent;
+                const count = sc.ok && sc.totalMatches ? sc.totalMatches : 0;
+                const filesMatched = sc.ok ? (sc.filesMatched ?? 0) : 0;
+                const stoppedReason = sc.ok ? sc.stoppedReason : undefined;
+                let suffix;
+                if (count === 0) {
+                    suffix = `No matches in ${scope}`;
+                }
+                else {
+                    const matchWord = count === 1 ? 'match' : 'matches';
+                    const fileInfo = filesMatched > 0
+                        ? ` in ${filesMatched} ${filesMatched === 1 ? 'file' : 'files'}`
+                        : '';
+                    suffix = `${count} ${matchWord}${fileInfo}`;
+                    if (stoppedReason === 'timeout') {
+                        suffix += ' [stopped — timeout]';
+                    }
+                    else if (stoppedReason === 'maxResults') {
+                        suffix += ' [truncated — max results]';
+                    }
+                    else if (stoppedReason === 'maxFiles') {
+                        suffix += ' [truncated — max files]';
+                    }
+                }
+                const finalCurrent = Math.max((sc.filesScanned ?? 0) + 1, progressCursor + 1);
+                notifyProgress(extra, {
+                    current: finalCurrent,
+                    total: finalCurrent,
+                    message: `🔎︎ grep: ${pattern} • ${suffix}`,
+                });
+                return result;
             }
-            else if (count === 1) {
-                suffix = '1 match';
+            catch (error) {
+                const finalCurrent = Math.max(progressCursor + 1, 1);
+                notifyProgress(extra, {
+                    current: finalCurrent,
+                    total: finalCurrent,
+                    message: `🔎︎ grep: ${pattern} in ${scope} • failed`,
+                });
+                throw error;
             }
-            else {
-                suffix = `${count} matches`;
-            }
-            const finalCurrent = (sc.filesScanned ?? 0) + 1;
-            notifyProgress(extra, {
-                current: finalCurrent,
-                message: `🔎︎ grep: ${normalizedArgs.pattern} ➟ ${suffix}`,
-            });
-            return result;
         },
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path ?? '.'),
     });
     const { isInitialized } = options;
-    const wrappedHandler = wrapToolHandler(handler, {
+    const validatedHandler = withValidatedArgs(SearchContentInputSchema, handler);
+    const wrappedHandler = wrapToolHandler(validatedHandler, {
         guard: isInitialized,
     });
     if (registerToolTaskIfAvailable(server, 'grep', SEARCH_CONTENT_TOOL, wrappedHandler, options.iconInfo, isInitialized))

package/dist/tools/search-files.js

@@ -4,7 +4,7 @@ import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_SEARCH_TIMEOUT_MS, } from '../lib/con
 import { ErrorCode } from '../lib/errors.js';
 import { searchFiles } from '../lib/file-operations/search-files.js';
 import { SearchFilesInputSchema, SearchFilesOutputSchema } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const SEARCH_FILES_TOOL = {
     title: 'Find Files',
@@ -43,6 +43,7 @@ async function handleSearchFiles(args, signal, onProgress) {
         pattern: args.pattern,
         results: relativeResults,
         totalMatches: result.summary.matched,
+        filesScanned: result.summary.filesScanned,
         ...(result.summary.truncated
             ? { truncated: result.summary.truncated }
             : {}),
@@ -89,24 +90,70 @@ export function registerSearchFilesTool(server, options = {}) {
         timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
         context: { path: args.path ?? '.' },
         run: async (signal) => {
+            const rawScopeLabel = args.path ? path.basename(args.path) : '.';
+            const scopeLabel = rawScopeLabel || '.';
+            const { pattern } = args;
+            const context = `${pattern} in ${scopeLabel}`;
+            let progressCursor = 0;
             notifyProgress(extra, {
                 current: 0,
-                message: `🔎︎ find: ${args.pattern}`,
+                message: `🔎︎ find: ${context}`,
             });
-            const result = await handleSearchFiles(args, signal, createProgressReporter(extra));
-            const sc = result.structuredContent;
-            const suffix = sc.ok && sc.totalMatches ? String(sc.totalMatches) : 'No matches';
-            const finalCurrent = (sc.filesScanned ?? 0) + 1;
-            notifyProgress(extra, {
-                current: finalCurrent,
-                message: `🔎︎ find: ${args.pattern} ➟ ${suffix}`,
-            });
-            return result;
+            const baseReporter = createProgressReporter(extra);
+            const progressWithMessage = ({ current, total, }) => {
+                if (current > progressCursor)
+                    progressCursor = current;
+                const fileWord = current === 1 ? 'file' : 'files';
+                baseReporter({
+                    current,
+                    ...(total !== undefined ? { total } : {}),
+                    message: `🔎︎ find: ${pattern} [${current} ${fileWord} scanned]`,
+                });
+            };
+            try {
+                const result = await handleSearchFiles(args, signal, progressWithMessage);
+                const sc = result.structuredContent;
+                const count = sc.ok ? (sc.totalMatches ?? 0) : 0;
+                const stoppedReason = sc.ok ? sc.stoppedReason : undefined;
+                let suffix;
+                if (count === 0) {
+                    suffix = `No matches in ${scopeLabel}`;
+                }
+                else {
+                    suffix = `${count} ${count === 1 ? 'match' : 'matches'}`;
+                    if (stoppedReason === 'timeout') {
+                        suffix += ' [stopped — timeout]';
+                    }
+                    else if (stoppedReason === 'maxResults') {
+                        suffix += ' [truncated — max results]';
+                    }
+                    else if (stoppedReason === 'maxFiles') {
+                        suffix += ' [truncated — max files]';
+                    }
+                }
+                const finalCurrent = Math.max((sc.filesScanned ?? 0) + 1, progressCursor + 1);
+                notifyProgress(extra, {
+                    current: finalCurrent,
+                    total: finalCurrent,
+                    message: `🔎︎ find: ${context} • ${suffix}`,
+                });
+                return result;
+            }
+            catch (error) {
+                const finalCurrent = Math.max(progressCursor + 1, 1);
+                notifyProgress(extra, {
+                    current: finalCurrent,
+                    total: finalCurrent,
+                    message: `🔎︎ find: ${context} • failed`,
+                });
+                throw error;
+            }
         },
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_INVALID_PATTERN, args.path),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
     const { isInitialized } = options;
-    const wrappedHandler = wrapToolHandler(handler, {
+    const validatedHandler = withValidatedArgs(SearchFilesInputSchema, handler);
+    const wrappedHandler = wrapToolHandler(validatedHandler, {
         guard: isInitialized,
     });
     if (registerToolTaskIfAvailable(server, 'find', SEARCH_FILES_TOOL, wrappedHandler, options.iconInfo, isInitialized))

package/dist/tools/shared.d.ts

@@ -1,5 +1,5 @@
 import type { ContentBlock, Icon, ProgressNotificationParams } from '@modelcontextprotocol/sdk/types.js';
-import type { z } from 'zod';
+import { z } from 'zod';
 import type { FileInfo } from '../config.js';
 import { ErrorCode } from '../lib/errors.js';
 import type { ResourceStore } from '../lib/resource-store.js';
@@ -19,6 +19,8 @@ export declare const IDEMPOTENT_WRITE_TOOL_ANNOTATIONS: {
     readonly idempotentHint: true;
     readonly openWorldHint: false;
 };
+export declare function shouldStripStructuredOutput(): boolean;
+export declare function maybeStripStructuredContentFromResult<T extends object>(result: T): T;
 type ResourceEntry = ReturnType<ResourceStore['putText']>;
 export declare function maybeExternalizeTextContent(resourceStore: ResourceStore | undefined, content: string, params: {
     name: string;
@@ -45,6 +47,8 @@ interface ToolErrorResponse extends Record<string, unknown> {
     isError: true;
 }
 export type ToolResult<T> = ToolResponse<T> | ToolErrorResponse;
+export declare function parseToolArgs<Schema extends z.ZodType>(schema: Schema, args: unknown): z.infer<Schema>;
+export declare function withValidatedArgs<Args, Result>(schema: z.ZodType<Args>, handler: (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>): (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>;
 type ProgressToken = string | number;
 export interface ToolExtra {
     signal?: AbortSignal;

package/dist/tools/shared.js

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 import { createDetailedError, ErrorCode, formatDetailedError, getSuggestion, McpError, } from '../lib/errors.js';
 import { createTimedAbortSignal } from '../lib/fs-helpers.js';
 import { withToolDiagnostics } from '../lib/observability.js';
@@ -5,6 +6,7 @@ import { getAllowedDirectories } from '../lib/path-validation.js';
 const MAX_INLINE_CONTENT_CHARS = 20_000;
 const MAX_INLINE_PREVIEW_CHARS = 4_000;
 const PROGRESS_RATE_LIMIT_MS = 50;
+const TRUE_ENV_VALUES = new Set(['1', 'true', 'yes']);
 export const READ_ONLY_TOOL_ANNOTATIONS = {
     readOnlyHint: true,
     idempotentHint: true,
@@ -20,6 +22,30 @@ export const IDEMPOTENT_WRITE_TOOL_ANNOTATIONS = {
     idempotentHint: true,
     openWorldHint: false,
 };
+export function shouldStripStructuredOutput() {
+    const value = process.env['FS_CONTEXT_STRIP_STRUCTURED'];
+    if (value === undefined)
+        return false;
+    return TRUE_ENV_VALUES.has(value.trim().toLowerCase());
+}
+export function maybeStripStructuredContentFromResult(result) {
+    if (!shouldStripStructuredOutput())
+        return result;
+    if (!Object.hasOwn(result, 'structuredContent'))
+        return result;
+    const rest = { ...result };
+    delete rest['structuredContent'];
+    return rest;
+}
+function maybeStripOutputSchema(tool) {
+    if (!shouldStripStructuredOutput())
+        return tool;
+    if (!Object.hasOwn(tool, 'outputSchema'))
+        return tool;
+    const mutable = { ...tool };
+    delete mutable['outputSchema'];
+    return mutable;
+}
 function buildTextPreview(text) {
     if (text.length <= MAX_INLINE_PREVIEW_CHARS)
         return text;
@@ -66,18 +92,33 @@ function resolveDetailedError(error, defaultCode, path) {
 export function buildToolResponse(text, structuredContent, extraContent = []) {
     return buildContentBlock(text, structuredContent, extraContent);
 }
+export function parseToolArgs(schema, args) {
+    const candidate = args === undefined ? {} : args;
+    const parsed = schema.safeParse(candidate);
+    if (parsed.success) {
+        return parsed.data;
+    }
+    throw new McpError(ErrorCode.E_INVALID_INPUT, `Invalid tool arguments: ${parsed.error.message}`, undefined, { errors: z.treeifyError(parsed.error) });
+}
+export function withValidatedArgs(schema, handler) {
+    return async (args, extra) => {
+        const normalizedArgs = parseToolArgs(schema, args);
+        return handler(normalizedArgs, extra);
+    };
+}
 function canSendProgress(extra) {
     return (extra._meta?.progressToken !== undefined &&
         extra.sendNotification !== undefined);
 }
 export function withDefaultIcons(tool, iconInfo) {
-    if (!iconInfo)
-        return tool;
+    if (!iconInfo) {
+        return maybeStripOutputSchema(tool);
+    }
     const existingIcons = tool.icons;
     if (existingIcons && existingIcons.length > 0) {
-        return tool;
+        return maybeStripOutputSchema(tool);
     }
-    return {
+    const withIcons = {
         ...tool,
         icons: [
             {
@@ -86,6 +127,7 @@ export function withDefaultIcons(tool, iconInfo) {
             },
         ],
     };
+    return maybeStripOutputSchema(withIcons);
 }
 export function buildFileInfoPayload(info) {
     return {
@@ -184,9 +226,11 @@ export function createProgressReporter(extra) {
     return (progress) => {
         const { current, total, message } = progress;
         // Enforce monotonic progress to prevent client confusion. Client behavior on
+        // out-of-order progress is undefined in the MCP spec.
         if (current <= lastProgress)
             return;
-        // Enforce rate-limiting to prevent client flooding. Progress updates that are
+        // Enforce rate-limiting to prevent client flooding. Progress updates faster
+        // than PROGRESS_RATE_LIMIT_MS are silently dropped.
         const now = Date.now();
         if (now - lastSentMs < PROGRESS_RATE_LIMIT_MS)
             return;
@@ -239,6 +283,7 @@ async function withProgress(message, extra, run, getCompletionMessage) {
             progressToken: token,
             progress: total,
             total,
+            message: `${message} • failed`,
         });
         throw error;
     }
@@ -247,7 +292,7 @@ export function wrapToolHandler(handler, options) {
     return async (args, extra) => {
         const resolvedExtra = extra ?? {};
         if (options.guard && !options.guard()) {
-            return buildNotInitializedResult();
+            return maybeStripStructuredContentFromResult(buildNotInitializedResult());
         }
         if (options.progressMessage) {
             const message = options.progressMessage(args);
@@ -255,9 +300,11 @@ export function wrapToolHandler(handler, options) {
             const completionFn = completionMessage
                 ? (result) => completionMessage(args, result)
                 : undefined;
-            return withProgress(message, resolvedExtra, () => handler(args, resolvedExtra), completionFn);
+            const result = await withProgress(message, resolvedExtra, () => handler(args, resolvedExtra), completionFn);
+            return maybeStripStructuredContentFromResult(result);
         }
-        return handler(args, resolvedExtra);
+        const result = await handler(args, resolvedExtra);
+        return maybeStripStructuredContentFromResult(result);
     };
 }
 export function resolvePathOrRoot(pathValue) {

package/dist/tools/stat-many.js

@@ -1,9 +1,10 @@
+import * as path from 'node:path';
 import { formatBytes, joinLines } from '../config.js';
 import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { getMultipleFileInfo } from '../lib/file-operations/file-info.js';
 import { GetMultipleFileInfoInputSchema, GetMultipleFileInfoOutputSchema, } from '../schemas.js';
-import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, wrapToolHandler, } from './shared.js';
+import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const GET_MULTIPLE_FILE_INFO_TOOL = {
     title: 'Get Multiple File Info',
@@ -72,9 +73,27 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
             onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, primaryPath),
         });
     };
-    const wrappedHandler = wrapToolHandler(handler, {
+    const validatedHandler = withValidatedArgs(GetMultipleFileInfoInputSchema, handler);
+    const wrappedHandler = wrapToolHandler(validatedHandler, {
         guard: options.isInitialized,
-        progressMessage: (args) => `🕮 stat_many: ${args.paths.length} paths`,
+        progressMessage: (args) => {
+            const first = path.basename(args.paths[0] ?? '');
+            const extra = args.paths.length > 1 ? `, ${path.basename(args.paths[1] ?? '')}…` : '';
+            return `🕮 stat_many: ${args.paths.length} paths [${first}${extra}]`;
+        },
+        completionMessage: (args, result) => {
+            if (result.isError)
+                return `🕮 stat_many: ${args.paths.length} paths • failed`;
+            const sc = result.structuredContent;
+            if (!sc.ok)
+                return `🕮 stat_many: ${args.paths.length} paths • failed`;
+            const total = sc.summary?.total ?? 0;
+            const succeeded = sc.summary?.succeeded ?? 0;
+            const failed = sc.summary?.failed ?? 0;
+            if (failed)
+                return `🕮 stat_many: ${succeeded}/${total} OK, ${failed} failed`;
+            return `🕮 stat_many: ${total} OK`;
+        },
     });
     if (registerToolTaskIfAvailable(server, 'stat_many', GET_MULTIPLE_FILE_INFO_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
         return;

package/dist/tools/stat.js

@@ -4,7 +4,7 @@ import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { getFileInfo } from '../lib/file-operations/file-info.js';
 import { GetFileInfoInputSchema, GetFileInfoOutputSchema } from '../schemas.js';
-import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, wrapToolHandler, } from './shared.js';
+import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 const GET_FILE_INFO_TOOL = {
     title: 'Get File Info',
     description: 'Get metadata (size, modified time, permissions, mime type) for a file or directory.',
@@ -45,8 +45,18 @@ export function registerGetFileInfoTool(server, options = {}) {
         run: (signal) => handleGetFileInfo(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, args.path),
     });
-    server.registerTool('stat', withDefaultIcons({ ...GET_FILE_INFO_TOOL }, options.iconInfo), wrapToolHandler(handler, {
+    const validatedHandler = withValidatedArgs(GetFileInfoInputSchema, handler);
+    server.registerTool('stat', withDefaultIcons({ ...GET_FILE_INFO_TOOL }, options.iconInfo), wrapToolHandler(validatedHandler, {
         guard: options.isInitialized,
         progressMessage: (args) => `🕮 stat: ${path.basename(args.path)}`,
+        completionMessage: (args, result) => {
+            const name = path.basename(args.path);
+            if (result.isError)
+                return `🕮 stat: ${name} • failed`;
+            const sc = result.structuredContent;
+            if (!sc.ok || !sc.info)
+                return `🕮 stat: ${name} • failed`;
+            return `🕮 stat: ${sc.info.name} • ${sc.info.type}, ${formatBytes(sc.info.size)}`;
+        },
     }));
 }