@j0hanz/filesystem-mcp 1.0.4 → 1.1.0

package/README.md

@@ -90,7 +90,7 @@ docker run -i --rm \
 
 ## Configuration
 
-The server requires specifying allowed directories via command-line arguments.
+Allowed directories can be provided via command-line arguments, via the MCP Roots protocol, or by using `--allow-cwd`.
 
 ### Arguments
 

package/dist/cli.d.ts

@@ -2,8 +2,7 @@ export declare class CliExitError extends Error {
     readonly exitCode: number;
     constructor(message: string, exitCode: number);
 }
-export interface ParseArgsResult {
+export declare function parseArgs(): Promise<{
     allowedDirs: string[];
     allowCwd: boolean;
-}
-export declare function parseArgs(): Promise<ParseArgsResult>;
+}>;

package/dist/completions.d.ts

@@ -4,6 +4,10 @@ interface CompletionResult {
     total?: number;
     hasMore?: boolean;
 }
-export declare function getPathCompletions(currentValue: string): Promise<CompletionResult>;
+interface CompletionOptions {
+    argumentName?: string;
+    contextArguments?: Record<string, string>;
+}
+export declare function getPathCompletions(currentValue: string, options?: CompletionOptions): Promise<CompletionResult>;
 export declare function registerCompletions(server: McpServer): void;
 export {};

package/dist/completions.js

@@ -3,6 +3,103 @@ import * as path from 'node:path';
 import { CompleteRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { getAllowedDirectories, isPathWithinDirectories, normalizePath, } from './lib/path-validation.js';
 const MAX_COMPLETION_ITEMS = 100;
+const PATH_ARGUMENTS = new Set([
+    'path',
+    'source',
+    'destination',
+    'original',
+    'modified',
+    'directory',
+    'file',
+    'root',
+    'cwd',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isPathLikeArgumentName(argName) {
+    return (PATH_ARGUMENTS.has(argName) ||
+        argName.endsWith('paths') ||
+        argName.endsWith('path') ||
+        argName.endsWith('files') ||
+        argName.endsWith('file') ||
+        argName.endsWith('dirs') ||
+        argName.endsWith('dir'));
+}
+function parseResourceReference(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (value['type'] !== 'ref/resource')
+        return undefined;
+    const { uri } = value;
+    if (typeof uri !== 'string')
+        return undefined;
+    return { type: 'ref/resource', uri };
+}
+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);
+        if (start === -1)
+            break;
+        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();
+            }
+        }
+        if (normalized.length > 0)
+            vars.push(normalized);
+        index = end + 1;
+    }
+    return vars;
+}
+function isPathArgumentFromReference(argumentName, ref) {
+    const resourceRef = parseResourceReference(ref);
+    if (!resourceRef)
+        return false;
+    const normalizedArg = argumentName.toLowerCase();
+    const templateVars = extractTemplateVariables(resourceRef.uri);
+    if (templateVars.length === 0)
+        return false;
+    const matchesVariable = templateVars.includes(normalizedArg);
+    if (!matchesVariable)
+        return false;
+    if (isPathLikeArgumentName(normalizedArg))
+        return true;
+    if (resourceRef.uri.toLowerCase().includes('file:///'))
+        return true;
+    const uriLooksPathLike = resourceRef.uri.includes('/') &&
+        (resourceRef.uri.toLowerCase().includes('path') ||
+            resourceRef.uri.toLowerCase().includes('file') ||
+            resourceRef.uri.toLowerCase().includes('dir') ||
+            resourceRef.uri.toLowerCase().includes('root') ||
+            resourceRef.uri.toLowerCase().includes('cwd'));
+    return uriLooksPathLike;
+}
+function extractContextArguments(value) {
+    if (!isRecord(value))
+        return undefined;
+    const context = value['arguments'];
+    if (!isRecord(context))
+        return undefined;
+    const entries = Object.entries(context).filter((entry) => typeof entry[1] === 'string');
+    if (entries.length === 0)
+        return undefined;
+    return Object.fromEntries(entries.map(([key, val]) => [key.toLowerCase(), val]));
+}
 function hasTrailingSeparator(value) {
     return (value.endsWith(path.sep) || value.endsWith('/') || value.endsWith('\\'));
 }
@@ -33,18 +130,97 @@ function resolveNamedRootContext(currentValue, allowed) {
     const remainder = rest.join(path.sep);
     return resolveFromBase(root, remainder, trailingSeparator);
 }
