@j0hanz/filesystem-mcp 1.13.2 → 1.14.1

package/dist/completions.js

@@ -1,6 +1,6 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
 import { CompleteRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { readdir, stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, parse, resolve, sep, } from 'node:path';
 import { getAllowedDirectories, isPathWithinDirectories, normalizePath, toPosixPath, } from './lib/paths.js';
 import { isRecord } from './lib/utils.js';
 import { getSortedToolContracts } from './resources/tool-info.js';
@@ -191,21 +191,21 @@ function rememberCompletionCacheValue(cache, key, value) {
     }
 }
 function hasTrailingSeparator(value) {
-    return (value.endsWith(path.sep) || value.endsWith('/') || value.endsWith('\\'));
+    return value.endsWith(sep) || value.endsWith('/') || value.endsWith('\\');
 }
 function isAbsolutePathInput(value) {
-    return (path.isAbsolute(value) ||
+    return (isAbsolute(value) ||
         /^[A-Za-z]:[\\/]/u.test(value) ||
         value.startsWith('\\\\'));
 }
 function resolveFromBase(base, rawValue, trailingSeparator) {
-    const normalizedValue = normalizePath(path.resolve(base, rawValue));
+    const normalizedValue = normalizePath(resolve(base, rawValue));
     if (trailingSeparator) {
         return { searchDir: normalizedValue, prefix: '' };
     }
     return {
-        searchDir: path.dirname(normalizedValue),
-        prefix: path.basename(normalizedValue),
+        searchDir: dirname(normalizedValue),
+        prefix: basename(normalizedValue),
     };
 }
 function resolveNamedRootContext(currentValue, allowed) {
@@ -225,18 +225,18 @@ function resolveNamedRootPath(value, allowed) {
     const root = findAllowedRootByName(parsed.rootName, allowed);
     if (!root)
         return undefined;
-    return normalizePath(path.resolve(root, parsed.remainder));
+    return normalizePath(resolve(root, parsed.remainder));
 }
 function parseNamedRootInput(value) {
     const normalizedInput = toPosixPath(value);
     const [rootName, ...rest] = normalizedInput.split('/');
     if (!rootName)
         return undefined;
-    return { rootName, remainder: rest.join(path.sep) };
+    return { rootName, remainder: rest.join(sep) };
 }
 function findAllowedRootByName(rootName, allowed) {
     const normalizedRootName = rootName.toLowerCase();
-    return allowed.find((candidate) => path.basename(candidate).toLowerCase() === normalizedRootName);
+    return allowed.find((candidate) => basename(candidate).toLowerCase() === normalizedRootName);
 }
 function chooseContextKeys(argumentName) {
     const normalized = argumentName.toLowerCase();
@@ -263,7 +263,7 @@ function resolveContextCandidatePath(candidate, allowed) {
         const base = allowed[0];
         if (!base)
             return undefined;
-        return normalizePath(path.resolve(base, candidate));
+        return normalizePath(resolve(base, candidate));
     }
     return resolveNamedRootPath(candidate, allowed);
 }
@@ -271,14 +271,14 @@ async function toAllowedContextDirectory(resolved, allowed) {
     if (!isPathWithinDirectories(resolved, allowed))
         return undefined;
     try {
-        const stats = await fs.stat(resolved);
+        const stats = await stat(resolved);
         if (stats.isDirectory())
             return resolved;
     }
     catch {
         // Fall back to parent path best-effort resolution.
     }
-    const parent = path.dirname(resolved);
+    const parent = dirname(resolved);
     return isPathWithinDirectories(parent, allowed) ? parent : undefined;
 }
 async function resolveContextBaseDirectory(argumentName, contextArguments, allowed) {
@@ -300,7 +300,7 @@ async function resolveContextBaseDirectory(argumentName, contextArguments, allow
     return undefined;
 }
 function withDirectorySeparator(value) {
-    return value.endsWith(path.sep) ? value : `${value}${path.sep}`;
+    return value.endsWith(sep) ? value : `${value}${sep}`;
 }
 function buildCompletionResult(values) {
     return {
@@ -314,8 +314,8 @@ function buildCompletionResponse(result) {
 }
 function sortCompletionMatches(matches) {
     matches.sort((left, right) => {
-        const leftIsDir = left.endsWith(path.sep);
-        const rightIsDir = right.endsWith(path.sep);
+        const leftIsDir = left.endsWith(sep);
+        const rightIsDir = right.endsWith(sep);
         if (leftIsDir && !rightIsDir)
             return -1;
         if (!leftIsDir && rightIsDir)
@@ -350,7 +350,7 @@ function collectAllowedRoots(allowed, predicate) {
 function getSearchContext(currentValue, allowed, contextBase) {
     const trailingSeparator = hasTrailingSeparator(currentValue);
     if (isAbsolutePathInput(currentValue)) {
-        return resolveFromBase(path.parse(currentValue).root || path.sep, currentValue, trailingSeparator);
+        return resolveFromBase(parse(currentValue).root || sep, currentValue, trailingSeparator);
     }
     const namedRootContext = resolveNamedRootContext(currentValue, allowed);
     if (namedRootContext) {
@@ -376,13 +376,13 @@ async function findMatchesInDirectory(searchDir, prefix, allowed) {
         return matches;
     }
     try {
-        const entries = await fs.readdir(searchDir, { withFileTypes: true });
+        const entries = await readdir(searchDir, { withFileTypes: true });
         const lowerPrefix = prefix.toLowerCase();
         for (const entry of entries) {
             if (entry.name.toLowerCase().startsWith(lowerPrefix)) {
-                const fullPath = path.join(searchDir, entry.name);
+                const fullPath = join(searchDir, entry.name);
                 const isDir = entry.isDirectory();
-                matches.push(isDir ? `${fullPath}${path.sep}` : fullPath);
+                matches.push(isDir ? `${fullPath}${sep}` : fullPath);
             }
         }
     }
@@ -396,17 +396,17 @@ function findRootPrefixMatches(currentValue, allowed) {
     if (!rootPrefix) {
         return collectAllowedRoots(allowed, () => true);
     }
-    return collectAllowedRoots(allowed, (root) => path.basename(root).toLowerCase().startsWith(rootPrefix));
+    return collectAllowedRoots(allowed, (root) => basename(root).toLowerCase().startsWith(rootPrefix));
 }
 function findMatchingRoots(searchDir, prefix, allowed) {
     const lowerPrefix = prefix.toLowerCase();
     const normalizedSearchDir = normalizePath(searchDir);
     return collectAllowedRoots(allowed, (root) => {
-        const rootDir = path.dirname(root);
+        const rootDir = dirname(root);
         // Check if root is a direct child of searchDir
         if (normalizePath(rootDir) !== normalizedSearchDir)
             return false;
-        return path.basename(root).toLowerCase().startsWith(lowerPrefix);
+        return basename(root).toLowerCase().startsWith(lowerPrefix);
     });
 }
 async function getPathCompletions(currentValue, options = {}) {
@@ -430,6 +430,34 @@ async function getPathCompletions(currentValue, options = {}) {
         return { values: [] };
     }
 }
+function handleTopicAndToolCompletions(ref, argName, argumentValue, topicValues, toolNameValues) {
+    if (!isRecord(ref))
+        return undefined;
+    const currentValue = argumentValue.toLowerCase();
+    if (ref['type'] === 'ref/prompt' && argName === 'topic') {
+        const filtered = currentValue
+            ? topicValues.filter((v) => v.startsWith(currentValue))
+            : topicValues;
+        return buildCompletionResponse(buildCompletionResult(filtered));
+    }
+    if (ref['type'] === 'ref/prompt' &&
+        ref['name'] === 'get-tool-help' &&
+        argName === 'name') {
+        const filtered = currentValue
+            ? toolNameValues.filter((value) => value.startsWith(currentValue))
+            : toolNameValues;
+        return buildCompletionResponse(buildCompletionResult(filtered));
+    }
+    if (ref['type'] === 'ref/resource' &&
+        ref['uri'] === 'internal://tool-info/{name}' &&
+        argName === 'name') {
+        const filtered = currentValue
+            ? toolNameValues.filter((value) => value.startsWith(currentValue))
+            : toolNameValues;
+        return buildCompletionResponse(buildCompletionResult(filtered));
+    }
+    return undefined;
+}
 export function registerCompletions(server, instructions = '') {
     const topicValues = extractTopicCompletions(instructions);
     const toolNameValues = extractToolNameCompletions();
@@ -437,34 +465,9 @@ export function registerCompletions(server, instructions = '') {
         const { params } = request;
         const { argument, ref } = params;
         const argName = argument.name.toLowerCase();
-        // Handle prompt topic completions
-        if (isRecord(ref) && ref['type'] === 'ref/prompt' && argName === 'topic') {
-            const currentValue = argument.value.toLowerCase();
-            const filtered = currentValue
-                ? topicValues.filter((v) => v.startsWith(currentValue))
-                : topicValues;
-            return buildCompletionResponse(buildCompletionResult(filtered));
-        }
-        if (isRecord(ref) &&
-            ref['type'] === 'ref/prompt' &&
-            ref['name'] === 'get-tool-help' &&
-            argName === 'name') {
-            const currentValue = argument.value.toLowerCase();
-            const filtered = currentValue
-                ? toolNameValues.filter((value) => value.startsWith(currentValue))
-                : toolNameValues;
-            return buildCompletionResponse(buildCompletionResult(filtered));
-        }
-        if (isRecord(ref) &&
-            ref['type'] === 'ref/resource' &&
-            ref['uri'] === 'internal://tool-info/{name}' &&
-            argName === 'name') {
-            const currentValue = argument.value.toLowerCase();
-            const filtered = currentValue
-                ? toolNameValues.filter((value) => value.startsWith(currentValue))
-                : toolNameValues;
-            return buildCompletionResponse(buildCompletionResult(filtered));
-        }
+        const predef = handleTopicAndToolCompletions(ref, argName, argument.value, topicValues, toolNameValues);
+        if (predef)
+            return predef;
         const enumResult = getEnumCompletions(argName, argument.value);
         if (enumResult) {
             return buildCompletionResponse(enumResult);

package/dist/config.d.ts

@@ -77,14 +77,13 @@ export interface SearchContentResult {
         readonly skippedTooLarge: number;
         readonly skippedBinary: number;
         readonly skippedInaccessible: number;
-        readonly linesSkippedDueToRegexTimeout: number;
         readonly stoppedReason?: 'maxResults' | 'maxFiles' | 'timeout';
     };
 }
 export interface MultipleFileInfoResult {
     readonly path: string;
     readonly info?: FileInfo;
-    readonly error?: string;
+    readonly error?: Error;
 }
 export interface GetMultipleFileInfoResult {
     readonly results: readonly MultipleFileInfoResult[];
@@ -96,18 +95,18 @@ export interface GetMultipleFileInfoResult {
     };
 }
 export declare const ErrorCode: {
-    readonly E_ACCESS_DENIED: "E_ACCESS_DENIED";
-    readonly E_NOT_FOUND: "E_NOT_FOUND";
-    readonly E_NOT_FILE: "E_NOT_FILE";
-    readonly E_NOT_DIRECTORY: "E_NOT_DIRECTORY";
-    readonly E_TOO_LARGE: "E_TOO_LARGE";
-    readonly E_TIMEOUT: "E_TIMEOUT";
-    readonly E_CANCELLED: "E_CANCELLED";
-    readonly E_INVALID_PATTERN: "E_INVALID_PATTERN";
-    readonly E_INVALID_INPUT: "E_INVALID_INPUT";
-    readonly E_PERMISSION_DENIED: "E_PERMISSION_DENIED";
-    readonly E_SYMLINK_NOT_ALLOWED: "E_SYMLINK_NOT_ALLOWED";
-    readonly E_UNKNOWN: "E_UNKNOWN";
+    readonly ACCESS_DENIED: "ACCESS_DENIED";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly NOT_FILE: "NOT_FILE";
+    readonly NOT_DIRECTORY: "NOT_DIRECTORY";
+    readonly TOO_LARGE: "TOO_LARGE";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly CANCELLED: "CANCELLED";
+    readonly INVALID_PATTERN: "INVALID_PATTERN";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly SYMLINK_NOT_ALLOWED: "SYMLINK_NOT_ALLOWED";
+    readonly UNKNOWN: "UNKNOWN";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 export declare function formatBytes(bytes: number): string;

package/dist/config.js

@@ -1,16 +1,16 @@
 export const ErrorCode = {
-    E_ACCESS_DENIED: 'E_ACCESS_DENIED',
-    E_NOT_FOUND: 'E_NOT_FOUND',
-    E_NOT_FILE: 'E_NOT_FILE',
-    E_NOT_DIRECTORY: 'E_NOT_DIRECTORY',
-    E_TOO_LARGE: 'E_TOO_LARGE',
-    E_TIMEOUT: 'E_TIMEOUT',
-    E_CANCELLED: 'E_CANCELLED',
-    E_INVALID_PATTERN: 'E_INVALID_PATTERN',
-    E_INVALID_INPUT: 'E_INVALID_INPUT',
-    E_PERMISSION_DENIED: 'E_PERMISSION_DENIED',
-    E_SYMLINK_NOT_ALLOWED: 'E_SYMLINK_NOT_ALLOWED',
-    E_UNKNOWN: 'E_UNKNOWN',
+    ACCESS_DENIED: 'ACCESS_DENIED',
+    NOT_FOUND: 'NOT_FOUND',
+    NOT_FILE: 'NOT_FILE',
+    NOT_DIRECTORY: 'NOT_DIRECTORY',
+    TOO_LARGE: 'TOO_LARGE',
+    TIMEOUT: 'TIMEOUT',
+    CANCELLED: 'CANCELLED',
+    INVALID_PATTERN: 'INVALID_PATTERN',
+    INVALID_INPUT: 'INVALID_INPUT',
+    PERMISSION_DENIED: 'PERMISSION_DENIED',
+    SYMLINK_NOT_ALLOWED: 'SYMLINK_NOT_ALLOWED',
+    UNKNOWN: 'UNKNOWN',
 };
 const BYTE_UNIT_LABELS = ['B', 'KB', 'MB', 'GB', 'TB'];
 export function formatBytes(bytes) {

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import process from 'node:process';
+import { createTimedAbortSignal } from './lib/abort.js';
 import { DEFAULT_SEARCH_TIMEOUT_MS } from './lib/constants.js';
 import { formatUnknownErrorMessage } from './lib/errors.js';
-import { createTimedAbortSignal } from './lib/fs-helpers.js';
 import { setAllowedDirectoriesResolved } from './lib/paths.js';
 import { CliExitError, parseArgs } from './cli.js';
 import { createServer, startHttpServer, startServer } from './server.js';

package/dist/lib/abort.d.ts

@@ -0,0 +1,7 @@
+export declare function assertNotAborted(signal?: AbortSignal, message?: string): void;
+export declare function withAbort<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T>;
+export declare function createTimedAbortSignal(baseSignal: AbortSignal | undefined, timeoutMs?: number): {
+    signal: AbortSignal;
+    cleanup: () => void;
+};
+export declare function withTimedAbortSignal<T>(baseSignal: AbortSignal | undefined, timeoutMs: number | undefined, run: (signal: AbortSignal) => Promise<T>): Promise<T>;

package/dist/lib/abort.js

@@ -0,0 +1,81 @@
+import { normalizeUnknownError } from './errors.js';
+function createAbortError(message = 'Operation aborted') {
+    return new DOMException(message, 'AbortError');
+}
+const SHARED_NOOP_SIGNAL = new AbortController().signal;
+function normalizeAbortReason(reason, message) {
+    if (reason instanceof Error)
+        return reason;
+    return createAbortError(message);
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+export function assertNotAborted(signal, message) {
+    if (!signal)
+        return;
+    try {
+        signal.throwIfAborted();
+    }
+    catch (reason) {
+        throw normalizeAbortReason(reason, message);
+    }
+}
+function getAbortError(signal, message) {
+    try {
+        signal.throwIfAborted();
+    }
+    catch (reason) {
+        return normalizeAbortReason(reason, message);
+    }
+    return createAbortError(message);
+}
+export function withAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            reject(getAbortError(signal));
+        };
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(normalizeUnknownError(error));
+        });
+    });
+}
+export function createTimedAbortSignal(baseSignal, timeoutMs) {
+    const timeoutSignal = isFiniteNumber(timeoutMs)
+        ? AbortSignal.timeout(timeoutMs)
+        : undefined;
+    if (baseSignal && timeoutSignal) {
+        return {
+            signal: AbortSignal.any([baseSignal, timeoutSignal]),
+            cleanup: () => { },
+        };
+    }
+    if (baseSignal) {
+        return { signal: baseSignal, cleanup: () => { } };
+    }
+    if (timeoutSignal) {
+        return { signal: timeoutSignal, cleanup: () => { } };
+    }
+    return { signal: SHARED_NOOP_SIGNAL, cleanup: () => { } };
+}
+export async function withTimedAbortSignal(baseSignal, timeoutMs, run) {
+    const { signal, cleanup } = createTimedAbortSignal(baseSignal, timeoutMs);
+    try {
+        return await run(signal);
+    }
+    finally {
+        cleanup();
+    }
+}

package/dist/lib/constants.d.ts

@@ -1,9 +1,11 @@
 export declare function parseTrueEnvFlag(value: string | undefined): boolean;
 export declare function parseEnvInt(envVar: string, defaultValue: number, min: number, max: number): number;
-export declare const DEFAULT_LOG_LEVEL: "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency";
+export declare const DEFAULT_LOG_LEVEL: "error" | "debug" | "info" | "notice" | "warning" | "critical" | "alert" | "emergency";
 export declare const DEFAULT_TASK_TTL_MS: number;
 export declare const MAX_TASK_TTL_MS: number;
 export declare const MAX_CONCURRENT_TASKS: number;
+export declare const TASK_CANCEL_POLL_MS = 2000;
+export declare const TASK_POLL_INTERVAL_MS = 100;
 export declare const PARALLEL_CONCURRENCY: number;
 export declare const MAX_SEARCHABLE_FILE_SIZE: number;
 export declare const MAX_TEXT_FILE_SIZE: number;

package/dist/lib/constants.js

@@ -1,4 +1,5 @@
 import { availableParallelism } from 'node:os';
+import { Logger } from './logger.js';
 const TRUE_ENV_VALUES = new Set(['1', 'true', 'yes', 'y', 'on']);
 const FALSE_ENV_VALUES = new Set(['0', 'false', 'no', 'n', 'off']);
 export function parseTrueEnvFlag(value) {
@@ -9,7 +10,7 @@ export function parseTrueEnvFlag(value) {
 const KIB = 1024;
 const MIB = 1024 * KIB;
 function logInvalidEnvValue(envVar, value, expected, defaultValue) {
-    console.error(`[WARNING] Invalid ${envVar} value: ${value} (must be ${expected}). Using default: ${String(defaultValue)}`);
+    Logger.warn(`Invalid ${envVar} value: ${value} (must be ${expected}). Using default: ${String(defaultValue)}`);
 }
 // Helper for parsing environment variables (only used for configurable values)
 export function parseEnvInt(envVar, defaultValue, min, max) {
@@ -66,7 +67,7 @@ function parseEnvLogLevel(envVar, defaultValue) {
     if (VALID_LOG_LEVELS.includes(normalized)) {
         return normalized;
     }
-    console.error(`[WARNING] Invalid ${envVar} value: ${value} (must be ${VALID_LOG_LEVELS.join('|')}). Using default: ${defaultValue}`);
+    Logger.warn(`Invalid ${envVar} value: ${value} (must be ${VALID_LOG_LEVELS.join('|')}). Using default: ${defaultValue}`);
     return defaultValue;
 }
 export const DEFAULT_LOG_LEVEL = parseEnvLogLevel('FILESYSTEM_MCP_LOG_LEVEL', 'info');
@@ -74,6 +75,11 @@ export const DEFAULT_LOG_LEVEL = parseEnvLogLevel('FILESYSTEM_MCP_LOG_LEVEL', 'i
 export const DEFAULT_TASK_TTL_MS = 5 * 60 * 1000;
 export const MAX_TASK_TTL_MS = parseEnvInt('FILESYSTEM_MCP_MAX_TASK_TTL_MS', 60 * 60 * 1000, 1_000, 24 * 60 * 60 * 1000);
 export const MAX_CONCURRENT_TASKS = parseEnvInt('FILESYSTEM_MCP_MAX_CONCURRENT_TASKS', 100, 1, 10_000);
+// How often (ms) a background task checks the store for client cancellation.
+export const TASK_CANCEL_POLL_MS = 2_000;
+// Suggested poll interval (ms) returned to the SDK/client for automatic task polling.
+// Filesystem operations complete quickly; a short interval avoids unnecessary latency.
+export const TASK_POLL_INTERVAL_MS = 100;
 // Auto-tuned parallelism based on CPU cores (no env override)
 const BYTES_PER_PARALLEL_TASK = 64 * MIB;
 const BYTES_PER_SEARCH_WORKER = 128 * MIB;

package/dist/lib/errors.d.ts

@@ -15,9 +15,13 @@ export declare function isTimeoutLikeError(error: unknown): boolean;
 export declare class McpError extends Error {
     code: ErrorCode;
     path?: string | undefined;
-    details?: Record<string, unknown> | undefined;
-    constructor(code: ErrorCode, message: string, path?: string | undefined, details?: Record<string, unknown> | undefined, cause?: unknown);
+    details?: Record<string, unknown>;
+    constructor(code: ErrorCode, message: string, path?: string | undefined, details?: Record<string, unknown>, cause?: unknown);
+    static notFound(message: string, path?: string, details?: Record<string, unknown>, cause?: unknown): McpError;
+    static invalidInput(message: string, path?: string, details?: Record<string, unknown>, cause?: unknown): McpError;
+    static accessDenied(message: string, path?: string, details?: Record<string, unknown>, cause?: unknown): McpError;
+    static timeout(message: string, path?: string, details?: Record<string, unknown>, cause?: unknown): McpError;
 }
 export declare function createDetailedError(error: unknown, path?: string, additionalDetails?: Record<string, unknown>): DetailedError;
 export declare function formatDetailedError(error: DetailedError): string;
-export declare function getSuggestion(code: ErrorCode): string;
+export declare function getSuggestion(code: ErrorCode): string | undefined;

package/dist/lib/errors.js

@@ -1,6 +1,7 @@
 import { constants as osConstants } from 'node:os';
 import { getSystemErrorMap, getSystemErrorName, inspect } from 'node:util';
 import { ErrorCode, joinLines } from '../config.js';
+import { getTraceContext } from './observability.js';
 export { ErrorCode };
 function isNativeError(error) {
     const candidate = Error;
@@ -100,20 +101,20 @@ export function normalizeUnknownError(error) {
         : new Error(formatUnknownErrorMessage(error));
 }
 const NODE_ERROR_CODE_MAP = {
-    ENOENT: ErrorCode.E_NOT_FOUND,
-    EACCES: ErrorCode.E_PERMISSION_DENIED,
-    EPERM: ErrorCode.E_PERMISSION_DENIED,
-    ENOTDIR: ErrorCode.E_NOT_DIRECTORY,
-    EISDIR: ErrorCode.E_NOT_FILE,
-    ELOOP: ErrorCode.E_SYMLINK_NOT_ALLOWED,
-    ENAMETOOLONG: ErrorCode.E_INVALID_INPUT,
-    ETIMEDOUT: ErrorCode.E_TIMEOUT,
-    EMFILE: ErrorCode.E_TIMEOUT,
-    ENFILE: ErrorCode.E_TIMEOUT,
-    EBUSY: ErrorCode.E_PERMISSION_DENIED,
-    ENOTEMPTY: ErrorCode.E_NOT_DIRECTORY,
-    EEXIST: ErrorCode.E_INVALID_INPUT,
-    EINVAL: ErrorCode.E_INVALID_INPUT,
+    ENOENT: ErrorCode.NOT_FOUND,
+    EACCES: ErrorCode.PERMISSION_DENIED,
+    EPERM: ErrorCode.PERMISSION_DENIED,
+    ENOTDIR: ErrorCode.NOT_DIRECTORY,
+    EISDIR: ErrorCode.NOT_FILE,
+    ELOOP: ErrorCode.SYMLINK_NOT_ALLOWED,
+    ENAMETOOLONG: ErrorCode.INVALID_INPUT,
+    ETIMEDOUT: ErrorCode.TIMEOUT,
+    EMFILE: ErrorCode.TIMEOUT,
+    ENFILE: ErrorCode.TIMEOUT,
+    EBUSY: ErrorCode.PERMISSION_DENIED,
+    ENOTEMPTY: ErrorCode.NOT_DIRECTORY,
+    EEXIST: ErrorCode.INVALID_INPUT,
+    EINVAL: ErrorCode.INVALID_INPUT,
 };
 function isKnownNodeErrorCode(code) {
     return code in NODE_ERROR_CODE_MAP;
@@ -169,26 +170,44 @@ export class McpError extends Error {
         super(message, { cause });
         this.code = code;
         this.path = path;
-        this.details = details;
         this.name = 'McpError';
         Object.setPrototypeOf(this, McpError.prototype);
+        const trace = getTraceContext();
+        if (trace?.traceparent || details) {
+            this.details = { ...trace, ...details };
+        }
+    }
+    static notFound(message, path, details, cause) {
+        return new McpError(ErrorCode.NOT_FOUND, message, path, details, cause);
+    }
+    static invalidInput(message, path, details, cause) {
+        return new McpError(ErrorCode.INVALID_INPUT, message, path, details, cause);
+    }
+    static accessDenied(message, path, details, cause) {
+        return new McpError(ErrorCode.ACCESS_DENIED, message, path, details, cause);
+    }
+    static timeout(message, path, details, cause) {
+        return new McpError(ErrorCode.TIMEOUT, message, path, details, cause);
     }
 }
 const ERROR_SUGGESTIONS = {
-    [ErrorCode.E_ACCESS_DENIED]: 'Check that the path is within an allowed directory. Use roots to see available workspace roots.',
-    [ErrorCode.E_NOT_FOUND]: 'Verify the path exists. Use ls to explore available files and directories.',
-    [ErrorCode.E_NOT_FILE]: 'The path points to a directory or other non-file. Use ls to explore its contents.',
-    [ErrorCode.E_NOT_DIRECTORY]: 'The path points to a file, not a directory. Use read to read file contents.',
-    [ErrorCode.E_TOO_LARGE]: 'The file exceeds the size limit. Use head to read a partial preview, or narrow the scope of what you read.',
-    [ErrorCode.E_TIMEOUT]: 'The operation timed out. Try a smaller scope (narrower path), fewer results (maxResults), or search fewer files.',
-    [ErrorCode.E_CANCELLED]: 'The operation was cancelled. This is not an error — no retry is needed unless you want to re-run the operation.',
-    [ErrorCode.E_INVALID_PATTERN]: 'The glob or regex pattern is invalid. Check syntax and escape special characters.',
-    [ErrorCode.E_INVALID_INPUT]: 'One or more input parameters are invalid. Check the tool documentation for correct usage.',
-    [ErrorCode.E_PERMISSION_DENIED]: 'Permission denied by the operating system. Check file permissions.',
-    [ErrorCode.E_SYMLINK_NOT_ALLOWED]: 'Symbolic links that escape allowed directories are not permitted for security reasons.',
-    [ErrorCode.E_UNKNOWN]: 'An unexpected error occurred. Check the error message for details.',
+    [ErrorCode.ACCESS_DENIED]: 'Run roots to list allowed directories.',
+    [ErrorCode.NOT_FOUND]: 'Run ls or find to verify the path.',
+    [ErrorCode.NOT_FILE]: 'Target is a directory, not a file.',
+    [ErrorCode.NOT_DIRECTORY]: 'Target is a file, not a directory.',
+    [ErrorCode.TOO_LARGE]: 'Use head/tail or line ranges to read partially.',
+    [ErrorCode.TIMEOUT]: 'Reduce scope, depth, or maxResults.',
+    [ErrorCode.CANCELLED]: undefined,
+    [ErrorCode.INVALID_PATTERN]: 'Check syntax and escape special characters.',
+    [ErrorCode.INVALID_INPUT]: undefined,
+    [ErrorCode.PERMISSION_DENIED]: 'Check OS file permissions.',
+    [ErrorCode.SYMLINK_NOT_ALLOWED]: 'Symlink escapes allowed directories.',
+    [ErrorCode.UNKNOWN]: undefined,
 };
-const NOT_FOUND_PATTERNS = ['enoent', 'no such file or directory'];
+const NOT_FOUND_PATTERNS = [
+    'no such file or directory',
+    'does not exist',
+];
 const PERMISSION_DENIED_PATTERNS = [
     'permission denied',
     'not permitted',
@@ -204,16 +223,16 @@ function classifyMessageError(error) {
     const message = isNativeError(error) ? error.message : String(error);
     const lower = message.toLowerCase();
     if (messageIncludesAny(lower, NOT_FOUND_PATTERNS)) {
-        return ErrorCode.E_NOT_FOUND;
+        return ErrorCode.NOT_FOUND;
     }
     if (messageIncludesAny(lower, PERMISSION_DENIED_PATTERNS)) {
-        return ErrorCode.E_PERMISSION_DENIED;
+        return ErrorCode.PERMISSION_DENIED;
     }
     if (lower.includes('not a directory')) {
-        return ErrorCode.E_NOT_DIRECTORY;
+        return ErrorCode.NOT_DIRECTORY;
     }
     if (lower.includes('is a directory')) {
-        return ErrorCode.E_NOT_FILE;
+        return ErrorCode.NOT_FILE;
     }
     return undefined;
 }
@@ -222,24 +241,28 @@ function classifyError(error) {
     let fallbackCode;
     const terminalCode = walkErrorChain(error, (candidate) => {
         if (isAbortErrorSingle(candidate)) {
-            return ErrorCode.E_CANCELLED;
+            return ErrorCode.CANCELLED;
         }
         if (timeoutCode === undefined && isTimeoutErrorSingle(candidate)) {
-            timeoutCode = ErrorCode.E_TIMEOUT;
+            timeoutCode = ErrorCode.TIMEOUT;
         }
         fallbackCode ??=
             getDirectErrorCode(candidate) ?? classifyMessageError(candidate);
         return undefined;
     });
-    return terminalCode ?? timeoutCode ?? fallbackCode ?? ErrorCode.E_UNKNOWN;
+    return terminalCode ?? timeoutCode ?? fallbackCode ?? ErrorCode.UNKNOWN;
 }
 export function createDetailedError(error, path, additionalDetails) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = formatUnknownErrorMessage(error);
     const code = classifyError(error);
     const suggestion = ERROR_SUGGESTIONS[code];
     const resolvedPath = resolveErrorPath(error, path);
     const details = mergeErrorDetails(error, additionalDetails);
-    const result = { code, message, suggestion };
+    const result = {
+        code,
+        message,
+        ...(suggestion ? { suggestion } : {}),
+    };
     if (resolvedPath)
         result.path = resolvedPath;
     if (details)
@@ -264,12 +287,12 @@ function mergeErrorDetails(error, additionalDetails) {
     return mergedDetails;
 }
 export function formatDetailedError(error) {
-    const lines = [`Error [${error.code}]: ${error.message}`];
-    if (error.path) {
-        lines.push(`Path: ${error.path}`);
+    const lines = [`${error.code}: ${error.message}`];
+    if (error.path && !error.message.includes(error.path)) {
+        lines.push(error.path);
     }
     if (error.suggestion) {
-        lines.push(`Suggestion: ${error.suggestion}`);
+        lines.push(error.suggestion);
     }
     return joinLines(lines);
 }

package/dist/lib/file-operations/core.d.ts

@@ -1,8 +1,8 @@
 import { type Ignore } from 'ignore';
 export declare function needsStatsForSort(sortBy: string): boolean;
-export declare function withOptionalStoppedReason<T extends object, R extends string>(summary: T, stoppedReason: R | undefined): T | (T & {
-    stoppedReason: R;
-});
+export declare function withOptionalStoppedReason<T extends object, R extends string>(summary: T, stoppedReason: R | undefined): T & {
+    stoppedReason?: R;
+};
 export interface DirentLike {
     isDirectory(): boolean;
     isFile(): boolean;