@j0hanz/filesystem-mcp 1.13.2 → 1.14.0

package/dist/tools/search-content.js

@@ -1,5 +1,4 @@
 import * as path from 'node:path';
-import { performance } from 'node:perf_hooks';
 import RE2 from 're2';
 import { DEFAULT_EXCLUDE_PATTERNS } from '../lib/constants.js';
 import { ErrorCode, formatUnknownErrorMessage, McpError, } from '../lib/errors.js';
@@ -19,13 +18,11 @@ const CONFIG = {
         maxFiles: 'max files',
     },
 };
-let searchMetricSequence = 0;
 const TRUTHY_SUMMARY_FIELDS = [
     'filesMatched',
     'skippedTooLarge',
     'skippedBinary',
     'skippedInaccessible',
-    'linesSkippedDueToRegexTimeout',
 ];
 function buildStructuredSummaryFields(summary) {
     const result = {};
@@ -53,15 +50,6 @@ function buildCompletionSuffix(count, filesMatched, scope, stoppedReason) {
         : '';
     return `${count} ${matchWord} in ${filesMatched} ${fileWord}${reasonSuffix}`;
 }
-function createSearchMetricNames() {
-    searchMetricSequence += 1;
-    const metricSuffix = `${Date.now()}_${searchMetricSequence}`;
-    return {
-        timerStartName: `searchContentStart_${metricSuffix}`,
-        timerEndName: `searchContentEnd_${metricSuffix}`,
-        metricName: `searchContent_${metricSuffix}`,
-    };
-}
 function compareNormalizedMatches(left, right) {
     const fileCompare = left.relativeFile.localeCompare(right.relativeFile);
     if (fileCompare !== 0)
@@ -80,7 +68,7 @@ function buildSearchPreviewState(matches, payloads) {
         needsExternalize,
         visibleMatches,
         visiblePayloads: payloads.slice(0, visibleCount),
-        heading: SearchResponseBuilder.buildHeading(matches.length, visibleMatches.length),
+        heading: buildHeading(matches.length, visibleMatches.length),
     };
 }
 export const SEARCH_CONTENT_TOOL = {
@@ -94,187 +82,164 @@ export const SEARCH_CONTENT_TOOL = {
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
     nuances: [
         'Inline results capped at 50 matches; full results via `resourceUri`.',
-        'Skips binary and oversized files.',
     ],
     gotchas: [
         'Skips binary/oversized files silently — verify with `stat` if no matches.',
     ],
     taskSupport: 'optional',
 };
-/**
- * Handles formatting and building the search response.
- */
-const SearchResponseBuilder = {
-    buildHeading(totalMatches, visibleMatches) {
-        if (visibleMatches >= totalMatches) {
-            return `Found ${totalMatches}:`;
-        }
-        return `Found ${totalMatches} (showing first ${visibleMatches}):`;
-    },
-    buildText(heading, matches, summary) {
-        if (matches.length === 0)
-            return 'No matches';
-        const text = this.buildMatchList(heading, matches);
-        if (!summary)
-            return text;
-        const summaryOpts = {
-            truncated: summary.truncated,
-            ...(summary.truncated
-                ? { truncatedReason: this.resolveTruncatedReason(summary) }
-                : {}),
-        };
-        return text + formatOperationSummary(summaryOpts);
-    },
-    buildStructured(summary, matches, options) {
+function buildHeading(totalMatches, visibleMatches) {
+    if (visibleMatches >= totalMatches) {
+        return `Found ${totalMatches}:`;
+    }
+    return `Found ${totalMatches} (showing first ${visibleMatches}):`;
+}
+function buildSearchText(heading, matches, summary) {
+    if (matches.length === 0)
+        return 'No matches';
+    const text = buildMatchList(heading, matches);
+    if (!summary)
+        return text;
+    const summaryOpts = {
+        truncated: summary.truncated,
+        ...(summary.truncated
+            ? { truncatedReason: resolveTruncatedReason(summary) }
+            : {}),
+    };
+    return text + formatOperationSummary(summaryOpts);
+}
+function buildSearchStructured(summary, matches) {
+    return {
+        ok: true,
+        matches,
+        totalMatches: summary.matches,
+        filesScanned: summary.filesScanned,
+        ...buildStructuredSummaryFields(summary),
+    };
+}
+function normalizeMatches(result) {
+    const relativeByFile = new Map();
+    const getRelativeFile = (file) => {
+        const cached = relativeByFile.get(file);
+        if (cached !== undefined)
+            return cached;
+        const relative = path.relative(result.basePath, file);
+        relativeByFile.set(file, relative);
+        return relative;
+    };
+    return result.matches
+        .map((match, index) => ({
+        ...match,
+        relativeFile: getRelativeFile(match.file),
+        index,
+    }))
+        .sort(compareNormalizedMatches);
+}
+function buildMatchPayloads(matches, context) {
+    return matches.map((match) => {
+        const column = findColumnOffset(match.content, context);
         return {
-            ok: true,
-            patternType: options.patternType,
-            caseSensitive: options.caseSensitive,
-            matches,
-            totalMatches: summary.matches,
-            filesScanned: summary.filesScanned,
-            ...buildStructuredSummaryFields(summary),
-        };
-    },
-    normalizeMatches(result) {
-        const relativeByFile = new Map();
-        const getRelativeFile = (file) => {
-            const cached = relativeByFile.get(file);
-            if (cached !== undefined)
-                return cached;
-            const relative = path.relative(result.basePath, file);
-            relativeByFile.set(file, relative);
-            return relative;
+            file: match.relativeFile,
+            line: match.line,
+            ...(column !== undefined ? { column } : {}),
+            content: match.content,
+            matchCount: match.matchCount,
+            ...(match.contextBefore
+                ? { contextBefore: [...match.contextBefore] }
+                : {}),
+            ...(match.contextAfter ? { contextAfter: [...match.contextAfter] } : {}),
         };
-        return result.matches
-            .map((match, index) => ({
-            ...match,
-            relativeFile: getRelativeFile(match.file),
-            index,
-        }))
-            .sort(compareNormalizedMatches);
-    },
-    buildMatchPayloads(matches, context) {
-        return matches.map((match) => {
-            const column = this.findColumnOffset(match.content, context);
-            return {
-                file: match.relativeFile,
-                line: match.line,
-                ...(column !== undefined ? { column } : {}),
-                content: match.content,
-                matchCount: match.matchCount,
-                ...(match.contextBefore
-                    ? { contextBefore: [...match.contextBefore] }
-                    : {}),
-                ...(match.contextAfter
-                    ? { contextAfter: [...match.contextAfter] }
-                    : {}),
-            };
-        });
-    },
-    buildMatchList(heading, matches) {
-        if (matches.length === 0)
-            return heading;
-        const parts = [heading];
-        for (const match of matches) {
-            parts.push(`\n  ${match.relativeFile}:${String(match.line).padStart(4)}: ${match.content}`);
-        }
-        return parts.join('');
-    },
-    resolveTruncatedReason(summary) {
-        if (summary.stoppedReason === 'timeout')
-            return 'timeout';
-        if (summary.stoppedReason === 'maxFiles') {
-            return `max files (${summary.filesScanned})`;
+    });
+}
+function buildMatchList(heading, matches) {
+    if (matches.length === 0)
+        return heading;
+    const parts = [heading];
+    for (const match of matches) {
+        parts.push(`\n  ${match.relativeFile}:${String(match.line).padStart(4)}: ${match.content}`);
+    }
+    return parts.join('');
+}
+function resolveTruncatedReason(summary) {
+    if (summary.stoppedReason === 'timeout')
+        return 'timeout';
+    if (summary.stoppedReason === 'maxFiles') {
+        return `max files (${summary.filesScanned})`;
+    }
+    return `max results (${summary.matches})`;
+}
+function findColumnOffset(content, context) {
+    try {
+        if (context.matcher) {
+            context.matcher.lastIndex = 0;
+            const match = context.matcher.exec(content);
+            return match ? match.index : undefined;
         }
-        return `max results (${summary.matches})`;
-    },
-    findColumnOffset(content, context) {
-        try {
-            if (context.matcher) {
-                context.matcher.lastIndex = 0;
-                const match = context.matcher.exec(content);
-                return match ? match.index : undefined;
-            }
-            if (context.caseSensitive) {
-                const idx = content.indexOf(context.pattern);
-                return idx >= 0 ? idx : undefined;
-            }
-            // Case-insensitive literal search
-            const idx = content.toLowerCase().indexOf(context.foldedPattern ?? '');
+        if (context.caseSensitive) {
+            const idx = content.indexOf(context.pattern);
             return idx >= 0 ? idx : undefined;
         }
-        catch {
-            return undefined;
-        }
-    },
-};
-const SearchExecutor = {
-    async run(args, basePath, signal, onProgress) {
-        const excludePatterns = args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS;
-        const { timerStartName, timerEndName, metricName } = createSearchMetricNames();
-        const options = {
-            includeHidden: args.includeHidden,
-            excludePatterns,
-            filePattern: args.filePattern,
-            caseSensitive: args.caseSensitive,
-            wholeWord: args.wholeWord,
-            contextLines: args.contextLines,
-            maxResults: args.maxResults,
-            isLiteral: !args.isRegex,
-            multiline: args.multiline,
-            ...(signal ? { signal } : {}),
-            ...(onProgress ? { onProgress } : {}),
-        };
-        performance.mark(timerStartName);
-        try {
-            return await searchContent(basePath, args.pattern, options);
-        }
-        catch (error) {
-            if (error instanceof Error && /regular expression/i.test(error.message)) {
-                throw new McpError(ErrorCode.E_INVALID_PATTERN, error.message);
-            }
-            throw error;
-        }
-        finally {
-            performance.mark(timerEndName);
-            performance.measure(metricName, timerStartName, timerEndName);
-            performance.clearMarks(timerStartName);
-            performance.clearMarks(timerEndName);
-            performance.clearMeasures(metricName);
-        }
-    },
-    createMatcher(args) {
-        if (!args.isRegex)
-            return undefined;
-        try {
-            const flags = (args.caseSensitive ? '' : 'i') + (args.multiline ? 'm' : '');
-            return new RE2(args.pattern, flags);
-        }
-        catch (error) {
-            throw new McpError(ErrorCode.E_INVALID_PATTERN, `Invalid regex pattern: ${formatUnknownErrorMessage(error)}`);
+        // Case-insensitive literal search
+        const idx = content.toLowerCase().indexOf(context.foldedPattern ?? '');
+        return idx >= 0 ? idx : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function executeSearch(args, basePath, signal, onProgress) {
+    const excludePatterns = args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS;
+    const options = {
+        includeHidden: args.includeHidden,
+        excludePatterns,
+        filePattern: args.filePattern,
+        caseSensitive: args.caseSensitive,
+        wholeWord: args.wholeWord,
+        contextLines: args.contextLines,
+        maxResults: args.maxResults,
+        isLiteral: !args.isRegex,
+        ...(signal ? { signal } : {}),
+        ...(onProgress ? { onProgress } : {}),
+    };
+    try {
+        return await searchContent(basePath, args.pattern, options);
+    }
+    catch (error) {
+        if (error instanceof Error && /regular expression/i.test(error.message)) {
+            throw new McpError(ErrorCode.E_INVALID_PATTERN, error.message);
         }
-    },
-    createSearchContext(args, matcher) {
-        return {
-            pattern: args.pattern,
-            caseSensitive: args.caseSensitive,
-            ...(matcher ? { matcher } : {}),
-            ...(!args.isRegex && !args.caseSensitive
-                ? { foldedPattern: args.pattern.toLowerCase() }
-                : {}),
-        };
-    },
-};
+        throw error;
+    }
+}
+function createSearchMatcher(args) {
+    if (!args.isRegex)
+        return undefined;
+    try {
+        const flags = args.caseSensitive ? '' : 'i';
+        return new RE2(args.pattern, flags);
+    }
+    catch (error) {
+        throw new McpError(ErrorCode.E_INVALID_PATTERN, `Invalid regex pattern: ${formatUnknownErrorMessage(error)}`);
+    }
+}
+function createSearchContext(args, matcher) {
+    return {
+        pattern: args.pattern,
+        caseSensitive: args.caseSensitive,
+        ...(matcher ? { matcher } : {}),
+        ...(!args.isRegex && !args.caseSensitive
+            ? { foldedPattern: args.pattern.toLowerCase() }
+            : {}),
+    };
+}
 async function handleSearchContent(args, signal, resourceStore, onProgress) {
     const basePath = resolvePathOrRoot(args.path);
-    const patternType = args.isRegex ? 'regex' : 'literal';
-    const regexMatcher = SearchExecutor.createMatcher(args);
-    const result = await SearchExecutor.run(args, basePath, signal, onProgress);
-    const normalizedMatches = SearchResponseBuilder.normalizeMatches(result);
-    const searchContext = SearchExecutor.createSearchContext(args, regexMatcher);
-    const matchPayloads = SearchResponseBuilder.buildMatchPayloads(normalizedMatches, searchContext);
-    const fullStructured = SearchResponseBuilder.buildStructured(result.summary, matchPayloads, { patternType, caseSensitive: args.caseSensitive });
+    const regexMatcher = createSearchMatcher(args);
+    const result = await executeSearch(args, basePath, signal, onProgress);
+    const normalizedMatches = normalizeMatches(result);
+    const searchContext = createSearchContext(args, regexMatcher);
+    const matchPayloads = buildMatchPayloads(normalizedMatches, searchContext);
+    const fullStructured = buildSearchStructured(result.summary, matchPayloads);
     const preview = buildSearchPreviewState(normalizedMatches, matchPayloads);
     if (resourceStore && preview.needsExternalize) {
         const previewStructured = {
@@ -288,7 +253,7 @@ async function handleSearchContent(args, signal, resourceStore, onProgress) {
             text: JSON.stringify(fullStructured),
         });
         previewStructured.resourceUri = entry.uri;
-        const text = SearchResponseBuilder.buildText(preview.heading, preview.visibleMatches);
+        const text = buildSearchText(preview.heading, preview.visibleMatches);
         return buildToolResponse(text, previewStructured, [
             buildResourceLink({
                 uri: entry.uri,
@@ -299,13 +264,14 @@ async function handleSearchContent(args, signal, resourceStore, onProgress) {
             }),
         ]);
     }
-    const text = SearchResponseBuilder.buildText(preview.heading, preview.visibleMatches, result.summary);
+    const text = buildSearchText(preview.heading, preview.visibleMatches, result.summary);
     return buildToolResponse(text, fullStructured);
 }
 export function registerSearchContentTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'grep',
         extra,
+        outputSchema: SearchContentOutputSchema,
         context: { path: args.path ?? '.' },
         run: async (signal) => {
             const { pattern, filePattern: scope } = args;
@@ -321,10 +287,8 @@ export function registerSearchContentTool(server, options = {}) {
             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;
-                const suffix = buildCompletionSuffix(count, filesMatched, scope, stoppedReason);
+                const { totalMatches = 0, filesMatched = 0, stoppedReason } = sc;
+                const suffix = buildCompletionSuffix(totalMatches, filesMatched, scope, stoppedReason);
                 const finalCurrent = resolveFinalProgressCurrent(progress, (sc.filesScanned ?? 0) + 1);
                 progress.complete(`${progressLabel} • ${suffix}`, finalCurrent);
                 return result;

package/dist/tools/search-files.js

@@ -14,10 +14,7 @@ export const SEARCH_FILES_TOOL = {
     inputSchema: SearchFilesInputSchema,
     outputSchema: SearchFilesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
-    nuances: [
-        'Respects `.gitignore` unless `includeIgnored=true`.',
-        'Returns relative paths plus metadata; may truncate.',
-    ],
+    nuances: ['Respects `.gitignore` unless `includeIgnored=true`.'],
     taskSupport: 'optional',
 };
 async function handleSearchFiles(args, signal, onProgress) {
@@ -52,7 +49,6 @@ async function handleSearchFiles(args, signal, onProgress) {
     const structured = {
         ok: true,
         root: basePath,
-        pattern: args.pattern,
         results: relativeResults,
         totalMatches: result.summary.matched,
         filesScanned: result.summary.filesScanned,
@@ -103,6 +99,7 @@ export function registerSearchFilesTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'find',
         extra,
+        outputSchema: SearchFilesOutputSchema,
         timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
         context: { path: args.path ?? '.' },
         run: async (signal) => {
@@ -129,14 +126,13 @@ export function registerSearchFilesTool(server, options = {}) {
             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;
+                const { totalMatches = 0, stoppedReason } = sc;
                 let suffix;
-                if (count === 0) {
+                if (totalMatches === 0) {
                     suffix = 'No matches';
                 }
                 else {
-                    suffix = `${count} ${count === 1 ? 'match' : 'matches'}`;
+                    suffix = `${totalMatches} ${totalMatches === 1 ? 'match' : 'matches'}`;
                     if (stoppedReason === 'timeout') {
                         suffix += ' [timeout]';
                     }

package/dist/tools/shared.d.ts

@@ -38,6 +38,12 @@ export declare function buildResourceLink(params: {
     description?: string;
     expiresAt?: string;
 }): ContentBlock;
+export declare function buildStructuredError(error: unknown, defaultCode: ErrorCode, path?: string): {
+    code: ErrorCode;
+    message: string;
+    path?: string;
+    suggestion?: string;
+};
 export declare function buildToolResponse<T>(text: string, structuredContent: T, extraContent?: ContentBlock[]): {
     content: ContentBlock[];
     structuredContent: T;
@@ -94,6 +100,7 @@ export declare function buildFileInfoPayload(info: FileInfo): FileInfoPayload;
 interface ToolExecutionOptions<T> {
     toolName: string;
     extra: ToolExtra;
+    outputSchema?: z.ZodType<T>;
     run: (signal: AbortSignal | undefined) => ToolResponse<T> | Promise<ToolResponse<T>>;
     onError: (error: unknown) => ToolResult<T>;
     context?: Record<string, unknown>;

package/dist/tools/shared.js

@@ -6,6 +6,7 @@ import { createDetailedError, ErrorCode, formatDetailedError, getSuggestion, Mcp
 import { createTimedAbortSignal } from '../lib/fs-helpers.js';
 import { withToolDiagnostics } from '../lib/observability.js';
 import { getAllowedDirectories } from '../lib/paths.js';
+import { createBase64JsonCodec } from '../lib/zod-codecs.js';
 export {} from './contract.js';
 const MAX_INLINE_CONTENT_CHARS = parseInt(process.env['FS_CONTEXT_MAX_INLINE_CHARS'] ?? '', 10) || 20_000;
 const MAX_INLINE_PREVIEW_CHARS = 4_000;
@@ -133,19 +134,48 @@ function resolveDetailedError(error, defaultCode, path) {
     }
     return detailed;
 }
+export function buildStructuredError(error, defaultCode, path) {
+    const detailed = resolveDetailedError(error, defaultCode, path);
+    return {
+        code: detailed.code,
+        message: detailed.message,
+        ...(detailed.path !== undefined ? { path: detailed.path } : {}),
+        ...(detailed.suggestion !== undefined
+            ? { suggestion: detailed.suggestion }
+            : {}),
+    };
+}
 export function buildToolResponse(text, structuredContent, extraContent = []) {
     return {
         content: [{ type: 'text', text }, ...extraContent],
         structuredContent,
     };
 }
+function validateStructuredContent(toolName, outputSchema, structuredContent) {
+    const parsed = outputSchema.safeParse(structuredContent);
+    if (parsed.success) {
+        return parsed.data;
+    }
+    throw new McpError(ErrorCode.E_UNKNOWN, `Tool "${toolName}" returned invalid structuredContent.`, undefined, { errors: z.treeifyError(parsed.error) });
+}
+function validateToolResponse(toolName, result, outputSchema) {
+    if (!outputSchema)
+        return result;
+    if (!Object.hasOwn(result, 'structuredContent')) {
+        throw new McpError(ErrorCode.E_UNKNOWN, `Tool "${toolName}" returned success without structuredContent.`);
+    }
+    return {
+        ...result,
+        structuredContent: validateStructuredContent(toolName, outputSchema, result.structuredContent),
+    };
+}
 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) });
+    throw new McpError(ErrorCode.E_INVALID_INPUT, `Invalid tool arguments:\n${z.prettifyError(parsed.error)}`, undefined, { errors: z.treeifyError(parsed.error) });
 }
 export function withValidatedArgs(schema, handler) {
     return async (args, extra) => {
@@ -222,7 +252,7 @@ export async function executeToolWithDiagnostics(options) {
     return withToolDiagnostics(options.toolName, () => withToolErrorHandling(async () => {
         const { signal, cleanup } = getToolSignal(options.extra.signal, options.timedSignal);
         try {
-            return await options.run(signal);
+            return validateToolResponse(options.toolName, await options.run(signal), options.outputSchema);
         }
         finally {
             cleanup();
@@ -461,19 +491,16 @@ export function resolvePathOrRoot(pathValue) {
     }
     return root;
 }
+const OffsetCursorSchema = z.strictObject({
+    offset: z.int().min(0),
+});
+const OffsetCursorCodec = createBase64JsonCodec(OffsetCursorSchema);
 export function encodeOffsetCursor(offset) {
-    return Buffer.from(JSON.stringify({ offset })).toString('base64url');
+    return z.encode(OffsetCursorCodec, { offset });
 }
 export function decodeOffsetCursor(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;
-            if (Number.isInteger(offset) && offset >= 0)
-                return offset;
-        }
+        return OffsetCursorCodec.parse(cursor).offset;
     }
     catch {
         // fall through to throw

package/dist/tools/stat-many.js

@@ -3,7 +3,7 @@ import { ErrorCode } from '../lib/errors.js';
 import { getMultipleFileInfo } from '../lib/file-operations/metadata.js';
 import { formatBytes, joinLines } from '../config.js';
 import { GetMultipleFileInfoInputSchema, GetMultipleFileInfoOutputSchema, } from '../schemas.js';
-import { buildBatchCompletionSuffix, buildBatchPathContext, buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, createBatchProgressCallbacks, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildBatchCompletionSuffix, buildBatchPathContext, buildFileInfoPayload, buildStructuredError, buildToolErrorResponse, buildToolResponse, createBatchProgressCallbacks, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const GET_MULTIPLE_FILE_INFO_TOOL = {
     name: 'stat_many',
@@ -14,7 +14,6 @@ export const GET_MULTIPLE_FILE_INFO_TOOL = {
     outputSchema: GetMultipleFileInfoOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
     taskSupport: 'optional',
-    nuances: ['Use before read/search when file size/type uncertainty exists.'],
 };
 function formatFileInfoDetail(info) {
     const lines = [
@@ -38,11 +37,13 @@ async function handleGetMultipleFileInfo(args, signal, onProgress) {
     const structuredResults = result.results.map((entry) => ({
         path: entry.path,
         info: entry.info ? buildFileInfoPayload(entry.info) : undefined,
-        error: entry.error,
+        error: entry.error
+            ? buildStructuredError(entry.error, ErrorCode.E_NOT_FOUND, entry.path)
+            : undefined,
     }));
     const text = result.results
         .map((entry) => entry.error
-        ? `${entry.path}: ${entry.error}`
+        ? `${entry.path}: ${buildStructuredError(entry.error, ErrorCode.E_NOT_FOUND, entry.path).message}`
         : entry.info
             ? formatFileInfoDetail(entry.info)
             : entry.path)
@@ -64,6 +65,7 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
         return executeToolWithDiagnostics({
             toolName: 'stat_many',
             extra,
+            outputSchema: GetMultipleFileInfoOutputSchema,
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: primaryPath },
             run: async (signal) => {

package/dist/tools/stat.js

@@ -15,7 +15,6 @@ export const GET_FILE_INFO_TOOL = {
     outputSchema: GetFileInfoOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
     taskSupport: 'forbidden',
-    nuances: ['Use before read/search when file size/type uncertainty exists.'],
 };
 function formatFileInfoDetails(info) {
     const lines = [
@@ -45,6 +44,7 @@ export function registerGetFileInfoTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'stat',
         extra,
+        outputSchema: GetFileInfoOutputSchema,
         timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
         context: { path: args.path },
         run: (signal) => handleGetFileInfo(args, signal),
@@ -58,7 +58,7 @@ export function registerGetFileInfoTool(server, options = {}) {
             if (result.isError)
                 return `🕮 stat: ${name} • failed`;
             const sc = result.structuredContent;
-            if (!sc.ok || !sc.info)
+            if (!sc.info)
                 return `🕮 stat: ${name} • failed`;
             return `🕮 stat: ${sc.info.name} • ${sc.info.type}, ${formatBytes(sc.info.size)}`;
         },

package/dist/tools/tree.js

@@ -14,7 +14,6 @@ export const TREE_TOOL = {
     outputSchema: TreeOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
     taskSupport: 'optional',
-    gotchas: ['`maxDepth=0` returns only the root node.'],
 };
 async function handleTree(args, signal, onProgress) {
     const basePath = resolvePathOrRoot(args.path);
@@ -45,6 +44,7 @@ export function registerTreeTool(server, options = {}) {
         return executeToolWithDiagnostics({
             toolName: 'tree',
             extra,
+            outputSchema: TreeOutputSchema,
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: targetPath },
             run: async (signal) => {