@j0hanz/filesystem-mcp 1.13.2 → 1.14.1

package/dist/lib/fs-helpers.js

@@ -50,36 +50,16 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import * as fsp from 'node:fs/promises';
-import * as path from 'node:path';
 import { isUtf8 } from 'node:buffer';
 import { randomUUID } from 'node:crypto';
+import { open, rename, stat, unlink, writeFile, } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { assertNotAborted, withAbort } from './abort.js';
 import { BINARY_CHECK_BUFFER_SIZE, KNOWN_BINARY_EXTENSIONS, MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY, } from './constants.js';
 import { ErrorCode, McpError, normalizeUnknownError } from './errors.js';
 import { assertAllowedFileAccess, validateExistingPath } from './paths.js';
-function createAbortError(message = 'Operation aborted') {
-    return new DOMException(message, 'AbortError');
-}
+export { assertNotAborted, createTimedAbortSignal, withAbort, withTimedAbortSignal, } from './abort.js';
 const READ_ONLY_FILE_FLAG = 'r';
-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 assertPositiveSafeIntegerOption(name, value, message) {
     if (value === undefined)
         return;
@@ -87,73 +67,15 @@ function assertPositiveSafeIntegerOption(name, value, message) {
         !Number.isFinite(value) ||
         !Number.isSafeInteger(value) ||
         value < 1) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, message ?? `${name} must be a positive integer`);
+        throw new McpError(ErrorCode.INVALID_INPUT, message ?? `${name} must be a positive integer`);
     }
 }
 function normalizeConcurrency(concurrency) {
     assertPositiveSafeIntegerOption('concurrency', concurrency);
     return concurrency;
 }
-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();
-    }
-}
 function createParallelAbortError() {
-    return createAbortError();
+    return new DOMException('Operation aborted', 'AbortError');
 }
 export async function processInParallel(items, processor, concurrency = PARALLEL_CONCURRENCY, signal) {
     const itemCount = items.length;
@@ -218,11 +140,11 @@ export function isHidden(name) {
     return name.startsWith('.');
 }
 function hasKnownBinaryExtension(filePath) {
-    const ext = path.extname(filePath).toLowerCase();
+    const ext = extname(filePath).toLowerCase();
     return KNOWN_BINARY_EXTENSIONS.has(ext);
 }
 async function openReadableFileHandle(filePath, signal) {
-    return withAbort(fsp.open(filePath, READ_ONLY_FILE_FLAG), signal);
+    return withAbort(open(filePath, READ_ONLY_FILE_FLAG), signal);
 }
 async function readProbe(handle, signal) {
     const buffer = Buffer.alloc(BINARY_CHECK_BUFFER_SIZE);
@@ -282,18 +204,16 @@ function validateReadOptions(options) {
     assertPositiveSafeIntegerOption('startLine', options.startLine, 'startLine must be at least 1');
     assertPositiveSafeIntegerOption('endLine', options.endLine, 'endLine must be at least 1');
     if (hasHead && (hasStart || hasEnd)) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'head cannot be used together with startLine/endLine');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'head cannot be used together with startLine/endLine');
     }
     if (hasTail && (hasHead || hasStart || hasEnd)) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'tail cannot be used together with head/startLine/endLine');
-    }
-    if (hasEnd && !hasStart) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'endLine requires startLine');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'tail cannot be used together with head/startLine/endLine');
     }