-function getSearchContext(currentValue, allowed) {
+function resolveNamedRootPath(value, allowed) {
+    const normalizedInput = value.replace(/\\/gu, '/');
+    const [rootName, ...rest] = normalizedInput.split('/');
+    if (!rootName)
+        return undefined;
+    const root = allowed.find((candidate) => path.basename(candidate).toLowerCase() === rootName.toLowerCase());
+    if (!root)
+        return undefined;
+    const remainder = rest.join(path.sep);
+    return normalizePath(path.resolve(root, remainder));
+}
+function chooseContextKeys(argumentName) {
+    const normalized = argumentName.toLowerCase();
+    if (normalized === 'destination') {
+        return ['source', 'path', 'cwd', 'root'];
+    }
+    if (normalized === 'path' ||
+        normalized === 'source' ||
+        normalized === 'original' ||
+        normalized === 'modified' ||
+        normalized === 'file') {
+        return ['path', 'cwd', 'root'];
+    }
+    return ['path', 'source', 'cwd', 'root'];
+}
+function resolveContextCandidatePath(candidate, allowed) {
+    if (isAbsolutePathInput(candidate)) {
+        return normalizePath(candidate);
+    }
+    if (allowed.length === 1) {
+        const base = allowed[0];
+        if (!base)
+            return undefined;
+        return normalizePath(path.resolve(base, candidate));
+    }
+    return resolveNamedRootPath(candidate, allowed);
+}
+async function toAllowedContextDirectory(resolved, allowed) {
+    if (!isPathWithinDirectories(resolved, allowed))
+        return undefined;
+    try {
+        const stats = await fs.stat(resolved);
+        if (stats.isDirectory())
+            return resolved;
+    }
+    catch {
+        // Fall back to parent path best-effort resolution.
+    }
+    const parent = path.dirname(resolved);
+    return isPathWithinDirectories(parent, allowed) ? parent : undefined;
+}
+async function resolveContextBaseDirectory(argumentName, contextArguments, allowed) {
+    if (!contextArguments || Object.keys(contextArguments).length === 0) {
+        return undefined;
+    }
+    const keys = chooseContextKeys(argumentName);
+    for (const key of keys) {
+        const candidate = contextArguments[key];
+        if (!candidate || candidate.trim().length === 0)
+            continue;
+        const resolved = resolveContextCandidatePath(candidate, allowed);
+        if (!resolved)
+            continue;
+        const baseDirectory = await toAllowedContextDirectory(resolved, allowed);
+        if (baseDirectory)
+            return baseDirectory;
+    }
+    return undefined;
+}
+function getSearchContext(currentValue, allowed, contextBase) {
     const trailingSeparator = hasTrailingSeparator(currentValue);
     if (isAbsolutePathInput(currentValue)) {
         return resolveFromBase(path.parse(currentValue).root || path.sep, currentValue, trailingSeparator);
     }
+    const namedRootContext = resolveNamedRootContext(currentValue, allowed);
+    if (namedRootContext) {
+        return namedRootContext;
+    }
+    if (contextBase) {
+        if (currentValue.length === 0) {
+            return { searchDir: contextBase, prefix: '' };
+        }
+        return resolveFromBase(contextBase, currentValue, trailingSeparator);
+    }
     if (allowed.length === 1) {
         const base = allowed[0];
         if (base) {
             return resolveFromBase(base, currentValue, trailingSeparator);
         }
     }
-    return resolveNamedRootContext(currentValue, allowed);
+    return undefined;
 }
 async function findMatchesInDirectory(searchDir, prefix, allowed) {
     const matches = [];
@@ -92,18 +268,19 @@ function findMatchingRoots(searchDir, prefix, allowed) {
     }
     return matches;
 }
-export async function getPathCompletions(currentValue) {
+export async function getPathCompletions(currentValue, options = {}) {
     const allowed = getAllowedDirectories();
-    // If empty, suggest allowed roots
-    if (!currentValue) {
-        return {
-            values: allowed,
-            total: allowed.length,
-            hasMore: false,
-        };
-    }
     try {
-        const context = getSearchContext(currentValue, allowed);
+        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,
+            };
+        }
+        const context = getSearchContext(currentValue, allowed, contextBase);
         if (!context) {
             const rootMatches = findRootPrefixMatches(currentValue, allowed);
             const sliced = rootMatches.slice(0, MAX_COMPLETION_ITEMS);
@@ -143,32 +320,19 @@ export async function getPathCompletions(currentValue) {
 export function registerCompletions(server) {
     server.server.setRequestHandler(CompleteRequestSchema, async (request) => {
         const { params } = request;
-        const { argument } = params;
-        const pathArguments = new Set([
-            'path',
-            'source',
-            'destination',
-            'original',
-            'modified',
-            'directory',
-            'file',
-            'root',
-            'cwd',
-        ]);
-        // Check if argument name is relevant or ends with path-like suffixes
+        const { argument, ref } = params;
         const argName = argument.name.toLowerCase();
-        const isPathArg = pathArguments.has(argName) ||
-            argName.endsWith('paths') ||
-            argName.endsWith('path') ||
-            argName.endsWith('files') ||
-            argName.endsWith('file') ||
-            argName.endsWith('dirs') ||
-            argName.endsWith('dir');
+        const isPathArg = isPathLikeArgumentName(argName) ||
+            isPathArgumentFromReference(argName, ref);
         if (!isPathArg) {
             return { completion: { values: [], total: 0, hasMore: false } };
         }
+        const contextArguments = extractContextArguments(params.context);
         const { value } = argument;
-        const completions = await getPathCompletions(value);
+        const completions = await getPathCompletions(value, {
+            argumentName: argName,
+            ...(contextArguments ? { contextArguments } : {}),
+        });
         return {
             completion: {
                 values: completions.values,

package/dist/index.js

@@ -19,6 +19,7 @@ async function shutdown(reason, exitCode = 0) {
         console.error(`Shutdown timed out (${reason}), forcing exit.`);
         process.exit(exitCode);
     }, SHUTDOWN_TIMEOUT_MS);
+    timer.unref();
     try {
         if (activeServer) {
             await activeServer.close();

package/dist/instructions.md

@@ -29,7 +29,7 @@ These instructions are available as a resource (internal://instructions) or prom
 ## PROGRESS & TASKS
 
 - Include `_meta.progressToken` in requests to receive `notifications/progress` updates for long-running tools.
-- Task-augmented tool calls are supported for `grep`, `find`, `search_and_replace`, `tree`, `read_many`, and `stat_many`:
+- Task-augmented tool calls are supported for `grep`, `find`, `calculate_hash`, `search_and_replace`, `tree`, `read_many`, and `stat_many`:
   - These tools declare `execution.taskSupport: "optional"` — invoke normally or as a task.
   - Send `tools/call` with `task` to get a task id.
   - Poll `tasks/get` and fetch results via `tasks/result`.

package/dist/lib/constants.js

@@ -33,9 +33,30 @@ function parseEnvList(envVar) {
         .filter((entry) => entry.length > 0);
 }
 // Auto-tuned parallelism based on CPU cores (no env override)
+const BYTES_PER_PARALLEL_TASK = 64 * 1024 * 1024;
+const BYTES_PER_SEARCH_WORKER = 128 * 1024 * 1024;
+function getAvailableMemory() {
+    if (typeof process.availableMemory !== 'function')
+        return undefined;
+    const available = process.availableMemory();
+    if (!Number.isFinite(available) || available <= 0)
+        return undefined;
+    return available;
+}
+function applyMemoryBound(cpuBound, bytesPerUnit, minValue) {
+    const availableMemory = getAvailableMemory();
+    if (availableMemory === undefined)
+        return cpuBound;
+    const memoryBound = Math.floor(availableMemory / bytesPerUnit);
+    return Math.min(cpuBound, Math.max(memoryBound, minValue));
+}
 function getOptimalParallelism() {
-    const cpuCores = availableParallelism();
-    return Math.min(Math.max(cpuCores, 4), 32);
+    const cpuBound = Math.min(Math.max(availableParallelism(), 4), 32);
+    return applyMemoryBound(cpuBound, BYTES_PER_PARALLEL_TASK, 2);
+}
+function getDefaultSearchWorkers() {
+    const cpuBound = Math.min(availableParallelism(), 8);
+    return applyMemoryBound(cpuBound, BYTES_PER_SEARCH_WORKER, 1);
 }
 // Hardcoded optimal values (no env override needed)
 export const PARALLEL_CONCURRENCY = getOptimalParallelism();
@@ -52,7 +73,7 @@ const ENV_ALLOWLIST = parseEnvList('FS_CONTEXT_ALLOWLIST');
  * Default: CPU cores (capped at 8 for optimal I/O performance).
  * Configurable via FS_CONTEXT_SEARCH_WORKERS env var.
  */
-export const SEARCH_WORKERS = parseEnvInt('FS_CONTEXT_SEARCH_WORKERS', Math.min(availableParallelism(), 8), 0, 16);
+export const SEARCH_WORKERS = parseEnvInt('FS_CONTEXT_SEARCH_WORKERS', getDefaultSearchWorkers(), 0, 16);
 // Hardcoded defaults
 export const DEFAULT_MAX_DEPTH = 10;
 export const DEFAULT_LIST_MAX_ENTRIES = 10000;

package/dist/lib/errors.js

@@ -1,9 +1,16 @@
 import { constants as osConstants } from 'node:os';
-import { getSystemErrorName, inspect } from 'node:util';
+import { getSystemErrorMap, getSystemErrorName, inspect } from 'node:util';
 import { ErrorCode, joinLines } from '../config.js';
 export { ErrorCode };
+function isNativeError(error) {
+    const candidate = Error;
+    if (typeof candidate.isError === 'function') {
+        return candidate.isError(error);
+    }
+    return error instanceof Error;
+}
 export function isNodeError(error) {
-    if (!(error instanceof Error))
+    if (!isNativeError(error))
         return false;
     if (!('code' in error))
         return false;
@@ -11,7 +18,7 @@ export function isNodeError(error) {
     return typeof code === 'string';
 }
 function getNodeErrno(error) {
-    if (!(error instanceof Error))
+    if (!isNativeError(error))
         return undefined;
     if (!('errno' in error))
         return undefined;
@@ -21,6 +28,7 @@ function getNodeErrno(error) {
     return errno;
 }
 const ERRNO_CODE_BY_VALUE = new Map();
+const SYSTEM_ERROR_MAP = getSystemErrorMap();
 for (const [name, value] of Object.entries(osConstants.errno)) {
     if (typeof value !== 'number')
         continue;
@@ -29,6 +37,15 @@ for (const [name, value] of Object.entries(osConstants.errno)) {
     }
 }
 const ERROR_CODE_RE = /^[A-Z][A-Z0-9_]+$/u;
+function getSystemErrorNameFromMap(errno) {
+    const direct = SYSTEM_ERROR_MAP.get(errno);
+    if (direct)
+        return direct[0];
+    const normalized = SYSTEM_ERROR_MAP.get(-Math.abs(errno));
+    if (normalized)
+        return normalized[0];
+    return undefined;
+}
 function getNodeErrorCodeFromErrno(errno) {
     const direct = ERRNO_CODE_BY_VALUE.get(errno);
     if (direct)
@@ -36,8 +53,11 @@ function getNodeErrorCodeFromErrno(errno) {
     const normalized = ERRNO_CODE_BY_VALUE.get(Math.abs(errno));
     if (normalized)
         return normalized;
+    const fromMap = getSystemErrorNameFromMap(errno);
+    if (fromMap && ERROR_CODE_RE.test(fromMap))
+        return fromMap;
     try {
-        const fromSystem = getSystemErrorName(errno);
+        const fromSystem = getSystemErrorName(errno <= 0 ? errno : -errno);
         return ERROR_CODE_RE.test(fromSystem) ? fromSystem : undefined;
     }
     catch {
@@ -55,7 +75,7 @@ function getNodeErrorCodeLabel(error) {
 export function formatUnknownErrorMessage(error) {
     if (typeof error === 'string')
         return error;
-    if (error instanceof Error)
+    if (isNativeError(error))
         return error.message;
     try {
         return inspect(error, {
@@ -99,7 +119,7 @@ function walkErrorChain(error, visitor) {
     while (current !== undefined && current !== null && !visited.has(current)) {
         if (visitor(current))
             return true;
-        if (!(current instanceof Error))
+        if (!isNativeError(current))
             break;
         visited.add(current);
         const next = current.cause;
@@ -108,7 +128,7 @@ function walkErrorChain(error, visitor) {
     return false;
 }
 function isAbortErrorSingle(error) {
-    if (!(error instanceof Error))
+    if (!isNativeError(error))
         return false;
     if (error.name === 'AbortError')
         return true;
@@ -119,7 +139,7 @@ export function isAbortError(error) {
     return walkErrorChain(error, isAbortErrorSingle);
 }
 function isTimeoutErrorSingle(error) {
-    if (!(error instanceof Error))
+    if (!isNativeError(error))
         return false;
     if (error.name === 'TimeoutError')
         return true;
@@ -178,7 +198,7 @@ function getDirectErrorCode(error) {
     return undefined;
 }
 function classifyMessageError(error) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = isNativeError(error) ? error.message : String(error);
     const lower = message.toLowerCase();
     if (lower.includes('enoent') || lower.includes('no such file or directory')) {
         return ErrorCode.E_NOT_FOUND;

package/dist/lib/observability.d.ts

@@ -5,12 +5,6 @@ interface OpsTraceContext {
     path?: string | undefined;
     [key: string]: unknown;
 }
-export interface ToolMetrics {
-    calls: number;
-    errors: number;
-    totalDurationMs: number;
-}
-export declare function getToolMetrics(): Record<string, ToolMetrics>;
 export declare function shouldPublishOpsTrace(): boolean;
 export declare function publishOpsTraceStart(context: OpsTraceContext): void;
 export declare function publishOpsTraceEnd(context: OpsTraceContext): void;

package/dist/lib/observability.js

@@ -23,9 +23,6 @@ function parseDetail(val) {
     return 0;
 }
 const globalMetrics = new Map();
-export function getToolMetrics() {
-    return Object.fromEntries(globalMetrics);
-}
 function updateMetrics(tool, ok, durationMs) {
     const current = globalMetrics.get(tool) ?? {
         calls: 0,
@@ -146,11 +143,23 @@ function getDelayStats(h) {
         exceeds: h.exceeds,
     };
 }
+function clearPublishedMeasures(entries) {
+    if (entries.length === 0)
+        return;
+    const names = new Set();
+    for (const entry of entries) {
+        names.add(entry.name);
+    }
+    for (const name of names) {
+        performance.clearMeasures(name);
+    }
+}
 function ensureObserver() {
     if (perfObserver)
         return;
     perfObserver = new PerformanceObserver((list) => {
-        for (const entry of list.getEntries()) {
+        const entries = list.getEntries();
+        for (const entry of entries) {
             CHANNELS.perf.publish({
                 phase: 'measure',
                 name: entry.name,
@@ -158,6 +167,13 @@ function ensureObserver() {
                 detail: entry.detail,
             });
         }
+        try {
+            // Keep the global timeline bounded while preserving published events.
+            clearPublishedMeasures(entries);
+        }
+        catch {
+            // Never allow observability cleanup to affect tool execution.
+        }
     });
     perfObserver.observe({ entryTypes: ['measure'] });
 }
@@ -208,22 +224,36 @@ export function startPerfMeasure(name, detail) {
     const startMark = `${name}:start:${id}`;
     const endMark = `${name}:end:${id}`;
     const runInCapturedContext = AsyncLocalStorage.snapshot();
+    let finished = false;
     performance.mark(startMark);
     return (ok) => {
-        runInCapturedContext(() => {
-            performance.mark(endMark);
-            let meta = enrichWithToolContext(detail);
-            if (ok !== undefined) {
-                meta = { ...(meta ?? {}), ok };
-            }
-            performance.measure(name, {
-                start: startMark,
-                end: endMark,
-                detail: meta,
+        if (finished)
+            return;
+        finished = true;
+        try {
+            runInCapturedContext(() => {
+                try {
+                    performance.mark(endMark);
+                    let meta = enrichWithToolContext(detail);
+                    if (ok !== undefined) {
+                        meta = { ...(meta ?? {}), ok };
+                    }
+                    performance.measure(name, {
+                        start: startMark,
+                        end: endMark,
+                        detail: meta,
+                    });
+                }
+                finally {
+                    performance.clearMarks(startMark);
+                    performance.clearMarks(endMark);
+                }
             });
+        }
+        catch {
             performance.clearMarks(startMark);
             performance.clearMarks(endMark);
-        });
+        }
     };
 }
 function publishToolStart(tool, pathVal) {

package/dist/schemas.d.ts

@@ -11,14 +11,6 @@ interface TreeEntry {
     relativePath: string;
     children?: TreeEntry[] | undefined;
 }
-export declare const ErrorSchema: z.ZodObject<{
-    code: z.ZodEnum<{
-        [x: string]: string;
-    }>;
-    message: z.ZodString;
-    path: z.ZodOptional<z.ZodString>;
-    suggestion: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
 export declare const ToolErrorResponseSchema: z.ZodObject<{
     ok: z.ZodLiteral<false>;
     error: z.ZodObject<{

package/dist/schemas.js

@@ -43,7 +43,7 @@ const TreeEntrySchema = z.lazy(() => z.strictObject({
     relativePath: z.string().describe('Relative path'),
     children: z.array(TreeEntrySchema).optional().describe('Children'),
 }));
-export const ErrorSchema = z.strictObject({
+const ErrorSchema = z.strictObject({
     code: z
         .enum(Object.values(ErrorCode))
         .describe('Error code (e.g. E_NOT_FOUND)'),

package/dist/tools/calculate-hash.js

@@ -3,12 +3,14 @@ import * as path from 'node:path';
 import { createHash } from 'node:crypto';
 import { createReadStream } from 'node:fs';
 import { ErrorCode } from '../lib/errors.js';
+import { isIgnoredByGitignore, loadRootGitignore, } from '../lib/file-operations/gitignore.js';
 import { globEntries } from '../lib/file-operations/glob-engine.js';
 import { assertNotAborted, createTimedAbortSignal, withAbort, } from '../lib/fs-helpers.js';
 import { withToolDiagnostics } from '../lib/observability.js';
 import { validateExistingPath } from '../lib/path-validation.js';
 import { CalculateHashInputSchema, CalculateHashOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, withDefaultIcons, withToolErrorHandling, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createProgressReporter, getExperimentalTaskRegistration, notifyProgress, withDefaultIcons, withToolErrorHandling, wrapToolHandler, } from './shared.js';
+import { createToolTaskHandler } from './task-support.js';
 const WINDOWS_PATH_SEPARATOR = /\\/gu;
 const CALCULATE_HASH_TOOL = {
     title: 'Calculate Hash',
@@ -52,9 +54,19 @@ function updateCompositeHash(hasher, pathLengthBytes, relativePath, fileHash) {
     hasher.update(relativePathBytes);
     hasher.update(fileHash);
 }
-async function hashDirectory(dirPath, signal) {
-    // Enumerate all files in directory (respects .gitignore by default)
+function reportHashProgress(onProgress, current, force = false) {
+    if (!onProgress || current === 0)
+        return;
+    if (!force && current % 25 !== 0)
+        return;
+    onProgress({ current });
+}
+async function hashDirectory(dirPath, options = {}) {
+    const { signal, onProgress } = options;
+    const gitignoreMatcher = await loadRootGitignore(dirPath, signal);
+    // Enumerate all files in directory.
     const entries = [];
+    let filesHashed = 0;
     for await (const entry of globEntries({
         cwd: dirPath,
         pattern: '**/*',
@@ -68,12 +80,19 @@ async function hashDirectory(dirPath, signal) {
         suppressErrors: true,
     })) {
         assertNotAborted(signal);
+        if (gitignoreMatcher &&
+            isIgnoredByGitignore(gitignoreMatcher, dirPath, entry.path)) {
+            continue;
+        }
         // entry.path is already absolute, no need to join
         const fileHash = await hashFile(entry.path, undefined, signal);
         // Use posix separators so hashes are stable across OS path separators.
         const relativePath = toStableRelativePath(dirPath, entry.path);
         entries.push({ path: relativePath, hash: fileHash });
+        filesHashed++;
+        reportHashProgress(onProgress, filesHashed);
     }
+    reportHashProgress(onProgress, filesHashed, true);
     assertNotAborted(signal);
     // Sort by path with byte-wise semantics for deterministic ordering.
     entries.sort(comparePaths);
@@ -89,13 +108,16 @@ async function hashDirectory(dirPath, signal) {
         fileCount: entries.length,
     };
 }
-async function handleCalculateHash(args, signal) {
+async function handleCalculateHash(args, signal, onProgress) {
     const validPath = await validateExistingPath(args.path, signal);
     // Check if path is a directory or file
     const stats = await withAbort(fs.stat(validPath), signal);
     if (stats.isDirectory()) {
         // Hash directory: composite hash of all files
-        const { hash, fileCount } = await hashDirectory(validPath, signal);
+        const { hash, fileCount } = await hashDirectory(validPath, {
+            ...(signal ? { signal } : {}),
+            ...(onProgress ? { onProgress } : {}),
+        });
         return buildToolResponse(`${hash} (${fileCount} files)`, {
             ok: true,
             path: validPath,
@@ -107,6 +129,7 @@ async function handleCalculateHash(args, signal) {
     else {
         // Hash single file
         const hash = await hashFile(validPath, 'hex', signal);
+        reportHashProgress(onProgress, 1, true);
         return buildToolResponse(hash, {
             ok: true,
             path: validPath,
@@ -117,19 +140,42 @@ async function handleCalculateHash(args, signal) {
 }
 export function registerCalculateHashTool(server, options = {}) {
     const handler = (args, extra) => withToolDiagnostics('calculate_hash', () => withToolErrorHandling(async () => {
+        notifyProgress(extra, {
+            current: 0,
+            message: `🕮 calculate_hash: ${path.basename(args.path)}`,
+        });
         const { signal, cleanup } = createTimedAbortSignal(extra.signal);
         try {
-            return await handleCalculateHash(args, signal);
+            const result = await handleCalculateHash(args, signal, createProgressReporter(extra));
+            const sc = result.structuredContent;
+            const totalFiles = sc.ok ? (sc.fileCount ?? 1) : 1;
+            const finalCurrent = totalFiles + 1;
+            const suffix = sc.ok
+                ? `${(sc.hash ?? '').slice(0, 8)}...`
+                : 'failed';
+            notifyProgress(extra, {
+                current: finalCurrent,
+                message: `🕮 calculate_hash: ${path.basename(args.path)} ➟ ${suffix}`,
+            });
+            return result;
         }
         finally {
             cleanup();
         }
     }, (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path)), { path: args.path });
-    server.registerTool('calculate_hash', withDefaultIcons({ ...CALCULATE_HASH_TOOL }, options.iconInfo), wrapToolHandler(handler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => {
-            const name = path.basename(args.path);
-            return `🕮 calculate_hash: ${name}`;
-        },
-    }));
+    });
+    const taskOptions = options.isInitialized
+        ? { guard: options.isInitialized }
+        : undefined;
+    const tasks = getExperimentalTaskRegistration(server);
+    if (tasks?.registerToolTask) {
+        tasks.registerToolTask('calculate_hash', withDefaultIcons({
+            ...CALCULATE_HASH_TOOL,
+            execution: { taskSupport: 'optional' },
+        }, options.iconInfo), createToolTaskHandler(wrappedHandler, taskOptions));
+        return;
+    }
+    server.registerTool('calculate_hash', withDefaultIcons({ ...CALCULATE_HASH_TOOL }, options.iconInfo), wrappedHandler);
 }

package/dist/tools/shared.d.ts

@@ -54,10 +54,9 @@ export interface ToolRegistrationOptions {
     serverIcon?: string;
     iconInfo?: IconInfo;
 }
-export interface ExperimentalTaskRegistration {
+export declare function getExperimentalTaskRegistration(server: McpServer): {
     registerToolTask?: (...args: unknown[]) => unknown;
-}
-export declare function getExperimentalTaskRegistration(server: McpServer): ExperimentalTaskRegistration | undefined;
+} | undefined;
 export declare function withToolErrorHandling<T>(run: () => Promise<ToolResponse<T>>, onError: (error: unknown) => ToolResult<T>): Promise<ToolResult<T>>;
 export declare function buildToolErrorResponse(error: unknown, defaultCode: ErrorCode, path?: string): ToolErrorResponse;
 export declare function createProgressReporter(extra: ToolExtra): (progress: {

package/dist/tools/task-support.js

@@ -1,6 +1,8 @@
 import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
 import { ErrorCode, McpError } from '../lib/errors.js';
 import { buildToolErrorResponse } from './shared.js';
+const RELATED_TASK_META_KEY = 'io.modelcontextprotocol/related-task';
+const TASK_STATUS_NOTIFICATION_METHOD = 'notifications/tasks/status';
 function isRecord(value) {
     return value !== null && typeof value === 'object';
 }
@@ -87,6 +89,60 @@ function normalizeCallToolResult(value) {
         return parsed.data;
     throw new McpError(ErrorCode.E_INVALID_INPUT, 'Stored task result is not a valid tool result.');
 }
+function withRelatedTaskMeta(result, taskId) {
+    if (!isRecord(result)) {
+        return {
+            _meta: {
+                [RELATED_TASK_META_KEY]: { taskId },
+            },
+        };
+    }
+    const existingMeta = isRecord(result['_meta']) ? result['_meta'] : {};
+    return {
+        ...result,
+        _meta: {
+            ...existingMeta,
+            [RELATED_TASK_META_KEY]: { taskId },
+        },
+    };
+}
+function getTaskStatusNotificationSender(extra) {
+    const candidate = extra.sendNotification;
+    return typeof candidate === 'function'
+        ? candidate
+        : undefined;
+}
+function buildTaskStatusNotificationParams(task) {
+    return {
+        taskId: task.taskId,
+        status: task.status,
+        ttl: task.ttl,
+        createdAt: task.createdAt,
+        lastUpdatedAt: task.lastUpdatedAt,
+        ...(task.pollInterval !== undefined
+            ? { pollInterval: task.pollInterval }
+            : {}),
+        ...(task.statusMessage !== undefined
+            ? { statusMessage: task.statusMessage }
+            : {}),
+    };
+}
+async function notifyTaskStatusIfPossible(extra, taskStore, taskId) {
+    const sendNotification = getTaskStatusNotificationSender(extra);
+    if (!sendNotification)
+        return;
+    try {
+        const task = await taskStore.getTask(taskId);
+        const normalized = normalizeGetTaskResult(task);
+        await sendNotification({
+            method: TASK_STATUS_NOTIFICATION_METHOD,
+            params: buildTaskStatusNotificationParams(normalized),
+        });
+    }
+    catch {
+        // Never fail task execution because status notifications are optional.
+    }
+}
 function getTaskStore(extra) {
     if (!extra.taskStore) {
         throw new McpError(ErrorCode.E_INVALID_INPUT, 'Task store not configured for task-capable tool.');
@@ -130,11 +186,12 @@ async function getCurrentTaskStatus(taskStore, taskId) {
     }
 }
 async function tryStoreTaskResult(taskStore, taskId, status, result) {
+    const resultWithTaskMeta = withRelatedTaskMeta(result, taskId);
     const beforeStatus = await getCurrentTaskStatus(taskStore, taskId);
     if (isTerminalTaskStatus(beforeStatus))
         return;
     try {
-        await taskStore.storeTaskResult(taskId, status, result);
+        await taskStore.storeTaskResult(taskId, status, resultWithTaskMeta);
     }
     catch (error) {
         const afterStatus = await getCurrentTaskStatus(taskStore, taskId);
@@ -160,16 +217,19 @@ export function createToolTaskHandler(run, options) {
             taskStore,
             taskId: task.taskId,
         };
+        void notifyTaskStatusIfPossible(taskExtra, taskStore, task.taskId);
         void (async () => {
             try {
                 const result = await run(args, taskExtra);
                 const status = isErrorResult(result) ? 'failed' : 'completed';
                 await tryStoreTaskResult(taskStore, task.taskId, status, result);
+                await notifyTaskStatusIfPossible(taskExtra, taskStore, task.taskId);
             }
             catch (error) {
                 const fallback = buildToolErrorResponse(error, ErrorCode.E_UNKNOWN);
                 try {
                     await tryStoreTaskResult(taskStore, task.taskId, 'failed', fallback);
+                    await notifyTaskStatusIfPossible(taskExtra, taskStore, task.taskId);
                 }
                 catch {
                     // Swallow to avoid unhandled rejections from background task writes.
@@ -190,7 +250,7 @@ export function createToolTaskHandler(run, options) {
         const taskStore = getTaskStore(extra);
         const taskId = getTaskId(extra);
         const result = await taskStore.getTaskResult(taskId);
-        return normalizeCallToolResult(result);
+        return normalizeCallToolResult(withRelatedTaskMeta(result, taskId));
     });
     return {
         createTask,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/filesystem-mcp",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "mcpName": "io.github.j0hanz/filesystem-mcp",
   "description": "MCP Server that enables LLMs to interact with the local filesystem.",
   "type": "module",
@@ -73,7 +73,6 @@
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@trivago/prettier-plugin-sort-imports": "^6.0.2",
-    "@types/diff": "^7.0.2",
     "@types/node": "^24",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",