@j0hanz/fetch-url-mcp 1.11.2 → 1.11.4

package/dist/lib/{mcp-tools.d.ts → mcp-interop.d.ts}

@@ -1,3 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 export type JsonRpcId = string | number | null;
@@ -60,5 +61,52 @@ export declare function createToolErrorResponse(message: string, url: string, ex
     details?: Record<string, unknown>;
 }): ToolErrorResponse;
 export declare function handleToolError(error: unknown, url: string, fallbackMessage?: string): ToolErrorResponse;
+type CleanupCallback = () => void;
+type RequestHandlerFn = (request: unknown, extra?: unknown) => Promise<unknown>;
+export declare function registerServerLifecycleCleanup(server: McpServer, callback: CleanupCallback): void;
+/**
+ * Retrieves the SDK's internal request-handler map.
+ *
+ * Depends on SDK private API `_requestHandlers` (verified against ^1.27.1).
+ * If the SDK changes this internal, the sdk-compat-guard.test.ts tests will fail.
+ */
+export declare function getSdkCallToolHandler(server: McpServer): RequestHandlerFn | null;
+/**
+ * Patches the SDK's internal capabilities to enable/disable task-mode tool calls.
+ *
+ * Depends on SDK private API `_capabilities.tasks.requests` (verified against ^1.27.1).
+ * If the SDK changes this internal, the sdk-compat-guard.test.ts tests will fail.
+ */
+export declare function setTaskToolCallCapability(server: McpServer, enabled: boolean): void;
+type ProgressToken = string | number;
+interface RequestMeta {
+    progressToken?: ProgressToken | undefined;
+    [key: string]: unknown;
+}
+export interface ProgressNotificationParams {
+    progressToken: ProgressToken;
+    progress: number;
+    total?: number;
+    message?: string;
+    _meta?: Record<string, unknown>;
+}
+export interface ProgressNotification {
+    method: 'notifications/progress';
+    params: ProgressNotificationParams;
+}
+export interface ToolHandlerExtra {
+    signal?: AbortSignal;
+    requestId?: string | number;
+    sessionId?: unknown;
+    requestInfo?: unknown;
+    _meta?: RequestMeta;
+    sendNotification?: (notification: ProgressNotification) => Promise<void>;
+    onProgress?: (progress: number, message: string) => void;
+    canReportProgress?: () => boolean;
+}
+export interface ProgressReporter {
+    report: (progress: number, message: string) => void;
+}
+export declare const createProgressReporter: (extra?: ToolHandlerExtra) => ProgressReporter;
 export {};
-//# sourceMappingURL=mcp-tools.d.ts.map
+//# sourceMappingURL=mcp-interop.d.ts.map

package/dist/lib/mcp-interop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-interop.d.ts","sourceRoot":"","sources":["../../src/lib/mcp-interop.ts"],"names":[],"mappings":"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"}

package/dist/lib/mcp-interop.js

