@j0hanz/filesystem-mcp 1.8.0 → 1.9.0

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

@@ -1,265 +0,0 @@
-import * as path from 'node:path';
-import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_SEARCH_TIMEOUT_MS, } from '../constants.js';
-import { withTimedAbortSignal } from '../fs-helpers.js';
-import { toPosixPath } from '../path-format.js';
-import { isSensitivePath } from '../path-policy.js';
-import { isPathWithinDirectories, normalizePath, validateExistingDirectory, validateExistingPathDetailed, } from '../path-validation.js';
-import { isEntryAccessibleByType, resolveEntryType, resolveStopReason, } from './common.js';
-import { isIgnoredByGitignore, loadRootGitignore } from './gitignore.js';
-import { globEntries } from './glob-engine.js';
-function toSafeNonNegativeInt(value, fallback) {
-    if (typeof value !== 'number' || !Number.isFinite(value))
-        return fallback;
-    const asInt = Math.floor(value);
-    return asInt >= 0 ? asInt : fallback;
-}
-function toSafePositiveInt(value, fallback) {
-    if (typeof value !== 'number' || !Number.isFinite(value))
-        return fallback;
-    const asInt = Math.floor(value);
-    return asInt > 0 ? asInt : fallback;
-}
-function toSafeBoolean(value, fallback) {
-    if (typeof value !== 'boolean')
-        return fallback;
-    return value;
-}
-function normalizeOptions(options) {
-    return {
-        maxDepth: toSafeNonNegativeInt(options.maxDepth, 5),
-        maxEntries: toSafeNonNegativeInt(options.maxEntries, 1000),
-        includeHidden: toSafeBoolean(options.includeHidden, false),
-        includeIgnored: toSafeBoolean(options.includeIgnored, false),
-        timeoutMs: toSafePositiveInt(options.timeoutMs, DEFAULT_SEARCH_TIMEOUT_MS),
-    };
-}
-function ensureParentNodes(rootNode, nodeByPath, relativePath) {
-    const normalized = toPosixPath(relativePath);
-    if (normalized.length === 0 || normalized === '.')
-        return rootNode;
-    const segments = [];
-    for (const segment of normalized.split('/')) {
-        if (segment.length > 0) {
-            segments.push(segment);
-        }
-    }
-    const parentSegmentCount = Math.max(0, segments.length - 1);
-    let current = rootNode;
-    let currentPath = '';
-    for (let index = 0; index < parentSegmentCount; index += 1) {
-        const segment = segments[index];
-        if (!segment)
-            continue;
-        currentPath =
-            currentPath.length === 0
-                ? segment
-                : path.posix.join(currentPath, segment);
-        let child = nodeByPath.get(currentPath);
-        if (!child) {
-            child = {
-                name: segment,
-                type: 'directory',
-                relativePath: currentPath,
-                children: [],
-            };
-            nodeByPath.set(currentPath, child);
-            current.children ??= [];
-            current.children.push(child);
-        }
-        current = child;
-    }
-    return current;
-}
-function sortTree(node) {
-    if (!node.children)
-        return;
-    node.children.sort(compareTreeEntries);
-    for (const child of node.children) {
-        sortTree(child);
-    }
-}
-function compareTreeEntries(a, b) {
-    const diff = getTreeTypeRank(a.type) - getTreeTypeRank(b.type);
-    if (diff !== 0)
-        return diff;
-    return a.name.localeCompare(b.name);
-}
-function getTreeTypeRank(type) {
-    if (type === 'directory')
-        return 0;
-    if (type === 'file')
-        return 1;
-    return 2;
-}
-async function resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal, accessDeps) {
-    const type = resolveEntryType(entry.dirent);
-    const isAccessible = await isEntryAccessibleByType(entry.path, type, rootDirectories, signal, accessDeps);
-    if (!isAccessible) {
-        return null;
-    }
-    if (gitignoreMatcher &&
-        isIgnoredByGitignore(gitignoreMatcher, root, entry.path, {
-            isDirectory: type === 'directory',
-        })) {
-        return null;
-    }
-    const relative = path.relative(root, entry.path) || path.basename(entry.path);
-    const relativePosix = toPosixPath(relative);
-    const name = path.basename(entry.path);
-    return { type, relativePosix, name };
-}
-function upsertChildNode(parent, nodeByPath, resolved, childPathIndexByParent) {
-    const ensureDirectoryShape = (node) => {
-        if (node.type === 'directory') {
-            node.children ??= [];
-        }
-        else {
-            delete node.children;
-        }
-    };
-    const maybeUpdateType = (existing, nextType) => {
-        if (existing.type === nextType)
-            return;
-        const preservePopulatedDirectory = existing.type === 'directory' &&
-            Array.isArray(existing.children) &&
-            existing.children.length > 0;
-        if (preservePopulatedDirectory)
-            return;
-        existing.type = nextType;
-        ensureDirectoryShape(existing);
-    };
-    const attachChild = (child) => {
-        parent.children ??= [];
-        let seen = childPathIndexByParent.get(parent);
-        if (!seen) {
-            seen = new Set();
-            for (const entry of parent.children) {
-                seen.add(entry.relativePath);
-            }
-            childPathIndexByParent.set(parent, seen);
-        }
-        const key = child.relativePath;
-        if (seen.has(key))
-            return;
-        seen.add(key);
-        parent.children.push(child);
-    };
-    const existing = nodeByPath.get(resolved.relativePosix);
-    if (existing) {
-        // Avoid duplicate directory nodes when a child file is encountered before the directory entry.
-        // Prefer preserving an existing populated directory node over overwriting it.
-        maybeUpdateType(existing, resolved.type);
-        existing.name = resolved.name;
-        existing.relativePath = resolved.relativePosix;
-        ensureDirectoryShape(existing);
-        attachChild(existing);
-        return;
-    }
-    const node = {
-        name: resolved.name,
-        type: resolved.type,
-        relativePath: resolved.relativePosix,
-        ...(resolved.type === 'directory' ? { children: [] } : {}),
-    };
-    nodeByPath.set(resolved.relativePosix, node);
-    attachChild(node);
-}
-export function formatTreeAscii(tree) {
-    const lines = [];
-    const walk = (node, prefix, isLast, isRoot) => {
-        let connector = '';
-        let linePrefix = '';
-        if (!isRoot) {
-            connector = isLast ? '└── ' : '├── ';
-            linePrefix = prefix;
-        }
-        lines.push(`${linePrefix}${connector}${node.name}`);
-        if (!node.children || node.children.length === 0)
-            return;
-        let nextPrefix = '';
-        if (!isRoot) {
-            const continuation = isLast ? '    ' : '│   ';
-            nextPrefix = `${prefix}${continuation}`;
-        }
-        const count = node.children.length;
-        for (let index = 0; index < count; index += 1) {
-            const child = node.children[index];
-            if (child) {
-                walk(child, nextPrefix, index === count - 1, false);
-            }
-        }
-    };
-    walk(tree, '', true, true);
-    return lines.join('\n');
-}
-export async function treeDirectory(dirPath, options = {}) {
-    const normalized = normalizeOptions(options);
-    return withTimedAbortSignal(options.signal, normalized.timeoutMs, async (signal) => {
-        const root = await validateExistingDirectory(dirPath, signal);
-        const rootNormalized = normalizePath(root);
-        const rootDirectories = [rootNormalized];
-        const accessDeps = {
-            normalizePath,
-            isPathWithinDirectories,
-            isSensitivePath,
-            validateSymlinkPath: validateExistingPathDetailed,
-        };
-        const excludePatterns = normalized.includeIgnored
-            ? []
-            : DEFAULT_EXCLUDE_PATTERNS;
-        const gitignoreMatcher = normalized.includeIgnored
-            ? null
-            : await loadRootGitignore(root, signal);
-        const rootNode = {
-            name: path.basename(root) || root,
-            type: 'directory',
-            relativePath: '.',
-            children: [],
-        };
-        const nodeByPath = new Map();
-        const childPathIndexByParent = new WeakMap();
-        let totalEntries = 0;
-        let truncated = false;
-        const stream = globEntries({
-            cwd: root,
-            pattern: '**/*',
-            excludePatterns,
-            includeHidden: normalized.includeHidden,
-            baseNameMatch: false,
-            caseSensitiveMatch: true,
-            maxDepth: normalized.maxDepth,
-            followSymbolicLinks: false,
-            onlyFiles: false,
-            stats: false,
-            suppressErrors: true,
-        });
-        for await (const entry of stream) {
-            const stopReason = resolveStopReason({
-                signal,
-                current: totalEntries,
-                max: normalized.maxEntries,
-                abortedReason: 'aborted',
-                maxReason: 'maxEntries',
-            });
-            if (stopReason) {
-                truncated = true;
-                break;
-            }
-            const resolved = await resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal, accessDeps);
-            if (!resolved) {
-                continue;
-            }
-            const parent = ensureParentNodes(rootNode, nodeByPath, resolved.relativePosix);
-            upsertChildNode(parent, nodeByPath, resolved, childPathIndexByParent);
-            totalEntries += 1;
-            options.onProgress?.({ current: totalEntries });
-        }
-        sortTree(rootNode);
-        return {
-            root,
-            tree: rootNode,
-            truncated,
-            totalEntries,
-        };
-    });
-}