-    if (options.startLine !== undefined &&
-        options.endLine !== undefined &&
-        options.endLine < options.startLine) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'endLine must be greater than or equal to startLine');
+    {
+        const effectiveStart = options.startLine ?? 1;
+        if (options.endLine !== undefined && options.endLine < effectiveStart) {
+            throw new McpError(ErrorCode.INVALID_INPUT, 'endLine must be greater than or equal to startLine (default: 1)');
+        }
     }
 }
 function normalizeOptions(options) {
@@ -309,12 +229,13 @@ function normalizeOptions(options) {
     if (options.tail !== undefined) {
         normalized.tail = options.tail;
     }
-    if (options.startLine !== undefined) {
-        normalized.startLine = options.startLine;
-    }
     if (options.endLine !== undefined) {
+        normalized.startLine = options.startLine ?? 1;
         normalized.endLine = options.endLine;
     }
+    else if (options.startLine !== undefined) {
+        normalized.startLine = options.startLine;
+    }
     if (options.signal) {
         normalized.signal = options.signal;
     }
@@ -340,13 +261,13 @@ function resolveReadMode(options) {
         return 'head';
     if (options.tail !== undefined)
         return 'tail';
-    if (options.startLine !== undefined)
+    if (options.startLine !== undefined || options.endLine !== undefined)
         return 'range';
     return 'full';
 }
 const STREAM_CHUNK_SIZE = 64 * 1024;
 function createTooLargeError(bytesRead, maxSize, requestedPath) {
-    return new McpError(ErrorCode.E_TOO_LARGE, `File exceeds maximum size (${bytesRead} > ${maxSize}): ${requestedPath}`, requestedPath, { size: bytesRead, maxSize });
+    return new McpError(ErrorCode.TOO_LARGE, `File exceeds size limit (${bytesRead} > ${maxSize} bytes)`, requestedPath, { size: bytesRead, maxSize });
 }
 async function readFileBufferWithLimit(handle, maxSize, requestedPath, signal) {
     const stream = handle.createReadStream({
@@ -522,19 +443,19 @@ async function assertNotBinary(validPath, filePath, normalized) {
     const isBinary = await isProbablyBinary(validPath, undefined, normalized.signal);
     if (!isBinary)
         return;
-    throw new McpError(ErrorCode.E_INVALID_INPUT, `Binary file detected: ${filePath}. Refusing to read as text.`, filePath);
+    throw new McpError(ErrorCode.INVALID_INPUT, 'Binary file detected.', filePath);
 }
 function assertSizeWithinLimit(size, maxSize, filePath) {
     if (size <= maxSize)
         return;
-    throw new McpError(ErrorCode.E_TOO_LARGE, `File too large: ${size} bytes (max: ${maxSize} bytes). Use head parameter to preview the first N lines.`, filePath, { size, maxSize });
+    throw new McpError(ErrorCode.TOO_LARGE, `File too large (${size} > ${maxSize} bytes). Use head to preview.`, filePath, { size, maxSize });
 }
 function requireReadOption(normalized, key, filePath) {
     const value = normalized[key];
     if (value !== undefined) {
         return value;
     }
-    throw new McpError(ErrorCode.E_INVALID_INPUT, `Missing ${key} option`, filePath);
+    throw new McpError(ErrorCode.INVALID_INPUT, `Missing ${key} option`, filePath);
 }
 async function executeHeadRead(context) {
     const head = requireReadOption(context.normalized, 'head', context.filePath);
@@ -605,7 +526,7 @@ async function readByMode(context) {
 }
 function assertFileStats(filePath, stats) {
     if (!stats.isFile()) {
-        throw new McpError(ErrorCode.E_NOT_FILE, `Not a file: ${filePath}`, filePath);
+        throw new McpError(ErrorCode.NOT_FILE, 'Not a regular file', filePath);
     }
 }
 async function readFileWithStatsInternal(filePath, validPath, stats, normalized) {
@@ -645,7 +566,7 @@ export async function readFile(filePath, options = {}) {
     const normalized = prepareReadOptions(options);
     const validPath = await validateExistingPath(filePath, normalized.signal);
     assertNotAborted(normalized.signal);
-    const stats = await withAbort(fsp.stat(validPath), normalized.signal);
+    const stats = await withAbort(stat(validPath), normalized.signal);
     return readFileWithStatsInternal(filePath, validPath, stats, normalized);
 }
 export async function atomicWriteFile(filePath, content, options = {}) {
@@ -653,13 +574,13 @@ export async function atomicWriteFile(filePath, content, options = {}) {
     const tempPath = `${filePath}.${randomUUID()}.tmp`;
     try {
         assertNotAborted(signal);
-        await fsp.writeFile(tempPath, content, { encoding, signal });
-        await withAbort(fsp.rename(tempPath, filePath), signal);
+        await writeFile(tempPath, content, { encoding, signal });
+        await withAbort(rename(tempPath, filePath), signal);
     }
     catch (error) {
         // Attempt cleanup on error, but don't overwrite the original error
         try {
-            await fsp.unlink(tempPath).catch(() => { });
+            await unlink(tempPath).catch(() => { });
         }
         catch {
             // Ignore cleanup errors

package/dist/lib/globs.d.ts

@@ -0,0 +1,2 @@
+export declare function isSafeGlobPattern(value: string): boolean;
+export declare function assertSafeGlobPattern(value: string, message?: string): void;

package/dist/lib/globs.js

@@ -0,0 +1,19 @@
+import { ErrorCode, McpError } from './errors.js';
+const ABSOLUTE_GLOB_RE = /^([/\\]|[A-Za-z]:[/\\]|\\\\)/u;
+const PARENT_SEGMENT_RE = /[\\/]\.\.(?:[/\\]|$)/u;
+export function isSafeGlobPattern(value) {
+    if (value.length === 0)
+        return false;
+    if (value.includes('**/**/**'))
+        return false;
+    if (ABSOLUTE_GLOB_RE.test(value))
+        return false;
+    if (value.startsWith('..') || PARENT_SEGMENT_RE.test(value))
+        return false;
+    return true;
+}
+export function assertSafeGlobPattern(value, message = 'Invalid glob or unsafe path (absolute/.. forbidden)') {
+    if (!isSafeGlobPattern(value)) {
+        throw new McpError(ErrorCode.INVALID_PATTERN, message);
+    }
+}

package/dist/lib/logger.d.ts

@@ -0,0 +1,28 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LoggingLevel } from '@modelcontextprotocol/sdk/types.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+export interface SessionContextData {
+    sessionId?: string;
+}
+export declare const SessionContext: AsyncLocalStorage<SessionContextData>;
+export interface LogEvent {
+    level: LoggingLevel;
+    message: string;
+    data?: unknown;
+    sessionId?: string;
+}
+export interface LoggingState {
+    minimumLevel: LoggingLevel;
+}
+export declare function createLoggingState(minimumLevel?: LoggingLevel): LoggingState;
+export declare function canSendMcpLogs(server: McpServer): boolean;
+export declare function logToMcp(server: McpServer | undefined, level: LoggingLevel, data: string, minLevel?: LoggingLevel): void;
+export declare const Logger: {
+    emit(level: LoggingLevel, message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    notice(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    critical(message: string, data?: unknown): void;
+};

package/dist/lib/logger.js

@@ -0,0 +1,91 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { channel } from 'node:diagnostics_channel';
+export const SessionContext = new AsyncLocalStorage();
+const LOG_CHANNEL = channel('filesystem-mcp:log');
+const MCP_LOGGER_NAME = 'filesystem-mcp';
+const LOG_LEVEL_ORDER = {
+    debug: 0,
+    info: 1,
+    notice: 2,
+    warning: 3,
+    error: 4,
+    critical: 5,
+    alert: 6,
+    emergency: 7,
+};
+export function createLoggingState(minimumLevel = 'debug') {
+    return { minimumLevel };
+}
+export function canSendMcpLogs(server) {
+    const capabilities = server.server.getClientCapabilities();
+    if (!capabilities || typeof capabilities !== 'object')
+        return false;
+    return 'logging' in capabilities && Boolean(capabilities.logging);
+}
+export function logToMcp(server, level, data, minLevel = 'debug') {
+    if (LOG_LEVEL_ORDER[level] < LOG_LEVEL_ORDER[minLevel]) {
+        return;
+    }
+    if (!server || !canSendMcpLogs(server)) {
+        console.error(`[${level.toUpperCase()}] ${data}`);
+        return;
+    }
+    const params = {
+        level,
+        logger: MCP_LOGGER_NAME,
+        data,
+    };
+    void server.sendLoggingMessage(params).catch((error) => {
+        console.error(`Failed to send MCP log: ${level} | ${data}`, formatTransportError(error));
+    });
+}
+function formatTransportError(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+export const Logger = {
+    emit(level, message, data) {
+        const session = SessionContext.getStore();
+        const event = {
+            level,
+            message,
+            ...(data !== undefined ? { data } : {}),
+            ...(session?.sessionId !== undefined
+                ? { sessionId: session.sessionId }
+                : {}),
+        };
+        if (LOG_CHANNEL.hasSubscribers) {
+            LOG_CHANNEL.publish(event);
+        }
+        else {
+            // Fallback if no subscribers
+            console.error(`[${level.toUpperCase()}] ${message}`, data ?? '');
+        }
+    },
+    debug(message, data) {
+        this.emit('debug', message, data);
+    },
+    info(message, data) {
+        this.emit('info', message, data);
+    },
+    notice(message, data) {
+        this.emit('notice', message, data);
+    },
+    warn(message, data) {
+        this.emit('warning', message, data);
+    },
+    error(message, data) {
+        this.emit('error', message, data);
+    },
+    critical(message, data) {
+        this.emit('critical', message, data);
+    },
+};

package/dist/lib/observability.d.ts

@@ -5,6 +5,11 @@ interface OpsTraceContext {
     path?: string | undefined;
     [key: string]: unknown;
 }
+export interface TraceContext {
+    traceparent: string;
+    tracestate?: string;
+    baggage?: string;
+}
 interface ToolMetrics {
     calls: number;
     errors: number;
@@ -19,8 +24,10 @@ export declare function getToolContextSnapshot(): {
     tool: string;
     path?: string;
 } | undefined;
+export declare function getTraceContext(): TraceContext | undefined;
 export declare function startPerfMeasure(name: string, detail?: Record<string, unknown>): ((ok?: boolean) => void) | undefined;
 export declare function withToolDiagnostics<T>(tool: string, run: () => Promise<T>, options?: {
     path?: string;
+    traceContext?: TraceContext;
 }): Promise<T>;
 export {};

package/dist/lib/observability.js

@@ -3,16 +3,18 @@ import { hash } from 'node:crypto';
 import { channel, tracingChannel } from 'node:diagnostics_channel';
 import { monitorEventLoopDelay, performance, PerformanceObserver, } from 'node:perf_hooks';
 import { parseTrueEnvFlag } from './constants.js';
+import { Logger } from './logger.js';
 import { isRecord } from './utils.js';
 // --- Configuration ---
 const ENV = process.env;
 let _cachedConfig;
 function readConfig() {
-    return (_cachedConfig ??= {
+    _cachedConfig ??= {
         enabled: parseTrueEnvFlag(ENV['FS_CONTEXT_DIAGNOSTICS']),
         detail: parseDetail(ENV['FS_CONTEXT_DIAGNOSTICS_DETAIL']),
         logToolErrors: parseTrueEnvFlag(ENV['FS_CONTEXT_TOOL_LOG_ERRORS']),
-    });
+    };
+    return _cachedConfig;
 }
 function parseDetail(val) {
     if (val === '2')
@@ -201,6 +203,9 @@ function applyToolContext(context) {
 export function getToolContextSnapshot() {
     return toolContext.getStore();
 }
+export function getTraceContext() {
+    return toolContext.getStore()?.traceContext;
+}
 function normalizeContext(ctx) {
     if (!ctx.path)
         return ctx;
@@ -254,16 +259,20 @@ export function startPerfMeasure(name, detail) {
         }
     };
 }
-function publishToolStart(tool, pathVal) {
+function publishToolStart(tool, pathVal, traceparent) {
     const event = { phase: 'start', tool };
     if (pathVal)
         event.path = pathVal;
+    if (traceparent)
+        event.traceparent = traceparent;
     CHANNELS.tool.publish(event);
 }
-function publishToolEnd(tool, ok, durationMs, errorMsg) {
+function publishToolEnd(tool, ok, durationMs, errorMsg, traceparent) {
     const event = { phase: 'end', tool, ok, durationMs };
     if (errorMsg)
         event.error = errorMsg;
+    if (traceparent)
+        event.traceparent = traceparent;
     CHANNELS.tool.publish(event);
 }
 function publishPerfEnd(tool, durationMs, eluStart, loopMonitor) {
@@ -281,13 +290,13 @@ function publishPerfEnd(tool, durationMs, eluStart, loopMonitor) {
     }
     CHANNELS.perf.publish(event);
 }
-async function runAndObserve(tool, run, pubTool, pubPerf, logErrors, pathVal) {
+async function runAndObserve(tool, run, pubTool, pubPerf, logErrors, pathVal, traceparent) {
     const startMs = performance.now();
     const eluStart = pubPerf ? performance.eventLoopUtilization() : undefined;
     const loopMonitor = pubPerf ? monitorEventLoopDelay() : undefined;
     loopMonitor?.enable();
     if (pubTool)
-        publishToolStart(tool, pathVal);
+        publishToolStart(tool, pathVal, traceparent);
     let result;
     const obs = { ok: false, errorMsg: undefined };
     try {
@@ -306,7 +315,7 @@ async function runAndObserve(tool, run, pubTool, pubPerf, logErrors, pathVal) {
         if (pubPerf && eluStart)
             publishPerfEnd(tool, durationMs, eluStart, loopMonitor);
         if (pubTool)
-            publishToolEnd(tool, obs.ok, durationMs, obs.errorMsg);
+            publishToolEnd(tool, obs.ok, durationMs, obs.errorMsg, traceparent);
         updateMetrics(tool, obs.ok, durationMs);
         if (logErrors && !obs.ok)
             logError(tool, durationMs, obs.errorMsg);
@@ -319,6 +328,7 @@ export async function withToolDiagnostics(tool, run, options) {
     const context = {
         tool,
         ...(options?.path ? { path: options.path } : {}),
+        ...(options?.traceContext ? { traceContext: options.traceContext } : {}),
     };
     return toolContext.run(context, async () => {
         if (!config.enabled) {
@@ -354,10 +364,10 @@ export async function withToolDiagnostics(tool, run, options) {
                 throw e;
             }
         }
-        return runAndObserve(tool, run, pubTool, pubPerf, config.logToolErrors, normalizedPath);
+        return runAndObserve(tool, run, pubTool, pubPerf, config.logToolErrors, normalizedPath, options?.traceContext?.traceparent);
     });
 }
 function logError(tool, durationMs, msg) {
     const suffix = msg ? `: ${msg}` : '';
-    console.error(`[ToolError] ${tool} failed in ${durationMs.toFixed(1)}ms${suffix}`);
+    Logger.error(`[ToolError] ${tool} failed in ${durationMs.toFixed(1)}ms${suffix}`);
 }