@j0hanz/filesystem-mcp 1.14.0 → 1.15.0

package/dist/tools/shared.js

@@ -1,10 +1,11 @@
-import * as path from 'node:path';
 import { channel } from 'node:diagnostics_channel';
+import { basename } from 'node:path';
 import { z } from 'zod';
+import { createTimedAbortSignal } from '../lib/abort.js';
 import { parseTrueEnvFlag } from '../lib/constants.js';
 import { createDetailedError, ErrorCode, formatDetailedError, getSuggestion, McpError, } from '../lib/errors.js';
-import { createTimedAbortSignal } from '../lib/fs-helpers.js';
-import { withToolDiagnostics } from '../lib/observability.js';
+import { Logger } from '../lib/logger.js';
+import { withToolDiagnostics, } from '../lib/observability.js';
 import { getAllowedDirectories } from '../lib/paths.js';
 import { createBase64JsonCodec } from '../lib/zod-codecs.js';
 export {} from './contract.js';
@@ -12,6 +13,20 @@ const MAX_INLINE_CONTENT_CHARS = parseInt(process.env['FS_CONTEXT_MAX_INLINE_CHA
 const MAX_INLINE_PREVIEW_CHARS = 4_000;
 const PROGRESS_RATE_LIMIT_MS = 50;
 const CONTEXT_DIAGNOSTICS_CHANNEL = channel('filesystem-mcp:context');
+// W3C Trace Context: version-traceid-parentid-traceflags
+const TRACEPARENT_RE = /^[\da-f]{2}-[\da-f]{32}-[\da-f]{16}-[\da-f]{2}$/i;
+function extractTraceContext(meta) {
+    const tp = meta?.traceparent;
+    if (typeof tp !== 'string' || !TRACEPARENT_RE.test(tp))
+        return undefined;
+    return {
+        traceparent: tp,
+        ...(typeof meta?.tracestate === 'string'
+            ? { tracestate: meta.tracestate }
+            : {}),
+        ...(typeof meta?.baggage === 'string' ? { baggage: meta.baggage } : {}),
+    };
+}
 function publishContextDiagnostics(event) {
     if (!CONTEXT_DIAGNOSTICS_CHANNEL.hasSubscribers)
         return;
@@ -45,11 +60,13 @@ function normalizeToolExecution(tool) {
         ? candidate['execution']
         : undefined;
     const executionTaskSupport = existingExecution?.['taskSupport'];
-    const resolvedTaskSupport = isTaskSupportLevel(topLevelTaskSupport)
-        ? topLevelTaskSupport
-        : isTaskSupportLevel(executionTaskSupport)
-            ? executionTaskSupport
-            : undefined;
+    let resolvedTaskSupport;
+    if (isTaskSupportLevel(topLevelTaskSupport)) {
+        resolvedTaskSupport = topLevelTaskSupport;
+    }
+    else if (isTaskSupportLevel(executionTaskSupport)) {
+        resolvedTaskSupport = executionTaskSupport;
+    }
     if (resolvedTaskSupport === undefined && topLevelTaskSupport === undefined) {
         return tool;
     }
@@ -106,6 +123,7 @@ export function maybeExternalizeTextContent(resourceStore, content, params) {
         chars: content.length,
         uri: entry.uri,
     });
+    Logger.debug(`Content externalized: ${params.name} (${content.length} chars) → ${entry.uri}`);
     return {
         entry,
         preview: buildTextPreview(content),
@@ -128,9 +146,12 @@ export function buildResourceLink(params) {
 }
 function resolveDetailedError(error, defaultCode, path) {
     const detailed = createDetailedError(error, path);
-    if (detailed.code === ErrorCode.E_UNKNOWN) {
+    if (detailed.code === ErrorCode.UNKNOWN) {
         detailed.code = defaultCode;
-        detailed.suggestion = getSuggestion(defaultCode);
+        const suggestion = getSuggestion(defaultCode);
+        if (suggestion) {
+            detailed.suggestion = suggestion;
+        }
     }
     return detailed;
 }
@@ -156,13 +177,13 @@ function validateStructuredContent(toolName, outputSchema, structuredContent) {
     if (parsed.success) {
         return parsed.data;
     }
-    throw new McpError(ErrorCode.E_UNKNOWN, `Tool "${toolName}" returned invalid structuredContent.`, undefined, { errors: z.treeifyError(parsed.error) });
+    throw new McpError(ErrorCode.UNKNOWN, `Tool "${toolName}" returned invalid structuredContent.`, undefined, { errors: z.treeifyError(parsed.error) });
 }
 function validateToolResponse(toolName, result, outputSchema) {
     if (!outputSchema)
         return result;
     if (!Object.hasOwn(result, 'structuredContent')) {
-        throw new McpError(ErrorCode.E_UNKNOWN, `Tool "${toolName}" returned success without structuredContent.`);
+        throw new McpError(ErrorCode.UNKNOWN, `Tool "${toolName}" returned success without structuredContent.`);
     }
     return {
         ...result,
@@ -175,12 +196,20 @@ function parseToolArgs(schema, args) {
     if (parsed.success) {
         return parsed.data;
     }
-    throw new McpError(ErrorCode.E_INVALID_INPUT, `Invalid tool arguments:\n${z.prettifyError(parsed.error)}`, undefined, { errors: z.treeifyError(parsed.error) });
+    throw new McpError(ErrorCode.INVALID_INPUT, `Invalid tool arguments:\n${z.prettifyError(parsed.error)}`);
 }
 export function withValidatedArgs(schema, handler) {
     return async (args, extra) => {
-        const normalizedArgs = parseToolArgs(schema, args);
-        return handler(normalizedArgs, extra);
+        try {
+            const normalizedArgs = parseToolArgs(schema, args);
+            return await handler(normalizedArgs, extra);
+        }
+        catch (error) {
+            if (error instanceof McpError && error.code === ErrorCode.INVALID_INPUT) {
+                return buildToolErrorResponse(error, ErrorCode.INVALID_INPUT);
+            }
+            throw error;
+        }
     };
 }
 function canSendProgress(extra) {
@@ -232,7 +261,7 @@ export function buildFileInfoPayload(info) {
             : {}),
     };
 }
-const NOT_INITIALIZED_ERROR = new McpError(ErrorCode.E_INVALID_INPUT, 'Client not initialized; wait for notifications/initialized');
+const NOT_INITIALIZED_ERROR = new McpError(ErrorCode.INVALID_INPUT, 'Client not initialized; wait for notifications/initialized');
 async function withToolErrorHandling(run, onError) {
     try {
         return await run();
@@ -249,6 +278,7 @@ function getToolSignal(extraSignal, timedSignal) {
     return { signal, cleanup };
 }
 export async function executeToolWithDiagnostics(options) {
+    const traceContext = extractTraceContext(options.extra._meta);
     return withToolDiagnostics(options.toolName, () => withToolErrorHandling(async () => {
         const { signal, cleanup } = getToolSignal(options.extra.signal, options.timedSignal);
         try {
@@ -257,7 +287,10 @@ export async function executeToolWithDiagnostics(options) {
         finally {
             cleanup();
         }
-    }, options.onError), options.context);
+    }, options.onError), {
+        ...options.context,
+        ...(traceContext ? { traceContext } : {}),
+    });
 }
 export function buildToolErrorResponse(error, defaultCode, path) {
     const detailed = resolveDetailedError(error, defaultCode, path);
@@ -269,7 +302,7 @@ export function buildToolErrorResponse(error, defaultCode, path) {
     };
 }
 function buildNotInitializedResult() {
-    return buildToolErrorResponse(NOT_INITIALIZED_ERROR, ErrorCode.E_INVALID_INPUT);
+    return buildToolErrorResponse(NOT_INITIALIZED_ERROR, ErrorCode.INVALID_INPUT);
 }
 async function reportProgress(extra, progress) {
     await updateTaskStoreProgress(extra, progress);
@@ -283,6 +316,10 @@ function formatTaskStatusMessage(progress) {
     }
     return progress.message ?? `${progress.current}`;
 }
+function isBenignTaskStatusUpdateError(error) {
+    return (error instanceof Error &&
+        /Task .*not found|terminal status/iu.test(error.message));
+}
 async function updateTaskStoreProgress(extra, progress) {
     const taskExtra = extra;
     if (typeof taskExtra.taskId === 'string' &&
@@ -294,7 +331,9 @@ async function updateTaskStoreProgress(extra, progress) {
                 await store.updateTaskStatus(taskExtra.taskId, 'working', formatTaskStatusMessage(progress));
             }
             catch (error) {
-                console.error('Failed to update task status message:', error);
+                if (isBenignTaskStatusUpdateError(error))
+                    return;
+                Logger.error('Failed to update task status message:', error);
             }
         }
     }
@@ -315,7 +354,7 @@ async function sendMcpProgressNotification(extra, progress) {
             });
         }
         catch (error) {
-            console.error('Failed to send progress notification:', error);
+            Logger.error('Failed to send progress notification:', error);
         }
     }
 }
@@ -480,14 +519,14 @@ export function resolvePathOrRoot(pathValue) {
         return pathValue;
     const roots = getAllowedDirectories();
     if (roots.length === 0) {
-        throw new McpError(ErrorCode.E_ACCESS_DENIED, 'No workspace roots configured. Use the roots tool to check, or configure roots via the MCP Roots protocol (or start with --allow-cwd / CLI directories).');
+        throw new McpError(ErrorCode.ACCESS_DENIED, 'No roots configured. Use roots tool, --allow-cwd, or MCP Roots protocol.');
     }
     if (roots.length > 1) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Multiple workspace roots configured. Provide an explicit path to disambiguate.');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Multiple roots configured. Provide an explicit path.');
     }
     const root = roots[0];
     if (!root) {
-        throw new McpError(ErrorCode.E_ACCESS_DENIED, 'Workspace root is unexpectedly undefined');
+        throw new McpError(ErrorCode.ACCESS_DENIED, 'Workspace root is unexpectedly undefined');
     }
     return root;
 }
@@ -505,14 +544,17 @@ export function decodeOffsetCursor(cursor) {
     catch {
         // fall through to throw
     }
-    throw new McpError(ErrorCode.E_INVALID_INPUT, `Invalid cursor: the cursor value is malformed or corrupted. Request the first page without a cursor.`);
+    throw new McpError(ErrorCode.INVALID_INPUT, `Invalid cursor. Request the first page without a cursor.`);
 }
 export function buildBatchPathContext(paths, unitLabel = 'paths') {
     const normalizedLabel = paths.length === 1 ? unitLabel.replace(/s$/i, '') : unitLabel;
-    const first = path.basename(paths[0] ?? '');
-    const extraPaths = paths.length > 1
-        ? `, ${path.basename(paths[1] ?? '')}${paths.length > 2 ? '…' : ''}`
-        : '';
+    const first = basename(paths[0] ?? '');
+    let extraPaths = '';
+    if (paths.length > 1) {
+        const secondPath = basename(paths[1] ?? '');
+        const ellipsis = paths.length > 2 ? '…' : '';
+        extraPaths = `, ${secondPath}${ellipsis}`;
+    }
     return `${paths.length} ${normalizedLabel} [${first}${extraPaths}]`;
 }
 export function truncateProgressPattern(pattern, maxLength = 40) {

package/dist/tools/stat-many.js

@@ -38,15 +38,19 @@ async function handleGetMultipleFileInfo(args, signal, onProgress) {
         path: entry.path,
         info: entry.info ? buildFileInfoPayload(entry.info) : undefined,
         error: entry.error
-            ? buildStructuredError(entry.error, ErrorCode.E_NOT_FOUND, entry.path)
+            ? buildStructuredError(entry.error, ErrorCode.NOT_FOUND, entry.path)
             : undefined,
     }));
     const text = result.results