package/dist/lib/option-utils.d.ts

@@ -1,3 +0,0 @@
-export declare function mergeOptions<T extends object>(defaults: T, overrides: Partial<T>): T;
-export declare function omitOptionKeys<T extends object, K extends keyof T>(input: T, keys: readonly K[]): Omit<T, K>;
-export declare function setIfDefined<T extends object, K extends keyof T>(target: T, key: K, value: T[K] | undefined): void;

package/dist/lib/option-utils.js

@@ -1,15 +0,0 @@
-export function mergeOptions(defaults, overrides) {
-    return { ...defaults, ...overrides };
-}
-export function omitOptionKeys(input, keys) {
-    const output = { ...input };
-    for (const key of keys) {
-        Reflect.deleteProperty(output, key);
-    }
-    return output;
-}
-export function setIfDefined(target, key, value) {
-    if (value !== undefined) {
-        target[key] = value;
-    }
-}

package/dist/lib/path-format.d.ts

@@ -1 +0,0 @@
-export declare function toPosixPath(value: string): string;

package/dist/lib/path-format.js

@@ -1,7 +0,0 @@
-const WINDOWS_PATH_SEPARATOR = '\\';
-const POSIX_PATH_SEPARATOR = '/';
-export function toPosixPath(value) {
-    return value.includes(WINDOWS_PATH_SEPARATOR)
-        ? value.replace(/\\/gu, POSIX_PATH_SEPARATOR)
-        : value;
-}

