@j0hanz/filesystem-mcp 1.6.2 → 1.7.0

package/README.md

@@ -474,10 +474,14 @@ Replace text in all files matching a glob. Replaces **all** occurrences per file
 
 ### Resources
 
-| URI                            | Description                        | MIME Type       |
-| :----------------------------- | :--------------------------------- | :-------------- |
-| `internal://instructions`      | Usage guidance for models          | `text/markdown` |
-| `filesystem-mcp://result/{id}` | Ephemeral cached large tool output | varies          |
+| URI                            | Description                         | MIME Type          |
+| :----------------------------- | :---------------------------------- | :----------------- |
+| `internal://instructions`      | Usage guidance for models           | `text/markdown`    |
+| `internal://tool-catalog`      | Tool routing and data-flow guide    | `text/markdown`    |
+| `internal://workflows`         | Explore/search/edit/patch workflows | `text/markdown`    |
+| `internal://tool-info/{name}`  | Per-tool nuances and gotchas        | `text/markdown`    |
+| `filesystem-mcp://metrics`     | Live per-tool metrics snapshot      | `application/json` |
+| `filesystem-mcp://result/{id}` | Ephemeral cached large tool output  | varies             |
 
 When a tool response includes a `resource_link`/`resourceUri`, treat it as authoritative for full payload retrieval and call `resources/read` with that URI.
 
@@ -565,7 +569,7 @@ Set `FS_CONTEXT_STRIP_STRUCTURED=1` to strip `structuredContent` from tool resul
 - **Input limits**: Paths are bounded to 4,096 characters; patterns to 1,000 characters.
 - **Atomic writes**: File writes use an atomic write-then-rename strategy to prevent partial writes.
 - **Docker**: The container runs as a non-root user (`mcp`).
-- **HTTP host binding**: The HTTP transport binds to `127.0.0.1` by default. Setting `FILESYSTEM_MCP_HTTP_HOST=0.0.0.0` binds to all network interfaces and exposes the server externally — only do this behind a trusted reverse proxy with `FILESYSTEM_MCP_AUTH_TOKEN` configured.
+- **HTTP host binding**: The HTTP transport binds to `127.0.0.1` by default. Setting `FILESYSTEM_MCP_HTTP_HOST=0.0.0.0` binds to all network interfaces and exposes the server externally — only do this behind a trusted reverse proxy with `FILESYSTEM_MCP_API_KEY` configured.
 
 > [!IMPORTANT]
 > All diagnostic output goes to `stderr`. Tool handlers must never write to `stdout`, as doing so would corrupt the stdio transport.
@@ -580,18 +584,16 @@ npm ci
 
 ### Scripts
 
-| Script          | Command                                                   | Purpose                             |
-| :-------------- | :-------------------------------------------------------- | :---------------------------------- |
-| `dev`           | `tsc --watch`                                             | Watch-mode TypeScript compilation   |
-| `dev:run`       | `node --watch dist/index.js`                              | Run built server with file watching |
-| `build`         | `node scripts/tasks.mjs build`                            | Production build                    |
-| `test`          | `node scripts/tasks.mjs test`                             | Run full test suite                 |
-| `test:fast`     | `node --test --import tsx/esm src/__tests__/**/*.test.ts` | Fast test runner (no build step)    |
-| `test:coverage` | `node scripts/tasks.mjs test --coverage`                  | Test with coverage                  |
-| `lint`          | `eslint .`                                                | Lint source files                   |
-| `lint:fix`      | `eslint . --fix`                                          | Auto-fix lint issues                |
-| `format`        | `prettier --write .`                                      | Format all files                    |
-| `type-check`    | `node scripts/tasks.mjs type-check`                       | TypeScript type checking            |
+| Script       | Command                             | Purpose                             |
+| :----------- | :---------------------------------- | :---------------------------------- |
+| `dev`        | `tsc --watch`                       | Watch-mode TypeScript compilation   |
+| `dev:run`    | `node --watch dist/index.js`        | Run built server with file watching |
+| `build`      | `node scripts/tasks.mjs build`      | Production build                    |
+| `test`       | `node scripts/tasks.mjs test`       | Run full test suite                 |
+| `lint`       | `eslint .`                          | Lint source files                   |
+| `lint:fix`   | `eslint . --fix`                    | Auto-fix lint issues                |
+| `format`     | `prettier --write .`                | Format all files                    |
+| `type-check` | `node scripts/tasks.mjs type-check` | TypeScript type checking            |
 
 ### MCP Inspector
 

package/dist/lib/errors.js