-        .map((entry) => entry.error
-        ? `${entry.path}: ${buildStructuredError(entry.error, ErrorCode.E_NOT_FOUND, entry.path).message}`
-        : entry.info
-            ? formatFileInfoDetail(entry.info)
-            : entry.path)
+        .map((entry) => {
+        if (entry.error) {
+            return `${entry.path}: ${buildStructuredError(entry.error, ErrorCode.NOT_FOUND, entry.path).message}`;
+        }
+        if (entry.info) {
+            return formatFileInfoDetail(entry.info);
+        }
+        return entry.path;
+    })
         .join('\n\n');
     const structured = {
         ok: true,
@@ -90,7 +94,7 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
                     throw error;
                 }
             },
-            onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, primaryPath),
+            onError: (error) => buildToolErrorResponse(error, ErrorCode.NOT_FOUND, primaryPath),
         });
     };
     const wrappedHandler = wrapToolHandler(handler, {

package/dist/tools/stat.js

@@ -1,4 +1,4 @@
-import * as path from 'node:path';
+import { basename } from 'node:path';
 import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { getFileInfo } from '../lib/file-operations/metadata.js';
@@ -48,13 +48,13 @@ export function registerGetFileInfoTool(server, options = {}) {
         timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
         context: { path: args.path },
         run: (signal) => handleGetFileInfo(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, args.path),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.NOT_FOUND, args.path),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => `🕮 stat: ${path.basename(args.path)}`,
+        progressMessage: (args) => `🕮 stat: ${basename(args.path)}`,
         completionMessage: (args, result) => {
-            const name = path.basename(args.path);
+            const name = basename(args.path);
             if (result.isError)
                 return `🕮 stat: ${name} • failed`;
             const sc = result.structuredContent;

package/dist/tools/task-support.d.ts

@@ -2,20 +2,21 @@ import type { ToolTaskHandler } from '@modelcontextprotocol/sdk/experimental/tas
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { AnySchema, SchemaOutput, ShapeOutput, ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 import type { RequestTaskStore } from '@modelcontextprotocol/sdk/shared/protocol.js';
-import type { IconInfo, ToolExtra, ToolResult } from './shared.js';
+import { type IconInfo, type ToolExtra, type ToolResult } from './shared.js';
 type TaskToolExtra = ToolExtra & {
     taskId?: string;
     taskStore?: RequestTaskStore;
     taskRequestedTtl?: number | null;
 };
-type ToolArgs<Args extends ZodRawShapeCompat | AnySchema | undefined> = Args extends ZodRawShapeCompat ? ShapeOutput<Args> : Args extends AnySchema ? SchemaOutput<Args> : undefined;
-export declare function registerToolTaskIfAvailable<Args extends ZodRawShapeCompat | AnySchema | undefined, Result>(server: McpServer, toolName: string, toolDef: object, run: (args: ToolArgs<Args>, extra: TaskToolExtra) => Promise<ToolResult<Result>>, iconInfo: IconInfo | undefined, guard?: () => boolean): boolean;
-export declare function createToolTaskHandler<Result>(run: (args: undefined, extra: TaskToolExtra) => Promise<ToolResult<Result>>, options?: {
+export type ToolSchema = ZodRawShapeCompat | AnySchema | undefined;
+type ToolArgs<Args extends ToolSchema> = Args extends ZodRawShapeCompat ? ShapeOutput<Args> : Args extends AnySchema ? SchemaOutput<Args> : undefined;
+export declare function registerToolTaskIfAvailable<Args extends ToolSchema, Result>(server: McpServer, toolName: string, toolDef: object, run: (args: ToolArgs<Args>, extra: TaskToolExtra) => Promise<ToolResult<Result>>, iconInfo: IconInfo | undefined, guard?: () => boolean): boolean;
+interface TaskHandlerOptions {
     guard?: () => boolean;
     toolName?: string;
-}): ToolTaskHandler;
-export declare function createToolTaskHandler<Args extends ZodRawShapeCompat | AnySchema, Result>(run: (args: ToolArgs<Args>, extra: TaskToolExtra) => Promise<ToolResult<Result>>, options?: {
-    guard?: () => boolean;
-    toolName?: string;
-}): ToolTaskHandler<Args>;
+    cancelPollMs?: number;
+    pollIntervalMs?: number;
+}
+export declare function createToolTaskHandler<Result>(run: (args: undefined, extra: TaskToolExtra) => Promise<ToolResult<Result>>, options?: TaskHandlerOptions): ToolTaskHandler;
+export declare function createToolTaskHandler<Args extends ZodRawShapeCompat | AnySchema, Result>(run: (args: ToolArgs<Args>, extra: TaskToolExtra) => Promise<ToolResult<Result>>, options?: TaskHandlerOptions): ToolTaskHandler<Args>;
 export {};

package/dist/tools/task-support.js

@@ -1,10 +1,11 @@
+import { CallToolResultSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { channel } from 'node:diagnostics_channel';
 import { performance } from 'node:perf_hooks';
 import { format } from 'node:util';
-import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
-import { DEFAULT_TASK_TTL_MS, MAX_CONCURRENT_TASKS, MAX_TASK_TTL_MS, } from '../lib/constants.js';
+import { DEFAULT_TASK_TTL_MS, MAX_CONCURRENT_TASKS, MAX_TASK_TTL_MS, TASK_CANCEL_POLL_MS, TASK_POLL_INTERVAL_MS, } from '../lib/constants.js';
 import { ErrorCode, McpError } from '../lib/errors.js';
+import { Logger } from '../lib/logger.js';
 import { isRecord } from '../lib/utils.js';
 import { buildToolErrorResponse, maybeStripStructuredContentFromResult, withDefaultIcons, } from './shared.js';
 const taskContext = new AsyncLocalStorage();
@@ -50,6 +51,7 @@ function hasTaskToolCapability(server) {
         isRecord(tasks.requests.tools.call));
 }
 const TASK_STATUS_NOTIFICATION_METHOD = 'notifications/tasks/status';
+const TASK_CREATED_NOTIFICATION_METHOD = 'notifications/tasks/created';
 function isRequestTaskStore(value) {
     return (isRecord(value) &&
         typeof value.createTask === 'function' &&
@@ -67,13 +69,13 @@ function isTaskExtra(value) {
 }
 function asCreateTaskExtra(value) {
     if (!isCreateTaskExtra(value)) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Task store not configured for task-capable tool.');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Task store not configured.');
     }
     return value;
 }
 function asTaskRequestExtra(value) {
     if (!isTaskExtra(value)) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Task id or task store missing for task operation.');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Task id or store missing.');
     }
     return value;
 }
@@ -90,11 +92,11 @@ function isTaskStatus(value) {
 }
 function normalizeGetTaskResult(value) {
     if (!isRecord(value) || typeof value.taskId !== 'string') {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Invalid task object.');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Invalid task object.');
     }
     const status = isTaskStatus(value.status) ? value.status : undefined;
     if (!status) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Invalid task status.');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Invalid task status.');
     }
     const createdAt = typeof value.createdAt === 'string'
         ? value.createdAt
