@j0hanz/fetch-url-mcp 1.3.1 → 1.5.0

package/dist/tasks/manager.js

@@ -1,10 +1,11 @@
-import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { Buffer } from 'node:buffer';
 import { randomUUID } from 'node:crypto';
 import { setInterval } from 'node:timers';
-import { config } from '../config.js';
-import { createUnrefTimeout } from '../timer-utils.js';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { config } from '../lib/core.js';
+import { RESOURCE_NOT_FOUND_ERROR_CODE, toError } from '../lib/utils.js';
+import { createUnrefTimeout } from '../lib/utils.js';
 const DEFAULT_TTL_MS = 60_000;
 const MIN_TTL_MS = 1_000;
 const MAX_TTL_MS = 86_400_000;
@@ -31,35 +32,61 @@ class TaskManager {
     tasks = new Map();
     ownerCounts = new Map();
     waiters = new Map();
-    constructor() {
-        this.startCleanupLoop();
-    }
-    startCleanupLoop() {
-        const interval = setInterval(() => {
+    cleanupInterval = null;
+    ensureCleanupLoop() {
+        if (this.cleanupInterval)
+            return;
+        this.cleanupInterval = setInterval(() => {
             this.removeExpiredTasks();
+            if (this.tasks.size === 0) {
+                this.stopCleanupLoop();
+            }
         }, CLEANUP_INTERVAL_MS);
-        interval.unref();
+        this.cleanupInterval.unref();
+    }
+    stopCleanupLoop() {
+        if (!this.cleanupInterval)
+            return;
+        clearInterval(this.cleanupInterval);
+        this.cleanupInterval = null;
     }
     removeExpiredTasks() {
         const now = Date.now();
-        const expired = [];
         for (const [id, task] of this.tasks) {
             if (this.isExpired(task, now)) {
-                expired.push(id);
+                this.removeTask(id);
             }
         }
-        for (const id of expired) {
-            this.removeTask(id);
-        }
     }
     removeTask(taskId) {
         const task = this.tasks.get(taskId);
         if (!task)
             return false;
         this.tasks.delete(taskId);
-        this.decrementOwnerCount(task.ownerKey);
+        this.releaseOwnerCount(task);
         return true;
     }
+    applyTaskUpdate(task, updates) {
+        Object.assign(task, updates);
+        task.lastUpdatedAt = new Date().toISOString();
+    }
+    cancelActiveTask(task, statusMessage) {
+        this.applyTaskUpdate(task, {
+            status: 'cancelled',
+            statusMessage,
+        });
+        this.notifyWaiters(task);
+        this.releaseOwnerCount(task);
+    }
+    releaseOwnerCount(task) {
+        const internal = task;
+        if (internal._ownerCounted === false)
+            return;
+        if ('_ownerCounted' in internal) {
+            internal._ownerCounted = false;
+        }
+        this.decrementOwnerCount(task.ownerKey);
+    }
     countTasksForOwner(ownerKey) {
         return this.ownerCounts.get(ownerKey) ?? 0;
     }
@@ -99,12 +126,14 @@ class TaskManager {
             ttl: normalizeTaskTtl(options?.ttl),
             pollInterval: DEFAULT_POLL_INTERVAL_MS,
             _createdAtMs: now.getTime(),
+            _ownerCounted: true,
         };
         this.tasks.set(task.taskId, task);
         this.incrementOwnerCount(ownerKey);
+        this.ensureCleanupLoop();
         return task;
     }
-    getTask(taskId, ownerKey) {
+    lookupActiveTask(taskId, ownerKey) {
         const task = this.tasks.get(taskId);
         if (!task)
             return undefined;
@@ -116,30 +145,26 @@ class TaskManager {
         }
         return task;
     }
+    getTask(taskId, ownerKey) {
+        return this.lookupActiveTask(taskId, ownerKey);
+    }
     updateTask(taskId, updates) {
         const task = this.tasks.get(taskId);
         if (!task)
             return;
         if (isTerminalStatus(task.status))
             return;
-        Object.assign(task, {
-            ...updates,
-            lastUpdatedAt: new Date().toISOString(),
-        });
+        this.applyTaskUpdate(task, updates);
         this.notifyWaiters(task);
     }
     cancelTask(taskId, ownerKey) {
-        const task = this.getTask(taskId, ownerKey);
+        const task = this.lookupActiveTask(taskId, ownerKey);
         if (!task)
             return undefined;
         if (isTerminalStatus(task.status)) {
             throw new McpError(ErrorCode.InvalidParams, `Cannot cancel task: already in terminal status '${task.status}'`);
         }
-        this.updateTask(taskId, {
-            status: 'cancelled',
-            statusMessage: 'The task was cancelled by request.',
-        });
-        this.decrementOwnerCount(task.ownerKey);
+        this.cancelActiveTask(task, 'The task was cancelled by request.');
         return this.tasks.get(taskId);
     }
     cancelTasksByOwner(ownerKey, statusMessage = 'The task was cancelled because its owner is no longer active.') {
@@ -151,11 +176,7 @@ class TaskManager {
                 continue;
             if (isTerminalStatus(task.status))
                 continue;
-            this.updateTask(task.taskId, {
-                status: 'cancelled',
-                statusMessage,
-            });
-            this.decrementOwnerCount(task.ownerKey);
+            this.cancelActiveTask(task, statusMessage);
             cancelled.push(task);
         }
         return cancelled;
@@ -165,12 +186,11 @@ class TaskManager {
         let collecting = anchorTaskId === null;
         let anchorFound = anchorTaskId === null;
         const now = Date.now();
-        const expired = [];
         for (const task of this.tasks.values()) {
             if (task.ownerKey !== ownerKey)
                 continue;
             if (this.isExpired(task, now)) {
-                expired.push(task.taskId);
+                this.removeTask(task.taskId);
                 continue;
             }
             if (!collecting) {
@@ -184,9 +204,6 @@ class TaskManager {
             if (page.length > pageSize)
                 break;
         }
-        for (const id of expired) {
-            this.removeTask(id);
-        }
         // Anchor task expired between pages; return empty list so callers stop
         // pagination cleanly. Silently falling back to page 0 risks infinite loops
         // for automated clients that always follow nextCursor.
@@ -198,14 +215,7 @@ class TaskManager {
     listTasks(options) {
         const { ownerKey, cursor, limit } = options;
         const pageSize = limit && limit > 0 ? limit : DEFAULT_PAGE_SIZE;
-        let anchorTaskId = null;
-        if (cursor !== undefined) {
-            const decoded = this.decodeCursor(cursor);
-            if (decoded === null) {
-                throw new McpError(ErrorCode.InvalidParams, 'Invalid cursor');
-            }
-            ({ anchorTaskId } = decoded);
-        }
+        const anchorTaskId = this.resolveAnchorTaskId(cursor);
         const page = this.collectPage(ownerKey, anchorTaskId, pageSize);
         const hasMore = page.length > pageSize;
         if (hasMore) {
@@ -214,27 +224,50 @@ class TaskManager {
         const nextCursor = this.resolveNextCursor(page, hasMore);
         return nextCursor ? { tasks: page, nextCursor } : { tasks: page };
     }
+    resolveAnchorTaskId(cursor) {
+        if (cursor === undefined)
+            return null;
+        const decoded = this.decodeCursor(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.tasks.get(taskId);
+        const task = this.lookupActiveTask(taskId, ownerKey);
         if (!task)
             return undefined;
-        if (ownerKey && task.ownerKey !== ownerKey)
-            return undefined;
-        if (this.isExpired(task)) {
-            this.removeTask(taskId);
-            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(error instanceof Error ? error : new Error(String(error)));
+                reject(toError(error));
             });
             let settled = false;
             let waiter = null;
@@ -248,16 +281,6 @@ class TaskManager {
                     signal.removeEventListener('abort', onAbort);
                 }
             };
-            const removeWaiter = () => {
-                if (waiter) {
-                    const set = this.waiters.get(taskId);
-                    if (set) {
-                        set.delete(waiter);
-                        if (set.size === 0)
-                            this.waiters.delete(taskId);
-                    }
-                }
-            };
             const settleOnce = (fn) => {
                 if (settled)
                     return;
@@ -267,7 +290,7 @@ class TaskManager {
             const onAbort = () => {
                 settleOnce(() => {
                     cleanup();
-                    removeWaiter();
+                    this.removeWaiter(taskId, waiter);
                     rejectInContext(new McpError(ErrorCode.ConnectionClosed, 'Request was cancelled'));
                 });
             };
@@ -285,12 +308,7 @@ class TaskManager {
                 onAbort();
                 return;
             }
-            let set = this.waiters.get(taskId);
-            if (!set) {
-                set = new Set();
-                this.waiters.set(taskId, set);
-            }
-            set.add(waiter);
+            this.addWaiter(taskId, waiter);
             if (signal) {
                 signal.addEventListener('abort', onAbort, { once: true });
             }
@@ -300,9 +318,11 @@ class TaskManager {
                 .then(() => {
                 settleOnce(() => {
                     cleanup();
-                    removeWaiter();
+                    this.removeWaiter(taskId, waiter);
                     this.removeTask(taskId);
-                    resolveInContext(undefined);
+                    rejectInContext(new McpError(RESOURCE_NOT_FOUND_ERROR_CODE, 'Task expired', {
+                        taskId,
+                    }));
                 });
             })
                 .catch(rejectInContext);
@@ -321,6 +341,9 @@ class TaskManager {
     isExpired(task, now = Date.now()) {
         return now - task._createdAtMs > task.ttl;
     }
+    maybeUpdateLastUpdatedAt(task) {
+        task.lastUpdatedAt = new Date().toISOString();
+    }
     shrinkTtlAfterDelivery(taskId) {
         const task = this.tasks.get(taskId);
         if (!task)
@@ -331,10 +354,12 @@ class TaskManager {
         const newTtl = elapsed + RESULT_DELIVERY_GRACE_MS;
         if (newTtl < task.ttl) {
             task.ttl = newTtl;
-            task.lastUpdatedAt = new Date().toISOString();
+            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) {
@@ -376,4 +401,3 @@ function isValidBase64UrlCursor(cursor) {
     return cursor.length % 4 !== 1;
 }
 export const taskManager = new TaskManager();
-//# sourceMappingURL=manager.js.map

package/dist/tasks/owner.d.ts

@@ -1,6 +1,6 @@
 import type { ServerResult } from '@modelcontextprotocol/sdk/types.js';
-import type { ProgressNotification } from '../tools.js';
-export interface HandlerExtra {
+import type { ProgressNotification } from '../lib/mcp-tools.js';
+interface HandlerExtra {
     sessionId?: string;
     authInfo?: {
         clientId?: string;
@@ -12,6 +12,7 @@ export interface HandlerExtra {
 }
 export interface ToolCallContext {
     ownerKey: string;
+    sessionId?: string;
     signal?: AbortSignal;
     requestId?: string | number;
     sendNotification?: (notification: ProgressNotification) => Promise<void>;
@@ -29,4 +30,3 @@ export declare function resolveToolCallContext(extra?: HandlerExtra): ToolCallCo
 export declare function isServerResult(value: unknown): value is ServerResult;
 export declare function tryReadToolStructuredError(value: unknown): string | undefined;
 export {};
-//# sourceMappingURL=owner.d.ts.map

package/dist/tasks/owner.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { isObject } from '../type-guards.js';
+import { isObject } from '../lib/utils.js';
 export function compact(obj) {
     const result = {};
     for (const key of Object.keys(obj)) {
@@ -62,6 +62,7 @@ export function resolveTaskOwnerKey(extra) {
 export function resolveToolCallContext(extra) {
     return compact({
         ownerKey: resolveTaskOwnerKey(extra),
+        sessionId: extra?.sessionId,
         signal: extra?.signal,
         requestId: extra?.requestId,
         sendNotification: extra?.sendNotification,
@@ -89,4 +90,3 @@ export function tryReadToolStructuredError(value) {
         return undefined;
     }
 }
-//# sourceMappingURL=owner.js.map

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

@@ -0,0 +1,11 @@
+import type { ServerResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolHandlerExtra } from '../lib/mcp-tools.js';
+export interface TaskCapableToolDescriptor<TArgs = unknown> {
+    name: string;
+    parseArguments: (args: unknown) => TArgs;
+    execute: (args: TArgs, extra?: ToolHandlerExtra) => Promise<ServerResult>;
+}
+export declare function registerTaskCapableTool<TArgs>(descriptor: TaskCapableToolDescriptor<TArgs>): void;
+export declare function unregisterTaskCapableTool(name: string): void;
+export declare function getTaskCapableTool(name: string): TaskCapableToolDescriptor | undefined;
+export declare function hasTaskCapableTool(name: string): boolean;

package/dist/tasks/tool-registry.js

@@ -0,0 +1,13 @@
+const taskCapableTools = new Map();
+export function registerTaskCapableTool(descriptor) {
+    taskCapableTools.set(descriptor.name, descriptor);
+}
+export function unregisterTaskCapableTool(name) {
+    taskCapableTools.delete(name);
+}
+export function getTaskCapableTool(name) {
+    return taskCapableTools.get(name);
+}
+export function hasTaskCapableTool(name) {
+    return taskCapableTools.has(name);
+}

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

@@ -0,0 +1,28 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ContentBlock } from '@modelcontextprotocol/sdk/types.js';
+import { type ToolHandlerExtra } from '../lib/mcp-tools.js';
+interface FetchUrlInput {
+    url: string;
+    skipNoiseRemoval?: boolean | undefined;
+    forceRefresh?: boolean | undefined;
+    maxInlineChars?: number | undefined;
+}
+type ToolContentBlockUnion = ContentBlock;
+interface ToolResponseBase {
+    [key: string]: unknown;
+    content: ToolContentBlockUnion[];
+    structuredContent?: Record<string, unknown> | undefined;
+    isError?: boolean;
+}
+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;
+export {};