package/dist/lib/path-policy.d.ts

@@ -1,2 +0,0 @@
-export declare function isSensitivePath(requestedPath: string, resolvedPath?: string): boolean;
-export declare function assertAllowedFileAccess(requestedPath: string, resolvedPath?: string): void;

package/dist/lib/path-policy.js

@@ -1,100 +0,0 @@
-import * as path from 'node:path';
-import { platform } from 'node:os';
-import { SENSITIVE_FILE_ALLOWLIST, SENSITIVE_FILE_DENYLIST, } from './constants.js';
-import { ErrorCode, McpError } from './errors.js';
-import { toPosixPath } from './path-format.js';
-const IS_WINDOWS = platform() === 'win32';
-const WINDOWS_ABSOLUTE_RE = /^[a-z]:\//iu;
-function normalizePathForMatch(input) {
-    return toPosixPath(path.normalize(input));
-}
-function normalizeForMatch(input) {
-    const normalized = normalizePathForMatch(input);
-    return IS_WINDOWS ? normalized.toLowerCase() : normalized;
-}
-function compilePatternGlobs(normalizedPattern) {
-    const globs = new Set([normalizedPattern]);
-    const isWindowsAbsolute = WINDOWS_ABSOLUTE_RE.test(normalizedPattern);
-    if (!normalizedPattern.startsWith('**/') && !isWindowsAbsolute) {
-        const withoutRoot = normalizedPattern.replace(/^\/+/u, '');
-        if (withoutRoot.length > 0) {
-            globs.add(`**/${withoutRoot}`);
-        }
-    }
-    return [...globs];
-}
-function compilePatterns(patterns) {
-    const unique = new Set();
-    for (const pattern of patterns) {
-        const trimmed = pattern.trim();
-        if (trimmed.length > 0) {
-            unique.add(trimmed);
-        }
-    }
-    const compiled = [];
-    for (const pattern of unique) {
-        const normalized = normalizeForMatch(pattern);
-        const matchesPath = normalized.includes('/');
-        compiled.push({
-            globs: matchesPath ? compilePatternGlobs(normalized) : [normalized],
-            matchesPath,
-        });
-    }
-    return compiled;
-}
-function toPatternSet(patterns) {
-    const pathGlobs = new Set();
-    const nameGlobs = new Set();
-    for (const pattern of patterns) {
-        const target = pattern.matchesPath ? pathGlobs : nameGlobs;
-        for (const glob of pattern.globs) {
-            target.add(glob);
-        }
-    }
-    return {
-        pathGlobs: [...pathGlobs],
-        nameGlobs: [...nameGlobs],
-    };
-}
-const DENY_PATTERNS = toPatternSet(compilePatterns(SENSITIVE_FILE_DENYLIST));
-const ALLOW_PATTERNS = toPatternSet(compilePatterns(SENSITIVE_FILE_ALLOWLIST));
-function uniquePair(primary, secondary) {
-    if (!secondary || secondary === primary)
-        return [primary];
-    return [primary, secondary];
-}
-function matchesAnyGlobs(globs, candidates) {
-    if (globs.length === 0 || candidates.length === 0)
-        return false;
-    for (const candidate of candidates) {
-        for (const glob of globs) {
-            if (path.posix.matchesGlob(candidate, glob))
-                return true;
-        }
-    }
-    return false;
-}
-export function isSensitivePath(requestedPath, resolvedPath) {
-    if (DENY_PATTERNS.pathGlobs.length === 0 &&
-        DENY_PATTERNS.nameGlobs.length === 0) {
-        return false;
-    }
-    const normalizedRequested = normalizeForMatch(requestedPath);
-    const normalizedResolved = resolvedPath
-        ? normalizeForMatch(resolvedPath)
-        : undefined;
-    const pathCandidates = uniquePair(normalizedRequested, normalizedResolved);
-    const nameCandidates = uniquePair(path.posix.basename(normalizedRequested), normalizedResolved ? path.posix.basename(normalizedResolved) : undefined);
-    if (matchesAnyGlobs(ALLOW_PATTERNS.pathGlobs, pathCandidates) ||
-        matchesAnyGlobs(ALLOW_PATTERNS.nameGlobs, nameCandidates)) {
-        return false;
-    }
-    return (matchesAnyGlobs(DENY_PATTERNS.pathGlobs, pathCandidates) ||
-        matchesAnyGlobs(DENY_PATTERNS.nameGlobs, nameCandidates));
-}
-export function assertAllowedFileAccess(requestedPath, resolvedPath) {
-    if (!isSensitivePath(requestedPath, resolvedPath))
-        return;
-    throw new McpError(ErrorCode.E_ACCESS_DENIED, `Access denied: sensitive file blocked by policy (${requestedPath}). ` +
-        'Set FS_CONTEXT_ALLOW_SENSITIVE=1 or use FS_CONTEXT_ALLOWLIST to override.', requestedPath);
-}

