@j0hanz/filesystem-mcp 1.14.0 → 1.14.1

package/dist/tools/search-files.js

@@ -1,4 +1,4 @@
-import * as path from 'node:path';
+import { basename, relative } from 'node:path';
 import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_SEARCH_TIMEOUT_MS, } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { searchFiles } from '../lib/file-operations/search.js';
@@ -17,6 +17,42 @@ export const SEARCH_FILES_TOOL = {
     nuances: ['Respects `.gitignore` unless `includeIgnored=true`.'],
     taskSupport: 'optional',
 };
+function buildTruncatedReason(summary) {
+    if (!summary.truncated)
+        return undefined;
+    if (summary.stoppedReason === 'timeout')
+        return 'timeout';
+    if (summary.stoppedReason === 'maxFiles')
+        return `max files (${summary.filesScanned})`;
+    return `max results (${summary.matched})`;
+}
+function buildRelativeResults(basePath, displayResults) {
+    const relativeResults = [];
+    for (const entry of displayResults) {
+        relativeResults.push({
+            path: relative(basePath, entry.path),
+            size: entry.size,
+            modified: entry.modified?.toISOString(),
+        });
+    }
+    return relativeResults;
+}
+function computeNextCursor(summary, displayResultsCount, cursorOffset) {
+    if (summary.truncated && displayResultsCount > 0) {
+        return encodeOffsetCursor(cursorOffset + displayResultsCount);
+    }
+    return undefined;
+}
+function applySummaryFields(structured, summary, nextCursor) {
+    if (summary.truncated)
+        structured.truncated = true;
+    if (summary.skippedInaccessible)
+        structured.skippedInaccessible = summary.skippedInaccessible;
+    if (summary.stoppedReason)
+        structured.stoppedReason = summary.stoppedReason;
+    if (nextCursor !== undefined)
+        structured.nextCursor = nextCursor;
+}
 async function handleSearchFiles(args, signal, onProgress) {
     const basePath = resolvePathOrRoot(args.path);
     const excludePatterns = args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS;
@@ -28,57 +64,34 @@ async function handleSearchFiles(args, signal, onProgress) {
         includeHidden: args.includeHidden,
         sortBy: args.sortBy,
         respectGitignore: !args.includeIgnored,
-        ...(args.maxDepth !== undefined ? { maxDepth: args.maxDepth } : {}),
-        ...(onProgress ? { onProgress } : {}),
-        ...(signal ? { signal } : {}),
     };
+    if (args.maxDepth !== undefined)
+        searchOptions.maxDepth = args.maxDepth;
+    if (onProgress)
+        searchOptions.onProgress = onProgress;
+    if (signal)
+        searchOptions.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
-        ? encodeOffsetCursor(cursorOffset + displayResults.length)
-        : undefined;
-    const relativeResults = [];
-    for (const entry of displayResults) {
-        relativeResults.push({
-            path: path.relative(result.basePath, entry.path),
-            size: entry.size,
-            modified: entry.modified?.toISOString(),
-        });
-    }
+    let displayResults = allResults;
+    if (cursorOffset > 0)
+        displayResults = allResults.slice(cursorOffset);
+    const nextCursor = computeNextCursor(result.summary, displayResults.length, cursorOffset);
+    const relativeResults = buildRelativeResults(result.basePath, displayResults);
     const structured = {
         ok: true,
         root: basePath,
         results: relativeResults,
         totalMatches: result.summary.matched,
         filesScanned: result.summary.filesScanned,
-        ...(result.summary.truncated
-            ? { truncated: result.summary.truncated }
-            : {}),
-        ...(result.summary.skippedInaccessible
-            ? { skippedInaccessible: result.summary.skippedInaccessible }
-            : {}),
-        ...(result.summary.stoppedReason
-            ? { stoppedReason: result.summary.stoppedReason }
-            : {}),
-        ...(nextCursor !== undefined ? { nextCursor } : {}),
     };
-    let truncatedReason;
-    if (result.summary.truncated) {
-        if (result.summary.stoppedReason === 'timeout') {
-            truncatedReason = 'timeout';
-        }
-        else if (result.summary.stoppedReason === 'maxFiles') {
-            truncatedReason = `max files (${result.summary.filesScanned})`;
-        }
-        else {
-            truncatedReason = `max results (${result.summary.matched})`;
-        }
-    }
+    applySummaryFields(structured, result.summary, nextCursor);
+    const truncatedReason = buildTruncatedReason(result.summary);
     const summaryOptions = {
         truncated: result.summary.truncated,
-        ...(truncatedReason ? { truncatedReason } : {}),
     };
+    if (truncatedReason)
+        summaryOptions.truncatedReason = truncatedReason;
     const textLines = [];
     if (relativeResults.length === 0) {
         textLines.push('No matches');
@@ -103,7 +116,7 @@ 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 rawScopeLabel = args.path ? basename(args.path) : '.';
             const scopeLabel = rawScopeLabel || '.';
             const { pattern } = args;
             const truncatedPattern = truncateProgressPattern(pattern);
@@ -161,7 +174,7 @@ export function registerSearchFilesTool(server, options = {}) {
                 throw error;
             }
         },
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.path),
     });
     const { isInitialized } = options;
     const wrappedHandler = wrapToolHandler(handler, {

package/dist/tools/shared.d.ts

@@ -63,6 +63,9 @@ export interface ToolExtra {
     signal?: AbortSignal;
     _meta?: {
         progressToken?: ProgressToken | undefined;
+        traceparent?: string | undefined;
+        tracestate?: string | undefined;
+        baggage?: string | undefined;
     };
     sendNotification?: (notification: {
         method: 'notifications/progress';

package/dist/tools/shared.js

@@ -1,10 +1,11 @@
-import * as path from 'node:path';
 import { channel } from 'node:diagnostics_channel';
+import { basename } from 'node:path';
 import { z } from 'zod';
+import { createTimedAbortSignal } from '../lib/abort.js';
 import { parseTrueEnvFlag } from '../lib/constants.js';
 import { createDetailedError, ErrorCode, formatDetailedError, getSuggestion, McpError, } from '../lib/errors.js';
-import { createTimedAbortSignal } from '../lib/fs-helpers.js';
-import { withToolDiagnostics } from '../lib/observability.js';
+import { Logger } from '../lib/logger.js';
+import { withToolDiagnostics, } from '../lib/observability.js';
 import { getAllowedDirectories } from '../lib/paths.js';
 import { createBase64JsonCodec } from '../lib/zod-codecs.js';
 export {} from './contract.js';
@@ -12,6 +13,20 @@ const MAX_INLINE_CONTENT_CHARS = parseInt(process.env['FS_CONTEXT_MAX_INLINE_CHA
 const MAX_INLINE_PREVIEW_CHARS = 4_000;
 const PROGRESS_RATE_LIMIT_MS = 50;
 const CONTEXT_DIAGNOSTICS_CHANNEL = channel('filesystem-mcp:context');
+// W3C Trace Context: version-traceid-parentid-traceflags
+const TRACEPARENT_RE = /^[\da-f]{2}-[\da-f]{32}-[\da-f]{16}-[\da-f]{2}$/i;
+function extractTraceContext(meta) {
+    const tp = meta?.traceparent;
+    if (typeof tp !== 'string' || !TRACEPARENT_RE.test(tp))
+        return undefined;
+    return {
+        traceparent: tp,
+        ...(typeof meta?.tracestate === 'string'
+            ? { tracestate: meta.tracestate }
+            : {}),
+        ...(typeof meta?.baggage === 'string' ? { baggage: meta.baggage } : {}),
+    };
+}
 function publishContextDiagnostics(event) {
     if (!CONTEXT_DIAGNOSTICS_CHANNEL.hasSubscribers)
         return;
@@ -45,11 +60,13 @@ function normalizeToolExecution(tool) {
         ? candidate['execution']
         : undefined;
     const executionTaskSupport = existingExecution?.['taskSupport'];
-    const resolvedTaskSupport = isTaskSupportLevel(topLevelTaskSupport)
-        ? topLevelTaskSupport
-        : isTaskSupportLevel(executionTaskSupport)
-            ? executionTaskSupport
-            : undefined;
+    let resolvedTaskSupport;
+    if (isTaskSupportLevel(topLevelTaskSupport)) {
+        resolvedTaskSupport = topLevelTaskSupport;
+    }
+    else if (isTaskSupportLevel(executionTaskSupport)) {
+        resolvedTaskSupport = executionTaskSupport;
+    }
     if (resolvedTaskSupport === undefined && topLevelTaskSupport === undefined) {
         return tool;
     }
@@ -106,6 +123,7 @@ export function maybeExternalizeTextContent(resourceStore, content, params) {
         chars: content.length,
         uri: entry.uri,
     });
+    Logger.debug(`Content externalized: ${params.name} (${content.length} chars) → ${entry.uri}`);
     return {
         entry,
         preview: buildTextPreview(content),
@@ -128,9 +146,12 @@ export function buildResourceLink(params) {
 }
 function resolveDetailedError(error, defaultCode, path) {
     const detailed = createDetailedError(error, path);
-    if (detailed.code === ErrorCode.E_UNKNOWN) {
+    if (detailed.code === ErrorCode.UNKNOWN) {
         detailed.code = defaultCode;
-        detailed.suggestion = getSuggestion(defaultCode);
+        const suggestion = getSuggestion(defaultCode);
+        if (suggestion) {
+            detailed.suggestion = suggestion;
+        }
     }
     return detailed;
 }
@@ -156,13 +177,13 @@ function validateStructuredContent(toolName, outputSchema, structuredContent) {
     if (parsed.success) {
         return parsed.data;
     }
-    throw new McpError(ErrorCode.E_UNKNOWN, `Tool "${toolName}" returned invalid structuredContent.`, undefined, { errors: z.treeifyError(parsed.error) });
+    throw new McpError(ErrorCode.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.`);
+        throw new McpError(ErrorCode.UNKNOWN, `Tool "${toolName}" returned success without structuredContent.`);
     }
     return {
         ...result,
@@ -175,12 +196,20 @@ function parseToolArgs(schema, args) {
     if (parsed.success) {
         return parsed.data;
     }
-    throw new McpError(ErrorCode.E_INVALID_INPUT, `Invalid tool arguments:\n${z.prettifyError(parsed.error)}`, undefined, { errors: z.treeifyError(parsed.error) });
+    throw new McpError(ErrorCode.INVALID_INPUT, `Invalid tool arguments:\n${z.prettifyError(parsed.error)}`);
 }
 export function withValidatedArgs(schema, handler) {
     return async (args, extra) => {
-        const normalizedArgs = parseToolArgs(schema, args);
-        return handler(normalizedArgs, extra);
+        try {
+            const normalizedArgs = parseToolArgs(schema, args);
+            return await handler(normalizedArgs, extra);
+        }
+        catch (error) {
+            if (error instanceof McpError && error.code === ErrorCode.INVALID_INPUT) {
+                return buildToolErrorResponse(error, ErrorCode.INVALID_INPUT);
+            }
+            throw error;
+        }
     };
 }
 function canSendProgress(extra) {
@@ -232,7 +261,7 @@ export function buildFileInfoPayload(info) {
             : {}),
     };
 }
-const NOT_INITIALIZED_ERROR = new McpError(ErrorCode.E_INVALID_INPUT, 'Client not initialized; wait for notifications/initialized');
+const NOT_INITIALIZED_ERROR = new McpError(ErrorCode.INVALID_INPUT, 'Client not initialized; wait for notifications/initialized');
 async function withToolErrorHandling(run, onError) {
     try {
         return await run();
@@ -249,6 +278,7 @@ function getToolSignal(extraSignal, timedSignal) {
     return { signal, cleanup };
 }
 export async function executeToolWithDiagnostics(options) {
+    const traceContext = extractTraceContext(options.extra._meta);
     return withToolDiagnostics(options.toolName, () => withToolErrorHandling(async () => {
         const { signal, cleanup } = getToolSignal(options.extra.signal, options.timedSignal);
         try {
@@ -257,7 +287,10 @@ export async function executeToolWithDiagnostics(options) {
         finally {
             cleanup();
         }
-    }, options.onError), options.context);
+    }, options.onError), {
+        ...options.context,
+        ...(traceContext ? { traceContext } : {}),
+    });
 }
 export function buildToolErrorResponse(error, defaultCode, path) {
     const detailed = resolveDetailedError(error, defaultCode, path);
@@ -269,7 +302,7 @@ export function buildToolErrorResponse(error, defaultCode, path) {
     };
 }
 function buildNotInitializedResult() {
-    return buildToolErrorResponse(NOT_INITIALIZED_ERROR, ErrorCode.E_INVALID_INPUT);
+    return buildToolErrorResponse(NOT_INITIALIZED_ERROR, ErrorCode.INVALID_INPUT);
 }
 async function reportProgress(extra, progress) {
     await updateTaskStoreProgress(extra, progress);
@@ -283,6 +316,10 @@ function formatTaskStatusMessage(progress) {
     }
     return progress.message ?? `${progress.current}`;
 }
+function isBenignTaskStatusUpdateError(error) {
+    return (error instanceof Error &&
+        /Task .*not found|terminal status/iu.test(error.message));
+}
 async function updateTaskStoreProgress(extra, progress) {
     const taskExtra = extra;
     if (typeof taskExtra.taskId === 'string' &&
@@ -294,7 +331,9 @@ async function updateTaskStoreProgress(extra, progress) {
                 await store.updateTaskStatus(taskExtra.taskId, 'working', formatTaskStatusMessage(progress));
             }
             catch (error) {
-                console.error('Failed to update task status message:', error);
+                if (isBenignTaskStatusUpdateError(error))
+                    return;
+                Logger.error('Failed to update task status message:', error);
             }
         }
     }
@@ -315,7 +354,7 @@ async function sendMcpProgressNotification(extra, progress) {
             });
         }
         catch (error) {
-            console.error('Failed to send progress notification:', error);
+            Logger.error('Failed to send progress notification:', error);
         }
     }
 }
@@ -480,14 +519,14 @@ export function resolvePathOrRoot(pathValue) {
         return pathValue;
     const roots = getAllowedDirectories();
     if (roots.length === 0) {
-        throw new McpError(ErrorCode.E_ACCESS_DENIED, 'No workspace roots configured. Use the roots tool to check, or configure roots via the MCP Roots protocol (or start with --allow-cwd / CLI directories).');
+        throw new McpError(ErrorCode.ACCESS_DENIED, 'No roots configured. Use roots tool, --allow-cwd, or MCP Roots protocol.');
     }
     if (roots.length > 1) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Multiple workspace roots configured. Provide an explicit path to disambiguate.');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Multiple roots configured. Provide an explicit path.');
     }
     const root = roots[0];
     if (!root) {
-        throw new McpError(ErrorCode.E_ACCESS_DENIED, 'Workspace root is unexpectedly undefined');
+        throw new McpError(ErrorCode.ACCESS_DENIED, 'Workspace root is unexpectedly undefined');
     }
     return root;
 }
@@ -505,14 +544,17 @@ export function decodeOffsetCursor(cursor) {
     catch {
         // fall through to throw
     }
-    throw new McpError(ErrorCode.E_INVALID_INPUT, `Invalid cursor: the cursor value is malformed or corrupted. Request the first page without a cursor.`);
+    throw new McpError(ErrorCode.INVALID_INPUT, `Invalid cursor. Request the first page without a cursor.`);
 }
 export function buildBatchPathContext(paths, unitLabel = 'paths') {
     const normalizedLabel = paths.length === 1 ? unitLabel.replace(/s$/i, '') : unitLabel;
-    const first = path.basename(paths[0] ?? '');
-    const extraPaths = paths.length > 1
-        ? `, ${path.basename(paths[1] ?? '')}${paths.length > 2 ? '…' : ''}`
-        : '';
+    const first = basename(paths[0] ?? '');
+    let extraPaths = '';
+    if (paths.length > 1) {
+        const secondPath = basename(paths[1] ?? '');
+        const ellipsis = paths.length > 2 ? '…' : '';
+        extraPaths = `, ${secondPath}${ellipsis}`;
+    }
     return `${paths.length} ${normalizedLabel} [${first}${extraPaths}]`;
 }
 export function truncateProgressPattern(pattern, maxLength = 40) {

package/dist/tools/stat-many.js

@@ -38,15 +38,19 @@ async function handleGetMultipleFileInfo(args, signal, onProgress) {
         path: entry.path,
         info: entry.info ? buildFileInfoPayload(entry.info) : undefined,
         error: entry.error
-            ? buildStructuredError(entry.error, ErrorCode.E_NOT_FOUND, entry.path)
+            ? buildStructuredError(entry.error, ErrorCode.NOT_FOUND, entry.path)
             : undefined,
     }));
     const text = result.results
-        .map((entry) => entry.error
-        ? `${entry.path}: ${buildStructuredError(entry.error, ErrorCode.E_NOT_FOUND, entry.path).message}`
-        : entry.info
-            ? formatFileInfoDetail(entry.info)
-            : entry.path)
+        .map((entry) => {
+        if (entry.error) {
+            return `${entry.path}: ${buildStructuredError(entry.error, ErrorCode.NOT_FOUND, entry.path).message}`;
+        }
+        if (entry.info) {
+            return formatFileInfoDetail(entry.info);
+        }
+        return entry.path;
+    })
         .join('\n\n');
     const structured = {
         ok: true,
@@ -90,7 +94,7 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
                     throw error;
                 }
             },
-            onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, primaryPath),
+            onError: (error) => buildToolErrorResponse(error, ErrorCode.NOT_FOUND, primaryPath),
         });
     };
     const wrappedHandler = wrapToolHandler(handler, {

package/dist/tools/stat.js

@@ -1,4 +1,4 @@
-import * as path from 'node:path';
+import { basename } from 'node:path';
 import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { getFileInfo } from '../lib/file-operations/metadata.js';
@@ -48,13 +48,13 @@ export function registerGetFileInfoTool(server, options = {}) {
         timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
         context: { path: args.path },
         run: (signal) => handleGetFileInfo(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, args.path),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.NOT_FOUND, args.path),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => `🕮 stat: ${path.basename(args.path)}`,
+        progressMessage: (args) => `🕮 stat: ${basename(args.path)}`,
         completionMessage: (args, result) => {
-            const name = path.basename(args.path);
+            const name = basename(args.path);
             if (result.isError)
                 return `🕮 stat: ${name} • failed`;
             const sc = result.structuredContent;

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

@@ -2,20 +2,21 @@ import type { ToolTaskHandler } from '@modelcontextprotocol/sdk/experimental/tas
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { AnySchema, SchemaOutput, ShapeOutput, ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 import type { RequestTaskStore } from '@modelcontextprotocol/sdk/shared/protocol.js';
-import type { IconInfo, ToolExtra, ToolResult } from './shared.js';
+import { type IconInfo, type ToolExtra, type ToolResult } from './shared.js';
 type TaskToolExtra = ToolExtra & {
     taskId?: string;
     taskStore?: RequestTaskStore;
     taskRequestedTtl?: number | null;
 };
-type ToolArgs<Args extends ZodRawShapeCompat | AnySchema | undefined> = Args extends ZodRawShapeCompat ? ShapeOutput<Args> : Args extends AnySchema ? SchemaOutput<Args> : undefined;
-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?: {
+export type ToolSchema = ZodRawShapeCompat | AnySchema | undefined;
+type ToolArgs<Args extends ToolSchema> = Args extends ZodRawShapeCompat ? ShapeOutput<Args> : Args extends AnySchema ? SchemaOutput<Args> : undefined;
+export declare function registerToolTaskIfAvailable<Args extends ToolSchema, Result>(server: McpServer, toolName: string, toolDef: object, run: (args: ToolArgs<Args>, extra: TaskToolExtra) => Promise<ToolResult<Result>>, iconInfo: IconInfo | undefined, guard?: () => boolean): boolean;
+interface TaskHandlerOptions {
     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>;
+    cancelPollMs?: number;
+    pollIntervalMs?: number;
+}
+export declare function createToolTaskHandler<Result>(run: (args: undefined, extra: TaskToolExtra) => Promise<ToolResult<Result>>, options?: TaskHandlerOptions): ToolTaskHandler;
+export declare function createToolTaskHandler<Args extends ZodRawShapeCompat | AnySchema, Result>(run: (args: ToolArgs<Args>, extra: TaskToolExtra) => Promise<ToolResult<Result>>, options?: TaskHandlerOptions): ToolTaskHandler<Args>;
 export {};