@@ -0,0 +1,354 @@
+import { setTimeout as setTimeoutPromise } from 'node:timers/promises';
+import {} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { logError, logWarn } from './core.js';
+import { FetchError, getErrorMessage, isAbortError, isObject, isSystemError, } from './utils.js';
+const paramsSchema = z.looseObject({
+    _meta: z.record(z.string(), z.unknown()).optional(),
+});
+const jsonRpcRequestIdSchema = z.union([z.string(), z.number()]);
+const jsonRpcRequestSchema = z.strictObject({
+    jsonrpc: z.literal('2.0'),
+    method: z.string().min(1),
+    id: jsonRpcRequestIdSchema.optional(),
+    params: paramsSchema.optional(),
+});
+const jsonRpcResultResponseSchema = z.strictObject({
+    jsonrpc: z.literal('2.0'),
+    id: jsonRpcRequestIdSchema,
+    result: z.record(z.string(), z.unknown()),
+});
+const jsonRpcErrorResponseSchema = z.strictObject({
+    jsonrpc: z.literal('2.0'),
+    id: jsonRpcRequestIdSchema.or(z.null()).optional(),
+    error: z.strictObject({
+        code: z.number().int(),
+        message: z.string(),
+        data: z.unknown().optional(),
+    }),
+});
+const jsonRpcResponseSchema = z.union([
+    jsonRpcResultResponseSchema,
+    jsonRpcErrorResponseSchema,
+]);
+const jsonRpcMessageSchema = z.union([
+    jsonRpcRequestSchema,
+    jsonRpcResponseSchema,
+]);
+export function isJsonRpcBatchRequest(body) {
+    return Array.isArray(body);
+}
+export function isMcpRequestBody(body) {
+    return jsonRpcRequestSchema.safeParse(body).success;
+}
+export function isJsonRpcResponseBody(body) {
+    return jsonRpcResponseSchema.safeParse(body).success;
+}
+export function isMcpMessageBody(body) {
+    return jsonRpcMessageSchema.safeParse(body).success;
+}
+function parseAcceptMediaTypes(header) {
+    if (!header)
+        return [];
+    return header
+        .split(',')
+        .map((v) => v.split(';', 1)[0]?.trim().toLowerCase() ?? '')
+        .filter((v) => v.length > 0);
+}
+export function acceptsEventStream(header) {
+    const mediaTypes = parseAcceptMediaTypes(header);
+    return mediaTypes.some((mediaType) => mediaType === 'text/event-stream');
+}
+export function acceptsJsonAndEventStream(header) {
+    const mediaTypes = parseAcceptMediaTypes(header);
+    const acceptsJson = mediaTypes.some((m) => m === '*/*' || m === 'application/json' || m === 'application/*');
+    if (!acceptsJson)
+        return false;
+    return mediaTypes.some((m) => m === '*/*' || m === 'text/event-stream' || m === 'text/*');
+}
+const PUBLIC_ERROR_REASONS = new Set(['aborted', 'queue_full', 'timeout']);
+function sanitizeToolErrorDetails(details) {
+    const sanitized = {};
+    const { retryAfter, timeout, reason } = details;
+    if (typeof retryAfter === 'number' ||
+        typeof retryAfter === 'string' ||
+        retryAfter === null) {
+        sanitized['retryAfter'] = retryAfter;
+    }
+    if (typeof timeout === 'number' && Number.isFinite(timeout) && timeout >= 0) {
+        sanitized['timeout'] = timeout;
+    }
+    if (typeof reason === 'string' && PUBLIC_ERROR_REASONS.has(reason)) {
+        sanitized['reason'] = reason;
+    }
+    return Object.keys(sanitized).length > 0 ? sanitized : undefined;
+}
+export function createToolErrorResponse(message, url, extra) {
+    const errorContent = {
+        error: message,
+        ...(extra?.code ? { code: extra.code } : {}),
+        url,
+        ...(extra?.statusCode !== undefined
+            ? { statusCode: extra.statusCode }
+            : {}),
+        ...(extra?.details ? { details: extra.details } : {}),
+    };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(errorContent) }],
+        isError: true,
+    };
+}
+function isValidationError(error) {
+    return (error instanceof Error &&
+        isSystemError(error) &&
+        error.code === 'VALIDATION_ERROR');
+}
+export function handleToolError(error, url, fallbackMessage = 'Operation failed') {
+    if (error instanceof FetchError) {
+        const { code: detailsCode, reason } = error.details;
+        const code = (typeof detailsCode === 'string'
+            ? detailsCode
+            : reason === 'queue_full'
+                ? 'queue_full'
+                : undefined) ?? error.code;
+        const details = sanitizeToolErrorDetails(error.details);
+        return createToolErrorResponse(error.message, url, {
+            code,
+            statusCode: error.statusCode,
+            ...(details ? { details } : {}),
+        });
+    }
+    if (isValidationError(error)) {
+        return createToolErrorResponse(error.message, url, {
+            code: 'VALIDATION_ERROR',
+        });
+    }
+    const code = isAbortError(error) ? 'ABORTED' : 'FETCH_ERROR';
+    const message = error instanceof Error
+        ? `${fallbackMessage}: ${error.message}`
+        : `${fallbackMessage}: Unknown error`;
+    return createToolErrorResponse(message, url, { code });
+}
+const patchedCleanupServers = new WeakSet();
+const serverCleanupCallbacks = new WeakMap();
+function getServerCleanupCallbackSet(server) {
+    let callbacks = serverCleanupCallbacks.get(server);
+    if (!callbacks) {
+        callbacks = new Set();
+        serverCleanupCallbacks.set(server, callbacks);
+    }
+    return callbacks;
+}
+function drainServerCleanupCallbacks(server) {
+    const callbacks = serverCleanupCallbacks.get(server);
+    if (!callbacks || callbacks.size === 0)
+        return;
+    const pending = [...callbacks];
+    callbacks.clear();
+    for (const callback of pending) {
+        try {
+            callback();
+        }
+        catch (error) {
+            logWarn('Server cleanup callback failed', { error });
+        }
+    }
+}
+function ensureServerCleanupHooks(server) {
+    if (patchedCleanupServers.has(server))
+        return;
+    patchedCleanupServers.add(server);
+    const originalOnClose = server.server.onclose;
+    server.server.onclose = () => {
+        drainServerCleanupCallbacks(server);
+        originalOnClose?.();
+    };
+    const originalClose = server.close.bind(server);
+    server.close = async () => {
+        drainServerCleanupCallbacks(server);
+        await originalClose();
+    };
+}
+export function registerServerLifecycleCleanup(server, callback) {
+    ensureServerCleanupHooks(server);
+    getServerCleanupCallbackSet(server).add(callback);
+}
+/**
+ * Retrieves the SDK's internal request-handler map.
+ *
+ * Depends on SDK private API `_requestHandlers` (verified against ^1.27.1).
+ * If the SDK changes this internal, the sdk-compat-guard.test.ts tests will fail.
+ */
+export function getSdkCallToolHandler(server) {
+    const maybeHandlers = Reflect.get(server.server, '_requestHandlers');
+    if (!(maybeHandlers instanceof Map))
+        return null;
+    const handler = maybeHandlers.get('tools/call');
+    return typeof handler === 'function' ? handler : null;
+}
+/**
+ * Patches the SDK's internal capabilities to enable/disable task-mode tool calls.
+ *
+ * Depends on SDK private API `_capabilities.tasks.requests` (verified against ^1.27.1).
+ * If the SDK changes this internal, the sdk-compat-guard.test.ts tests will fail.
+ */
+export function setTaskToolCallCapability(server, enabled) {
+    const capabilities = Reflect.get(server.server, '_capabilities');
+    if (!isObject(capabilities))
+        return;
+    const tasks = isObject(capabilities.tasks)
+        ? capabilities.tasks
+        : undefined;
+    if (!tasks)
+        return;
+    const requests = isObject(tasks.requests)
+        ? tasks.requests
+        : undefined;
+    if (!requests)
+        return;
+    if (enabled) {
+        requests.tools = { call: {} };
+        return;
+    }
+    delete requests.tools;
+}
+const DEFAULT_PROGRESS_TOTAL = 8;
+const PROGRESS_NOTIFICATION_TIMEOUT_MS = 5000;
+function resolveRelatedTaskMeta(meta) {
+    const related = meta?.['io.modelcontextprotocol/related-task'];
+    if (!isObject(related))
+        return undefined;
+    const { taskId } = related;
+    return typeof taskId === 'string' ? { taskId } : undefined;
+}
+class ToolProgressReporter {
+    token;
+    handlers;
+    taskMeta;
+    isTerminal = false;
+    lastProgress = -1;
+    lastMessage;
+    pendingNotification;
+    isDispatching = false;
+    constructor(token, handlers, taskMeta) {
+        this.token = token;
+        this.handlers = handlers;
+        this.taskMeta = taskMeta;
+    }
+    static create(extra = {}) {
+        const token = extra._meta?.progressToken ?? null;
+        const { onProgress } = extra;
+        if (token === null && !onProgress) {
+            return { report: () => { } };
+        }
+        return new ToolProgressReporter(token, {
+            send: extra.sendNotification,
+            onProgress,
+            canReport: extra.canReportProgress,
+        }, resolveRelatedTaskMeta(extra._meta));
+    }
+    /**
+     * Report progress toward completion. Steps are monotonic (never decrease)
+     * and may be skipped under normal conditions (e.g., fast responses skip
+     * intermediate steps). Clients should treat progress as "at least this far"
+     * rather than expecting every step to fire sequentially.
+     */
+    report(progress, message) {
+        if (this.isTerminal || this.handlers.canReport?.() === false)
+            return;
+        const effectiveProgress = Math.max(progress, this.lastProgress);
+        const isIncreasing = effectiveProgress > this.lastProgress;
+        const isMessageChanged = message !== this.lastMessage;
+        this.lastProgress = effectiveProgress;
+        this.lastMessage = message;
+        if (effectiveProgress >= DEFAULT_PROGRESS_TOTAL) {
+            this.isTerminal = true;
+        }
+        if (isIncreasing || isMessageChanged) {
+            try {
+                this.handlers.onProgress?.(effectiveProgress, message);
+            }
+            catch (error) {
+                logError('Progress callback failed', {
+                    error: getErrorMessage(error),
+                    progress: effectiveProgress,
+                    message,
+                });
+            }
+        }
+        if (!isIncreasing || this.token === null || !this.handlers.send)
+            return;
+        this.pendingNotification = this.createProgressNotification(this.token, effectiveProgress, message);
+        this.flushNotifications();
+    }
+    flushNotifications() {
+        if (this.isDispatching || !this.handlers.send)
+            return;
+        this.isDispatching = true;
+        void (async () => {
+            try {
+                while (this.pendingNotification) {
+                    if (this.handlers.canReport?.() === false) {
+                        this.pendingNotification = undefined;
+                        return;
+                    }
+                    const notification = this.pendingNotification;
+                    this.pendingNotification = undefined;
+                    await this.sendWithTimeout(notification);
+                }
+            }
+            finally {
+                this.isDispatching = false;
+            }
+        })();
+    }
+    async sendWithTimeout(notification) {
+        if (!this.handlers.send)
+            return;
+        const ac = new AbortController();
+        const timeoutPromise = setTimeoutPromise(PROGRESS_NOTIFICATION_TIMEOUT_MS, { timeout: true }, { signal: ac.signal, ref: false }).catch((err) => {
+            if (err.name === 'AbortError')
+                return { ok: true };
+            throw err;
+        });
+        try {
+            const outcome = await Promise.race([
+                this.handlers.send(notification).then(() => {
+                    ac.abort();
+                    return { ok: true };
+                }),
+                timeoutPromise,
+            ]);
+            if ('timeout' in outcome) {
+                logWarn('Progress notification timed out', {
+                    progress: notification.params.progress,
+                    message: notification.params.message,
+                });
+            }
+        }
+        catch (error) {
+            logWarn('Failed to send progress notification', {
+                error: getErrorMessage(error),
+                progress: notification.params.progress,
+                message: notification.params.message,
+            });
+        }
+    }
+    createProgressNotification(token, progress, message) {
+        return {
+            method: 'notifications/progress',
+            params: {
+                progressToken: token,
+                progress,
+                total: DEFAULT_PROGRESS_TOTAL,
+                message,
+                ...(this.taskMeta && {
+                    _meta: {
+                        'io.modelcontextprotocol/related-task': this.taskMeta,
+                    },
+                }),
+            },
+        };
+    }
+}
+export const createProgressReporter = (extra) => ToolProgressReporter.create(extra);