@@ -123,7 +125,7 @@ function normalizeCallToolResult(value) {
     const parsed = CallToolResultSchema.safeParse(value);
     if (parsed.success)
         return parsed.data;
-    throw new McpError(ErrorCode.E_INVALID_INPUT, 'Stored task result is not a valid tool result.');
+    throw new McpError(ErrorCode.INVALID_INPUT, 'Invalid stored task result.');
 }
 function getToolResultErrorCode(result) {
     if (!isRecord(result) || result.isError !== true)
@@ -143,7 +145,7 @@ function getToolResultErrorCode(result) {
     return match ? match[1] : undefined;
 }
 function isCancelledToolResult(result) {
-    return getToolResultErrorCode(result) === ErrorCode.E_CANCELLED;
+    return getToolResultErrorCode(result) === ErrorCode.CANCELLED;
 }
 function resolveTaskResultStatuses(result) {
     if (isCancelledToolResult(result)) {
@@ -192,6 +194,31 @@ function buildTaskStatusNotificationParams(task) {
         params.statusMessage = task.statusMessage;
     return params;
 }
+async function notifyTaskCreatedIfPossible(extra, taskId, toolName) {
+    const { sendNotification } = extra;
+    if (typeof sendNotification !== 'function')
+        return;
+    const notify = sendNotification;
+    try {
+        await notify({
+            method: TASK_CREATED_NOTIFICATION_METHOD,
+            params: {
+                _meta: {
+                    'modelcontextprotocol.io/related-task': {
+                        taskId,
+                    },
+                },
+            },
+        });
+    }
+    catch {
+        publishTaskDiagnostics({
+            phase: 'task_status_notify_failed',
+            taskId,
+            ...(toolName ? { toolName } : {}),
+        });
+    }
+}
 async function notifyTaskStatusIfPossible(extra, taskStore, taskId, toolName) {
     const { sendNotification } = extra;
     if (typeof sendNotification !== 'function')
@@ -222,13 +249,13 @@ async function notifyTaskStatusIfPossible(extra, taskStore, taskId, toolName) {
 }
 function getTaskStore(extra) {
     if (!extra.taskStore) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Task store not configured for task-capable tool.');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Task store not configured.');
     }
     return extra.taskStore;
 }
 function getTaskId(extra) {
     if (!extra.taskId) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Task id missing for task operation.');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Task id missing.');
     }
     return extra.taskId;
 }
