@j0hanz/fetch-url-mcp 1.10.2 → 1.10.3

package/dist/tasks/manager.js

@@ -1,11 +1,9 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { Buffer } from 'node:buffer';
 import { randomUUID } from 'node:crypto';
 import { setInterval } from 'node:timers';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { config } from '../lib/core.js';
-import { toError } from '../lib/utils.js';
-import { createUnrefTimeout } from '../lib/utils.js';
+import { decodeTaskCursor, encodeTaskCursor } from './cursor-codec.js';
+import { TaskWaiterRegistry, waitForTerminalTask as waitForTerminalTaskWithDeadline, } from './waiters.js';
 const DEFAULT_TTL_MS = 60_000;
 const MIN_TTL_MS = 1_000;
 const MAX_TTL_MS = 86_400_000;
@@ -13,7 +11,6 @@ const DEFAULT_POLL_INTERVAL_MS = 1_000;
 const DEFAULT_OWNER_KEY = 'default';
 const DEFAULT_PAGE_SIZE = 50;
 const CLEANUP_INTERVAL_MS = 60_000;
-const MAX_CURSOR_LENGTH = 256;
 const RESULT_DELIVERY_GRACE_MS = 10_000;
 const TASK_STATUS_VALUES = new Set([
     'working',
@@ -59,7 +56,7 @@ function normalizeTaskTtl(ttl) {
 class TaskManager {
     tasks = new Map();
     ownerCounts = new Map();
-    waiters = new Map();
+    waiters = new TaskWaiterRegistry(isTerminalStatus);
     cleanupInterval = null;
     ensureCleanupLoop() {
         if (this.cleanupInterval)
@@ -259,116 +256,27 @@ class TaskManager {
     resolveAnchorTaskId(cursor) {
         if (cursor === undefined)
             return null;
-        const decoded = this.decodeCursor(cursor);
+        const decoded = decodeTaskCursor(cursor);
         if (decoded === null) {
             throw new McpError(ErrorCode.InvalidParams, 'Invalid cursor');
         }
         return decoded.anchorTaskId;
     }
-    addWaiter(taskId, waiter) {
-        let set = this.waiters.get(taskId);
-        if (!set) {
-            set = new Set();
-            this.waiters.set(taskId, set);
-        }
-        set.add(waiter);
-    }
-    removeWaiter(taskId, waiter) {
-        if (!waiter)
-            return;
-        const set = this.waiters.get(taskId);
-        if (!set)
-            return;
-        set.delete(waiter);
-        if (set.size === 0) {
-            this.waiters.delete(taskId);
-        }
-    }
     async waitForTerminalTask(taskId, ownerKey, signal) {
-        const task = this.lookupActiveTask(taskId, ownerKey);
-        if (!task)
-            return undefined;
-        if (isTerminalStatus(task.status))
-            return task;
-        // isExpired() above guarantees task.ttl has not elapsed; compute deadlineMs
-        // for the promise-based timeout below.
-        const deadlineMs = task._createdAtMs + task.ttl;
-        return new Promise((resolve, reject) => {
-            // Bind resolve/reject to the AsyncLocalStorage context of the caller, so that any context values (e.g. requestId) are preserved when we later call them from a different tick.
-            const resolveInContext = AsyncLocalStorage.bind((value) => {
-                resolve(value);
-            });
-            const rejectInContext = AsyncLocalStorage.bind((error) => {
-                reject(toError(error));
-            });
-            let settled = false;
-            let waiter = null;
-            let deadlineTimeout;
-            const cleanup = () => {
-                if (deadlineTimeout) {
-                    deadlineTimeout.cancel();
-                    deadlineTimeout = undefined;
-                }
-                if (signal) {
-                    signal.removeEventListener('abort', onAbort);
-                }
-            };
-            const settleOnce = (fn) => {
-                if (settled)
-                    return;
-                settled = true;
-                fn();
-            };
-            const onAbort = () => {
-                settleOnce(() => {
-                    cleanup();
-                    this.removeWaiter(taskId, waiter);
-                    rejectInContext(new McpError(ErrorCode.ConnectionClosed, 'Request was cancelled'));
-                });
-            };
-            waiter = (updated) => {
-                settleOnce(() => {
-                    cleanup();
-                    if (updated.ownerKey !== ownerKey) {
-                        resolveInContext(undefined);
-                        return;
-                    }
-                    resolveInContext(updated);
-                });
-            };
-            if (signal?.aborted) {
-                onAbort();
-                return;
-            }
-            this.addWaiter(taskId, waiter);
-            if (signal) {
-                signal.addEventListener('abort', onAbort, { once: true });
-            }
-            const timeoutMs = Math.max(0, deadlineMs - Date.now());
-            deadlineTimeout = createUnrefTimeout(timeoutMs, { timeout: true });
-            void deadlineTimeout.promise
-                .then(() => {
-                settleOnce(() => {
-                    cleanup();
-                    this.removeWaiter(taskId, waiter);
-                    this.removeTask(taskId);
-                    rejectInContext(new McpError(ErrorCode.InvalidParams, 'Task expired', {
-                        taskId,
-                    }));
-                });
-            })
-                .catch(rejectInContext);
+        return waitForTerminalTaskWithDeadline({
+            taskId,
+            ownerKey,
+            ...(signal ? { signal } : {}),
+            lookupTask: (currentTaskId, currentOwnerKey) => this.lookupActiveTask(currentTaskId, currentOwnerKey),
+            removeTask: (currentTaskId) => {
+                this.removeTask(currentTaskId);
+            },
+            registry: this.waiters,
+            isTerminalStatus,
         });
     }
     notifyWaiters(task) {
-        if (!isTerminalStatus(task.status))
-            return;
-        const waiters = this.waiters.get(task.taskId);
-        if (!waiters)
-            return;
-        this.waiters.delete(task.taskId);
-        for (const waiter of waiters)
-            waiter(task);
+        this.waiters.notify(task);
     }
     isExpired(task, now = Date.now()) {
         return now - task._createdAtMs > task.ttl;
@@ -389,47 +297,11 @@ class TaskManager {
             this.maybeUpdateLastUpdatedAt(task);
         }
     }
-    encodeCursor(taskId) {
-        // Base64url-encode the taskId to produce a compact opaque cursor string.
-        // The taskId is a UUID, which is 36 ASCII chars, so the resulting cursor will be 48 chars (36 * 4/3) plus padding if any.
-        return Buffer.from(taskId, 'utf8').toString('base64url');
-    }
-    decodeCursor(cursor) {
-        try {
-            if (!isValidBase64UrlCursor(cursor))
-                return null;
-            const decoded = Buffer.from(cursor, 'base64url').toString('utf8');
-            // Basic sanity: non-empty and plausible taskId length (UUIDs are 36 chars)
-            if (!decoded || decoded.length > 128)
-                return null;
-            return { anchorTaskId: decoded };
-        }
-        catch {
-            return null;
-        }
-    }
     resolveNextCursor(page, hasMore) {
         if (!hasMore)
             return undefined;
         const lastTask = page.at(-1);
-        return lastTask ? this.encodeCursor(lastTask.taskId) : undefined;
-    }
-}
-function isValidBase64UrlCursor(cursor) {
-    if (!cursor)
-        return false;
-    if (cursor.length > MAX_CURSOR_LENGTH)
-        return false;
-    if (!/^[A-Za-z0-9_-]+={0,2}$/u.test(cursor))
-        return false;
-    const firstPaddingIndex = cursor.indexOf('=');
-    if (firstPaddingIndex !== -1) {
-        for (let i = firstPaddingIndex; i < cursor.length; i += 1) {
-            if (cursor[i] !== '=')
-                return false;
-        }
-        return cursor.length % 4 === 0;
+        return lastTask ? encodeTaskCursor(lastTask.taskId) : undefined;
     }
-    return cursor.length % 4 !== 1;
 }
 export const taskManager = new TaskManager();

package/dist/tasks/owner.d.ts

@@ -1,5 +1,7 @@
 import type { ServerResult } from '@modelcontextprotocol/sdk/types.js';
 import type { ProgressNotification } from '../lib/progress.js';
+import type { ToolHandlerExtra } from '../lib/progress.js';
+import { type ToolCallRequestMeta } from './call-contract.js';
 interface HandlerExtra {
     sessionId?: string;
     authInfo?: {
@@ -9,14 +11,17 @@ interface HandlerExtra {
     signal?: AbortSignal;
     requestId?: string | number;
     sendNotification?: (notification: ProgressNotification) => Promise<void>;
+    requestInfo?: unknown;
 }
-export interface ToolCallContext {
+export interface ToolExecutionContext {
     ownerKey: string;
     sessionId?: string;
     signal?: AbortSignal;
     requestId?: string | number;
     sendNotification?: (notification: ProgressNotification) => Promise<void>;
+    requestMeta?: ToolCallRequestMeta;
 }
+export type ToolCallContext = ToolExecutionContext;
 /** Strip keys whose value is `undefined`, returning an object with only the
  * present keys. Return type correctly omits the `undefined` union so the result
  * is compatible with `exactOptionalPropertyTypes`. */
@@ -26,7 +31,12 @@ type Compacted<T extends object> = {
 export declare function compact<T extends object>(obj: T): Compacted<T>;
 export declare function parseHandlerExtra(extra: unknown): HandlerExtra | undefined;
 export declare function resolveTaskOwnerKey(extra?: HandlerExtra): string;
-export declare function resolveToolCallContext(extra?: HandlerExtra): ToolCallContext;
+export declare function resolveRequestIdFromExtra(extra: unknown): string | undefined;
+export declare function resolveSessionIdFromExtra(extra: unknown): string | undefined;
+export declare function resolveToolExecutionContext(extra?: HandlerExtra, requestMeta?: ToolCallRequestMeta): ToolExecutionContext;
+export declare function resolveToolCallContext(extra?: HandlerExtra, requestMeta?: ToolCallRequestMeta): ToolCallContext;
+export declare function buildToolHandlerExtra(context: ToolExecutionContext, requestMeta?: ToolCallRequestMeta): ToolHandlerExtra;
+export declare function withRequestContextIfMissing<TParams, TResult, TExtra = unknown>(handler: (params: TParams, extra?: TExtra) => Promise<TResult>): (params: TParams, extra?: TExtra) => Promise<TResult>;
 export declare function isServerResult(value: unknown): value is ServerResult;
 export declare function tryReadToolStructuredError(value: unknown): string | undefined;
 export {};

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;AAGvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAO/D,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;CAC1E;AAED,MAAM,WAAW,eAAe;IAC9B,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;CAC1E;AAED;;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,CAyB1E;AAED,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,MAAM,CAMhE;AAED,wBAAgB,sBAAsB,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,eAAe,CAQ5E;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":"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"}

package/dist/tasks/owner.js

@@ -1,6 +1,8 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { isObject } from '../lib/utils.js';
+import { getRequestId, runWithRequestContext } from '../lib/core.js';
+import { isObject, readNestedRecord } from '../lib/utils.js';
+import { sanitizeToolCallMeta, } from './call-contract.js';
 export function compact(obj) {
     const result = {};
     for (const key of Object.keys(obj)) {
@@ -60,15 +62,62 @@ export function resolveTaskOwnerKey(extra) {
         return `token:${createHash('sha256').update(extra.authInfo.token).digest('hex')}`;
     return 'default';
 }
-export function resolveToolCallContext(extra) {
+export function resolveRequestIdFromExtra(extra) {
+    if (!isObject(extra))
+        return undefined;
+    const { requestId } = extra;
+    if (typeof requestId === 'string')
+        return requestId;
+    if (typeof requestId === 'number')
+        return String(requestId);
+    return undefined;
+}
+export function resolveSessionIdFromExtra(extra) {
+    if (!isObject(extra))
+        return undefined;
+    const { sessionId } = extra;
+    if (typeof sessionId === 'string')
+        return sessionId;
+    const headers = readNestedRecord(extra, ['requestInfo', 'headers']);
+    const headerValue = headers ? headers['mcp-session-id'] : undefined;
+    return typeof headerValue === 'string' ? headerValue : undefined;
+}
+export function resolveToolExecutionContext(extra, requestMeta) {
     return compact({
         ownerKey: resolveTaskOwnerKey(extra),
         sessionId: extra?.sessionId,
         signal: extra?.signal,
         requestId: extra?.requestId,
         sendNotification: extra?.sendNotification,
+        requestMeta: sanitizeToolCallMeta(requestMeta),
     });
 }
+export function resolveToolCallContext(extra, requestMeta) {
+    return resolveToolExecutionContext(extra, requestMeta);
+}
+export function buildToolHandlerExtra(context, requestMeta) {
+    return compact({
+        signal: context.signal,
+        requestId: context.requestId,
+        sendNotification: context.sendNotification,
+        _meta: sanitizeToolCallMeta(requestMeta ?? context.requestMeta),
+    });
+}
+export function withRequestContextIfMissing(handler) {
+    return async (params, extra) => {
+        const existingRequestId = getRequestId();
+        if (existingRequestId) {
+            return handler(params, extra);
+        }
+        const derivedRequestId = resolveRequestIdFromExtra(extra) ?? randomUUID();
+        const derivedSessionId = resolveSessionIdFromExtra(extra);
+        return runWithRequestContext({
+            requestId: derivedRequestId,
+            operationId: derivedRequestId,
+            ...(derivedSessionId ? { sessionId: derivedSessionId } : {}),
+        }, () => handler(params, extra));
+    };
+}
 export function isServerResult(value) {
     return (isObject(value) && Array.isArray(value.content));
 }

package/dist/tasks/tool-registry.d.ts

@@ -4,6 +4,7 @@ export interface TaskCapableToolDescriptor<TArgs = unknown> {
     name: string;
     parseArguments: (args: unknown) => TArgs;
     execute: (args: TArgs, extra?: ToolHandlerExtra) => Promise<ServerResult>;
+    getCompletionStatusMessage?: (result: ServerResult) => string | undefined;
 }
 export declare function registerTaskCapableTool<TArgs>(descriptor: TaskCapableToolDescriptor<TArgs>): void;
 export declare function unregisterTaskCapableTool(name: string): void;

package/dist/tasks/tool-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/tasks/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAEvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,yBAAyB,CAAC,KAAK,GAAG,OAAO;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,KAAK,CAAC;IACzC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,gBAAgB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CAC3E;AAID,wBAAgB,uBAAuB,CAAC,KAAK,EAC3C,UAAU,EAAE,yBAAyB,CAAC,KAAK,CAAC,GAC3C,IAAI,CAKN;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,GACX,yBAAyB,GAAG,SAAS,CAEvC;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,6BAA6B,IAAI,OAAO,CAEvD"}
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/tasks/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAEvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,yBAAyB,CAAC,KAAK,GAAG,OAAO;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,KAAK,CAAC;IACzC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,gBAAgB,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC1E,0BAA0B,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,MAAM,GAAG,SAAS,CAAC;CAC3E;AAID,wBAAgB,uBAAuB,CAAC,KAAK,EAC3C,UAAU,EAAE,yBAAyB,CAAC,KAAK,CAAC,GAC3C,IAAI,CAKN;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,GACX,yBAAyB,GAAG,SAAS,CAEvC;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,6BAA6B,IAAI,OAAO,CAEvD"}

package/dist/tasks/waiters.d.ts

@@ -0,0 +1,27 @@
+interface WaitableTask {
+    taskId: string;
+    ownerKey: string;
+    status: string;
+    ttl: number;
+    _createdAtMs: number;
+}
+type TaskWaiter<TTask extends WaitableTask> = (task: TTask) => void;
+export declare class TaskWaiterRegistry<TTask extends WaitableTask> {
+    private readonly isTerminalStatus;
+    private waiters;
+    constructor(isTerminalStatus: (status: TTask['status']) => boolean);
+    add(taskId: string, waiter: TaskWaiter<TTask>): void;
+    remove(taskId: string, waiter: TaskWaiter<TTask> | null): void;
+    notify(task: TTask): void;
+}
+export declare function waitForTerminalTask<TTask extends WaitableTask>(options: {
+    taskId: string;
+    ownerKey: string;
+    signal?: AbortSignal;
+    lookupTask: (taskId: string, ownerKey: string) => TTask | undefined;
+    removeTask: (taskId: string) => void;
+    registry: TaskWaiterRegistry<TTask>;
+    isTerminalStatus: (status: TTask['status']) => boolean;
+}): Promise<TTask | undefined>;
+export {};
+//# sourceMappingURL=waiters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"waiters.d.ts","sourceRoot":"","sources":["../../src/tasks/waiters.ts"],"names":[],"mappings":"AAOA,UAAU,YAAY;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,KAAK,UAAU,CAAC,KAAK,SAAS,YAAY,IAAI,CAAC,IAAI,EAAE,KAAK,KAAK,IAAI,CAAC;AAEpE,qBAAa,kBAAkB,CAAC,KAAK,SAAS,YAAY;IAItD,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAHnC,OAAO,CAAC,OAAO,CAA6C;gBAGzC,gBAAgB,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,OAAO;IAGzE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,IAAI;IASpD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,IAAI;IAY9D,MAAM,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI;CAS1B;AAED,wBAAsB,mBAAmB,CAAC,KAAK,SAAS,YAAY,EAAE,OAAO,EAAE;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,KAAK,GAAG,SAAS,CAAC;IACpE,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACpC,gBAAgB,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC;CACxD,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAwF7B"}

package/dist/tasks/waiters.js

@@ -0,0 +1,113 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { toError } from '../lib/utils.js';
+import { createUnrefTimeout } from '../lib/utils.js';
+export class TaskWaiterRegistry {
+    isTerminalStatus;
+    waiters = new Map();
+    constructor(isTerminalStatus) {
+        this.isTerminalStatus = isTerminalStatus;
+    }
+    add(taskId, waiter) {
+        let set = this.waiters.get(taskId);
+        if (!set) {
+            set = new Set();
+            this.waiters.set(taskId, set);
+        }
+        set.add(waiter);
+    }
+    remove(taskId, waiter) {
+        if (!waiter)
+            return;
+        const set = this.waiters.get(taskId);
+        if (!set)
+            return;
+        set.delete(waiter);
+        if (set.size === 0) {
+            this.waiters.delete(taskId);
+        }
+    }
+    notify(task) {
+        if (!this.isTerminalStatus(task.status))
+            return;
+        const waiters = this.waiters.get(task.taskId);
+        if (!waiters)
+            return;
+        this.waiters.delete(task.taskId);
+        for (const waiter of waiters)
+            waiter(task);
+    }
+}
+export async function waitForTerminalTask(options) {
+    const task = options.lookupTask(options.taskId, options.ownerKey);
+    if (!task)
+        return undefined;
+    if (options.isTerminalStatus(task.status))
+        return task;
+    const deadlineMs = task._createdAtMs + task.ttl;
+    return new Promise((resolve, reject) => {
+        const resolveInContext = AsyncLocalStorage.bind((value) => {
+            resolve(value);
+        });
+        const rejectInContext = AsyncLocalStorage.bind((error) => {
+            reject(toError(error));
+        });
+        let settled = false;
+        let waiter = null;
+        let deadlineTimeout;
+        const cleanup = () => {
+            if (deadlineTimeout) {
+                deadlineTimeout.cancel();
+                deadlineTimeout = undefined;
+            }
+            if (options.signal) {
+                options.signal.removeEventListener('abort', onAbort);
+            }
+        };
+        const settleOnce = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            fn();
+        };
+        const onAbort = () => {
+            settleOnce(() => {
+                cleanup();
+                options.registry.remove(options.taskId, waiter);
+                rejectInContext(new McpError(ErrorCode.ConnectionClosed, 'Request was cancelled'));
+            });
+        };
+        waiter = (updated) => {
+            settleOnce(() => {
+                cleanup();
+                if (updated.ownerKey !== options.ownerKey) {
+                    resolveInContext(undefined);
+                    return;
+                }
+                resolveInContext(updated);
+            });
+        };
+        if (options.signal?.aborted) {
+            onAbort();
+            return;
+        }
+        options.registry.add(options.taskId, waiter);
+        if (options.signal) {
+            options.signal.addEventListener('abort', onAbort, { once: true });
+        }
+        const timeoutMs = Math.max(0, deadlineMs - Date.now());
+        deadlineTimeout = createUnrefTimeout(timeoutMs, { timeout: true });
+        void deadlineTimeout.promise
+            .then(() => {
+            settleOnce(() => {
+                cleanup();
+                options.registry.remove(options.taskId, waiter);
+                options.removeTask(options.taskId);
+                rejectInContext(new McpError(ErrorCode.InvalidParams, 'Task expired', {
+                    taskId: options.taskId,
+                }));
+            });
+        })
+            .catch(rejectInContext);
+    });
+}

package/dist/tools/fetch-url-progress.d.ts

@@ -0,0 +1,17 @@
+import type { ServerResult } from '@modelcontextprotocol/sdk/types.js';
+import type { SharedFetchStage } from '../lib/fetch-pipeline.js';
+import type { ProgressReporter } from '../lib/progress.js';
+export declare function buildFetchSuccessSummary(contentSize: number): string;
+export declare function getFetchCompletionStatusMessage(result: ServerResult): string | undefined;
+export declare class FetchUrlProgressPlan {
+    private readonly reporter;
+    private readonly context;
+    private path;
+    constructor(reporter: ProgressReporter, context: string);
+    reportStart(): void;
+    reportStage(stage: SharedFetchStage): void;
+    reportSuccess(contentSize: number): void;
+    reportFailure(cancelled: boolean): void;
+    private mapStage;
+}
+//# sourceMappingURL=fetch-url-progress.d.ts.map

package/dist/tools/fetch-url-progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-url-progress.d.ts","sourceRoot":"","sources":["../../src/tools/fetch-url-progress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAEvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAW3D,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,YAAY,GACnB,MAAM,GAAG,SAAS,CAUpB;AAED,qBAAa,oBAAoB;IAI7B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,IAAI,CAAwB;gBAGjB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,MAAM;IAGlC,WAAW,IAAI,IAAI;IAInB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAM1C,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAIxC,aAAa,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI;IAIvC,OAAO,CAAC,QAAQ;CAiCjB"}

package/dist/tools/fetch-url-progress.js

@@ -0,0 +1,78 @@
+import { isObject } from '../lib/utils.js';
+function formatContentSize(contentSize) {
+    if (contentSize < 1000)
+        return `${contentSize} chars`;
+    if (contentSize < 1_000_000)
+        return `${(contentSize / 1024).toFixed(1)} KB`;
+    return `${(contentSize / (1024 * 1024)).toFixed(1)} MB`;
+}
+export function buildFetchSuccessSummary(contentSize) {
+    return `Done — ${formatContentSize(contentSize)}`;
+}
+export function getFetchCompletionStatusMessage(result) {
+    if (!isObject(result))
+        return undefined;
+    const { structuredContent } = result;
+    if (!isObject(structuredContent))
+        return undefined;
+    const { contentSize } = structuredContent;
+    return typeof contentSize === 'number'
+        ? buildFetchSuccessSummary(contentSize)
+        : undefined;
+}
+export class FetchUrlProgressPlan {
+    reporter;
+    context;
+    path = 'unknown';
+    constructor(reporter, context) {
+        this.reporter = reporter;
+        this.context = context;
+    }
+    reportStart() {
+        this.reporter.report(1, 'Preparing request');
+    }
+    reportStage(stage) {
+        const mapped = this.mapStage(stage);
+        if (!mapped)
+            return;
+        this.reporter.report(mapped.step, mapped.message);
+    }
+    reportSuccess(contentSize) {
+        this.reporter.report(8, buildFetchSuccessSummary(contentSize));
+    }
+    reportFailure(cancelled) {
+        this.reporter.report(8, cancelled ? 'Cancelled' : 'Failed');
+    }
+    mapStage(stage) {
+        switch (stage) {
+            case 'resolve_url':
+                return { step: 2, message: 'Resolving URL' };
+            case 'check_cache':
+                return { step: 3, message: 'Checking cache' };
+            case 'cache_hit':
+                this.path = 'cache_hit';
+                return { step: 4, message: 'Loaded from cache' };
+            case 'cache_restore':
+                this.path = 'cache_hit';
+                return { step: 5, message: 'Restoring cached content' };
+            case 'fetch_remote':
+                this.path = 'cache_miss';
+                return { step: 4, message: `Fetching ${this.context}` };
+            case 'response_ready':
+                this.path = 'cache_miss';
+                return { step: 5, message: 'Received response' };
+            case 'transform_start':
+                this.path = 'cache_miss';
+                return { step: 6, message: 'Parsing HTML -> Markdown' };
+            case 'prepare_output':
+                return {
+                    step: this.path === 'cache_miss' ? 7 : 6,
+                    message: 'Preparing output',
+                };
+            case 'finalize_output':
+                if (this.path === 'cache_miss')
+                    return undefined;
+                return { step: 7, message: 'Finalizing output' };
+        }
+    }
+}

package/dist/tools/fetch-url.d.ts

@@ -12,14 +12,10 @@ interface ToolResponseBase {
 }
 export declare const FETCH_URL_TOOL_NAME = "fetch-url";
 export declare function fetchUrlToolHandler(input: FetchUrlInput, extra?: ToolHandlerExtra): Promise<ToolResponseBase>;
-/**
- * Stdio-path guard: ensures a request context (requestId, sessionId) is set
- * in AsyncLocalStorage before invoking the handler. On the HTTP path the SDK
- * populates `extra.requestId`/`extra.requestInfo`, so this is a no-op there.
- * On the stdio path there is no SDK-provided context, so we derive one from
- * the extra fields or generate a fresh UUID.
- */
-export declare function withRequestContextIfMissing<TParams, TResult, TExtra = unknown>(handler: (params: TParams, extra?: TExtra) => Promise<TResult>): (params: TParams, extra?: TExtra) => Promise<TResult>;
-export declare function registerTools(server: McpServer): void;
+type TaskSupport = 'optional' | 'forbidden';
+export interface ToolRegistrationControls {
+    setTaskSupport: (support: TaskSupport) => void;
+}
+export declare function registerTools(server: McpServer): ToolRegistrationControls;
 export {};
 //# sourceMappingURL=fetch-url.d.ts.map

package/dist/tools/fetch-url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-url.d.ts","sourceRoot":"","sources":["../../src/tools/fetch-url.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,YAAY,EAEb,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyBxB,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EACL,mBAAmB,EAIpB,MAAM,eAAe,CAAC;AAMvB,KAAK,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEzD,UAAU,gBAAgB;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,mBAAmB,cAAc,CAAC;AA4N/C,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,aAAa,EACpB,KAAK,CAAC,EAAE,gBAAgB,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAQ3B;AAsBD;;;;;;GAMG;AACH,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;AAwBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAqCrD"}
+{"version":3,"file":"fetch-url.d.ts","sourceRoot":"","sources":["../../src/tools/fetch-url.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,YAAY,EAEb,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBxB,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EACL,mBAAmB,EAIpB,MAAM,eAAe,CAAC;AAYvB,KAAK,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEzD,UAAU,gBAAgB;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAsL/C,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,aAAa,EACpB,KAAK,CAAC,EAAE,gBAAgB,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAQ3B;AAqBD,KAAK,WAAW,GAAG,UAAU,GAAG,WAAW,CAAC;AAE5C,MAAM,WAAW,wBAAwB;IACvC,cAAc,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;CAChD;AA2BD,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,wBAAwB,CAsCzE"}