@j0hanz/filesystem-mcp 1.19.0 → 2.0.0

package/dist/lib/logger.js

@@ -1,91 +0,0 @@
-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 };
-}
-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

@@ -1,33 +0,0 @@
-interface OpsTraceContext {
-    op: string;
-    engine?: string;
-    tool?: string;
-    path?: string | undefined;
-    [key: string]: unknown;
-}
-export interface TraceContext {
-    traceparent: string;
-    tracestate?: string;
-    baggage?: string;
-}
-interface ToolMetrics {
-    calls: number;
-    errors: number;
-    totalDurationMs: number;
-}
-export declare const globalMetrics: Map<string, ToolMetrics>;
-export declare function shouldPublishOpsTrace(): boolean;
-export declare function publishOpsTraceStart(context: OpsTraceContext): void;
-export declare function publishOpsTraceEnd(context: OpsTraceContext): void;
-export declare function publishOpsTraceError(context: OpsTraceContext, error: unknown): void;
-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

@@ -1,373 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-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() {
-    _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')
-        return 2;
-    if (val === '1')
-        return 1;
-    return 0;
-}
-export const globalMetrics = new Map();
-function updateMetrics(tool, ok, durationMs) {
-    const current = globalMetrics.get(tool) ?? {
-        calls: 0,
-        errors: 0,
-        totalDurationMs: 0,
-    };
-    current.calls++;
-    if (!ok)
-        current.errors++;
-    current.totalDurationMs += durationMs;
-    globalMetrics.set(tool, current);
-}
-// --- Channels & Observability State ---
-const CHANNELS = {
-    tool: channel('filesystem-mcp:tool'),
-    perf: channel('filesystem-mcp:perf'),
-    ops: tracingChannel('filesystem-mcp:ops'),
-};
-const toolContext = new AsyncLocalStorage({
-    name: 'filesystem-mcp:tool',
-});
-let perfObserver;
-let traceCounter = 0;
-// --- Helpers: Result Analysis ---
-function extractOutcome(result) {
-    if (!isRecord(result)) {
-        return { ok: true };
-    }
-    if (result['isError'] === true) {
-        const err = extractErrorMessage(result);
-        return { ok: false, error: err };
-    }
-    if (typeof result['ok'] === 'boolean') {
-        if (result['ok'])
-            return { ok: true };
-        return { ok: false, error: extractErrorMessage(result) };
-    }
-    const content = result['structuredContent'];
-    if (isRecord(content) && typeof content['ok'] === 'boolean') {
-        if (content['ok'])
-            return { ok: true };
-        const err = extractResultError(content);
-        return err ? { ok: false, error: err } : { ok: false };
-    }
-    return { ok: true };
-}
-function extractErrorMessage(source) {
-    if (typeof source === 'string')
-        return source;
-    if (source instanceof Error)
-        return source.message;
-    if (isRecord(source)) {
-        const struct = source['structuredContent'];
-        if (isRecord(struct)) {
-            const err = struct['error'];
-            if (isRecord(err) && typeof err['message'] === 'string')
-                return err['message'];
-        }
-        if (typeof source['message'] === 'string')
-            return source['message'];
-        const errObj = source['error'];
-        if (isRecord(errObj) && typeof errObj['message'] === 'string') {
-            return errObj['message'];
-        }
-    }
-    try {
-        return String(source);
-    }
-    catch {
-        return 'Unknown error';
-    }
-}
-function extractResultError(structured) {
-    const err = structured['error'];
-    return isRecord(err) && typeof err['message'] === 'string'
-        ? err['message']
-        : undefined;
-}
-function sanitizePathForDiagnostics(path) {
-    const { detail } = readConfig();
-    if (!path || detail === 0)
-        return undefined;
-    if (detail === 2)
-        return path;
-    return hash('sha256', path, 'hex').slice(0, 16);
-}
-function enrichWithToolContext(detail) {
-    const current = toolContext.getStore();
-    if (!current)
-        return detail;
-    const merged = { ...(detail ?? {}) };
-    if (!Object.hasOwn(merged, 'tool')) {
-        merged.tool = current.tool;
-    }
-    const normalizedPath = sanitizePathForDiagnostics(current.path);
-    if (normalizedPath && !Object.hasOwn(merged, 'path')) {
-        merged.path = normalizedPath;
-    }
-    return merged;
-}
-// --- Perf Helpers ---
-function toMs(nanos) {
-    return nanos / 1_000_000;
-}
-function getDelayStats(h) {
-    if (h.count === 0)
-        return undefined;
-    return {
-        min: toMs(h.min),
-        max: toMs(h.max),
-        mean: toMs(h.mean),
-        p50: toMs(h.percentile(50)),
-        p95: toMs(h.percentile(95)),
-        p99: toMs(h.percentile(99)),
-        exceeds: h.exceeds,
-    };
-}
-function clearPublishedMeasures(entries) {
-    if (entries.length === 0)
-        return;
-    const names = new Set();
-    for (const entry of entries) {
-        names.add(entry.name);
-    }
-    for (const name of names) {
-        performance.clearMeasures(name);
-    }
-}
-function ensureObserver() {
-    if (perfObserver)
-        return;
-    perfObserver = new PerformanceObserver((list) => {
-        const entries = list.getEntries();
-        for (const entry of entries) {
-            CHANNELS.perf.publish({
-                phase: 'measure',
-                name: entry.name,
-                durationMs: entry.duration,
-                detail: entry.detail,
-            });
-        }
-        try {
-            // Keep the global timeline bounded while preserving published events.
-            clearPublishedMeasures(entries);
-        }
-        catch {
-            // Never allow observability cleanup to affect tool execution.
-        }
-    });
-    perfObserver.observe({ entryTypes: ['measure'] });
-}
-// --- Public API ---
-export function shouldPublishOpsTrace() {
-    return readConfig().enabled && CHANNELS.ops.hasSubscribers;
-}
-export function publishOpsTraceStart(context) {
-    CHANNELS.ops.start.publish(normalizeContext(applyToolContext(context)));
-}
-export function publishOpsTraceEnd(context) {
-    CHANNELS.ops.end.publish(normalizeContext(applyToolContext(context)));
-}
-export function publishOpsTraceError(context, error) {
-    CHANNELS.ops.error.publish({
-        ...normalizeContext(applyToolContext(context)),
-        error,
-    });
-}
-function applyToolContext(context) {
-    const current = toolContext.getStore();
-    if (!current)
-        return context;
-    const merged = { ...context };
-    merged.tool ??= current.tool;
-    merged.path ??= current.path;
-    return merged;
-}
-export function getToolContextSnapshot() {
-    return toolContext.getStore();
-}
-export function getTraceContext() {
-    return toolContext.getStore()?.traceContext;
-}
-function normalizeContext(ctx) {
-    if (!ctx.path)
-        return ctx;
-    const normalized = sanitizePathForDiagnostics(ctx.path);
-    if (!normalized) {
-        const copy = { ...ctx };
-        delete copy.path;
-        return copy;
-    }
-    return { ...ctx, path: normalized };
-}
-function clearMeasureMarks(startMark, endMark) {
-    performance.clearMarks(startMark);
-    performance.clearMarks(endMark);
-}
-export function startPerfMeasure(name, detail) {
-    if (!readConfig().enabled || !CHANNELS.perf.hasSubscribers)
-        return undefined;
-    ensureObserver();
-    const id = ++traceCounter;
-    const startMark = `${name}:start:${id}`;
-    const endMark = `${name}:end:${id}`;
-    const runInCapturedContext = AsyncLocalStorage.snapshot();
-    let finished = false;
-    performance.mark(startMark);
-    return (ok) => {
-        if (finished)
-            return;
-        finished = true;
-        try {
-            runInCapturedContext(() => {
-                try {
-                    performance.mark(endMark);
-                    let meta = enrichWithToolContext(detail);
-                    if (ok !== undefined) {
-                        meta = { ...(meta ?? {}), ok };
-                    }
-                    performance.measure(name, {
-                        start: startMark,
-                        end: endMark,
-                        detail: meta,
-                    });
-                }
-                finally {
-                    clearMeasureMarks(startMark, endMark);
-                }
-            });
-        }
-        catch {
-            clearMeasureMarks(startMark, endMark);
-        }
-    };
-}
-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, 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) {
-    const elu = performance.eventLoopUtilization(eluStart);
-    const event = {
-        phase: 'end',
-        tool,
-        durationMs,
-        elu: { idle: elu.idle, active: elu.active, utilization: elu.utilization },
-    };
-    if (loopMonitor) {
-        const delays = getDelayStats(loopMonitor);
-        if (delays)
-            event.eventLoopDelay = delays;
-    }
-    CHANNELS.perf.publish(event);
-}
-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, traceparent);
-    let result;
-    const obs = { ok: false, errorMsg: undefined };
-    try {
-        result = await run();
-        const { ok, error } = extractOutcome(result);
-        obs.ok = ok;
-        obs.errorMsg = error;
-    }
-    catch (err) {
-        obs.errorMsg = extractErrorMessage(err);
-        throw err;
-    }
-    finally {
-        const durationMs = performance.now() - startMs;
-        loopMonitor?.disable();
-        if (pubPerf && eluStart)
-            publishPerfEnd(tool, durationMs, eluStart, loopMonitor);
-        if (pubTool)
-            publishToolEnd(tool, obs.ok, durationMs, obs.errorMsg, traceparent);
-        updateMetrics(tool, obs.ok, durationMs);
-        if (logErrors && !obs.ok)
-            logError(tool, durationMs, obs.errorMsg);
-    }
-    return result;
-}
-export async function withToolDiagnostics(tool, run, options) {
-    const config = readConfig();
-    const normalizedPath = sanitizePathForDiagnostics(options?.path);
-    const context = {
-        tool,
-        ...(options?.path ? { path: options.path } : {}),
-        ...(options?.traceContext ? { traceContext: options.traceContext } : {}),
-    };
-    return toolContext.run(context, async () => {
-        if (!config.enabled) {
-            if (!config.logToolErrors)
-                return run();
-            const start = performance.now();
-            try {
-                const res = await run();
-                const { ok, error } = extractOutcome(res);
-                if (!ok)
-                    logError(tool, performance.now() - start, error);
-                return res;
-            }
-            catch (e) {
-                logError(tool, performance.now() - start, extractErrorMessage(e));
-                throw e;
-            }
-        }
-        const pubTool = CHANNELS.tool.hasSubscribers;
-        const pubPerf = CHANNELS.perf.hasSubscribers;
-        if (!pubTool && !pubPerf) {
-            const start = performance.now();
-            try {
-                const res = await run();
-                const duration = performance.now() - start;
-                const { ok } = extractOutcome(res);
-                updateMetrics(tool, ok, duration);
-                return res;
-            }
-            catch (e) {
-                const duration = performance.now() - start;
-                updateMetrics(tool, false, duration);
-                throw e;
-            }
-        }
-        return runAndObserve(tool, run, pubTool, pubPerf, config.logToolErrors, normalizedPath, options?.traceContext?.traceparent);
-    });
-}
-function logError(tool, durationMs, msg) {
-    const suffix = msg ? `: ${msg}` : '';
-    Logger.error(`[ToolError] ${tool} failed in ${durationMs.toFixed(1)}ms${suffix}`);
-}