package/dist/lib/progress-reporting.d.ts

@@ -1,11 +0,0 @@
-export interface ProgressPayload {
-    current: number;
-    total?: number;
-}
-export type ProgressCallback = ((progress: ProgressPayload) => void) | undefined;
-export interface PeriodicProgressOptions {
-    total?: number;
-    throttleModulo?: number;
-    force?: boolean;
-}
-export declare function reportPeriodicProgress(onProgress: ProgressCallback, current: number, options?: PeriodicProgressOptions): void;

package/dist/lib/progress-reporting.js

@@ -1,13 +0,0 @@
-export function reportPeriodicProgress(onProgress, current, options = {}) {
-    if (!onProgress || current === 0)
-        return;
-    const throttleModulo = options.throttleModulo ?? 1;
-    const force = options.force ?? false;
-    if (!force && throttleModulo > 1 && current % throttleModulo !== 0) {
-        return;
-    }
-    onProgress({
-        current,
-        ...(options.total !== undefined ? { total: options.total } : {}),
-    });
-}

package/dist/lib/type-guards.d.ts

@@ -1 +0,0 @@
-export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/lib/type-guards.js

@@ -1,3 +0,0 @@
-export function isRecord(value) {
-    return value !== null && typeof value === 'object';
-}

package/dist/server/capabilities.d.ts

