@j0hanz/filesystem-mcp 1.9.1 → 1.11.0

package/README.md

@@ -6,7 +6,7 @@
 
 [![Add to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40j0hanz%2Ffilesystem-mcp%40latest&id=%40j0hanz%2Ffilesystem-mcp&name=filesystem-mcp&description=MCP%20Server%20that%20enables%20LLMs%20to%20interact%20with%20the%20local%20filesystem.)
 
-MCP Server that enables LLMs to interact with the local filesystem. Provides 18 tools for navigation, search, file management, and analysis — all scoped to allowed directories.
+A local filesystem MCP server that lets LLMs and AI agents read, write, search, diff, patch, and manage files safely and efficiently. Built for reliable, structured, and controlled filesystem interaction.
 
 ## Overview
 
@@ -484,7 +484,7 @@ Make precise, targeted edits to source files. Use `edit` for surgical replacemen
 
 ### Diff and Patch Workflow
 
-Compare file versions and apply patches. Generate a unified diff with `diff_files`, preview with `apply_patch(dryRun: true)`, then apply. Useful for code review assistance and conflict resolution.
+Compare file versions and apply patches. Generate a unified diff with `diff_files`, preview with `apply_patch(dryRun: true)`, then apply. Supports both single-file and multi-file patches (best-effort per file with per-file `results[]`).
 
 **Relevant tools:** `diff_files`, `apply_patch`
 
@@ -762,15 +762,15 @@ Generate a unified diff between two files. Output feeds directly into `apply_pat
 
 #### `apply_patch`
 
-Apply a unified diff patch to a file. Workflow: `diff_files` -> `apply_patch(dryRun)` -> `apply_patch`.
+Apply a unified diff patch to one or more files. Single-file: throws on failure. Multi-file: best-effort per file with `results[]`. Workflow: `diff_files` -> `apply_patch(dryRun)` -> `apply_patch`.
 
-| Parameter                | Type    | Required | Description                                |
-| ------------------------ | ------- | -------- | ------------------------------------------ |
-| `path`                   | string  | **yes**  | Path to file to patch                      |
-| `patch`                  | string  | **yes**  | Unified diff with `@@` hunk headers        |
-| `fuzzFactor`             | integer | no       | Max fuzzy mismatches per hunk (0-20)       |
-| `autoConvertLineEndings` | boolean | no       | Auto-convert line endings. Default: `true` |
-| `dryRun`                 | boolean | no       | Validate without writing. Default: `false` |
+| Parameter                | Type    | Required | Description                                                |
+| ------------------------ | ------- | -------- | ---------------------------------------------------------- |
+| `path`                   | string  | **yes**  | Path to file (single) or base directory (multi-file patch) |
+| `patch`                  | string  | **yes**  | Unified diff with `@@` hunk headers (single or multi-file) |
+| `fuzzFactor`             | integer | no       | Max fuzzy mismatches per hunk (0-20)                       |
+| `autoConvertLineEndings` | boolean | no       | Auto-convert line endings. Default: `true`                 |
+| `dryRun`                 | boolean | no       | Validate without writing. Default: `false`                 |
 
 ---
 

package/dist/completions.js

@@ -5,6 +5,7 @@ import { getAllowedDirectories, isPathWithinDirectories, normalizePath, toPosixP
 import { isRecord } from './lib/utils.js';
 const MAX_COMPLETION_ITEMS = 100;
 const COMPLETION_RATE_LIMIT_MS = 100;
+const MAX_COMPLETION_CACHE_KEYS = 128;
 // WeakMap keyed by McpServer instance so that each HTTP session gets isolated
 // rate-limit state. In stdio mode there is a single server; in HTTP mode every
 // session creates its own McpServer, so cross-session cache pollution is avoided.
@@ -39,6 +40,9 @@ const PATH_ARGUMENTS = new Set([
     'root',
     'cwd',
 ]);
+const DESTINATION_CONTEXT_KEYS = ['source', 'path', 'cwd', 'root'];
+const PRIMARY_PATH_CONTEXT_KEYS = ['path', 'cwd', 'root'];
+const DEFAULT_CONTEXT_KEYS = ['path', 'source', 'cwd', 'root'];
 function isPathLikeArgumentName(argName) {
     return (PATH_ARGUMENTS.has(argName) ||
         argName.endsWith('paths') ||
@@ -48,6 +52,22 @@ function isPathLikeArgumentName(argName) {
         argName.endsWith('dirs') ||
         argName.endsWith('dir'));
 }
+function isTemplateVariableChar(char) {
+    const code = char.charCodeAt(0);
+    const isDigit = code >= 48 && code <= 57;
+    const isUpper = code >= 65 && code <= 90;
+    const isLower = code >= 97 && code <= 122;
+    return isDigit || isUpper || isLower || code === 95;
+}
+function normalizeTemplateVariable(raw) {
+    let normalized = '';
+    for (const char of raw) {
+        if (isTemplateVariableChar(char)) {
+            normalized += char.toLowerCase();
+        }
+    }
+    return normalized;
+}
 function parseResourceReference(value) {
     if (!isRecord(value))
         return undefined;
@@ -60,13 +80,6 @@ function parseResourceReference(value) {
 }
 function extractTemplateVariables(uri) {
     const vars = [];
-    const isVariableChar = (char) => {
-        const code = char.charCodeAt(0);
-        const isDigit = code >= 48 && code <= 57;
-        const isUpper = code >= 65 && code <= 90;
-        const isLower = code >= 97 && code <= 122;
-        return isDigit || isUpper || isLower || code === 95;
-    };
     let index = 0;
     while (index < uri.length) {
         const start = uri.indexOf('{', index);
@@ -75,13 +88,7 @@ function extractTemplateVariables(uri) {
         const end = uri.indexOf('}', start + 1);
         if (end === -1)
             break;
-        const raw = uri.slice(start + 1, end);
-        let normalized = '';
-        for (const char of raw) {
-            if (isVariableChar(char)) {
-                normalized += char.toLowerCase();
-            }
-        }
+        const normalized = normalizeTemplateVariable(uri.slice(start + 1, end));
         if (normalized.length > 0)
             vars.push(normalized);
         index = end + 1;
@@ -129,6 +136,43 @@ function extractContextArguments(value) {
         return undefined;
     return normalized;
 }
+function serializeCompletionRef(ref) {
+    if (!isRecord(ref) || typeof ref['type'] !== 'string') {
+        return { type: 'unknown' };
+    }
+    if (ref['type'] === 'ref/prompt' && typeof ref['name'] === 'string') {
+        return { type: ref['type'], name: ref['name'] };
+    }
+    if (ref['type'] === 'ref/resource' && typeof ref['uri'] === 'string') {
+        return { type: ref['type'], uri: ref['uri'] };
+    }
+    return { type: ref['type'] };
+}
+function serializeContextArguments(contextArguments) {
+    if (!contextArguments)
+        return [];
+    return Object.entries(contextArguments).sort(([left], [right]) => left.localeCompare(right));
+}
+function buildCompletionCacheKey(params) {
+    return JSON.stringify({
+        argumentName: params.argumentName.toLowerCase(),
+        value: params.value,
+        ref: serializeCompletionRef(params.ref),
+        contextArguments: serializeContextArguments(params.contextArguments),
+    });
+}
+function rememberCompletionCacheValue(cache, key, value) {
+    if (cache.has(key)) {
+        cache.delete(key);
+    }
+    cache.set(key, value);
+    while (cache.size > MAX_COMPLETION_CACHE_KEYS) {
+        const oldest = cache.keys().next();
+        if (oldest.done)
+            break;
+        cache.delete(oldest.value);
+    }
+}
 function hasTrailingSeparator(value) {
     return (value.endsWith(path.sep) || value.endsWith('/') || value.endsWith('\\'));
 }
@@ -180,16 +224,19 @@ function findAllowedRootByName(rootName, allowed) {
 function chooseContextKeys(argumentName) {
     const normalized = argumentName.toLowerCase();
     if (normalized === 'destination') {
-        return ['source', 'path', 'cwd', 'root'];
+        return [...DESTINATION_CONTEXT_KEYS];
     }
     if (normalized === 'path' ||
         normalized === 'source' ||
         normalized === 'original' ||
         normalized === 'modified' ||
         normalized === 'file') {
-        return ['path', 'cwd', 'root'];
+        return [...PRIMARY_PATH_CONTEXT_KEYS];
     }
-    return ['path', 'source', 'cwd', 'root'];
+    return [...DEFAULT_CONTEXT_KEYS];
+}
+function hasContextArguments(contextArguments) {
+    return (contextArguments !== undefined && Object.keys(contextArguments).length > 0);
 }
 function resolveContextCandidatePath(candidate, allowed) {
     if (isAbsolutePathInput(candidate)) {
@@ -218,17 +265,7 @@ async function toAllowedContextDirectory(resolved, allowed) {
     return isPathWithinDirectories(parent, allowed) ? parent : undefined;
 }
 async function resolveContextBaseDirectory(argumentName, contextArguments, allowed) {
-    if (!contextArguments) {
-        return undefined;
-    }
-    let hasContextArgument = false;
-    for (const key in contextArguments) {
-        if (!Object.prototype.hasOwnProperty.call(contextArguments, key))
-            continue;
-        hasContextArgument = true;
-        break;
-    }
-    if (!hasContextArgument) {
+    if (!hasContextArguments(contextArguments)) {
         return undefined;
     }
     const keys = chooseContextKeys(argumentName);
@@ -245,6 +282,54 @@ async function resolveContextBaseDirectory(argumentName, contextArguments, allow
     }
     return undefined;
 }
+function withDirectorySeparator(value) {
+    return value.endsWith(path.sep) ? value : `${value}${path.sep}`;
+}
+function buildCompletionResult(values) {
+    return {
+        values: values.slice(0, MAX_COMPLETION_ITEMS),
+        total: values.length,
+        hasMore: values.length > MAX_COMPLETION_ITEMS,
+    };
+}
+function buildCompletionResponse(result) {
+    return { completion: result };
+}
+function sortCompletionMatches(matches) {
+    matches.sort((left, right) => {
+        const leftIsDir = left.endsWith(path.sep);
+        const rightIsDir = right.endsWith(path.sep);
+        if (leftIsDir && !rightIsDir)
+            return -1;
+        if (!leftIsDir && rightIsDir)
+            return 1;
+        return left.localeCompare(right);
+    });
+}
+function mergeCompletionMatches(...matchGroups) {
+    const uniqueMatches = new Set();
+    for (const group of matchGroups) {
+        for (const match of group) {
+            uniqueMatches.add(match);
+        }
+    }
+    const merged = [...uniqueMatches];
+    sortCompletionMatches(merged);
+    return merged;
+}
+function getRootPrefix(currentValue) {
+    const normalizedInput = toPosixPath(currentValue);
+    return (normalizedInput.split('/')[0] ?? '').toLowerCase();
+}
+function collectAllowedRoots(allowed, predicate) {
+    const matches = [];
+    for (const root of allowed) {
+        if (predicate(root)) {
+            matches.push(withDirectorySeparator(root));
+        }
+    }
+    return matches;
+}
 function getSearchContext(currentValue, allowed, contextBase) {
     const trailingSeparator = hasTrailingSeparator(currentValue);
     if (isAbsolutePathInput(currentValue)) {
@@ -290,38 +375,22 @@ async function findMatchesInDirectory(searchDir, prefix, allowed) {
     return matches;
 }
 function findRootPrefixMatches(currentValue, allowed) {
-    const normalizedInput = toPosixPath(currentValue);
-    const rootPrefix = (normalizedInput.split('/')[0] ?? '').toLowerCase();
+    const rootPrefix = getRootPrefix(currentValue);
     if (!rootPrefix) {
-        const matches = [];
-        for (const root of allowed) {
-            matches.push(`${root}${path.sep}`);
-        }
-        return matches;
+        return collectAllowedRoots(allowed, () => true);
     }
-    const matches = [];
-    for (const root of allowed) {
-        if (!path.basename(root).toLowerCase().startsWith(rootPrefix))
-            continue;
-        matches.push(`${root}${path.sep}`);
-    }
-    return matches;
+    return collectAllowedRoots(allowed, (root) => path.basename(root).toLowerCase().startsWith(rootPrefix));
 }
 function findMatchingRoots(searchDir, prefix, allowed) {
-    const matches = [];
     const lowerPrefix = prefix.toLowerCase();
     const normalizedSearchDir = normalizePath(searchDir);
-    for (const root of allowed) {
+    return collectAllowedRoots(allowed, (root) => {
         const rootDir = path.dirname(root);
         // Check if root is a direct child of searchDir
-        if (normalizePath(rootDir) === normalizedSearchDir) {
-            const rootName = path.basename(root);
-            if (rootName.toLowerCase().startsWith(lowerPrefix)) {
-                matches.push(`${root}${path.sep}`);
-            }
-        }
-    }
-    return matches;
+        if (normalizePath(rootDir) !== normalizedSearchDir)
+            return false;
+        return path.basename(root).toLowerCase().startsWith(lowerPrefix);
+    });
 }
 export async function getPathCompletions(currentValue, options = {}) {
     const allowed = getAllowedDirectories();
@@ -329,47 +398,16 @@ export async function getPathCompletions(currentValue, options = {}) {
         const contextBase = await resolveContextBaseDirectory(options.argumentName ?? '', options.contextArguments, allowed);
         // If no value and no context base, suggest roots.
         if (!currentValue && !contextBase) {
-            return {
-                values: allowed,
-                total: allowed.length,
-                hasMore: false,
-            };
+            return buildCompletionResult(allowed);
         }
         const context = getSearchContext(currentValue, allowed, contextBase);
         if (!context) {
-            const rootMatches = findRootPrefixMatches(currentValue, allowed);
-            const sliced = rootMatches.slice(0, MAX_COMPLETION_ITEMS);
-            return {
-                values: sliced,
-                total: rootMatches.length,
-                hasMore: rootMatches.length > MAX_COMPLETION_ITEMS,
-            };
+            return buildCompletionResult(findRootPrefixMatches(currentValue, allowed));
         }
         const { searchDir, prefix } = context;
         const dirMatches = await findMatchesInDirectory(searchDir, prefix, allowed);
         const rootMatches = findMatchingRoots(searchDir, prefix, allowed);
-        // Deduplicate and sort
-        const unique = new Set();
-        for (const match of dirMatches)
-            unique.add(match);
-        for (const match of rootMatches)
-            unique.add(match);
-        const uniqueMatches = Array.from(unique);
-        uniqueMatches.sort((a, b) => {
-            const aIsDir = a.endsWith(path.sep);
-            const bIsDir = b.endsWith(path.sep);
-            if (aIsDir && !bIsDir)
-                return -1;
-            if (!aIsDir && bIsDir)
-                return 1;
-            return a.localeCompare(b);
-        });
-        const sliced = uniqueMatches.slice(0, MAX_COMPLETION_ITEMS);
-        return {
-            values: sliced,
-            total: uniqueMatches.length,
-            hasMore: uniqueMatches.length > MAX_COMPLETION_ITEMS,
-        };
+        return buildCompletionResult(mergeCompletionMatches(dirMatches, rootMatches));
     }
     catch {
         return { values: [] };
@@ -387,50 +425,37 @@ export function registerCompletions(server, instructions = '') {
             const filtered = currentValue
                 ? topicValues.filter((v) => v.startsWith(currentValue))
                 : topicValues;
-            const sliced = filtered.slice(0, MAX_COMPLETION_ITEMS);
-            return {
-                completion: {
-                    values: sliced,
-                    total: filtered.length,
-                    hasMore: filtered.length > MAX_COMPLETION_ITEMS,
-                },
-            };
+            return buildCompletionResponse(buildCompletionResult(filtered));
         }
         const isPathArg = isPathLikeArgumentName(argName) ||
             isPathArgumentFromReference(argName, ref);
         if (!isPathArg) {
-            return { completion: { values: [], total: 0, hasMore: false } };
+            return buildCompletionResponse(buildCompletionResult([]));
         }
+        const contextArguments = extractContextArguments(params.context);
+        const cacheKey = buildCompletionCacheKey({
+            argumentName: argName,
+            value: argument.value,
+            ref,
+            ...(contextArguments ? { contextArguments } : {}),
+        });
         const now = Date.now();
         const sessionState = getCompletionState(server);
-        const lastCallMs = sessionState.lastCallMs.get(argName) ?? 0;
+        const lastCallMs = sessionState.lastCallMs.get(cacheKey) ?? 0;
         if (now - lastCallMs < COMPLETION_RATE_LIMIT_MS) {
-            const lastResult = sessionState.lastResult.get(argName);
+            const lastResult = sessionState.lastResult.get(cacheKey);
             if (lastResult) {
-                return {
-                    completion: {
-                        values: lastResult.values,
-                        total: lastResult.total,
-                        hasMore: lastResult.hasMore,
-                    },
-                };
+                return buildCompletionResponse(lastResult);
             }
-            return { completion: { values: [], total: 0, hasMore: false } };
+            return buildCompletionResponse(buildCompletionResult([]));
         }
-        sessionState.lastCallMs.set(argName, now);
-        const contextArguments = extractContextArguments(params.context);
+        rememberCompletionCacheValue(sessionState.lastCallMs, cacheKey, now);
         const { value } = argument;
         const completions = await getPathCompletions(value, {
             argumentName: argName,
             ...(contextArguments ? { contextArguments } : {}),
         });
-        sessionState.lastResult.set(argName, completions);
-        return {
-            completion: {
-                values: completions.values,
-                total: completions.total,
-                hasMore: completions.hasMore,
-            },
-        };
+        rememberCompletionCacheValue(sessionState.lastResult, cacheKey, completions);
+        return buildCompletionResponse(completions);
     });
 }

package/dist/lib/constants.d.ts

@@ -2,6 +2,7 @@ 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 REQUIRED_MCP_PROTOCOL_VERSION = "2025-11-25";
+export declare const DEFAULT_TASK_TTL_MS: number;
 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

@@ -71,6 +71,8 @@ function parseEnvLogLevel(envVar, defaultValue) {
 }
 export const DEFAULT_LOG_LEVEL = parseEnvLogLevel('FILESYSTEM_MCP_LOG_LEVEL', 'info');
 export const REQUIRED_MCP_PROTOCOL_VERSION = '2025-11-25';
+// Default TTL for MCP tasks when the client does not specify one (5 minutes).
+export const DEFAULT_TASK_TTL_MS = 5 * 60 * 1000;
 // 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/file-operations/metadata.d.ts

@@ -24,6 +24,7 @@ interface TreeEntry {
     name: string;
     type: EntryType;
     relativePath: string;
+    size?: number;
     children?: TreeEntry[];
 }
 interface TreeOptions {
@@ -31,6 +32,7 @@ interface TreeOptions {
     maxEntries?: number;
     includeHidden?: boolean;
     includeIgnored?: boolean;
+    includeSizes?: boolean;
     timeoutMs?: number;
     signal?: AbortSignal;
     onProgress?: (progress: {
@@ -51,8 +53,9 @@ interface ReadMultipleResult {
     content?: string;
     truncated?: boolean;
     totalLines?: number;
-    readMode?: 'full' | 'head' | 'range';
+    readMode?: 'full' | 'head' | 'tail' | 'range';
     head?: number;
+    tail?: number;
     startLine?: number;
     endLine?: number;
     linesRead?: number;
@@ -64,6 +67,7 @@ interface ReadMultipleOptions {
     maxSize?: number;
     maxTotalSize?: number;
     head?: number;
+    tail?: number;
     startLine?: number;
     endLine?: number;
     signal?: AbortSignal;

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

@@ -408,6 +408,7 @@ function normalizeTreeOptions(options) {
         maxEntries: toSafeNonNegativeInt(options.maxEntries, 1000),
         includeHidden: toSafeBoolean(options.includeHidden, false),
         includeIgnored: toSafeBoolean(options.includeIgnored, false),
+        includeSizes: toSafeBoolean(options.includeSizes, false),
         timeoutMs: toSafePositiveInt(options.timeoutMs, DEFAULT_SEARCH_TIMEOUT_MS),
     };
 }
@@ -608,7 +609,7 @@ export async function treeDirectory(dirPath, options = {}) {
             maxDepth: normalized.maxDepth,
             followSymbolicLinks: false,
             onlyFiles: false,
-            stats: false,
+            stats: normalized.includeSizes,
             suppressErrors: true,
         });
         for await (const entry of stream) {
@@ -629,6 +630,14 @@ export async function treeDirectory(dirPath, options = {}) {
             }
             const parent = ensureParentNodes(rootNode, nodeByPath, resolved.relativePosix);
             upsertChildNode(parent, nodeByPath, resolved, childPathIndexByParent);
+            if (normalized.includeSizes &&
+                resolved.type === 'file' &&
+                entry.stats) {
+                const node = nodeByPath.get(resolved.relativePosix);
+                if (node) {
+                    node.size = entry.stats.size;
+                }
+            }
             totalEntries += 1;
             options.onProgress?.({ current: totalEntries });
         }
@@ -665,6 +674,8 @@ function buildReadMultipleResult(filePath, result) {
         output.totalLines = result.totalLines;
     if (result.head !== undefined)
         output.head = result.head;
+    if (result.tail !== undefined)
+        output.tail = result.tail;
     if (result.startLine !== undefined)
         output.startLine = result.startLine;
     if (result.endLine !== undefined)
@@ -709,6 +720,8 @@ function normalizeReadMultipleOptions(options) {
 function applyLineSelection(target, source) {
     if (source.head !== undefined)
         target.head = source.head;
+    if (source.tail !== undefined)
+        target.tail = source.tail;
     if (source.startLine !== undefined)
         target.startLine = source.startLine;
     if (source.endLine !== undefined)

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

@@ -5,6 +5,7 @@ export declare const MatcherOptionsSchema: z.ZodObject<{
     caseSensitive: z.ZodBoolean;
     wholeWord: z.ZodBoolean;
     isLiteral: z.ZodBoolean;
+    multiline: z.ZodBoolean;
 }, z.core.$strict>;
 export type MatcherOptions = z.infer<typeof MatcherOptionsSchema>;
 export type Matcher = (line: string) => number;
@@ -27,6 +28,7 @@ declare const SearchOptionsSchema: z.ZodObject<{
     contextLines: z.ZodInt;
     wholeWord: z.ZodBoolean;
     isLiteral: z.ZodBoolean;
+    multiline: z.ZodBoolean;
     includeHidden: z.ZodBoolean;
     baseNameMatch: z.ZodBoolean;
     caseSensitiveFileMatch: z.ZodBoolean;