package/dist/lib/paths.d.ts

@@ -1,35 +0,0 @@
-import type { Root } from '@modelcontextprotocol/server';
-export declare function toPosixPath(value: string): string;
-export declare function isSensitivePath(requestedPath: string, resolvedPath?: string): boolean;
-export declare function assertAllowedFileAccess(requestedPath: string, resolvedPath?: string): void;
-export interface AllowedDirectoriesState {
-    primary: string[];
-    expanded: string[];
-}
-/**
- * Normalizes any path-like input to an absolute path suitable for comparisons.
- * - Expands "~" home directory shorthand.
- * - Resolves against process CWD if relative.
- * - Lowercases Windows drive letter for stable comparisons.
- */
-export declare function normalizePath(p: string): string;
-export declare function withAllowedDirectoriesState<T>(state: AllowedDirectoriesState, run: () => T): T;
-export declare function setAllowedDirectoriesStateResolved(state: AllowedDirectoriesState): void;
-export declare function getAllowedDirectories(): string[];
-export declare function isAllowedDirectoryRoot(normalizedPath: string): boolean;
-export declare function isPathWithinDirectories(normalizedPath: string, allowedDirs: readonly string[]): boolean;
-export declare function resolveAllowedDirectoriesState(dirs: readonly string[], signal?: AbortSignal): Promise<AllowedDirectoriesState>;
-export declare function setAllowedDirectoriesResolved(dirs: readonly string[], signal?: AbortSignal): Promise<void>;
-export declare function getReservedDeviceNameForPath(requestedPath: string): string | undefined;
-export declare function isWindowsDriveRelativePath(requestedPath: string): boolean;
-interface ValidatedPathDetails {
-    requestedPath: string;
-    resolvedPath: string;
-    isSymlink: boolean;
-}
-export declare function validateExistingPathDetailed(requestedPath: string, signal?: AbortSignal): Promise<ValidatedPathDetails>;
-export declare function validateExistingPath(requestedPath: string, signal?: AbortSignal): Promise<string>;
-export declare function validateExistingDirectory(requestedPath: string, signal?: AbortSignal): Promise<string>;
-export declare function validatePathForWrite(requestedPath: string, signal?: AbortSignal): Promise<string>;
-export declare function getValidRootDirectories(roots: Root[], signal?: AbortSignal): Promise<string[]>;
-export {};