package/dist/lib/task-handlers.js

@@ -8,7 +8,7 @@ import { taskManager } from '../tasks/manager.js';
 import { isServerResult, parseHandlerExtra, resolveTaskOwnerKey, resolveToolCallContext, } from '../tasks/owner.js';
 import { hasRegisteredTaskCapableTools, hasTaskCapableTool, } from '../tasks/registry.js';
 import { logWarn, runWithRequestContext } from './core.js';
-import { getSdkCallToolHandler } from './sdk-interop.js';
+import { getSdkCallToolHandler } from './mcp-interop.js';
 export { cancelTasksForOwner, abortAllTaskExecutions, } from '../tasks/execution.js';
 /* -------------------------------------------------------------------------------------------------
  * Task handler schemas and registration

package/dist/resources/index.js

@@ -3,7 +3,7 @@ import { ErrorCode, McpError, SubscribeRequestSchema, UnsubscribeRequestSchema,
 import { get as getCacheEntry, getEntryMeta, keys as listCacheKeys, onCacheUpdate, parseCacheKey, } from '../lib/core.js';
 import { logWarn } from '../lib/core.js';
 import { config } from '../lib/core.js';
-import { registerServerLifecycleCleanup } from '../lib/sdk-interop.js';
+import { registerServerLifecycleCleanup } from '../lib/mcp-interop.js';
 import { buildOptionalIcons } from '../lib/utils.js';
 import { isObject } from '../lib/utils.js';
 import { parseCachedPayload, resolveCachedPayloadContent } from '../schemas.js';

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAoD9D,eAAO,MAAM,uBAAuB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAG9D,CAAC;AAgBJ,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,iBAAiB,GAAG,SAAS,CAQ/B;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAErE;AAUD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACzC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjC;AAED,eAAO,MAAM,wBAAwB,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAM1D,CAAC;AAwCL,eAAO,MAAM,mBAAmB;;;kBAgB/B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;kBAqC/B,CAAC;AAEH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAkBpE;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,GAChD,MAAM,CAER;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC7D,MAAM,GAAG,IAAI,CAEf"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAoD9D,eAAO,MAAM,uBAAuB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAG9D,CAAC;AAgBJ,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,iBAAiB,GAAG,SAAS,CAQ/B;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAErE;AAUD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACzC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjC;AAED,eAAO,MAAM,wBAAwB,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAM1D,CAAC;AAwCL,eAAO,MAAM,mBAAmB;;;kBAkB/B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;kBAqC/B,CAAC;AAEH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAkBpE;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,GAChD,MAAM,CAER;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC7D,MAAM,GAAG,IAAI,CAEf"}

package/dist/schemas.js

@@ -99,7 +99,7 @@ export const fetchUrlInputSchema = z.strictObject({
         .httpUrl('Expected HTTP or HTTPS URL')
         .min(1, 'URL required')
         .max(config.constants.maxUrlLength, `URL exceeds ${config.constants.maxUrlLength} chars`)
-        .describe(`Target URL. Max ${config.constants.maxUrlLength} chars.`),
+        .describe(`Target URL. Max ${config.constants.maxUrlLength} chars. Example: https://example.com`),
     forceRefresh: z
         .boolean('Expected boolean')
         .optional()

package/dist/server.js

@@ -5,10 +5,10 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { SetLevelRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { config } from './lib/core.js';
 import { getSessionId, logError, logInfo, setLogLevel, setMcpServer, } from './lib/core.js';
-import { setTaskToolCallCapability } from './lib/sdk-interop.js';
-import { abortAllTaskExecutions, registerTaskHandlers, } from './lib/task-handlers.js';
+import { setTaskToolCallCapability } from './lib/mcp-interop.js';
 import { toError } from './lib/utils.js';
 import { buildServerInstructions, registerCacheResourceTemplate, registerGetHelpPrompt, registerInstructionResource, } from './resources/index.js';
+import { abortAllTaskExecutions, registerTaskHandlers, } from './tasks/handlers.js';
 import { registerTools as registerFetchUrlTool } from './tools/fetch-url.js';
 import { shutdownTransformWorkerPool } from './transform/transform.js';
 /* -------------------------------------------------------------------------------------------------

package/dist/tasks/handlers.d.ts

@@ -0,0 +1,11 @@
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { cancelTasksForOwner, abortAllTaskExecutions } from './execution.js';
+interface TaskHandlerRegistrationOptions {
+    requireInterception?: boolean;
+}
+interface TaskHandlerRegistrationResult {
+    interceptedToolsCall: boolean;
+    taskCapableToolsRegistered: boolean;
+}
+export declare function registerTaskHandlers(server: McpServer, options?: TaskHandlerRegistrationOptions): TaskHandlerRegistrationResult;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/tasks/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/tasks/handlers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmCzE,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AA4D7E,UAAU,8BAA8B;IACtC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,UAAU,6BAA6B;IACrC,oBAAoB,EAAE,OAAO,CAAC;IAC9B,0BAA0B,EAAE,OAAO,CAAC;CACrC;AACD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,OAAO,CAAC,EAAE,8BAA8B,GACvC,6BAA6B,CA+J/B"}

package/dist/tasks/handlers.js

@@ -0,0 +1,151 @@
+import { randomUUID } from 'node:crypto';
+import {} from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CallToolRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { logWarn, runWithRequestContext } from '../lib/core.js';
+import { getSdkCallToolHandler } from '../lib/mcp-interop.js';
+import { parseExtendedCallToolRequest, withRelatedTaskMeta, } from './call-contract.js';
+import { abortTaskExecution, emitTaskStatusNotification, handleToolCallRequest, throwTaskNotFound, toTaskSummary, } from './execution.js';
+import { taskManager } from './manager.js';
+import { isServerResult, parseHandlerExtra, resolveTaskOwnerKey, resolveToolCallContext, } from './owner.js';
+import { hasRegisteredTaskCapableTools, hasTaskCapableTool, } from './registry.js';
+export { cancelTasksForOwner, abortAllTaskExecutions } from './execution.js';
+/* -------------------------------------------------------------------------------------------------
+ * Task handler schemas and registration
+ * ------------------------------------------------------------------------------------------------- */
+const TaskGetSchema = z.looseObject({
+    method: z.literal('tasks/get', 'Expected "tasks/get"'),
+    params: z.looseObject({ taskId: z.string('Expected string') }, 'Expected object'),
+}, 'Invalid request');
+const TaskListSchema = z.looseObject({
+    method: z.literal('tasks/list', 'Expected "tasks/list"'),
+    params: z
+        .looseObject({
+        cursor: z.string('Expected string').optional(),
+    }, 'Expected object')
+        .optional(),
+}, 'Invalid request');
+const TaskCancelSchema = z.looseObject({
+    method: z.literal('tasks/cancel', 'Expected "tasks/cancel"'),
+    params: z.looseObject({ taskId: z.string('Expected string') }, 'Expected object'),
+}, 'Invalid request');
+const TaskResultSchema = z.looseObject({
+    method: z.literal('tasks/result', 'Expected "tasks/result"'),
+    params: z.looseObject({ taskId: z.string('Expected string') }, 'Expected object'),
+}, 'Invalid request');
+function resolveOwnerScopedExtra(extra) {
+    const parsedExtra = parseHandlerExtra(extra);
+    return {
+        parsedExtra,
+        ownerKey: resolveTaskOwnerKey(parsedExtra),
+    };
+}
+export function registerTaskHandlers(server, options) {
+    const sdkCallToolHandler = getSdkCallToolHandler(server);
+    const taskCapableToolsRegistered = hasRegisteredTaskCapableTools();
+    const requireInterception = options?.requireInterception ?? true;
+    if (!sdkCallToolHandler) {
+        if (taskCapableToolsRegistered && requireInterception) {
+            throw new Error('Task-capable tools are registered but SDK tools/call interception is unavailable. Upgrade compatibility or disable strict interception with TASKS_REQUIRE_INTERCEPTION=false.');
+        }
+        logWarn('Task call interception disabled: SDK tools/call handler unavailable; task-capable tools require MCP SDK compatibility update', { sdkVersion: 'unknown' });
+    }
+    if (sdkCallToolHandler) {
+        server.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+            const parsedExtra = parseHandlerExtra(extra);
+            const requestId = parsedExtra?.requestId !== undefined
+                ? String(parsedExtra.requestId)
+                : randomUUID();
+            return runWithRequestContext({
+                requestId,
+                operationId: requestId,
+                ...(parsedExtra?.sessionId
+                    ? { sessionId: parsedExtra.sessionId }
+                    : {}),
+            }, () => {
+                const toolName = request.params.name;
+                // Only intercept task-capable tools managed by the local task registry.
+                // Delegate all other tools to the SDK handler to avoid shadowing future tools.
+                if (!hasTaskCapableTool(toolName)) {
+                    return sdkCallToolHandler(request, extra);
+                }
+                const parsed = parseExtendedCallToolRequest(request);
+                const context = resolveToolCallContext(parsedExtra, parsed.params._meta);
+                return handleToolCallRequest(server, parsed, context);
+            });
+        });
+    }
+    server.server.setRequestHandler(TaskGetSchema, (request, extra) => {
+        const { taskId } = request.params;
+        const { ownerKey } = resolveOwnerScopedExtra(extra);
+        const task = taskManager.getTask(taskId, ownerKey);
+        if (!task)
+            throwTaskNotFound();
+        return toTaskSummary(task);
+    });
+    server.server.setRequestHandler(TaskResultSchema, async (request, extra) => {
+        const { taskId } = request.params;
+        const { parsedExtra, ownerKey } = resolveOwnerScopedExtra(extra);
+        const task = await taskManager.waitForTerminalTask(taskId, ownerKey, parsedExtra?.signal);
+        if (!task)
+            throwTaskNotFound();
+        try {
+            if (task.status === 'failed') {
+                if (task.error) {
+                    throw new McpError(task.error.code, task.error.message, task.error.data);
+                }
+                const failedResult = (task.result ?? null);
+                const fallback = failedResult ?? {
+                    content: [
+                        {
+                            type: 'text',
+                            text: task.statusMessage ?? 'Task execution failed',
+                        },
+                    ],
+                    isError: true,
+                };
+                return withRelatedTaskMeta(fallback, task.taskId);
+            }
+            if (task.status === 'cancelled') {
+                throw new McpError(ErrorCode.InvalidRequest, 'Task was cancelled', {
+                    taskId: task.taskId,
+                    status: 'cancelled',
+                    ...(task.statusMessage ? { statusMessage: task.statusMessage } : {}),
+                });
+            }
+            const result = isServerResult(task.result)
+                ? task.result
+                : { content: [] };
+            return withRelatedTaskMeta(result, task.taskId);
+        }
+        finally {
+            // Shrink TTL only after the result has been fully constructed and
+            // is about to be delivered — avoids premature expiry if result
+            // construction throws.
+            taskManager.shrinkTtlAfterDelivery(taskId);
+        }
+    });
+    server.server.setRequestHandler(TaskListSchema, (request, extra) => {
+        const { ownerKey } = resolveOwnerScopedExtra(extra);
+        const cursor = request.params?.cursor;
+        const { tasks, nextCursor } = taskManager.listTasks(cursor === undefined ? { ownerKey } : { ownerKey, cursor });
+        return {
+            tasks: tasks.map((task) => toTaskSummary(task)),
+            nextCursor,
+        };
+    });
+    server.server.setRequestHandler(TaskCancelSchema, (request, extra) => {
+        const { taskId } = request.params;
+        const { ownerKey } = resolveOwnerScopedExtra(extra);
+        const task = taskManager.cancelTask(taskId, ownerKey);
+        if (!task)
+            throwTaskNotFound();
+        abortTaskExecution(taskId);
+        emitTaskStatusNotification(server, task);
+        return toTaskSummary(task);
+    });
+    return {
+        interceptedToolsCall: sdkCallToolHandler !== null,
+        taskCapableToolsRegistered,
+    };
+}