@@ -125,15 +125,16 @@ function walkErrorChain(error, visitor) {
     let current = error;
     const visited = new Set();
     while (current !== undefined && current !== null && !visited.has(current)) {
-        if (visitor(current))
-            return true;
+        const visitedResult = visitor(current);
+        if (visitedResult !== undefined)
+            return visitedResult;
         if (!isNativeError(current))
             break;
         visited.add(current);
         const next = current.cause;
         current = next;
     }
-    return false;
+    return undefined;
 }
 function isAbortErrorSingle(error) {
     if (!isNativeError(error))
@@ -144,7 +145,7 @@ function isAbortErrorSingle(error) {
     return code === 'ABORT_ERR';
 }
 export function isAbortError(error) {
-    return walkErrorChain(error, isAbortErrorSingle);
+    return (walkErrorChain(error, (candidate) => isAbortErrorSingle(candidate) ? true : undefined) === true);
 }
 function isTimeoutErrorSingle(error) {
     if (!isNativeError(error))
@@ -158,7 +159,7 @@ function isTimeoutErrorSingle(error) {
     return message.includes('timed out') || message.includes('timeout');
 }
 export function isTimeoutLikeError(error) {
-    return walkErrorChain(error, isTimeoutErrorSingle);
+    return (walkErrorChain(error, (candidate) => isTimeoutErrorSingle(candidate) ? true : undefined) === true);
 }
 export class McpError extends Error {
     code;
@@ -224,17 +225,20 @@ function classifyMessageError(error) {
     return undefined;
 }
 function classifyError(error) {
-    if (isAbortError(error)) {
-        return ErrorCode.E_CANCELLED;
-    }
-    if (isTimeoutLikeError(error)) {
-        return ErrorCode.E_TIMEOUT;
-    }
-    const direct = getDirectErrorCode(error);
-    if (direct)
-        return direct;
-    const messageCode = classifyMessageError(error);
-    return messageCode ?? ErrorCode.E_UNKNOWN;
+    let timeoutCode;
+    let fallbackCode;
+    const terminalCode = walkErrorChain(error, (candidate) => {
+        if (isAbortErrorSingle(candidate)) {
+            return ErrorCode.E_CANCELLED;
+        }
+        if (timeoutCode === undefined && isTimeoutErrorSingle(candidate)) {
+            timeoutCode = ErrorCode.E_TIMEOUT;
+        }
+        fallbackCode ??=
+            getDirectErrorCode(candidate) ?? classifyMessageError(candidate);
+        return undefined;
+    });
+    return terminalCode ?? timeoutCode ?? fallbackCode ?? ErrorCode.E_UNKNOWN;
 }
 export function createDetailedError(error, path, additionalDetails) {
     const message = error instanceof Error ? error.message : String(error);

package/dist/lib/file-operations/glob-engine.js

@@ -106,40 +106,57 @@ function buildHiddenPatterns(normalizedPattern, maxDepth) {
 function shouldUseGlobDirents(options) {
     return !options.stats && !options.followSymbolicLinks;
 }
-function assertOptionsShape(options) {
-    const unknownOptions = options;
-    if (unknownOptions === null || typeof unknownOptions !== 'object') {
-        throw new TypeError('globEntries: options must be an object');
-    }
-    const o = unknownOptions;
-    if (typeof o.cwd !== 'string') {
-        throw new TypeError('globEntries: options.cwd must be a string');
+function assertOptionString(options, key) {
+    if (typeof options[key] !== 'string') {
+        throw new TypeError(`globEntries: options.${key} must be a string`);
     }
-    if (typeof o.pattern !== 'string') {
-        throw new TypeError('globEntries: options.pattern must be a string');
-    }
-    if (!Array.isArray(o.excludePatterns)) {
+}
+function assertExcludePatternsOption(options) {
+    if (!Array.isArray(options.excludePatterns)) {
         throw new TypeError('globEntries: options.excludePatterns must be an array');
     }
-    for (const p of o.excludePatterns) {
-        if (typeof p !== 'string') {
+    for (const pattern of options.excludePatterns) {
+        if (typeof pattern !== 'string') {
             throw new TypeError('globEntries: options.excludePatterns must contain only strings');
         }
     }
+}
+function assertBooleanOptions(options) {
     for (const key of GLOB_BOOLEAN_OPTION_KEYS) {
-        if (typeof o[key] !== 'boolean') {
+        if (typeof options[key] !== 'boolean') {
             throw new TypeError(`globEntries: options.${key} must be a boolean`);
         }
     }
-    if (o.maxDepth !== undefined) {
-        if (typeof o.maxDepth !== 'number' || !Number.isFinite(o.maxDepth)) {
-            throw new TypeError('globEntries: options.maxDepth must be a finite number');
-        }
+}
+function assertOptionalMaxDepth(options) {
+    const { maxDepth } = options;
+    if (maxDepth === undefined)
+        return;
+    if (typeof maxDepth !== 'number' || !Number.isFinite(maxDepth)) {
+        throw new TypeError('globEntries: options.maxDepth must be a finite number');
     }
-    if (o.suppressErrors !== undefined && typeof o.suppressErrors !== 'boolean') {
+}
+function assertOptionalSuppressErrors(options) {
+    const { suppressErrors } = options;
+    if (suppressErrors === undefined)
+        return;
+    if (typeof suppressErrors !== 'boolean') {
         throw new TypeError('globEntries: options.suppressErrors must be a boolean');
     }
 }
+function assertOptionsShape(options) {
+    const unknownOptions = options;
+    if (unknownOptions === null || typeof unknownOptions !== 'object') {
+        throw new TypeError('globEntries: options must be an object');
+    }
+    const o = unknownOptions;
+    assertOptionString(o, 'cwd');
+    assertOptionString(o, 'pattern');
+    assertExcludePatternsOption(o);
+    assertBooleanOptions(o);
+    assertOptionalMaxDepth(o);
+    assertOptionalSuppressErrors(o);
+}
 function normalizeOptions(options) {
     const cwd = path.resolve(options.cwd);
     const normalizedPattern = normalizePattern(options.pattern, options.baseNameMatch);

package/dist/lib/fs-helpers.js

@@ -120,23 +120,22 @@ function createParallelAbortError() {
     return createAbortError();
 }
 export async function processInParallel(items, processor, concurrency = PARALLEL_CONCURRENCY, signal) {
-    if (items.length === 0)
+    const itemCount = items.length;
+    if (itemCount === 0)
         return { results: [], errors: [] };
     const effectiveConcurrency = normalizeConcurrency(concurrency);
     // Pre-allocate slots by index to guarantee input-order output.
-    const resultSlots = new Array(items.length);
+    const resultSlots = new Array(itemCount);
     const errors = [];
     if (signal?.aborted)
         throw createParallelAbortError();
     let nextIndex = 0;
     const next = async () => {
-        while (nextIndex < items.length) {
+        while (nextIndex < itemCount) {
             if (signal?.aborted)
                 throw createParallelAbortError();
-            const index = nextIndex++;
-            // Check again because another worker might have incremented past length
-            if (index >= items.length)
-                break;
+            const index = nextIndex;
+            nextIndex += 1;
             const item = items[index];
             try {
                 const result = await processor(item);
@@ -154,7 +153,7 @@ export async function processInParallel(items, processor, concurrency = PARALLEL
             }
         }
     };
-    const workerCount = Math.min(items.length, effectiveConcurrency);
+    const workerCount = Math.min(itemCount, effectiveConcurrency);
     const workers = new Array(workerCount);
     for (let index = 0; index < workerCount; index += 1) {
         workers[index] = next();

package/dist/lib/path-policy.js

@@ -36,45 +36,61 @@ function compilePatterns(patterns) {
         const normalized = normalizeForMatch(pattern);
         const matchesPath = normalized.includes('/');
         compiled.push({
-            raw: normalized,
             globs: matchesPath ? compilePatternGlobs(normalized) : [normalized],
             matchesPath,
         });
     }
     return compiled;
 }
-const DENY_PATTERNS = compilePatterns(SENSITIVE_FILE_DENYLIST);
-const ALLOW_PATTERNS = compilePatterns(SENSITIVE_FILE_ALLOWLIST);
+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 matchesAny(patterns, pathCandidates, nameCandidates) {
-    for (const pattern of patterns) {
-        const candidates = pattern.matchesPath ? pathCandidates : nameCandidates;
-        for (const candidate of candidates) {
-            for (const glob of pattern.globs) {
-                if (path.posix.matchesGlob(candidate, glob))
-                    return true;
-            }
+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.length === 0)
+    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 (matchesAny(ALLOW_PATTERNS, pathCandidates, nameCandidates)) {
+    if (matchesAnyGlobs(ALLOW_PATTERNS.pathGlobs, pathCandidates) ||
+        matchesAnyGlobs(ALLOW_PATTERNS.nameGlobs, nameCandidates)) {
         return false;
     }
-    return matchesAny(DENY_PATTERNS, pathCandidates, nameCandidates);
+    return (matchesAnyGlobs(DENY_PATTERNS.pathGlobs, pathCandidates) ||
+        matchesAnyGlobs(DENY_PATTERNS.nameGlobs, nameCandidates));
 }
 export function assertAllowedFileAccess(requestedPath, resolvedPath) {
     if (!isSensitivePath(requestedPath, resolvedPath))

package/dist/resources/generated-instructions.js

@@ -15,6 +15,10 @@ 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.
 </resources>

package/dist/tools/calculate-hash.js

@@ -9,7 +9,7 @@ import { globEntries } from '../lib/file-operations/glob-engine.js';
 import { assertNotAborted, withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath } from '../lib/path-validation.js';
 import { CalculateHashInputSchema, CalculateHashOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const WINDOWS_PATH_SEPARATOR = /\\/gu;
 export const CALCULATE_HASH_TOOL = {
@@ -158,17 +158,10 @@ export function registerCalculateHashTool(server, options = {}) {
         context: { path: args.path },
         run: async (signal) => {
             const baseName = path.basename(args.path);
-            let progressCursor = 0;
-            notifyProgress(extra, {
-                current: 0,
-                message: `🕮 calculate_hash: ${baseName}`,
-            });
-            const baseReporter = createProgressReporter(extra);
+            const progress = createToolProgressSession(extra, `🕮 calculate_hash: ${baseName}`);
             const progressWithMessage = ({ current, total, }) => {
-                if (current > progressCursor)
-                    progressCursor = current;
                 const fileWord = current === 1 ? 'file' : 'files';
-                baseReporter({
+                progress.update({
                     current,
                     ...(total !== undefined ? { total } : {}),
                     message: `🕮 calculate_hash: ${baseName} [${current} ${fileWord} hashed]`,
@@ -178,7 +171,7 @@ export function registerCalculateHashTool(server, options = {}) {
                 const result = await handleCalculateHash(args, signal, progressWithMessage);
                 const sc = result.structuredContent;
                 const totalFiles = sc.ok ? (sc.fileCount ?? 1) : 1;
-                const finalCurrent = Math.max(totalFiles + 1, progressCursor + 1);
+                const finalCurrent = Math.max(totalFiles + 1, progress.getCurrent() + 1);
                 let suffix;
                 if (!sc.ok) {
                     suffix = 'failed';
@@ -189,20 +182,11 @@ export function registerCalculateHashTool(server, options = {}) {
                 else {
                     suffix = `${(sc.hash ?? '').slice(0, 8)}...`;
                 }
-                notifyProgress(extra, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `🕮 calculate_hash: ${baseName} • ${suffix}`,
-                });
+                progress.complete(`🕮 calculate_hash: ${baseName} • ${suffix}`, finalCurrent);
                 return result;
             }
             catch (error) {
-                const finalCurrent = Math.max(progressCursor + 1, 1);
-                notifyProgress(extra, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `🕮 calculate_hash: ${baseName} • failed`,
-                });
+                progress.fail(`🕮 calculate_hash: ${baseName} • failed`);
                 throw error;
             }
         },

package/dist/tools/read-multiple.js

@@ -3,7 +3,7 @@ import { DEFAULT_READ_MANY_MAX_TOTAL_SIZE, DEFAULT_SEARCH_TIMEOUT_MS, } from '..
 import { ErrorCode } from '../lib/errors.js';
 import { readMultipleFiles } from '../lib/file-operations/read-multiple-files.js';
 import { ReadMultipleFilesInputSchema, ReadMultipleFilesOutputSchema, } from '../schemas.js';
-import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, maybeExternalizeTextContent, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const READ_MULTIPLE_FILES_TOOL = {
     name: 'read_many',
@@ -20,6 +20,33 @@ export const READ_MULTIPLE_FILES_TOOL = {
         'Per-file `truncationReason` can be `head`, `range`, or `externalized`.',
     ],
 };
+function toStructuredReadManyResult(result) {
+    const structured = {
+        path: result.path,
+    };
+    if (result.content !== undefined)
+        structured.content = result.content;
+    if (result.truncated)
+        structured.truncated = result.truncated;
+    if (result.resourceUri)
+        structured.resourceUri = result.resourceUri;
+    if (result.head !== undefined)
+        structured.head = result.head;
+    if (result.startLine !== undefined)
+        structured.startLine = result.startLine;
+    if (result.endLine !== undefined)
+        structured.endLine = result.endLine;
+    if (result.hasMoreLines)
+        structured.hasMoreLines = result.hasMoreLines;
+    if (result.totalLines !== undefined)
+        structured.totalLines = result.totalLines;
+    if (result.truncationReason) {
+        structured.truncationReason = result.truncationReason;
+    }
+    if (result.error)
+        structured.error = result.error;
+    return structured;
+}
 async function handleReadMultipleFiles(args, signal, resourceStore, onReadComplete) {
     const options = {
         ...(signal ? { signal } : {}),
@@ -70,25 +97,7 @@ async function handleReadMultipleFiles(args, signal, resourceStore, onReadComple
     }
     const structured = {
         ok: true,
-        results: mappedResults.map((result) => ({
-            path: result.path,
-            ...(result.content !== undefined ? { content: result.content } : {}),
-            ...(result.truncated ? { truncated: result.truncated } : {}),
-            ...(result.resourceUri ? { resourceUri: result.resourceUri } : {}),
-            ...(result.head !== undefined ? { head: result.head } : {}),
-            ...(result.startLine !== undefined
-                ? { startLine: result.startLine }
-                : {}),
-            ...(result.endLine !== undefined ? { endLine: result.endLine } : {}),
-            ...(result.hasMoreLines ? { hasMoreLines: result.hasMoreLines } : {}),
-            ...(result.totalLines !== undefined
-                ? { totalLines: result.totalLines }
-                : {}),
-            ...(result.truncationReason
-                ? { truncationReason: result.truncationReason }
-                : {}),
-            ...(result.error ? { error: result.error } : {}),
-        })),
+        results: mappedResults.map((result) => toStructuredReadManyResult(result)),
         summary: {
             total: mappedResults.length,
             succeeded,
@@ -130,18 +139,9 @@ export function registerReadMultipleFilesTool(server, options = {}) {
                     ? `, ${path.basename(args.paths[1] ?? '')}${args.paths.length > 2 ? '…' : ''}`
                     : '';
                 const context = `${args.paths.length} files [${first}${extraPaths}]`;
-                let progressCursor = 0;
-                notifyProgress(extra, {
-                    current: 0,
-                    message: `🕮 read_many: ${context}`,
-                });
-                const baseReporter = createProgressReporter(extra);
+                const progress = createToolProgressSession(extra, `🕮 read_many: ${context}`);
                 const onReadComplete = () => {
-                    progressCursor++;
-                    baseReporter({
-                        current: progressCursor,
-                        message: `🕮 read_many: ${context} [${progressCursor}/${args.paths.length} read]`,
-                    });
+                    progress.increment((current) => `🕮 read_many: ${context} [${current}/${args.paths.length} read]`);
                 };
                 try {
                     const result = await handleReadMultipleFiles(args, signal, options.resourceStore, onReadComplete);
@@ -156,21 +156,12 @@ export function registerReadMultipleFilesTool(server, options = {}) {
                     else {
                         suffix = `${total} files read`;
                     }
-                    const finalCurrent = Math.max(total, progressCursor + 1);
-                    notifyProgress(extra, {
-                        current: finalCurrent,
-                        total: finalCurrent,
-                        message: `🕮 read_many: ${context} • ${suffix}`,
-                    });
+                    const finalCurrent = Math.max(total, progress.getCurrent() + 1);
+                    progress.complete(`🕮 read_many: ${context} • ${suffix}`, finalCurrent);
                     return result;
                 }
                 catch (error) {
-                    const finalCurrent = Math.max(progressCursor + 1, 1);
-                    notifyProgress(extra, {
-                        current: finalCurrent,
-                        total: finalCurrent,
-                        message: `🕮 read_many: ${context} • failed`,
-                    });
+                    progress.fail(`🕮 read_many: ${context} • failed`);
                     throw error;
                 }
             },

package/dist/tools/replace-in-files.js

@@ -9,7 +9,7 @@ import { globEntries } from '../lib/file-operations/glob-engine.js';
 import { atomicWriteFile, withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath, validatePathForWrite, } from '../lib/path-validation.js';
 import { SearchAndReplaceInputSchema, SearchAndReplaceOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, createProgressReporter, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, notifyProgress, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const SEARCH_AND_REPLACE_TOOL = {
     name: 'search_and_replace',
@@ -56,31 +56,42 @@ function createRegexMatcher(pattern) {
         throw new McpError(ErrorCode.E_INVALID_INPUT, `Invalid regex pattern: ${formatUnknownErrorMessage(error)}`);
     }
 }
-function countRegexMatches(content, regex) {
-    regex.lastIndex = 0;
-    let count = 0;
-    while (regex.exec(content) !== null) {
-        count++;
-        if (regex.lastIndex === 0) {
-            regex.lastIndex++;
+function createRegexReplacementMatcher(regex) {
+    const count = (content) => {
+        regex.lastIndex = 0;
+        let matchCount = 0;
+        while (regex.exec(content) !== null) {
+            matchCount++;
+            if (regex.lastIndex === 0) {
+                regex.lastIndex++;
+            }
         }
-    }
-    return count;
+        return matchCount;
+    };
+    const replace = (content, replacement) => {
+        regex.lastIndex = 0;
+        return content.replace(regex, replacement);
+    };
+    return { count, replace };
 }
-function countLiteralMatches(content, searchPattern) {
-    let count = 0;
-    let pos = content.indexOf(searchPattern);
-    const patternLength = searchPattern.length;
-    while (pos !== -1) {
-        count++;
-        pos = content.indexOf(searchPattern, pos + patternLength);
-    }
-    return count;
+function createLiteralReplacementMatcher(searchPattern) {
+    const count = (content) => {
+        let matchCount = 0;
+        let pos = content.indexOf(searchPattern);
+        const patternLength = searchPattern.length;
+        while (pos !== -1) {
+            matchCount++;
+            pos = content.indexOf(searchPattern, pos + patternLength);
+        }
+        return matchCount;
+    };
+    const replace = (content, replacement) => content.replaceAll(searchPattern, () => replacement);
+    return { count, replace };
 }
 function formatFileTooLargeError(filePath, size, maxFileSize) {
     return `File too large: ${filePath} (${size} bytes > ${maxFileSize} bytes)`;
 }
-async function processEntry(entryPath, args, regex, maxFileSize, signal, summary) {
+async function processEntry(entryPath, options, replacement, matcher, maxFileSize, signal, summary) {
     let validPath;
     try {
         validPath = await validatePathForWrite(entryPath, signal);
@@ -107,22 +118,13 @@ async function processEntry(entryPath, args, regex, maxFileSize, signal, summary
             encoding: 'utf-8',
             signal,
         });
-        const matchCount = args.isRegex && regex
-            ? countRegexMatches(content, regex)
-            : countLiteralMatches(content, args.searchPattern);
+        const matchCount = matcher.count(content);
         if (matchCount > 0) {
             summary.totalMatches += matchCount;
             summary.filesChanged++;
             recordChangedFile(summary, validPath, matchCount);
-            let newContent;
-            if (args.isRegex && regex) {
-                regex.lastIndex = 0;
-                newContent = content.replace(regex, args.replacement);
-            }
-            else {
-                newContent = content.replaceAll(args.searchPattern, () => args.replacement);
-            }
-            if ((args.dryRun || args.returnDiff) &&
+            const newContent = matcher.replace(content, replacement);
+            if ((options.dryRun || options.returnDiff) &&
                 summary.diff.length < MAX_DIFF_SIZE) {
                 const patch = createTwoFilesPatch(path.basename(validPath), path.basename(validPath), content, newContent, 'Original', 'Modified');
                 // Only append if it won't exceed the limit too much
@@ -130,7 +132,7 @@ async function processEntry(entryPath, args, regex, maxFileSize, signal, summary
                     summary.diff += patch;
                 }
             }
-            if (!args.dryRun) {
+            if (!options.dryRun) {
                 await atomicWriteFile(validPath, newContent, {
                     encoding: 'utf-8',
                     signal,
@@ -195,6 +197,13 @@ function createReplacementRegex(args) {
     }
     return createRegexMatcher(args.searchPattern);
 }
+function createReplacementMatcher(args) {
+    const regex = createReplacementRegex(args);
+    if (regex) {
+        return createRegexReplacementMatcher(regex);
+    }
+    return createLiteralReplacementMatcher(args.searchPattern);
+}
 function reportReplaceProgress(onProgress, current, force = false) {
     if (current === 0)
         return;
@@ -205,7 +214,7 @@ function reportReplaceProgress(onProgress, current, force = false) {
 export async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
     const maxFileSize = MAX_TEXT_FILE_SIZE;
     const root = await resolveSearchRoot(args.path, signal);
-    const regex = createReplacementRegex(args);
+    const matcher = createReplacementMatcher(args);
     const entries = globEntries({
         cwd: root,
         pattern: args.filePattern,
@@ -226,7 +235,10 @@ export async function handleSearchAndReplace(args, signal, onProgress = () => {
             summary.processedFiles++;
             reportReplaceProgress(onProgress, summary.processedFiles);
         },
-        runEntry: async (entryPath) => processEntry(entryPath, args, regex, maxFileSize, signal, summary),
+        runEntry: async (entryPath) => processEntry(entryPath, {
+            dryRun: args.dryRun,
+            returnDiff: args.returnDiff ?? false,
+        }, args.replacement, matcher, maxFileSize, signal, summary),
     });
     reportReplaceProgress(onProgress, summary.processedFiles, true);
     const failureSuffix = summary.failedFiles > 0 ? ` (${summary.failedFiles} failed)` : '';
@@ -256,16 +268,9 @@ export function registerSearchAndReplaceTool(server, options = {}) {
         run: async (signal) => {
             const dryLabel = args.dryRun ? ' [dry run]' : '';
             const context = `"${args.searchPattern}" in ${args.filePattern}${dryLabel}`;
-            let progressCursor = 0;
-            notifyProgress(extra, {
-                current: 0,
-                message: `🛠 search_and_replace: ${context}`,
-            });
-            const baseReporter = createProgressReporter(extra);
+            const progress = createToolProgressSession(extra, `🛠 search_and_replace: ${context}`);
             const progressWithMessage = ({ current, total, }) => {
-                if (current > progressCursor)
-                    progressCursor = current;
-                baseReporter({
+                progress.update({
                     current,
                     ...(total !== undefined ? { total } : {}),
                     message: `🛠 search_and_replace: ${args.searchPattern} [${current} files processed]`,
@@ -274,7 +279,7 @@ export function registerSearchAndReplaceTool(server, options = {}) {
             try {
                 const result = await handleSearchAndReplace(args, signal, progressWithMessage);
                 const sc = result.structuredContent;
-                const finalCurrent = Math.max((sc.processedFiles ?? 0) + 1, progressCursor + 1);
+                const finalCurrent = Math.max((sc.processedFiles ?? 0) + 1, progress.getCurrent() + 1);
                 const matchWord = (sc.matches ?? 0) === 1 ? 'match' : 'matches';
                 const fileWord = (sc.filesChanged ?? 0) === 1 ? 'file' : 'files';
                 let endSuffix = `${sc.matches ?? 0} ${matchWord} in ${sc.filesChanged ?? 0} ${fileWord}`;
@@ -282,20 +287,11 @@ export function registerSearchAndReplaceTool(server, options = {}) {
                     endSuffix += `, ${sc.failedFiles} failed`;
                 if (sc.dryRun)
                     endSuffix += ' [dry run]';
-                notifyProgress(extra, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `🛠 search_and_replace: ${context} • ${endSuffix}`,
-                });
+                progress.complete(`🛠 search_and_replace: ${context} • ${endSuffix}`, finalCurrent);
                 return result;
             }
             catch (error) {
-                const finalCurrent = Math.max(progressCursor + 1, 1);
-                notifyProgress(extra, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `🛠 search_and_replace: ${context} • failed`,
-                });
+                progress.fail(`🛠 search_and_replace: ${context} • failed`);
                 throw error;
             }
         },

package/dist/tools/search-content.js

@@ -5,7 +5,7 @@ import { DEFAULT_EXCLUDE_PATTERNS } from '../lib/constants.js';
 import { ErrorCode, formatUnknownErrorMessage, McpError, } from '../lib/errors.js';
 import { searchContent } from '../lib/file-operations/search-content.js';
 import { SearchContentInputSchema, SearchContentOutputSchema, } from '../schemas.js';
-import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const MAX_INLINE_MATCHES = parseInt(process.env['FS_CONTEXT_MAX_INLINE_MATCHES'] ?? '', 10) || 50;
 export const SEARCH_CONTENT_TOOL = {
@@ -207,28 +207,16 @@ export function registerSearchContentTool(server, options = {}) {
         run: async (signal) => {
             const scope = args.filePattern;
             const { pattern } = args;
-            let progressCursor = 0;
-            notifyProgress(extra, {
-                current: 0,
-                message: `🔎︎ grep: ${pattern} in ${scope}`,
-            });
-            const baseReporter = createProgressReporter(extra);
+            const progress = createToolProgressSession(extra, `🔎︎ grep: ${pattern} in ${scope}`);
             const progressWithMessage = ({ current, total, }) => {
-                if (current > progressCursor)
-                    progressCursor = current;
                 const fileWord = current === 1 ? 'file' : 'files';
-                baseReporter({
+                progress.update({
                     current,
                     ...(total !== undefined ? { total } : {}),
                     message: `🔎︎ grep: ${pattern} [${current} ${fileWord} scanned]`,
                 });
             };
             try {
-                if (signal) {
-                    signal.addEventListener('abort', () => {
-                        console.error('searchContent signal aborted!');
-                    });
-                }
                 const result = await handleSearchContent(args, signal, options.resourceStore, progressWithMessage);
                 const sc = result.structuredContent;
                 const count = sc.ok && sc.totalMatches ? sc.totalMatches : 0;
@@ -254,21 +242,12 @@ export function registerSearchContentTool(server, options = {}) {
                         suffix += ' [truncated — max files]';
                     }
                 }
-                const finalCurrent = Math.max((sc.filesScanned ?? 0) + 1, progressCursor + 1);
-                notifyProgress(extra, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `🔎︎ grep: ${pattern} • ${suffix}`,
-                });
+                const finalCurrent = Math.max((sc.filesScanned ?? 0) + 1, progress.getCurrent() + 1);
+                progress.complete(`🔎︎ grep: ${pattern} • ${suffix}`, finalCurrent);
                 return result;
             }
             catch (error) {
-                const finalCurrent = Math.max(progressCursor + 1, 1);
-                notifyProgress(extra, {
-                    current: finalCurrent,
-                    total: finalCurrent,
-                    message: `🔎︎ grep: ${pattern} in ${scope} • failed`,
-                });
+                progress.fail(`🔎︎ grep: ${pattern} in ${scope} • failed`);
                 throw error;
             }
         },

package/dist/tools/shared.d.ts

@@ -112,6 +112,18 @@ export declare function notifyProgress(extra: ToolExtra, progress: {
     total?: number;
     message?: string;
 }): void;
+export interface ToolProgressSession {
+    update: (progress: {
+        current: number;
+        total?: number;
+        message: string;
+    }) => void;
+    increment: (messageForCurrent: (current: number) => string) => void;
+    complete: (message: string, minimumCurrent?: number) => void;
+    fail: (message: string, minimumCurrent?: number) => void;
+    getCurrent: () => number;
+}
+export declare function createToolProgressSession(extra: ToolExtra, startMessage: string): ToolProgressSession;
 export declare function wrapToolHandler<Args, Result>(handler: (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>, options: {
     guard?: (() => boolean) | undefined;
     progressMessage?: (args: Args) => string;

package/dist/tools/shared.js

@@ -280,6 +280,55 @@ export function notifyProgress(extra, progress) {
         return;
     void reportProgress(extra, progress);
 }
+export function createToolProgressSession(extra, startMessage) {
+    notifyProgress(extra, {
+        current: 0,
+        message: startMessage,
+    });
+    let cursor = 0;
+    const baseReporter = createProgressReporter(extra);
+    const setCursor = (value) => {
+        if (value > cursor)
+            cursor = value;
+        return cursor;
+    };
+    return {
+        update: ({ current, total, message }) => {
+            const normalized = setCursor(current);
+            baseReporter({
+                current: normalized,
+                ...(total !== undefined ? { total } : {}),
+                message,
+            });
+        },
+        increment: (messageForCurrent) => {
+            const next = setCursor(cursor + 1);
+            baseReporter({
+                current: next,
+                message: messageForCurrent(next),
+            });
+        },
+        complete: (message, minimumCurrent) => {
+            const finalCurrent = Math.max(cursor + 1, minimumCurrent ?? 1, 1);
+            notifyProgress(extra, {
+                current: finalCurrent,
+                total: finalCurrent,
+                message,
+            });
+            cursor = finalCurrent;
+        },
+        fail: (message, minimumCurrent) => {
+            const finalCurrent = Math.max(cursor + 1, minimumCurrent ?? 1, 1);
+            notifyProgress(extra, {
+                current: finalCurrent,
+                total: finalCurrent,
+                message,
+            });
+            cursor = finalCurrent;
+        },
+        getCurrent: () => cursor,
+    };
+}
 async function withProgress(message, extra, run, getCompletionMessage) {
     if (!canReportProgress(extra)) {
         return run();

package/dist/tools/stat-many.js

@@ -4,7 +4,7 @@ import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { getMultipleFileInfo } from '../lib/file-operations/file-info.js';
 import { GetMultipleFileInfoInputSchema, GetMultipleFileInfoOutputSchema, } from '../schemas.js';
-import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const GET_MULTIPLE_FILE_INFO_TOOL = {
     name: 'stat_many',
@@ -79,18 +79,9 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
                     ? `, ${path.basename(args.paths[1] ?? '')}${args.paths.length > 2 ? '…' : ''}`
                     : '';
                 const context = `${args.paths.length} paths [${first}${extraPaths}]`;
-                let progressCursor = 0;
-                notifyProgress(extra, {
-                    current: 0,
-                    message: `🕮 stat_many: ${context}`,
-                });
-                const baseReporter = createProgressReporter(extra);
+                const progress = createToolProgressSession(extra, `🕮 stat_many: ${context}`);
                 const onProgress = () => {
-                    progressCursor++;
-                    baseReporter({
-                        current: progressCursor,
-                        message: `🕮 stat_many: ${context} [${progressCursor}/${args.paths.length} scanned]`,
-                    });
+                    progress.increment((current) => `🕮 stat_many: ${context} [${current}/${args.paths.length} scanned]`);
                 };
                 try {
                     const result = await handleGetMultipleFileInfo(args, signal, onProgress);
@@ -105,21 +96,12 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
                     else {
                         suffix = `${total} OK`;
                     }
-                    const finalCurrent = Math.max(total, progressCursor + 1);
-                    notifyProgress(extra, {
-                        current: finalCurrent,
-                        total: finalCurrent,
-                        message: `🕮 stat_many: ${context} • ${suffix}`,
-                    });
+                    const finalCurrent = Math.max(total, progress.getCurrent() + 1);
+                    progress.complete(`🕮 stat_many: ${context} • ${suffix}`, finalCurrent);
                     return result;
                 }
                 catch (error) {
-                    const finalCurrent = Math.max(progressCursor + 1, 1);
-                    notifyProgress(extra, {
-                        current: finalCurrent,
-                        total: finalCurrent,
-                        message: `🕮 stat_many: ${context} • failed`,
-                    });
+                    progress.fail(`🕮 stat_many: ${context} • failed`);
                     throw error;
                 }
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/filesystem-mcp",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "mcpName": "io.github.j0hanz/filesystem-mcp",
   "description": "MCP Server that enables LLMs to interact with the local filesystem.",
   "type": "module",
@@ -37,8 +37,6 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "node scripts/tasks.mjs test",
-    "test:fast": "node --test --import tsx/esm src/__tests__/**/*.test.ts node-tests/**/*.test.ts",
-    "test:coverage": "node scripts/tasks.mjs test --coverage",
     "knip": "knip",
     "knip:fix": "knip --fix",
     "inspector": "npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js ${workspaceFolder}",