@@ -1,10 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-interface CapabilityOptions {
-    enablePromptListChanged?: boolean;
-    enableTaskToolRequests?: boolean;
-}
-type ServerCapabilities = NonNullable<ConstructorParameters<typeof McpServer>[1]>['capabilities'];
-type NonOptionalServerCapabilities = NonNullable<ServerCapabilities>;
-export declare function buildServerCapabilities(options?: CapabilityOptions): NonOptionalServerCapabilities;
-export declare function supportsTaskToolRequests(): boolean;
-export {};

package/dist/server/capabilities.js

@@ -1,48 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-let cachedTaskToolSupport;
-function detectTaskToolSupport() {
-    if (cachedTaskToolSupport !== undefined) {
-        return cachedTaskToolSupport;
-    }
-    try {
-        // Instantiate a minimal, unconnected probe server to duck-type check for
-        // task tool support. The probe has no transport or active connections, so
-        // close() only releases in-memory state; fire-and-forget is safe here.
-        const probe = new McpServer({
-            name: 'filesystem-mcp-capability-probe',
-            version: '0.0.0',
-        }, { capabilities: { tools: {} } });
-        cachedTaskToolSupport =
-            typeof probe.experimental.tasks.registerToolTask === 'function';
-        probe.close().catch(() => { });
-    }
-    catch {
-        cachedTaskToolSupport = false;
-    }
-    return cachedTaskToolSupport;
-}
-export function buildServerCapabilities(options = {}) {
-    const capabilities = {
-        logging: {},
-        resources: {},
-        tools: {},
-        prompts: options.enablePromptListChanged ? { listChanged: true } : {},
-        completions: {},
-    };
-    if (options.enableTaskToolRequests) {
-        // NOTE: enabling task tool requests requires the caller to configure
-        // an InMemoryTaskStore and InMemoryTaskMessageQueue on the McpServer.
-        // InMemoryTaskStore accumulates completed task records with no TTL eviction —
-        // suitable for short-lived stdio sessions. Long-running HTTP servers should
-        // replace it with a TTL-evicting store to avoid unbounded memory growth.
-        capabilities.tasks = {
-            list: {},
-            cancel: {},
-            requests: { tools: { call: {} } },
-        };
-    }
-    return capabilities;
-}
-export function supportsTaskToolRequests() {
-    return detectTaskToolSupport();
-}

package/dist/server/logging.d.ts

@@ -1,7 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { LoggingLevel } from '@modelcontextprotocol/sdk/types.js';
-export interface LoggingState {
-    minimumLevel: LoggingLevel;
-}
-export declare function createLoggingState(minimumLevel?: LoggingLevel): LoggingState;
-export declare function logToMcp(server: McpServer | undefined, level: LoggingLevel, data: string, minLevel?: LoggingLevel): void;

package/dist/server/logging.js

@@ -1,41 +0,0 @@
-import { formatUnknownErrorMessage } from '../lib/errors.js';
-import { isRecord } from '../lib/type-guards.js';
-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 (!isRecord(capabilities))
-        return false;
-    if (!('logging' in capabilities))
-        return false;
-    return !!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(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}`, formatUnknownErrorMessage(error));
-    });
-}

package/dist/server/types.d.ts

@@ -1,4 +0,0 @@
-export interface ServerOptions {
-    allowCwd?: boolean;
-    cliAllowedDirs?: string[];
-}

package/dist/server/types.js

@@ -1 +0,0 @@
-export {};