package/dist/tasks/owner.d.ts

@@ -1,6 +1,5 @@
 import type { ServerResult } from '@modelcontextprotocol/sdk/types.js';
-import type { ProgressNotification } from '../lib/progress.js';
-import type { ToolHandlerExtra } from '../lib/progress.js';
+import type { ProgressNotification, ToolHandlerExtra } from '../lib/mcp-interop.js';
 import { type ToolCallRequestMeta } from './call-contract.js';
 interface HandlerExtra {
     sessionId?: string;

package/dist/tasks/owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../src/tasks/owner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAIvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAM5B,UAAU,YAAY;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC;AAED,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAEnD;;sDAEsD;AACtD,KAAK,SAAS,CAAC,CAAC,SAAS,MAAM,IAAI;KAChC,CAAC,IAAI,MAAM,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,SAAS,KAAK,GACnD,KAAK,GACL,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;CAClC,CAAC;AAEF,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAQ9D;AA2BD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CA0B1E;AAED,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,MAAM,CAMhE;AAuDD,wBAAgB,sBAAsB,CACpC,KAAK,CAAC,EAAE,YAAY,EACpB,WAAW,CAAC,EAAE,mBAAmB,GAChC,eAAe,CAEjB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,oBAAoB,EAC7B,WAAW,CAAC,EAAE,mBAAmB,GAChC,gBAAgB,CAOlB;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,EAC5E,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAC7D,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAmBvD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAIpE;AAWD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAgB7E"}
+{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../src/tasks/owner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAIvE,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAM5B,UAAU,YAAY;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC;AAED,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAEnD;;sDAEsD;AACtD,KAAK,SAAS,CAAC,CAAC,SAAS,MAAM,IAAI;KAChC,CAAC,IAAI,MAAM,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,SAAS,KAAK,GACnD,KAAK,GACL,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;CAClC,CAAC;AAEF,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAQ9D;AA2BD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CA0B1E;AAED,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,MAAM,CAMhE;AAuDD,wBAAgB,sBAAsB,CACpC,KAAK,CAAC,EAAE,YAAY,EACpB,WAAW,CAAC,EAAE,mBAAmB,GAChC,eAAe,CAEjB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,oBAAoB,EAC7B,WAAW,CAAC,EAAE,mBAAmB,GAChC,gBAAgB,CAOlB;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,EAC5E,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAC7D,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAmBvD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAIpE;AAWD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAgB7E"}

package/dist/tasks/registry.d.ts

@@ -1,5 +1,5 @@
 import type { ServerResult } from '@modelcontextprotocol/sdk/types.js';
-import type { ToolHandlerExtra } from '../lib/progress.js';
+import type { ToolHandlerExtra } from '../lib/mcp-interop.js';
 export type TaskCapableToolSupport = 'optional' | 'forbidden';
 export interface TaskCapableToolDescriptor<TArgs = unknown> {
     name: string;