@j0hanz/filesystem-mcp 1.2.4 → 1.3.1

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

@@ -10,7 +10,8 @@ import { validateExistingPath, validatePathForWrite, } from '../lib/path-validat
 import { SearchAndReplaceInputSchema, SearchAndReplaceOutputSchema, } from '../schemas.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 = {
+export const SEARCH_AND_REPLACE_TOOL = {
+    name: 'search_and_replace',
     title: 'Search and Replace',
     description: 'Search and replace text across multiple files matching a glob pattern. ' +
         'Replaces ALL occurrences in each file (unlike `edit` which replaces only the first). ' +
@@ -20,6 +21,12 @@ const SEARCH_AND_REPLACE_TOOL = {
     inputSchema: SearchAndReplaceInputSchema,
     outputSchema: SearchAndReplaceOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    gotchas: [
+        'Literal mode is default; `isRegex=true` enables RE2 + capture replacements (`$1`, `$2`).',
+    ],
+    nuances: [
+        'Changed-file sample and failure sample are capped/truncated in output.',
+    ],
 };
 const MAX_FAILURES = 20;
 const REPLACE_CONCURRENCY = Math.min(PARALLEL_CONCURRENCY, 8);
@@ -189,8 +196,8 @@ async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
     const entries = globEntries({
         cwd: root,
         pattern: args.filePattern,
-        excludePatterns: DEFAULT_EXCLUDE_PATTERNS,
-        includeHidden: false,
+        excludePatterns: args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS,
+        includeHidden: args.includeHidden ?? false,
         baseNameMatch: false,
         caseSensitiveMatch: true, // Default to sensitive for file paths
         followSymbolicLinks: false,
@@ -279,11 +286,11 @@ export function registerSearchAndReplaceTool(server, options = {}) {
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
     const { isInitialized } = options;
-    const validatedHandler = withValidatedArgs(SearchAndReplaceInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: isInitialized,
     });
-    if (registerToolTaskIfAvailable(server, 'search_and_replace', SEARCH_AND_REPLACE_TOOL, wrappedHandler, options.iconInfo, isInitialized))
+    const validatedHandler = withValidatedArgs(SearchAndReplaceInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'search_and_replace', SEARCH_AND_REPLACE_TOOL, validatedHandler, options.iconInfo, isInitialized))
         return;
-    server.registerTool('search_and_replace', withDefaultIcons({ ...SEARCH_AND_REPLACE_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('search_and_replace', withDefaultIcons({ ...SEARCH_AND_REPLACE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/roots.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_ALLOWED_DIRECTORIES_TOOL: ToolContract;
 export declare function registerListAllowedDirectoriesTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/roots.js

@@ -3,7 +3,8 @@ 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, withValidatedArgs, wrapToolHandler, } from './shared.js';
-const LIST_ALLOWED_DIRECTORIES_TOOL = {
+export const LIST_ALLOWED_DIRECTORIES_TOOL = {
+    name: 'roots',
     title: 'Workspace Roots',
     description: 'List the workspace roots this server can access. ' +
         'Call this first to see available directories. ' +
@@ -11,6 +12,7 @@ const LIST_ALLOWED_DIRECTORIES_TOOL = {
     inputSchema: ListAllowedDirectoriesInputSchema,
     outputSchema: ListAllowedDirectoriesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: ['Other tools are constrained to these roots.'],
 };
 function buildTextRoots(dirs) {
     if (dirs.length === 0) {
@@ -38,8 +40,7 @@ export function registerListAllowedDirectoriesTool(server, options = {}) {
         run: () => handleListAllowedDirectories(),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN),
     });
-    const validatedHandler = withValidatedArgs(ListAllowedDirectoriesInputSchema, handler);
-    server.registerTool('roots', withDefaultIcons({ ...LIST_ALLOWED_DIRECTORIES_TOOL }, options.iconInfo), wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: () => '≣ roots',
         completionMessage: (_args, result) => {
@@ -51,5 +52,7 @@ export function registerListAllowedDirectoriesTool(server, options = {}) {
             const count = sc.rootsCount ?? 0;
             return `≣ roots • ${count} ${count === 1 ? 'root' : 'roots'}`;
         },
-    }));
+    });
+    const validatedHandler = withValidatedArgs(ListAllowedDirectoriesInputSchema, wrappedHandler);
+    server.registerTool('roots', withDefaultIcons({ ...LIST_ALLOWED_DIRECTORIES_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/search-content.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_CONTENT_TOOL: ToolContract;
 export declare function registerSearchContentTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/search-content.js

@@ -7,8 +7,9 @@ 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, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const MAX_INLINE_MATCHES = 50;
-const SEARCH_CONTENT_TOOL = {
+const MAX_INLINE_MATCHES = parseInt(process.env['FS_CONTEXT_MAX_INLINE_MATCHES'] ?? '', 10) || 50;
+export const SEARCH_CONTENT_TOOL = {
+    name: 'grep',
     title: 'Search Content',
     description: 'Search for text within file contents (grep-like). ' +
         'Returns matching lines. ' +
@@ -18,6 +19,13 @@ const SEARCH_CONTENT_TOOL = {
     inputSchema: SearchContentInputSchema,
     outputSchema: SearchContentOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: [
+        'Inline match rows are capped (first 50); full structured results are externalized via `resourceUri`.',
+        'Skips binary and oversized files.',
+    ],
+    gotchas: [
+        'Inline match rows are capped (first 50); full structured results are externalized via `resourceUri`.',
+    ],
 };
 function assertValidRegexPattern(pattern) {
     try {
@@ -261,11 +269,11 @@ export function registerSearchContentTool(server, options = {}) {
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path ?? '.'),
     });
     const { isInitialized } = options;
-    const validatedHandler = withValidatedArgs(SearchContentInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: isInitialized,
     });
-    if (registerToolTaskIfAvailable(server, 'grep', SEARCH_CONTENT_TOOL, wrappedHandler, options.iconInfo, isInitialized))
+    const validatedHandler = withValidatedArgs(SearchContentInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'grep', SEARCH_CONTENT_TOOL, validatedHandler, options.iconInfo, isInitialized))
         return;
-    server.registerTool('grep', withDefaultIcons({ ...SEARCH_CONTENT_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('grep', withDefaultIcons({ ...SEARCH_CONTENT_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/search-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_FILES_TOOL: ToolContract;
 export declare function registerSearchFilesTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/search-files.js

@@ -6,7 +6,26 @@ 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, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const SEARCH_FILES_TOOL = {
+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;
+}
+export const SEARCH_FILES_TOOL = {
+    name: 'find',
     title: 'Find Files',
     description: 'Find files by glob pattern (e.g., **/*.ts). ' +
         'Returns a list of matching files with metadata. ' +
@@ -15,12 +34,19 @@ 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.',
+    ],
 };
 async function handleSearchFiles(args, signal, onProgress) {
     const basePath = resolvePathOrRoot(args.path);
     const excludePatterns = args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS;
+    const cursorOffset = args.cursor !== undefined ? decodeCursor(args.cursor) : 0;
+    const pageSize = args.maxResults;
+    const fetchMax = cursorOffset + pageSize;
     const searchOptions = {
-        maxResults: args.maxResults,
+        maxResults: fetchMax,
         includeHidden: args.includeHidden,
         sortBy: args.sortBy,
         respectGitignore: !args.includeIgnored,
@@ -29,8 +55,13 @@ async function handleSearchFiles(args, signal, onProgress) {
         ...(signal ? { signal } : {}),
     };
     const result = await searchFiles(basePath, args.pattern, excludePatterns, searchOptions);
+    const allResults = result.results;
+    const displayResults = cursorOffset > 0 ? allResults.slice(cursorOffset) : allResults;
+    const nextCursor = result.summary.truncated && displayResults.length > 0
+        ? encodeCursor(cursorOffset + displayResults.length)
+        : undefined;
     const relativeResults = [];
-    for (const entry of result.results) {
+    for (const entry of displayResults) {
         relativeResults.push({
             path: path.relative(result.basePath, entry.path),
             size: entry.size,
@@ -53,6 +84,7 @@ async function handleSearchFiles(args, signal, onProgress) {
         ...(result.summary.stoppedReason
             ? { stoppedReason: result.summary.stoppedReason }
             : {}),
+        ...(nextCursor !== undefined ? { nextCursor } : {}),
     };
     let truncatedReason;
     if (result.summary.truncated) {
@@ -152,11 +184,11 @@ export function registerSearchFilesTool(server, options = {}) {
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
     const { isInitialized } = options;
-    const validatedHandler = withValidatedArgs(SearchFilesInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: isInitialized,
     });
-    if (registerToolTaskIfAvailable(server, 'find', SEARCH_FILES_TOOL, wrappedHandler, options.iconInfo, isInitialized))
+    const validatedHandler = withValidatedArgs(SearchFilesInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'find', SEARCH_FILES_TOOL, validatedHandler, options.iconInfo, isInitialized))
         return;
-    server.registerTool('find', withDefaultIcons({ ...SEARCH_FILES_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('find', withDefaultIcons({ ...SEARCH_FILES_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/shared.d.ts

@@ -4,6 +4,7 @@ import type { FileInfo } from '../config.js';
 import { ErrorCode } from '../lib/errors.js';
 import type { ResourceStore } from '../lib/resource-store.js';
 import type { ToolErrorResponseSchema } from '../schemas.js';
+export { type ToolContract } from './contract.js';
 export declare const READ_ONLY_TOOL_ANNOTATIONS: {
     readonly readOnlyHint: true;
     readonly idempotentHint: true;
@@ -48,7 +49,7 @@ interface ToolErrorResponse extends Record<string, unknown> {
 }
 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>>;
+export declare function withValidatedArgs<Args, Result>(schema: z.ZodType<Args>, handler: (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>): (args: unknown, extra: ToolExtra) => Promise<ToolResult<Result>>;
 type ProgressToken = string | number;
 export interface ToolExtra {
     signal?: AbortSignal;
@@ -116,4 +117,3 @@ export declare function wrapToolHandler<Args, Result>(handler: (args: Args, extr
     completionMessage?: (args: Args, result: ToolResult<Result>) => string | undefined;
 }): (args: Args, extra?: ToolExtra) => Promise<ToolResult<Result>>;
 export declare function resolvePathOrRoot(pathValue: string | undefined): string;
-export {};

package/dist/tools/shared.js

@@ -1,12 +1,20 @@
+import { channel } from 'node:diagnostics_channel';
 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';
 import { getAllowedDirectories } from '../lib/path-validation.js';
-const MAX_INLINE_CONTENT_CHARS = 20_000;
+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;
 const PROGRESS_RATE_LIMIT_MS = 50;
 const TRUE_ENV_VALUES = new Set(['1', 'true', 'yes']);
+const CONTEXT_DIAGNOSTICS_CHANNEL = channel('filesystem-mcp:context');
+function publishContextDiagnostics(event) {
+    if (!CONTEXT_DIAGNOSTICS_CHANNEL.hasSubscribers)
+        return;
+    CONTEXT_DIAGNOSTICS_CHANNEL.publish(event);
+}
 export const READ_ONLY_TOOL_ANNOTATIONS = {
     readOnlyHint: true,
     idempotentHint: true,
@@ -61,6 +69,13 @@ export function maybeExternalizeTextContent(resourceStore, content, params) {
         ...(params.mimeType !== undefined ? { mimeType: params.mimeType } : {}),
         text: content,
     });
+    publishContextDiagnostics({
+        phase: 'externalize_text',
+        name: params.name,
+        ...(params.mimeType !== undefined ? { mimeType: params.mimeType } : {}),
+        chars: content.length,
+        uri: entry.uri,
+    });
     return {
         entry,
         preview: buildTextPreview(content),

package/dist/tools/stat-many.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 GET_MULTIPLE_FILE_INFO_TOOL: ToolContract;
 export declare function registerGetMultipleFileInfoTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/stat-many.js

@@ -6,12 +6,14 @@ 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, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const GET_MULTIPLE_FILE_INFO_TOOL = {
+export const GET_MULTIPLE_FILE_INFO_TOOL = {
+    name: 'stat_many',
     title: 'Get Multiple File Info',
     description: 'Get metadata for multiple files or directories in one request.',
     inputSchema: GetMultipleFileInfoInputSchema,
     outputSchema: GetMultipleFileInfoOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: ['Use before read/search when file size/type uncertainty exists.'],
 };
 function formatFileInfoDetail(info) {
     const lines = [
@@ -73,8 +75,7 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
             onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, primaryPath),
         });
     };
-    const validatedHandler = withValidatedArgs(GetMultipleFileInfoInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const first = path.basename(args.paths[0] ?? '');
@@ -95,7 +96,8 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
             return `🕮 stat_many: ${total} OK`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'stat_many', GET_MULTIPLE_FILE_INFO_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(GetMultipleFileInfoInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'stat_many', GET_MULTIPLE_FILE_INFO_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('stat_many', withDefaultIcons({ ...GET_MULTIPLE_FILE_INFO_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('stat_many', withDefaultIcons({ ...GET_MULTIPLE_FILE_INFO_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/stat.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 GET_FILE_INFO_TOOL: ToolContract;
 export declare function registerGetFileInfoTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/stat.js

@@ -5,12 +5,14 @@ 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, withValidatedArgs, wrapToolHandler, } from './shared.js';
-const GET_FILE_INFO_TOOL = {
+export const GET_FILE_INFO_TOOL = {
+    name: 'stat',
     title: 'Get File Info',
     description: 'Get metadata (size, modified time, permissions, mime type) for a file or directory.',
     inputSchema: GetFileInfoInputSchema,
     outputSchema: GetFileInfoOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: ['Use before read/search when file size/type uncertainty exists.'],
 };
 function formatFileInfoDetails(info) {
     const lines = [
@@ -45,8 +47,7 @@ export function registerGetFileInfoTool(server, options = {}) {
         run: (signal) => handleGetFileInfo(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, args.path),
     });
-    const validatedHandler = withValidatedArgs(GetFileInfoInputSchema, handler);
-    server.registerTool('stat', withDefaultIcons({ ...GET_FILE_INFO_TOOL }, options.iconInfo), wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => `🕮 stat: ${path.basename(args.path)}`,
         completionMessage: (args, result) => {
@@ -58,5 +59,7 @@ export function registerGetFileInfoTool(server, options = {}) {
                 return `🕮 stat: ${name} • failed`;
             return `🕮 stat: ${sc.info.name} • ${sc.info.type}, ${formatBytes(sc.info.size)}`;
         },
-    }));
+    });
+    const validatedHandler = withValidatedArgs(GetFileInfoInputSchema, wrappedHandler);
+    server.registerTool('stat', withDefaultIcons({ ...GET_FILE_INFO_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/task-support.d.ts

@@ -18,8 +18,10 @@ export declare function tryRegisterToolTask<Args extends ZodRawShapeCompat | Any
 export declare function registerToolTaskIfAvailable<Args extends ZodRawShapeCompat | AnySchema | undefined, Result>(server: McpServer, toolName: string, toolDef: object, run: (args: ToolArgs<Args>, extra: TaskToolExtra) => Promise<ToolResult<Result>>, iconInfo: IconInfo | undefined, guard?: () => boolean): boolean;
 export declare function createToolTaskHandler<Result>(run: (args: undefined, extra: TaskToolExtra) => Promise<ToolResult<Result>>, options?: {
     guard?: () => boolean;
+    toolName?: string;
 }): ToolTaskHandler;
 export declare function createToolTaskHandler<Args extends ZodRawShapeCompat | AnySchema, Result>(run: (args: ToolArgs<Args>, extra: TaskToolExtra) => Promise<ToolResult<Result>>, options?: {
     guard?: () => boolean;
+    toolName?: string;
 }): ToolTaskHandler<Args>;
 export {};

package/dist/tools/task-support.js

@@ -1,3 +1,4 @@
+import { channel } from 'node:diagnostics_channel';
 import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
 import { ErrorCode, McpError } from '../lib/errors.js';
 import { isRecord } from '../lib/type-guards.js';
@@ -43,6 +44,12 @@ function hasTaskToolCapability(server) {
 }
 const RELATED_TASK_META_KEY = 'io.modelcontextprotocol/related-task';
 const TASK_STATUS_NOTIFICATION_METHOD = 'notifications/tasks/status';
+const TASK_DIAGNOSTICS_CHANNEL = channel('filesystem-mcp:tasks');
+function publishTaskDiagnostics(event) {
+    if (!TASK_DIAGNOSTICS_CHANNEL.hasSubscribers)
+        return;
+    TASK_DIAGNOSTICS_CHANNEL.publish(event);
+}
 function isRequestTaskStore(value) {
     if (!isRecord(value))
         return false;
@@ -174,7 +181,7 @@ function buildTaskStatusNotificationParams(task) {
         params.statusMessage = task.statusMessage;
     return params;
 }
-async function notifyTaskStatusIfPossible(extra, taskStore, taskId) {
+async function notifyTaskStatusIfPossible(extra, taskStore, taskId, toolName) {
     const { sendNotification } = extra;
     if (typeof sendNotification !== 'function')
         return;
@@ -186,8 +193,19 @@ async function notifyTaskStatusIfPossible(extra, taskStore, taskId) {
             method: TASK_STATUS_NOTIFICATION_METHOD,
             params: buildTaskStatusNotificationParams(normalized),
         });
+        publishTaskDiagnostics({
+            phase: 'task_status_notified',
+            taskId,
+            status: normalized.status,
+            ...(toolName !== undefined ? { toolName } : {}),
+        });
     }
     catch {
+        publishTaskDiagnostics({
+            phase: 'task_status_notify_failed',
+            taskId,
+            ...(toolName !== undefined ? { toolName } : {}),
+        });
         // Never fail task execution because status notifications are optional.
     }
 }
@@ -206,6 +224,14 @@ function getTaskId(extra) {
 function isErrorResult(result) {
     return 'isError' in result && result.isError === true;
 }
+// Strips structuredContent from a tool result if present, without modifying the original object.  This is used when storing error results as 'completed' to prevent client-side output schema validation errors, while still allowing the human-readable error message in content[0].text to be returned to clients.
+function withoutStructuredContent(result) {
+    if (!Object.hasOwn(result, 'structuredContent'))
+        return result;
+    const stripped = { ...result };
+    delete stripped['structuredContent'];
+    return stripped;
+}
 const TERMINAL_TASK_STATUSES = new Set([
     'completed',
     'failed',
@@ -234,18 +260,33 @@ async function tryStoreTaskResult(taskStore, taskId, status, result) {
         throw error;
     }
 }
-async function runTaskInBackground(run, args, extra, taskStore, taskId) {
+async function runTaskInBackground(run, args, extra, taskStore, taskId, toolName) {
     try {
-        const result = maybeStripStructuredContentFromResult(await run(args, extra));
-        const status = isErrorResult(result) ? 'failed' : 'completed';
+        const rawResult = await run(args, extra);
+        const status = isCancelledToolResult(rawResult) ? 'failed' : 'completed';
+        const result = isErrorResult(rawResult) && status === 'completed'
+            ? withoutStructuredContent(rawResult)
+            : maybeStripStructuredContentFromResult(rawResult);
         await tryStoreTaskResult(taskStore, taskId, status, result);
-        await notifyTaskStatusIfPossible(extra, taskStore, taskId);
+        publishTaskDiagnostics({
+            phase: 'task_result_stored',
+            taskId,
+            status,
+            ...(toolName !== undefined ? { toolName } : {}),
+        });
+        await notifyTaskStatusIfPossible(extra, taskStore, taskId, toolName);
     }
     catch (error) {
         const fallback = maybeStripStructuredContentFromResult(buildToolErrorResponse(error, ErrorCode.E_UNKNOWN));
         try {
             await tryStoreTaskResult(taskStore, taskId, 'failed', fallback);
-            await notifyTaskStatusIfPossible(extra, taskStore, taskId);
+            publishTaskDiagnostics({
+                phase: 'task_result_stored',
+                taskId,
+                status: 'failed',
+                ...(toolName !== undefined ? { toolName } : {}),
+            });
+            await notifyTaskStatusIfPossible(extra, taskStore, taskId, toolName);
         }
         catch (innerError) {
             console.error(`Failed to store task failure result for task ${taskId}:`, innerError);
@@ -267,7 +308,10 @@ export function tryRegisterToolTask(server, toolName, toolDef, taskHandler, icon
     return true;
 }
 export function registerToolTaskIfAvailable(server, toolName, toolDef, run, iconInfo, guard) {
-    const taskOptions = guard ? { guard } : undefined;
+    const taskOptions = {
+        ...(guard ? { guard } : {}),
+        toolName,
+    };
     return tryRegisterToolTask(server, toolName, toolDef, createToolTaskHandler(run, taskOptions), iconInfo);
 }
 export function createToolTaskHandler(run, options) {
@@ -281,13 +325,21 @@ export function createToolTaskHandler(run, options) {
         const task = await taskStore.createTask({
             ttl: extra.taskRequestedTtl ?? null,
         });
+        publishTaskDiagnostics({
+            phase: 'task_created',
+            taskId: task.taskId,
+            status: task.status,
+            ...(options?.toolName !== undefined
+                ? { toolName: options.toolName }
+                : {}),
+        });
         const taskExtra = {
             ...extra,
             taskStore,
             taskId: task.taskId,
         };
-        void notifyTaskStatusIfPossible(taskExtra, taskStore, task.taskId);
-        void runTaskInBackground(run, args, taskExtra, taskStore, task.taskId);
+        void notifyTaskStatusIfPossible(taskExtra, taskStore, task.taskId, options?.toolName);
+        void runTaskInBackground(run, args, taskExtra, taskStore, task.taskId, options?.toolName);
         return { task };
     });
     const getTask = (async (argsOrExtra, maybeExtra) => {

package/dist/tools/tree.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 TREE_TOOL: ToolContract;
 export declare function registerTreeTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/tree.js

@@ -5,7 +5,8 @@ import { formatTreeAscii, treeDirectory } from '../lib/file-operations/tree.js';
 import { TreeInputSchema, TreeOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const TREE_TOOL = {
+export const TREE_TOOL = {
+    name: 'tree',
     title: 'Tree',
     description: 'Render a directory tree (bounded recursion). ' +
         'Returns an ASCII tree for quick scanning and a structured JSON tree for programmatic use. ' +
@@ -13,6 +14,7 @@ const TREE_TOOL = {
     inputSchema: TreeInputSchema,
     outputSchema: TreeOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    gotchas: ['`maxDepth=0` returns only the root node.'],
 };
 async function handleTree(args, signal) {
     const basePath = resolvePathOrRoot(args.path);
@@ -47,8 +49,7 @@ export function registerTreeTool(server, options = {}) {
             onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_DIRECTORY, targetPath),
         });
     };
-    const validatedHandler = withValidatedArgs(TreeInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             if (args.path) {
@@ -69,7 +70,8 @@ export function registerTreeTool(server, options = {}) {
             return `≣ tree: ${base} • ${count} ${count === 1 ? 'entry' : 'entries'}`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'tree', TREE_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(TreeInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'tree', TREE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('tree', withDefaultIcons({ ...TREE_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('tree', withDefaultIcons({ ...TREE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/write-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 WRITE_FILE_TOOL: ToolContract;
 export declare function registerWriteFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/write-file.js

@@ -6,12 +6,19 @@ import { validatePathForWrite } from '../lib/path-validation.js';
 import { WriteFileInputSchema, WriteFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const WRITE_FILE_TOOL = {
+export const WRITE_FILE_TOOL = {
+    name: 'write',
     title: 'Write File',
     description: 'Write content to a file. Creates the file if it does not exist.',
     inputSchema: WriteFileInputSchema,
     outputSchema: WriteFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    nuances: [
+        'Creates parent directories automatically; overwrites existing content.',
+    ],
+    gotchas: [
+        'Creates parent directories automatically; overwrites existing content.',
+    ],
 };
 async function handleWriteFile(args, signal) {
     const validPath = await validatePathForWrite(args.path, signal);
@@ -34,8 +41,7 @@ export function registerWriteFileTool(server, options = {}) {
         run: (signal) => handleWriteFile(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
-    const validatedHandler = withValidatedArgs(WriteFileInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => `🛠 write: ${path.basename(args.path)} [${args.content.length} chars]`,
         completionMessage: (args, result) => {
@@ -48,7 +54,8 @@ export function registerWriteFileTool(server, options = {}) {
             return `🛠 write: ${name} • ${sc.bytesWritten ?? 0} bytes`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'write', WRITE_FILE_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(WriteFileInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'write', WRITE_FILE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('write', withDefaultIcons({ ...WRITE_FILE_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('write', withDefaultIcons({ ...WRITE_FILE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools.d.ts

@@ -1,4 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ToolContract } from './tools/contract.js';
 import type { ToolRegistrationOptions } from './tools/shared.js';
 export { buildToolErrorResponse, buildToolResponse } from './tools/shared.js';
+export declare const ALL_TOOLS: ToolContract[];
 export declare function registerAllTools(server: McpServer, options?: ToolRegistrationOptions): void;