@j0hanz/filesystem-mcp 1.7.2 → 1.8.0

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

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export declare const MatcherOptionsSchema: z.ZodObject<{
+    caseSensitive: z.ZodBoolean;
+    wholeWord: z.ZodBoolean;
+    isLiteral: z.ZodBoolean;
+}, z.core.$strict>;
+export type MatcherOptions = z.infer<typeof MatcherOptionsSchema>;
+export type Matcher = (line: string) => number;
+export declare function validatePattern(pattern: string, options: MatcherOptions): void;
+export declare function buildMatcher(pattern: string, options: MatcherOptions): Matcher;

package/dist/lib/file-operations/search-matcher.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import RE2 from 're2';
+import safeRegex from 'safe-regex2';
+export const MatcherOptionsSchema = z.strictObject({
+    caseSensitive: z.boolean(),
+    wholeWord: z.boolean(),
+    isLiteral: z.boolean(),
+});
+function countRegexLineMatches(regex, line) {
+    regex.lastIndex = 0;
+    let count = 0;
+    while (regex.exec(line) !== null) {
+        count++;
+        if (regex.lastIndex === 0)
+            regex.lastIndex++;
+    }
+    return count;
+}
+function escapeLiteral(pattern) {
+    return pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function buildRegexPattern(pattern, options) {
+    const escaped = options.isLiteral ? escapeLiteral(pattern) : pattern;
+    return options.wholeWord ? `\\b${escaped}\\b` : escaped;
+}
+export function validatePattern(pattern, options) {
+    if (options.isLiteral && pattern.length === 0)
+        return;
+    if (options.isLiteral && !options.wholeWord)
+        return;
+    const final = buildRegexPattern(pattern, options);
+    if (!safeRegex(final)) {
+        throw new Error(`Potentially unsafe regular expression (ReDoS risk): ${pattern}`);
+    }
+}
+function buildLiteralMatcher(pattern, options) {
+    if (!options.caseSensitive) {
+        const final = escapeLiteral(pattern);
+        const regex = new RegExp(final, 'gi');
+        return (line) => countRegexLineMatches(regex, line);
+    }
+    // Fast path for case-sensitive literal
+    const needle = pattern;
+    if (needle.length === 0)
+        return () => 0;
+    return (line) => {
+        if (line.length === 0)
+            return 0;
+        let count = 0;
+        let pos = line.indexOf(needle);
+        while (pos !== -1) {
+            count++;
+            pos = line.indexOf(needle, pos + needle.length);
+        }
+        return count;
+    };
+}
+function buildRegexMatcher(final, caseSensitive) {
+    const regex = new RE2(final, caseSensitive ? 'g' : 'gi');
+    return (line) => countRegexLineMatches(regex, line);
+}
+export function buildMatcher(pattern, options) {
+    if (options.isLiteral && pattern.length === 0)
+        return () => 0;
+    if (options.isLiteral && !options.wholeWord) {
+        // fast path for simple literal search
+        return buildLiteralMatcher(pattern, options);
+    }
+    const final = buildRegexPattern(pattern, options);
+    validatePattern(pattern, options); // Re-validate to be safe
+    return buildRegexMatcher(final, options.caseSensitive);
+}

package/dist/lib/file-operations/search-worker.js

@@ -2,7 +2,9 @@ import { parentPort, threadId, workerData } from 'node:worker_threads';
 import { formatUnknownErrorMessage } from '../errors.js';
 import { isProbablyBinary } from '../fs-helpers.js';
 import { startPerfMeasure } from '../observability.js';
-import { buildMatcher, scanFileInWorker } from './search-content.js';
+import { scanFileInWorker } from './search-content.js';
+import { buildMatcher } from './search-matcher.js';
+import {} from './search-matcher.js';
 const matcherCache = new Map();
 const MAX_MATCHER_CACHE_SIZE = 100;
 function getMatcherCacheKey(pattern, options) {

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

@@ -1,7 +1,7 @@
-type TreeEntryType = 'file' | 'directory' | 'symlink' | 'other';
+import type { EntryType } from './common.js';
 interface TreeEntry {
     name: string;
-    type: TreeEntryType;
+    type: EntryType;
     relativePath: string;
     children?: TreeEntry[];
 }

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

@@ -1,11 +1,12 @@
 import * as path from 'node:path';
 import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_SEARCH_TIMEOUT_MS, } from '../constants.js';
-import { createTimedAbortSignal } from '../fs-helpers.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, resolveEntryType } from './glob-engine.js';
+import { globEntries } from './glob-engine.js';
 function toSafeNonNegativeInt(value, fallback) {
     if (typeof value !== 'number' || !Number.isFinite(value))
         return fallback;
@@ -90,36 +91,11 @@ function getTreeTypeRank(type) {
         return 1;
     return 2;
 }
-function getStopReason(signal, totalEntries, maxEntries) {
-    if (signal.aborted) {
-        return 'aborted';
-    }
-    if (totalEntries >= maxEntries) {
-        return 'maxEntries';
-    }
-    return undefined;
-}
-async function resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal) {
+async function resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal, accessDeps) {
     const type = resolveEntryType(entry.dirent);
-    if (type !== 'symlink') {
-        const normalized = normalizePath(entry.path);
-        if (!isPathWithinDirectories(normalized, rootDirectories)) {
-            return null;
-        }
-        if (isSensitivePath(entry.path, normalized)) {
-            return null;
-        }
-    }
-    else {
-        try {
-            const validated = await validateExistingPathDetailed(entry.path, signal);
-            if (isSensitivePath(validated.requestedPath, validated.resolvedPath)) {
-                return null;
-            }
-        }
-        catch {
-            return null;
-        }
+    const isAccessible = await isEntryAccessibleByType(entry.path, type, rootDirectories, signal, accessDeps);
+    if (!isAccessible) {
+        return null;
     }
     if (gitignoreMatcher &&
         isIgnoredByGitignore(gitignoreMatcher, root, entry.path, {
@@ -218,11 +194,16 @@ export function formatTreeAscii(tree) {
 }
 export async function treeDirectory(dirPath, options = {}) {
     const normalized = normalizeOptions(options);
-    const { signal, cleanup } = createTimedAbortSignal(options.signal, normalized.timeoutMs);
-    const root = await validateExistingDirectory(dirPath, signal);
-    const rootNormalized = normalizePath(root);
-    const rootDirectories = [rootNormalized];
-    try {
+    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;
@@ -253,12 +234,18 @@ export async function treeDirectory(dirPath, options = {}) {
             suppressErrors: true,
         });
         for await (const entry of stream) {
-            const stopReason = getStopReason(signal, totalEntries, normalized.maxEntries);
+            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);
+            const resolved = await resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal, accessDeps);
             if (!resolved) {
                 continue;
             }
@@ -274,8 +261,5 @@ export async function treeDirectory(dirPath, options = {}) {
             truncated,
             totalEntries,
         };
-    }
-    finally {
-        cleanup();
-    }
+    });
 }

package/dist/lib/fs-helpers.d.ts

@@ -7,6 +7,7 @@ export declare function createTimedAbortSignal(baseSignal: AbortSignal | undefin
     signal: AbortSignal;
     cleanup: () => void;
 };
+export declare function withTimedAbortSignal<T>(baseSignal: AbortSignal | undefined, timeoutMs: number | undefined, run: (signal: AbortSignal) => Promise<T>): Promise<T>;
 interface ParallelResult<R> {
     results: R[];
     errors: {

package/dist/lib/fs-helpers.js

@@ -110,6 +110,15 @@ export function createTimedAbortSignal(baseSignal, timeoutMs) {
     }
     return createNoopSignal();
 }
+export async function withTimedAbortSignal(baseSignal, timeoutMs, run) {
+    const { signal, cleanup } = createTimedAbortSignal(baseSignal, timeoutMs);
+    try {
+        return await run(signal);
+    }
+    finally {
+        cleanup();
+    }
+}
 function createNoopSignal() {
     return { signal: SHARED_NOOP_SIGNAL, cleanup: () => { } };
 }

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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,15 @@
+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-validation.d.ts

@@ -8,6 +8,7 @@ import { McpError } from './errors.js';
  */
 export declare function normalizePath(p: string): string;
 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 setAllowedDirectoriesResolved(dirs: readonly string[], signal?: AbortSignal): Promise<void>;
 export declare function getReservedDeviceNameForPath(requestedPath: string): string | undefined;

package/dist/lib/path-validation.js

@@ -124,6 +124,13 @@ function setAllowedDirectoriesState(primary, expanded) {
 export function getAllowedDirectories() {
     return [...allowedDirectoriesExpanded];
 }
+export function isAllowedDirectoryRoot(normalizedPath) {
+    for (const dir of allowedDirectoriesExpanded) {
+        if (isSamePath(normalizedPath, dir))
+            return true;
+    }
+    return false;
+}
 function getAllowedDirectoriesForRelativeResolution() {
     return allowedDirectoriesPrimary.length > 0
         ? allowedDirectoriesPrimary

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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,13 @@
+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/prompts.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { withDefaultIcons } from './tools/shared.js';
 const HELP_PROMPT_NAME = 'get-help';
 const HELP_PROMPT_TITLE = 'Get Help';
-const HELP_PROMPT_DESCRIPTION = 'Retrieve the full filesystem-mcp XML usage guide.';
+const HELP_PROMPT_DESCRIPTION = 'Return filesystem-mcp usage instructions.';
 function filterInstructionsByTopic(instructions, topic) {
     const normalized = topic.trim().toLowerCase();
     if (!normalized)
@@ -16,7 +16,7 @@ function filterInstructionsByTopic(instructions, topic) {
         .map((sec) => sec.split('\n')[0]?.replace(/^##\s*/u, '') ?? '')
         .filter(Boolean)
         .join(', ');
-    return `Section '${topic}' not found. Available sections: ${available}\n\n${instructions}`;
+    return `Section '${topic}' not found. Available: ${available}\n\n${instructions}`;
 }
 export function registerGetHelpPrompt(server, instructions, iconInfo) {
     const baseConfig = withDefaultIcons({ title: HELP_PROMPT_TITLE, description: HELP_PROMPT_DESCRIPTION }, iconInfo);
@@ -26,7 +26,7 @@ export function registerGetHelpPrompt(server, instructions, iconInfo) {
             topic: z
                 .string()
                 .optional()
-                .describe('Section heading prefix to filter (e.g. "error handling strategy"). Omit for full instructions.'),
+                .describe('Optional section heading prefix (example: "error handling"). Omit to return full instructions.'),
         },
     }, ({ topic }) => {
         const text = topic

package/dist/resources/generated-instructions.js

@@ -2,7 +2,7 @@ import { buildToolCatalogDetailsOnly } from './tool-catalog.js';
 import { buildCoreContextPack, getSharedConstraints, getToolContracts, } from './tool-info.js';
 import { buildWorkflowGuide } from './workflows.js';
 const INSTRUCTIONS_HEADER = `<role>
-Expert filesystem agent. Operate ONLY within allowed roots. Always discover before acting — never guess paths.
+Filesystem agent for local paths only. Operate inside allowed roots. Discover before action. Never guess paths.
 </role>
 
 <tools_overview>
@@ -15,16 +15,16 @@ Expert filesystem agent. Operate ONLY within allowed roots. Always discover befo
 </tools_overview>
 
 <resources>
-- \`internal://instructions\`: Full server usage guide.
-- \`internal://tool-catalog\`: Tool routing and cross-tool data-flow guide.
-- \`internal://workflows\`: Standard operating sequences (explore/search/edit/patch).
-- \`internal://tool-info/{name}\`: Per-tool details (nuances/gotchas), e.g. \`internal://tool-info/read\`.
-- \`filesystem-mcp://result/{id}\`: Large output cache. Call \`resources/read\` immediately if \`resourceUri\` is returned.
-- \`filesystem-mcp://metrics\`: Live per-tool stats.
+- \`internal://instructions\`: Full usage reference.
+- \`internal://tool-catalog\`: Tool routing and data-flow rules.
+- \`internal://workflows\`: Standard execution sequences.
+- \`internal://tool-info/{name}\`: Per-tool nuances and gotchas (example: \`internal://tool-info/read\`).
+- \`filesystem-mcp://result/{id}\`: Cached large output. If \`resourceUri\` is returned, call \`resources/read\` immediately.
+- \`filesystem-mcp://metrics\`: Per-tool runtime metrics.
 </resources>
 
 <task_protocol>
-Async execution: provide \`_meta.progressToken\` in \`tools/call\`, poll \`tasks/get\`, call \`tasks/result\`.
+Async execution: pass \`_meta.progressToken\` in \`tools/call\`, poll \`tasks/get\`, then call \`tasks/result\`.
 Task-capable: \`find\`, \`tree\`, \`read\`, \`read_many\`, \`stat_many\`, \`grep\`, \`mkdir\`, \`write\`, \`mv\`, \`rm\`, \`calculate_hash\`, \`apply_patch\`, \`search_and_replace\`.
 </task_protocol>
 `;
@@ -35,19 +35,19 @@ ${getSharedConstraints()
 </constraints>
 
 <error_handling>
-- \`E_ACCESS_DENIED\` → Call \`roots\`; use allowed path.
-- \`E_NOT_FOUND\`     → Call \`ls\`/\`find\`; verify spelling.
-- \`E_TOO_LARGE\`     → Use range/head or \`read_many\`.
-- \`E_TIMEOUT\`       → Reduce scope or result limits.
+- \`E_ACCESS_DENIED\` => call \`roots\`, then use an allowed path.
+- \`E_NOT_FOUND\` => call \`ls\` or \`find\`, then verify spelling.
+- \`E_TOO_LARGE\` => use \`head\`, line ranges, or \`read_many\`.
+- \`E_TIMEOUT\` => reduce scope or result limits.
 </error_handling>
 `;
 function formatToolSection(tool) {
     const parts = [`### ${tool.name}\n${tool.description}`];
     if (tool.nuances && tool.nuances.length > 0) {
-        parts.push(...tool.nuances.map((n) => `» ${n}`));
+        parts.push(...tool.nuances.map((n) => `- Nuance: ${n}`));
     }
     if (tool.gotchas && tool.gotchas.length > 0) {
-        parts.push(...tool.gotchas.map((g) => `⚠ ${g}`));
+        parts.push(...tool.gotchas.map((g) => `- Gotcha: ${g}`));
     }
     return parts.join('\n');
 }

package/dist/resources/tool-catalog.js

@@ -9,21 +9,21 @@ diff_files (patch text) -> apply_patch.patch
 
 ## Search Strategy
 
-- Use \`find\` for glob-based file discovery.
-- Use \`grep\` for content-based searches.
-- Use \`search_and_replace\` ONLY for bulk replacements, not for discovery.
+- Use \`find\` for glob file discovery.
+- Use \`grep\` for text search.
+- Use \`search_and_replace\` only for replacement, never discovery.
 
 ## Write Strategy
 
-- Use \`edit\` for precise, single-occurrence string replacements in existing files.
-- Use \`write\` to create new files or completely overwrite existing content.
-- Use \`search_and_replace\` for bulk regex replacements across multiple files.
+- Use \`edit\` for precise, first-occurrence replacements in existing files.
+- Use \`write\` to create files or overwrite full contents.
+- Use \`search_and_replace\` for bulk multi-file replacements.
 
 ## Patch Management
 
-- Always generate a patch with \`diff_files\` first.
-- Always use \`dryRun: true\` with \`apply_patch\` to verify changes.
-- \`apply_patch\` works on unified diff format.
+- Generate patches with \`diff_files\` first.
+- Run \`apply_patch\` with \`dryRun: true\` before writing.
+- \`apply_patch\` accepts unified diffs only.
 </tool_selection_guide>
 `;
 export function buildToolCatalog() {

package/dist/resources/tool-info.js

@@ -37,10 +37,10 @@ export function buildCoreContextPack() {
 }
 export function getSharedConstraints() {
     return [
-        'Allowed roots only (negotiated via CLI).',
-        'Sensitive files denylisted by default.',
-        `Max file size (${Math.floor(MAX_TEXT_FILE_SIZE / 1024 / 1024)}MB) & search results (${MAX_SEARCH_RESULTS} files, ${DEFAULT_SEARCH_CONTENT_RESULTS} lines) enforced.`,
-        'If a response includes `resourceUri`, call `resources/read` immediately — results expire on process restart.',
+        'Use allowed roots only (provided by CLI negotiation).',
+        'Sensitive paths are denylisted by default.',
+        `Limits are enforced: max file size ${Math.floor(MAX_TEXT_FILE_SIZE / 1024 / 1024)}MB; search caps ${MAX_SEARCH_RESULTS} files and ${DEFAULT_SEARCH_CONTENT_RESULTS} lines.`,
+        'If a response includes `resourceUri`, call `resources/read` immediately; cached results expire on process restart.',
     ];
 }
 export function buildToolInfo(name) {
@@ -49,7 +49,7 @@ export function buildToolInfo(name) {
         return undefined;
     const lines = [`## ${entry.name}`, '', entry.description];
     if (entry.annotations && entry.annotations.length > 0) {
-        lines.push('', `**Annotations:** ${entry.annotations.join(', ')}`);
+        lines.push('', `**Hints:** ${entry.annotations.join(', ')}`);
     }
     if (entry.nuances && entry.nuances.length > 0) {
         lines.push('', '**Nuances:**');

package/dist/resources/workflows.js

@@ -1,33 +1,33 @@
 export function buildWorkflowGuide() {
     return `<workflows>
 ### A: EXPLORE
-Use when: navigating an unfamiliar directory or reading file content.
-1. \`roots\` (List allowed paths).
-2. \`ls\` (files) | \`tree\` (structure).
-3. \`stat\` | \`stat_many\` (size/type check).
-4. \`read\` | \`read_many\` (content).
-   > **Strict:** Never guess paths. Resolve first.
+Use when: you need directory layout or file content.
+1. \`roots\` (list allowed paths).
+2. \`ls\` (flat view) or \`tree\` (recursive view).
+3. \`stat\` or \`stat_many\` (type and size checks).
+4. \`read\` or \`read_many\` (read content).
+   > **Strict:** Resolve paths first. Never guess.
 
 ### B: SEARCH
-Use when: locating files by name pattern or by content match.
+Use when: you need files by pattern or content.
 1. \`find\` (glob candidates).
-2. \`grep\` (content search).
-3. \`read\` (verify context).
-   > **Strict:** Use \`grep\` for content search, not \`find\`.
+2. \`grep\` (content matches).
+3. \`read\` (verify matched context).
+   > **Strict:** Do content search with \`grep\`, not \`find\`.
 
 ### C: EDIT
-Use when: modifying existing files or reorganizing the filesystem.
-1. \`edit\` (precise string match).
-2. \`search_and_replace\` (bulk regex/glob).
-3. \`mv\` | \`rm\` (file layout).
-4. \`mkdir\` (create dirs).
+Use when: you need to modify files or layout.
+1. \`edit\` (targeted string replacement).
+2. \`search_and_replace\` (bulk replacements).
+3. \`mv\` or \`rm\` (layout changes).
+4. \`mkdir\` (directory creation).
    > **Strict:** Confirm destructive ops (\`write\`, \`mv\`, \`rm\`, bulk replace).
 
 ### D: PATCH
-Use when: applying structured diffs produced by \`diff_files\`.
+Use when: applying unified diffs from \`diff_files\`.
 1. \`diff_files\` (generate).
 2. \`apply_patch\` (dryRun: true).
 3. \`apply_patch\` (dryRun: false).
-   > **Tip:** Pass \`diff_files\` output directly into \`apply_patch\`.
+   > **Tip:** Feed \`diff_files\` output directly to \`apply_patch\`.
 </workflows>`;
 }