@j0hanz/superfetch 2.4.4 → 2.4.6

package/dist/mcp.js

@@ -1,8 +1,8 @@
-import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { z } from 'zod';
 import { McpServer, ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { registerCachedContentResource } from './cache.js';
 import { config } from './config.js';
 import { destroyAgents } from './fetch.js';
@@ -12,10 +12,10 @@ import { taskManager } from './tasks.js';
 import { FETCH_URL_TOOL_NAME, fetchUrlToolHandler, registerTools, } from './tools.js';
 import { shutdownTransformWorkerPool } from './transform.js';
 import { isObject } from './type-guards.js';
-function getLocalIcons() {
+async function getLocalIcons() {
     try {
         const iconPath = new URL('../assets/logo.svg', import.meta.url);
-        const buffer = readFileSync(iconPath);
+        const buffer = await readFile(iconPath);
         return [
             {
                 src: `data:image/svg+xml;base64,${buffer.toString('base64')}`,
@@ -28,8 +28,8 @@ function getLocalIcons() {
         return undefined;
     }
 }
-function createServerInfo() {
-    const localIcons = getLocalIcons();
+async function createServerInfo() {
+    const localIcons = await getLocalIcons();
     return {
         name: config.server.name,
         version: config.server.version,
@@ -40,6 +40,7 @@ function createServerCapabilities() {
     return {
         tools: { listChanged: true },
         resources: { listChanged: true, subscribe: true },
+        prompts: {},
         logging: {},
         tasks: {
             list: {},
@@ -52,9 +53,9 @@ function createServerCapabilities() {
         },
     };
 }
-function createServerInstructions(serverVersion) {
+async function createServerInstructions(serverVersion) {
     try {
-        const raw = readFileSync(new URL('./instructions.md', import.meta.url), 'utf8');
+        const raw = await readFile(new URL('./instructions.md', import.meta.url), 'utf8');
         return raw.replaceAll('{{SERVER_VERSION}}', serverVersion).trim();
     }
     catch {
@@ -77,83 +78,233 @@ function registerInstructionsResource(server, instructions) {
     }));
 }
 // Schemas based on methods strings
-const TaskGetSchema = z.object({ method: z.literal('tasks/get') });
-const TaskListSchema = z.object({ method: z.literal('tasks/list') });
-const TaskCancelSchema = z.object({ method: z.literal('tasks/cancel') });
-const TaskResultSchema = z.object({ method: z.literal('tasks/result') });
-function registerTaskHandlers(server) {
-    server.server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const extendedParams = request
-            .params;
-        const taskOptions = extendedParams.task;
-        if (taskOptions) {
-            // Validate tool support
-            if (extendedParams.name !== FETCH_URL_TOOL_NAME) {
-                throw new Error(`Tool '${extendedParams.name}' does not support task execution`);
-            }
-            // Create Task
-            const task = taskManager.createTask(taskOptions.ttl !== undefined ? { ttl: taskOptions.ttl } : undefined);
-            // Start Async Execution
-            void (async () => {
-                try {
-                    const args = extendedParams.arguments;
-                    if (!isObject(args) ||
-                        typeof args.url !== 'string') {
-                        throw new Error('Invalid arguments for fetch-url');
-                    }
-                    const validArgs = args;
-                    const controller = new AbortController();
-                    const result = await fetchUrlToolHandler(validArgs, {
-                        signal: controller.signal,
-                        requestId: task.taskId, // Correlation
-                        ...(extendedParams._meta ? { _meta: extendedParams._meta } : {}),
-                    });
-                    // Update Task on Success
-                    taskManager.updateTask(task.taskId, {
-                        status: 'completed',
-                        result,
-                    });
-                }
-                catch (error) {
-                    // Update Task on Failure
-                    taskManager.updateTask(task.taskId, {
-                        status: 'failed',
-                        statusMessage: error instanceof Error ? error.message : String(error),
-                        error: error instanceof Error ? error.message : String(error),
-                    });
+const TaskGetSchema = z.object({
+    method: z.literal('tasks/get'),
+    params: z.object({ taskId: z.string() }),
+});
+const TaskListSchema = z.object({
+    method: z.literal('tasks/list'),
+    params: z
+        .object({
+        cursor: z.string().optional(),
+    })
+        .optional(),
+});
+const TaskCancelSchema = z.object({
+    method: z.literal('tasks/cancel'),
+    params: z.object({ taskId: z.string() }),
+});
+const TaskResultSchema = z.object({
+    method: z.literal('tasks/result'),
+    params: z.object({ taskId: z.string() }),
+});
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isRecord(value) {
+    return isObject(value);
+}
+function isValidTask(task) {
+    if (task === undefined)
+        return true;
+    if (!isRecord(task))
+        return false;
+    const { ttl } = task;
+    return ttl === undefined || typeof ttl === 'number';
+}
+function isValidMeta(meta) {
+    if (meta === undefined)
+        return true;
+    if (!isRecord(meta))
+        return false;
+    const { progressToken } = meta;
+    if (progressToken !== undefined &&
+        typeof progressToken !== 'string' &&
+        typeof progressToken !== 'number') {
+        return false;
+    }
+    const related = meta['io.modelcontextprotocol/related-task'];
+    if (related === undefined)
+        return true;
+    if (!isRecord(related))
+        return false;
+    const { taskId } = related;
+    return typeof taskId === 'string';
+}
+function isExtendedCallToolRequest(request) {
+    if (!isRecord(request))
+        return false;
+    const { method, params } = request;
+    if (method !== 'tools/call')
+        return false;
+    if (!isRecord(params))
+        return false;
+    const { name, arguments: args, task, _meta, } = params;
+    return (isNonEmptyString(name) &&
+        (args === undefined || isRecord(args)) &&
+        isValidTask(task) &&
+        isValidMeta(_meta));
+}
+function resolveTaskOwnerKey(extra) {
+    if (extra?.sessionId)
+        return `session:${extra.sessionId}`;
+    if (extra?.authInfo?.clientId)
+        return `client:${extra.authInfo.clientId}`;
+    if (extra?.authInfo?.token)
+        return `token:${extra.authInfo.token}`;
+    return 'default';
+}
+function resolveToolCallContext(extra) {
+    const context = {
+        ownerKey: resolveTaskOwnerKey(extra),
+    };
+    if (extra?.signal)
+        context.signal = extra.signal;
+    if (extra?.requestId !== undefined)
+        context.requestId = extra.requestId;
+    if (extra?.sendNotification)
+        context.sendNotification = extra.sendNotification;
+    return context;
+}
+function requireFetchUrlArgs(args) {
+    if (!isObject(args) || typeof args.url !== 'string') {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid arguments for fetch-url');
+    }
+    return { url: args.url };
+}
+function throwTaskNotFound() {
+    throw new McpError(ErrorCode.InvalidParams, 'Failed to retrieve task: Task not found');
+}
+function requireFetchUrlToolName(name) {
+    if (name === FETCH_URL_TOOL_NAME)
+        return;
+    throw new McpError(ErrorCode.MethodNotFound, `Tool '${name}' does not support task execution`);
+}
+function buildRelatedTaskMeta(taskId, meta) {
+    return {
+        ...(meta ?? {}),
+        'io.modelcontextprotocol/related-task': { taskId },
+    };
+}
+function buildCreateTaskResult(task) {
+    return {
+        task,
+        _meta: {
+            'io.modelcontextprotocol/related-task': {
+                taskId: task.taskId,
+                status: task.status,
+                ...(task.statusMessage ? { statusMessage: task.statusMessage } : {}),
+                createdAt: task.createdAt,
+                lastUpdatedAt: task.lastUpdatedAt,
+                ttl: task.ttl,
+                pollInterval: task.pollInterval,
+            },
+        },
+    };
+}
+async function runFetchTaskExecution(params) {
+    const { taskId, args, meta, sendNotification } = params;
+    try {
+        const controller = new AbortController();
+        const relatedMeta = buildRelatedTaskMeta(taskId, meta);
+        const result = await fetchUrlToolHandler(args, {
+            signal: controller.signal,
+            requestId: taskId, // Correlation
+            _meta: relatedMeta,
+            ...(sendNotification ? { sendNotification } : {}),
+        });
+        const isToolError = typeof result.isError === 'boolean'
+            ? result.isError
+            : false;
+        taskManager.updateTask(taskId, {
+            status: isToolError ? 'failed' : 'completed',
+            ...(isToolError
+                ? {
+                    statusMessage: result
+                        .structuredContent?.error ?? 'Tool execution failed',
                 }
-            })();
-            // Return Immediate CreateTaskResult
-            const response = {
-                task: {
-                    taskId: task.taskId,
-                    status: task.status,
-                    ...(task.statusMessage ? { statusMessage: task.statusMessage } : {}),
-                    createdAt: task.createdAt,
-                    lastUpdatedAt: task.lastUpdatedAt,
-                    ttl: task.ttl,
-                    pollInterval: task.pollInterval,
-                },
-            };
-            return response;
-        }
-        if (extendedParams.name === FETCH_URL_TOOL_NAME) {
-            const args = extendedParams.arguments;
-            if (!isObject(args) ||
-                typeof args.url !== 'string') {
-                throw new Error('Invalid arguments for fetch-url');
+                : {}),
+            result,
+        });
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorPayload = error instanceof McpError
+            ? {
+                code: error.code,
+                message: errorMessage,
+                data: error.data,
             }
-            return fetchUrlToolHandler({ url: args.url }, {
-                ...(extendedParams._meta ? { _meta: extendedParams._meta } : {}),
-            });
+            : {
+                code: ErrorCode.InternalError,
+                message: errorMessage,
+            };
+        taskManager.updateTask(taskId, {
+            status: 'failed',
+            statusMessage: errorMessage,
+            error: errorPayload,
+        });
+    }
+}
+function handleTaskToolCall(params, context) {
+    requireFetchUrlToolName(params.name);
+    const validArgs = requireFetchUrlArgs(params.arguments);
+    const task = taskManager.createTask(params.task?.ttl !== undefined ? { ttl: params.task.ttl } : undefined, 'Task started', context.ownerKey);
+    const executionParams = {
+        taskId: task.taskId,
+        args: validArgs,
+        ...(params._meta ? { meta: params._meta } : {}),
+        ...(context.sendNotification
+            ? { sendNotification: context.sendNotification }
+            : {}),
+    };
+    void runFetchTaskExecution(executionParams);
+    return buildCreateTaskResult({
+        taskId: task.taskId,
+        status: task.status,
+        ...(task.statusMessage ? { statusMessage: task.statusMessage } : {}),
+        createdAt: task.createdAt,
+        lastUpdatedAt: task.lastUpdatedAt,
+        ttl: task.ttl,
+        pollInterval: task.pollInterval,
+    });
+}
+async function handleDirectToolCall(params, context) {
+    const args = requireFetchUrlArgs(params.arguments);
+    return fetchUrlToolHandler({ url: args.url }, {
+        ...(context.signal ? { signal: context.signal } : {}),
+        ...(context.requestId ? { requestId: context.requestId } : {}),
+        ...(context.sendNotification
+            ? { sendNotification: context.sendNotification }
+            : {}),
+        ...(params._meta ? { _meta: params._meta } : {}),
+    });
+}
+async function handleToolCallRequest(request, context) {
+    const { params } = request;
+    if (params.task) {
+        return handleTaskToolCall(params, context);
+    }
+    if (params.name === FETCH_URL_TOOL_NAME) {
+        return handleDirectToolCall(params, context);
+    }
+    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${params.name}`);
+}
+function registerTaskHandlers(server) {
+    server.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const context = resolveToolCallContext(extra);
+        if (!isExtendedCallToolRequest(request)) {
+            throw new McpError(ErrorCode.InvalidParams, 'Invalid tool request');
         }
-        throw new Error(`Tool not found: ${extendedParams.name}`);
+        const result = await handleToolCallRequest(request, context);
+        return result;
     });
-    server.server.setRequestHandler(TaskGetSchema, async (request) => {
+    server.server.setRequestHandler(TaskGetSchema, async (request, extra) => {
         const { taskId } = request.params;
-        const task = taskManager.getTask(taskId);
+        const ownerKey = resolveTaskOwnerKey(extra);
+        const task = taskManager.getTask(taskId, ownerKey);
         if (!task) {
-            throw new Error('Task not found');
+            throwTaskNotFound();
         }
         return Promise.resolve({
             taskId: task.taskId,
@@ -165,20 +316,37 @@ function registerTaskHandlers(server) {
             pollInterval: task.pollInterval,
         });
     });
-    server.server.setRequestHandler(TaskResultSchema, async (request) => {
+    server.server.setRequestHandler(TaskResultSchema, async (request, extra) => {
         const { taskId } = request.params;
-        const task = taskManager.getTask(taskId);
+        const ownerKey = resolveTaskOwnerKey(extra);
+        const task = await taskManager.waitForTerminalTask(taskId, ownerKey, extra?.signal);
         if (!task) {
-            throw new Error('Task not found');
-        }
-        if (task.status === 'working' || task.status === 'input_required') {
-            throw new Error('Task execution in progress');
+            throwTaskNotFound();
         }
         if (task.status === 'failed') {
-            return Promise.resolve(task.result ?? { isError: true, content: [] });
+            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 Promise.resolve({
+                ...fallback,
+                _meta: {
+                    ...fallback._meta,
+                    'io.modelcontextprotocol/related-task': { taskId: task.taskId },
+                },
+            });
         }
         if (task.status === 'cancelled') {
-            throw new Error('Task was cancelled');
+            throw new McpError(ErrorCode.InvalidRequest, 'Task was cancelled');
         }
         const result = (task.result ?? { content: [] });
         return Promise.resolve({
@@ -189,8 +357,10 @@ function registerTaskHandlers(server) {
             },
         });
     });
-    server.server.setRequestHandler(TaskListSchema, async () => {
-        const tasks = taskManager.listTasks();
+    server.server.setRequestHandler(TaskListSchema, async (request, extra) => {
+        const ownerKey = resolveTaskOwnerKey(extra);
+        const cursor = request.params?.cursor;
+        const { tasks, nextCursor } = taskManager.listTasks(cursor === undefined ? { ownerKey } : { ownerKey, cursor });
         return Promise.resolve({
             tasks: tasks.map((t) => ({
                 taskId: t.taskId,
@@ -200,14 +370,15 @@ function registerTaskHandlers(server) {
                 ttl: t.ttl,
                 pollInterval: t.pollInterval,
             })),
-            nextCursor: undefined,
+            nextCursor,
         });
     });
-    server.server.setRequestHandler(TaskCancelSchema, async (request) => {
+    server.server.setRequestHandler(TaskCancelSchema, async (request, extra) => {
         const { taskId } = request.params;
-        const task = taskManager.cancelTask(taskId);
+        const ownerKey = resolveTaskOwnerKey(extra);
+        const task = taskManager.cancelTask(taskId, ownerKey);
         if (!task) {
-            throw new Error('Task not found');
+            throwTaskNotFound();
         }
         return Promise.resolve({
             taskId: task.taskId,
@@ -220,19 +391,41 @@ function registerTaskHandlers(server) {
         });
     });
 }
-export function createMcpServer() {
-    const instructions = createServerInstructions(config.server.version);
-    const server = new McpServer(createServerInfo(), {
+function registerPrompts(server) {
+    if (config.tools.enabled.includes(FETCH_URL_TOOL_NAME)) {
+        server.registerPrompt('summarize-webpage', {
+            description: 'Summarize the content of a webpage given its URL.',
+            argsSchema: {
+                url: z.string().describe('The URL to summarize'),
+            },
+        }, (args) => ({
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `Please summarize the content of the webpage at the following URL: ${args.url}`,
+                    },
+                },
+            ],
+        }));
+    }
+}
+export async function createMcpServer() {
+    const instructions = await createServerInstructions(config.server.version);
+    const serverInfo = await createServerInfo();
+    const server = new McpServer(serverInfo, {
         capabilities: createServerCapabilities(),
         instructions,
     });
     setMcpServer(server);
-    const localIcons = getLocalIcons();
-    registerTools(server, localIcons);
+    const localIcons = await getLocalIcons();
+    registerTools(server);
     registerCachedContentResource(server, localIcons);
     registerInstructionsResource(server, instructions);
     registerConfigResource(server);
     registerTaskHandlers(server);
+    registerPrompts(server);
     return server;
 }
 function attachServerErrorHandler(server) {
@@ -290,7 +483,7 @@ async function connectStdioServer(server, transport) {
     }
 }
 export async function startStdioServer() {
-    const server = createMcpServer();
+    const server = await createMcpServer();
     const transport = new StdioServerTransport();
     attachServerErrorHandler(server);
     registerSignalHandlers(createShutdownHandler(server));

package/dist/observability.js

@@ -65,11 +65,12 @@ function writeLog(level, message, meta) {
         return;
     process.stderr.write(`${formatLogEntry(level, message, meta)}\n`);
     if (mcpServer) {
+        const sessionId = getSessionId();
         mcpServer.server
             .sendLoggingMessage({
             level: mapToMcpLevel(level),
             data: meta ? { message, ...meta } : message,
-        })
+        }, sessionId)
             .catch(() => { });
     }
 }

package/dist/tasks.d.ts

@@ -1,6 +1,12 @@
 export type TaskStatus = 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled';
+export interface TaskError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
 export interface TaskState {
     taskId: string;
+    ownerKey: string;
     status: TaskStatus;
     statusMessage?: string;
     createdAt: string;
@@ -8,7 +14,7 @@ export interface TaskState {
     ttl: number;
     pollInterval: number;
     result?: unknown;
-    error?: unknown;
+    error?: TaskError;
 }
 export interface CreateTaskOptions {
     ttl?: number;
@@ -27,11 +33,24 @@ export interface CreateTaskResult {
 }
 export declare class TaskManager {
     private tasks;
-    createTask(options?: CreateTaskOptions, statusMessage?: string): TaskState;
-    getTask(taskId: string): TaskState | undefined;
+    private waiters;
+    createTask(options?: CreateTaskOptions, statusMessage?: string, ownerKey?: string): TaskState;
+    getTask(taskId: string, ownerKey?: string): TaskState | undefined;
     updateTask(taskId: string, updates: Partial<Omit<TaskState, 'taskId' | 'createdAt'>>): void;
-    cancelTask(taskId: string): TaskState | undefined;
-    listTasks(): TaskState[];
+    cancelTask(taskId: string, ownerKey?: string): TaskState | undefined;
+    listTasks(options: {
+        ownerKey: string;
+        cursor?: string;
+        limit?: number;
+    }): {
+        tasks: TaskState[];
+        nextCursor?: string;
+    };
     cleanupExpiredTasks(): number;
+    waitForTerminalTask(taskId: string, ownerKey: string, signal?: AbortSignal): Promise<TaskState | undefined>;
+    private notifyWaiters;
+    private isExpired;
+    private encodeCursor;
+    private decodeCursor;
 }
 export declare const taskManager: TaskManager;