@@ -260,6 +287,10 @@ async function isTaskAlreadyTerminal(taskStore, taskId) {
         return false;
     }
 }
+function isMissingTaskStoreError(error) {
+    return (error instanceof Error &&
+        /Task .*not found|not found after cancellation/iu.test(error.message));
+}
 async function countActiveTasks(taskStore) {
     if (typeof taskStore.listTasks !== 'function')
         return 0;
@@ -281,11 +312,11 @@ function resolveRequestedTaskTtl(requestedTtl) {
     if (requestedTtl == null)
         return DEFAULT_TASK_TTL_MS;
     if (!Number.isFinite(requestedTtl)) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Task ttl must be a finite number of milliseconds.');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Task TTL must be finite.');
     }
     const normalized = Math.trunc(requestedTtl);
     if (normalized <= 0) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Task ttl must be greater than zero.');
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Task TTL must be > 0.');
     }
     return Math.min(normalized, MAX_TASK_TTL_MS);
 }
@@ -294,18 +325,40 @@ async function safelyStoreTaskResult(taskStore, taskId, storedStatus, result) {
         await taskStore.storeTaskResult(taskId, storedStatus, result);
     }
     catch (error) {
+        if (isMissingTaskStoreError(error))
+            return;
         // If task was already cancelled/failed by another process, ignore the write error
         if (await isTaskAlreadyTerminal(taskStore, taskId))
             return;
         throw error;
     }
 }
