@j0hanz/filesystem-mcp 1.14.0 → 1.14.1

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,24 +170,39 @@ 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 = [
     'no such file or directory',
@@ -207,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;
 }
@@ -225,16 +241,16 @@ 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 = formatUnknownErrorMessage(error);
@@ -242,7 +258,11 @@ export function createDetailedError(error, path, additionalDetails) {
     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)
@@ -267,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;

package/dist/lib/file-operations/core.js

@@ -1,5 +1,5 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
 import ignore, {} from 'ignore';
 import { isNodeError } from '../errors.js';
 import { toPosixPath } from '../paths.js';
@@ -40,7 +40,8 @@ export function compareOptionalNumberDesc(left, right, tieBreak) {
 }
 export function stableSortByDerivedString(items, derive, tieBreak) {
     const decorated = [];
-    for (let index = 0; index < items.length; index += 1) {
+    const len = items.length;
+    for (let index = 0; index < len; index++) {
         const item = items[index];
         if (item === undefined)
             continue;
@@ -59,7 +60,8 @@ export function stableSortByDerivedString(items, derive, tieBreak) {
             return tiedCompare;
         return left.index - right.index;
     });
-    for (let index = 0; index < decorated.length; index += 1) {
+    const decoratedLen = decorated.length;
+    for (let index = 0; index < decoratedLen; index++) {
         const entry = decorated[index];
         if (!entry)
             continue;
@@ -74,13 +76,14 @@ export function applyIndexedValues(output, results) {
     }
 }
 export function applyIndexedErrors(options) {
-    for (const failure of options.errors) {
-        const resolvedIndex = options.resolveIndex(failure.index);
+    const { output, errors, resolveIndex, buildValue } = options;
+    for (const failure of errors) {
+        const resolvedIndex = resolveIndex(failure.index);
         if (resolvedIndex === undefined)
             continue;
-        if (resolvedIndex < 0 || resolvedIndex >= options.output.length)
+        if (resolvedIndex < 0 || resolvedIndex >= output.length)
             continue;
-        options.output[resolvedIndex] = options.buildValue(resolvedIndex, failure.error);
+        output[resolvedIndex] = buildValue(resolvedIndex, failure.error);
     }
 }
 export async function isEntryAccessibleByType(entryPath, entryType, rootDirectories, signal, deps) {
@@ -101,8 +104,9 @@ export async function isEntryAccessibleByType(entryPath, entryType, rootDirector
 }
 function parseGitignoreLines(contents) {
     const lines = [];
-    for (const line of contents.split(/\r?\n/u)) {
-        const trimmed = line.trim();
+    const parts = contents.split(/\r?\n/u);
+    for (const part of parts) {
+        const trimmed = part.trim();
         if (trimmed.length > 0) {
             lines.push(trimmed);
         }
@@ -110,13 +114,15 @@ function parseGitignoreLines(contents) {
     return lines;
 }
 export async function loadRootGitignore(root, signal) {
-    const gitignorePath = path.join(root, '.gitignore');
-    let contents;
+    const gitignorePath = join(root, '.gitignore');
     try {
-        contents = await fs.readFile(gitignorePath, {
+        const contents = await readFile(gitignorePath, {
             encoding: 'utf-8',
             signal,
         });
+        const matcher = ignore();
+        matcher.add(parseGitignoreLines(contents));
+        return matcher;
     }
     catch (error) {
         if (isNodeError(error) && error.code === 'ENOENT') {
@@ -124,16 +130,13 @@ export async function loadRootGitignore(root, signal) {
         }
         throw error;
     }
-    const matcher = ignore();
-    matcher.add(parseGitignoreLines(contents));
-    return matcher;
 }
 export function isIgnoredByGitignore(matcher, root, absolutePath, options = {}) {
-    let relative = options.relativePath;
-    relative ??= path.relative(root, absolutePath);
-    if (relative.length === 0)
+    let { relativePath } = options;
+    relativePath ??= relative(root, absolutePath);
+    if (relativePath.length === 0)
         return false;
-    const normalized = toPosixPath(relative);
+    const normalized = toPosixPath(relativePath);
     if (options.isDirectory) {
         return matcher.ignores(normalized.endsWith('/') ? normalized : `${normalized}/`);
     }

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

@@ -1,5 +1,5 @@
 import type { FileInfo, GetMultipleFileInfoResult, ListDirectoryResult } from '../../config.js';
-import type { EntryType } from './core.js';
+import { type EntryType } from './core.js';
 interface FileInfoOptions {
     includeMimeType?: boolean | undefined;
     signal?: AbortSignal | undefined;
@@ -60,7 +60,7 @@ interface ReadMultipleResult {
     endLine?: number;
     linesRead?: number;
     hasMoreLines?: boolean;
-    error?: string;
+    error?: Error;
 }
 interface ReadMultipleOptions {
     encoding?: BufferEncoding;

package/dist/lib/file-operations/metadata.js

@@ -1,12 +1,53 @@
-import * as fsp from 'node:fs/promises';
-import * as path from 'node:path';
+import { lstat, readdir, readlink, stat, } from 'node:fs';
+import { basename, join, parse, relative } from 'node:path';
+import { assertNotAborted, withAbort, withTimedAbortSignal } from '../abort.js';
 import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_LIST_MAX_ENTRIES, DEFAULT_MAX_DEPTH, DEFAULT_READ_MANY_MAX_TOTAL_SIZE, DEFAULT_SEARCH_TIMEOUT_MS, getMimeType, MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY, } from '../constants.js';
 import { isAbortError } from '../errors.js';
-import { assertNotAborted, getFileType, isHidden, processInParallel, readFile, readFileWithStats, withAbort, withTimedAbortSignal, } from '../fs-helpers.js';
+import { getFileType, isHidden, processInParallel, readFile, readFileWithStats, } from '../fs-helpers.js';
 import { assertSafeGlobPattern } from '../globs.js';
 import { assertAllowedFileAccess, isPathWithinDirectories, isSensitivePath, normalizePath, toPosixPath, validateExistingDirectory, validateExistingPath, validateExistingPathDetailed, } from '../paths.js';
 import { applyIndexedErrors, applyIndexedValues, isEntryAccessibleByType, isIgnoredByGitignore, loadRootGitignore, needsStatsForSort, resolveEntryType, resolveStopReason, withOptionalStoppedReason, } from './core.js';
 import { globEntries } from './traversal.js';
+function statAsync(filePath) {
+    return new Promise((resolve, reject) => {
+        stat(filePath, (err, stats) => {
+            if (err)
+                reject(err);
+            else
+                resolve(stats);
+        });
+    });
+}
+function readlinkAsync(filePath) {
+    return new Promise((resolve, reject) => {
+        readlink(filePath, (err, linkString) => {
+            if (err)
+                reject(err);
+            else
+                resolve(linkString);
+        });
+    });
+}
+function readdirAsync(dirPath, options) {
+    return new Promise((resolve, reject) => {
+        readdir(dirPath, options, (err, files) => {
+            if (err)
+                reject(err);
+            else
+                resolve(files);
+        });
+    });
+}
+function lstatAsync(filePath) {
+    return new Promise((resolve, reject) => {
+        lstat(filePath, (err, stats) => {
+            if (err)
+                reject(err);
+            else
+                resolve(stats);
+        });
+    });
+}
 const ACCESS_DEPS = {
     normalizePath,
     isPathWithinDirectories,
@@ -49,7 +90,7 @@ function buildFileInfoResult(name, requestedPath, isSymlink, stats, mimeType, sy
 async function getSymlinkTarget(pathToRead, signal) {
     assertNotAborted(signal);
     try {
-        return await withAbort(fsp.readlink(pathToRead), signal);
+        return await withAbort(readlinkAsync(pathToRead), signal);
     }
     catch (error) {
         if (isAbortError(error))
@@ -62,14 +103,14 @@ export async function getFileInfo(filePath, options = {}) {
     assertNotAborted(signal);
     const { requestedPath, resolvedPath, isSymlink } = await validateExistingPathDetailed(filePath, signal);
     assertAllowedFileAccess(requestedPath, resolvedPath);
-    const { base: name, ext: rawExt } = path.parse(requestedPath);
+    const { base: name, ext: rawExt } = parse(requestedPath);
     const ext = rawExt.toLowerCase();
     const includeMimeType = options.includeMimeType !== false;
     const mimeType = includeMimeType && ext.length > 0 ? getMimeType(ext) : undefined;
     const symlinkTarget = isSymlink
         ? await getSymlinkTarget(requestedPath, signal)
         : undefined;
-    const stats = await withAbort(fsp.stat(resolvedPath), signal);
+    const stats = await withAbort(statAsync(resolvedPath), signal);
     return buildFileInfoResult(name, requestedPath, isSymlink, stats, mimeType, symlinkTarget);
 }
 function buildEmptyResult() {
@@ -131,7 +172,7 @@ export async function getMultipleFileInfo(paths, options = {}) {
             : undefined,
         buildValue: (resolvedIndex, error) => ({
             path: paths[resolvedIndex] ?? UNKNOWN_PATH,
-            error: error.message,
+            error,
         }),
     });
     return {
@@ -168,12 +209,12 @@ function resolveMaxDepth(normalized) {
     return normalized.pattern ? normalized.maxDepth : 1;
 }
 async function* readDirectoryEntries(basePath, normalized, needsStats, signal) {
-    const dirents = await withAbort(fsp.readdir(basePath, { withFileTypes: true }), signal);
+    const dirents = await withAbort(readdirAsync(basePath, { withFileTypes: true }), signal);
     if (!needsStats) {
         for (const dirent of dirents) {
             if (!normalized.includeHidden && isHidden(dirent.name))
                 continue;
-            yield { path: path.join(basePath, dirent.name), dirent };
+            yield { path: join(basePath, dirent.name), dirent };
         }
         return;
     }
@@ -181,12 +222,12 @@ async function* readDirectoryEntries(basePath, normalized, needsStats, signal) {
     for (const dirent of dirents) {
         if (!normalized.includeHidden && isHidden(dirent.name))
             continue;
-        filtered.push({ dirent, entryPath: path.join(basePath, dirent.name) });
+        filtered.push({ dirent, entryPath: join(basePath, dirent.name) });
     }
     const { results, errors } = await processInParallel(filtered, async ({ entryPath, dirent }) => ({
         path: entryPath,
         dirent,
-        stats: await withAbort(fsp.lstat(entryPath), signal),
+        stats: await withAbort(lstatAsync(entryPath), signal),
     }), PARALLEL_CONCURRENCY, signal);
     if (errors.length > 0) {
         throw errors[0]?.error ?? new Error('Failed to read entry stats');
@@ -216,13 +257,13 @@ function shouldUseFastPath(normalized, maxDepth) {
         maxDepth === 1);
 }
 function resolveRelativePath(basePath, entryPath) {
-    return path.relative(basePath, entryPath) || path.basename(entryPath);
+    return relative(basePath, entryPath) || basename(entryPath);
 }
 async function resolveSymlinkTarget(entryType, includeSymlinkTargets, entryPath) {
     if (entryType !== 'symlink' || !includeSymlinkTargets) {
         return undefined;
     }
-    return fsp.readlink(entryPath).catch(() => undefined);
+    return readlinkAsync(entryPath).catch(() => undefined);
 }
 function updateTotals(entryType, totals) {
     if (entryType === 'file')
@@ -234,7 +275,7 @@ function buildDirectoryEntry(basePath, entry, entryType, needsStats, symlinkTarg
     const size = needsStats && entry.stats?.isFile() ? entry.stats.size : undefined;
     const modified = needsStats ? entry.stats?.mtime : undefined;
     return {
-        name: path.basename(entry.path),
+        name: basename(entry.path),
         path: entry.path,
         relativePath: resolveRelativePath(basePath, entry.path),
         type: entryType,
@@ -423,7 +464,7 @@ async function resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher,
         return null;
     }
     const relativePosix = toPosixPath(resolveRelativePath(root, entry.path));
-    const name = path.basename(entry.path);
+    const name = basename(entry.path);
     return { type, relativePosix, name };
 }
 function upsertChildNode(parent, nodeByPath, resolved, childPathIndexByParent) {
@@ -523,7 +564,7 @@ export async function treeDirectory(dirPath, options = {}) {
             ? null
             : await loadRootGitignore(root, signal);
         const rootNode = {
-            name: path.basename(root) || root,
+            name: basename(root) || root,
             type: 'directory',
             relativePath: '.',
             children: [],
@@ -675,7 +716,7 @@ function resolveNormalizedReadOptions(options) {
 }
 async function validateFile(filePath, index, signal) {
     const validPath = await validateExistingPath(filePath, signal);
-    const stats = await withAbort(fsp.stat(validPath), signal);
+    const stats = await withAbort(statAsync(validPath), signal);
     return { filePath, index, validPath, stats };
 }
 function markRemainingSkipped(startIndex, total, skippedBudget) {
@@ -810,7 +851,7 @@ function applySkippedBudget(output, skippedBudget, filePaths, maxTotalSize) {
             continue;
         output[index] = {
             path: filePath,
-            error: `Skipped: combined estimated read would exceed maxTotalSize (${maxTotalSize} bytes)`,
+            error: new Error(`Skipped: combined estimated read would exceed maxTotalSize (${maxTotalSize} bytes)`),
         };
     }
 }
@@ -829,7 +870,7 @@ export async function readMultipleFiles(filePaths, options = {}) {
         resolveIndex: (failureIndex) => resolveErrorOriginalIndex(failureIndex, filesToProcess, filePaths.length),
         buildValue: (resolvedIndex, error) => ({
             path: filePaths[resolvedIndex] ?? UNKNOWN_PATH,
-            error: error.message,
+            error,
         }),
     });
     applySkippedBudget(output, skippedBudget, filePaths, normalized.maxTotalSize);