-async function runTaskInBackground(run, args, extra, taskStore, taskId, toolName) {
+async function isTaskCancelled(taskStore, taskId) {
+    try {
+        const task = await taskStore.getTask(taskId);
+        return isRecord(task) && task.status === 'cancelled';
+    }
+    catch {
+        return false;
+    }
+}
+async function runTaskInBackground(run, args, extra, taskStore, taskId, toolName, cancelPollMs) {
+    // Create a dedicated AbortController for background execution.
+    // The original request signal is stale once createTask returns.
+    const taskAbort = new AbortController();
+    const taskExtra = { ...extra, signal: taskAbort.signal };
+    // Poll the task store for client-initiated cancellation.
+    const cancelPoller = setInterval(() => {
+        void isTaskCancelled(taskStore, taskId).then((cancelled) => {
+            if (cancelled)
+                taskAbort.abort(new Error('Task cancelled by client'));
+        });
+    }, cancelPollMs ?? TASK_CANCEL_POLL_MS);
     const start = performance.now();
     let taskStatuses;
     let result;
     try {
-        const rawResult = await taskContext.run({ taskId, toolName, startTime: start }, () => run(args, extra));
+        const rawResult = await taskContext.run({ taskId, toolName, startTime: start }, () => run(args, taskExtra));
         taskStatuses = resolveTaskResultStatuses(rawResult);
         result = isErrorResult(rawResult)
             ? withoutStructuredContent(rawResult)
@@ -313,7 +366,10 @@ async function runTaskInBackground(run, args, extra, taskStore, taskId, toolName
     }
     catch (error) {
         taskStatuses = { storedStatus: 'failed', reportedStatus: 'failed' };
-        result = maybeStripStructuredContentFromResult(buildToolErrorResponse(error, ErrorCode.E_UNKNOWN));
+        result = maybeStripStructuredContentFromResult(buildToolErrorResponse(error, ErrorCode.UNKNOWN));
+    }
+    finally {
+        clearInterval(cancelPoller);
     }
     const durationMs = performance.now() - start;
     try {
@@ -328,7 +384,7 @@ async function runTaskInBackground(run, args, extra, taskStore, taskId, toolName
         await notifyTaskStatusIfPossible(extra, taskStore, taskId, toolName);
     }
     catch (innerError) {
-        console.error(format('Failed to store task result for task %s:', taskId), innerError);
+        Logger.error(format('Failed to store task result for task %s:', taskId), innerError);
         const syntheticTask = {
             taskId,
             status: taskStatuses.reportedStatus === 'cancelled' ? 'cancelled' : 'failed',
@@ -339,10 +395,16 @@ async function runTaskInBackground(run, args, extra, taskStore, taskId, toolName
         };
         const { sendNotification } = extra;
         if (typeof sendNotification === 'function') {
-            void sendNotification({
-                method: TASK_STATUS_NOTIFICATION_METHOD,
-                params: buildTaskStatusNotificationParams(syntheticTask),
-            });
+            try {
+                await sendNotification({
+                    method: TASK_STATUS_NOTIFICATION_METHOD,
+                    params: buildTaskStatusNotificationParams(syntheticTask),
+                });
+            }
+            catch {
+                // Best effort only: transport may already be closed while a cancelled
+                // task is still unwinding in the background.
+            }
         }
     }
 }
@@ -379,15 +441,23 @@ export function createToolTaskHandler(run, options) {
         const extra = asCreateTaskExtra(maybeExtra ?? argsOrExtra);
         const args = (maybeExtra ? argsOrExtra : undefined);
         if (options?.guard && !options.guard()) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, 'Client not initialized; wait for notifications/initialized');
+            throw new McpError(ErrorCode.INVALID_INPUT, 'Client not initialized; wait for notifications/initialized');
         }
         const taskStore = getTaskStore(extra);
         if ((await countActiveTasks(taskStore)) >= MAX_CONCURRENT_TASKS) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, `Too many active tasks. Limit: ${String(MAX_CONCURRENT_TASKS)}.`);
+            throw new McpError(ErrorCode.INVALID_INPUT, `Too many active tasks (limit: ${String(MAX_CONCURRENT_TASKS)}).`);
         }
         const task = await taskStore.createTask({
             ttl: resolveRequestedTaskTtl(extra.taskRequestedTtl),
+            pollInterval: options?.pollIntervalMs ?? TASK_POLL_INTERVAL_MS,
         });
+        const toolLabel = options?.toolName ?? 'tool';
+        try {
+            await taskStore.updateTaskStatus(task.taskId, 'working', `${toolLabel}: starting`);
+        }
+        catch {
+            // Best effort — status message is informational.
+        }
         publishTaskDiagnostics({
             phase: 'task_created',
             taskId: task.taskId,
@@ -399,8 +469,9 @@ export function createToolTaskHandler(run, options) {
             taskStore,
             taskId: task.taskId,
         };
+        void notifyTaskCreatedIfPossible(taskExtra, task.taskId, options?.toolName);
         void notifyTaskStatusIfPossible(taskExtra, taskStore, task.taskId, options?.toolName);
-        void runTaskInBackground(run, args, taskExtra, taskStore, task.taskId, options?.toolName);
+        void runTaskInBackground(run, args, taskExtra, taskStore, task.taskId, options?.toolName, options?.cancelPollMs);
         return { task };
     });
     const getTask = (async (argsOrExtra, maybeExtra) => {

package/dist/tools/tree.js

@@ -1,4 +1,4 @@
-import * as path from 'node:path';
+import { basename } from 'node:path';
 import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { formatTreeAscii, treeDirectory, } from '../lib/file-operations/metadata.js';
@@ -48,7 +48,7 @@ export function registerTreeTool(server, options = {}) {
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: targetPath },
             run: async (signal) => {
-                const context = args.path ? path.basename(args.path) : '.';
+                const context = args.path ? basename(args.path) : '.';
                 let progressCursor = 0;
                 const knownTotal = args.maxEntries;
                 notifyProgress(extra, {
@@ -93,7 +93,7 @@ export function registerTreeTool(server, options = {}) {
                     throw error;
                 }
             },
-            onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_DIRECTORY, targetPath),
+            onError: (error) => buildToolErrorResponse(error, ErrorCode.NOT_DIRECTORY, targetPath),
         });
     };
     const wrappedHandler = wrapToolHandler(handler, {

package/dist/tools/write-file.js

@@ -1,7 +1,9 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { basename, dirname } from 'node:path';
+import { withAbort } from '../lib/abort.js';
 import { ErrorCode } from '../lib/errors.js';
-import { atomicWriteFile, withAbort } from '../lib/fs-helpers.js';
+import { atomicWriteFile } from '../lib/fs-helpers.js';
+import { Logger } from '../lib/logger.js';
 import { validatePathForWrite } from '../lib/paths.js';
 import { formatBytes } from '../config.js';
 import { WriteFileInputSchema, WriteFileOutputSchema } from '../schemas.js';
@@ -19,9 +21,10 @@ export const WRITE_FILE_TOOL = {
 async function handleWriteFile(args, signal) {
     const validPath = await validatePathForWrite(args.path, signal);
     // Ensure parent directory exists
-    await withAbort(fs.mkdir(path.dirname(validPath), { recursive: true }), signal);
+    await withAbort(mkdir(dirname(validPath), { recursive: true }), signal);
     await atomicWriteFile(validPath, args.content, { encoding: 'utf-8', signal });
     const bytesWritten = Buffer.byteLength(args.content, 'utf-8');
+    Logger.info(`write: ${args.path} (${bytesWritten} bytes)`);
     return buildToolResponse(`Successfully wrote to file: ${args.path}`, {
         ok: true,
         path: validPath,
@@ -36,13 +39,13 @@ export function registerWriteFileTool(server, options = {}) {
         timedSignal: {},
         context: { path: args.path },
         run: (signal) => handleWriteFile(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.UNKNOWN, args.path),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => `🛠 write: ${path.basename(args.path)}`,
+        progressMessage: (args) => `🛠 write: ${basename(args.path)}`,
         completionMessage: (args, result) => {
-            const name = path.basename(args.path);
+            const name = basename(args.path);
             if (result.isError)
                 return `🛠 write: ${name} • failed`;
             const sc = result.structuredContent;