@j0hanz/superfetch 2.5.2 → 2.6.0

package/dist/mcp-validator.js

@@ -1,12 +1,14 @@
 import { z } from 'zod';
 // --- Validation ---
 const paramsSchema = z.looseObject({});
-const mcpRequestSchema = z.looseObject({
+const mcpRequestSchema = z
+    .object({
     jsonrpc: z.literal('2.0'),
     method: z.string().min(1),
     id: z.union([z.string(), z.number(), z.null()]).optional(),
     params: paramsSchema.optional(),
-});
+})
+    .strict();
 export function isJsonRpcBatchRequest(body) {
     return Array.isArray(body);
 }

package/dist/mcp.js

@@ -1,23 +1,31 @@
+import { randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
+import process from 'node:process';
 import { z } from 'zod';
 import { McpServer, ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { registerCachedContentResource } from './cache.js';
 import { config } from './config.js';
-import { logError, logInfo, setMcpServer } from './observability.js';
+import { logError, logInfo, runWithRequestContext, setMcpServer, } from './observability.js';
 import { registerConfigResource } from './resources.js';
 import { taskManager } from './tasks.js';
-import { FETCH_URL_TOOL_NAME, fetchUrlToolHandler, registerTools, } from './tools.js';
+import { FETCH_URL_TOOL_NAME, fetchUrlInputSchema, fetchUrlToolHandler, registerTools, } from './tools.js';
 import { shutdownTransformWorkerPool } from './transform.js';
 import { isObject } from './type-guards.js';
-async function getLocalIcons() {
+/* -------------------------------------------------------------------------------------------------
+ * Icons + server info
+ * ------------------------------------------------------------------------------------------------- */
+async function getLocalIcons(signal) {
     try {
         const iconPath = new URL('../assets/logo.svg', import.meta.url);
-        const buffer = await readFile(iconPath);
+        const base64 = await readFile(iconPath, {
+            encoding: 'base64',
+            ...(signal ? { signal } : {}),
+        });
         return [
             {
-                src: `data:image/svg+xml;base64,${buffer.toString('base64')}`,
+                src: `data:image/svg+xml;base64,${base64}`,
                 mimeType: 'image/svg+xml',
                 sizes: ['any'],
             },
@@ -27,18 +35,10 @@ async function getLocalIcons() {
         return undefined;
     }
 }
-async function createServerInfo() {
-    const localIcons = await getLocalIcons();
-    return {
-        name: config.server.name,
-        version: config.server.version,
-        ...(localIcons ? { icons: localIcons } : {}),
-    };
-}
 function createServerCapabilities() {
     return {
         tools: { listChanged: false },
-        resources: { listChanged: false, subscribe: false },
+        resources: { listChanged: true, subscribe: true },
         logging: {},
         tasks: {
             list: {},
@@ -51,15 +51,25 @@ function createServerCapabilities() {
         },
     };
 }
-async function createServerInstructions(serverVersion) {
+async function createServerInstructions(serverVersion, signal) {
     try {
-        const raw = await readFile(new URL('./instructions.md', import.meta.url), 'utf8');
+        const raw = await readFile(new URL('./instructions.md', import.meta.url), {
+            encoding: 'utf8',
+            ...(signal ? { signal } : {}),
+        });
         return raw.replaceAll('{{SERVER_VERSION}}', serverVersion).trim();
     }
     catch {
         return `Instructions unavailable | ${serverVersion}`;
     }
 }
+function createServerInfo(icons) {
+    return {
+        name: config.server.name,
+        version: config.server.version,
+        ...(icons ? { icons } : {}),
+    };
+}
 function registerInstructionsResource(server, instructions) {
     server.registerResource('instructions', new ResourceTemplate('internal://instructions', { list: undefined }), {
         title: `SuperFetch MCP | ${config.server.version}`,
@@ -75,7 +85,9 @@ function registerInstructionsResource(server, instructions) {
         ],
     }));
 }
-// Schemas based on methods strings
+/* -------------------------------------------------------------------------------------------------
+ * Tasks API schemas
+ * ------------------------------------------------------------------------------------------------- */
 const TaskGetSchema = z.object({
     method: z.literal('tasks/get'),
     params: z.object({ taskId: z.string() }),
@@ -96,53 +108,37 @@ 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;
+const ExtendedCallToolRequestSchema = z.looseObject({
+    method: z.literal('tools/call'),
+    params: z.looseObject({
+        name: z.string().min(1),
+        arguments: z.record(z.string(), z.unknown()).optional(),
+        task: z
+            .object({
+            ttl: z.number().optional(),
+        })
+            .optional(),
+        _meta: z
+            .looseObject({
+            progressToken: z.union([z.string(), z.number()]).optional(),
+            'io.modelcontextprotocol/related-task': z
+                .object({
+                taskId: z.string(),
+            })
+                .optional(),
+        })
+            .optional(),
+    }),
+});
+function parseExtendedCallToolRequest(request) {
+    const parsed = ExtendedCallToolRequestSchema.safeParse(request);
+    if (parsed.success)
+        return parsed.data;
+    throw new McpError(ErrorCode.InvalidParams, 'Invalid tool request');
 }
 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}`;
@@ -165,10 +161,11 @@ function resolveToolCallContext(extra) {
     return context;
 }
 function requireFetchUrlArgs(args) {
-    if (!isObject(args) || typeof args.url !== 'string') {
+    const parsed = fetchUrlInputSchema.safeParse(args);
+    if (!parsed.success) {
         throw new McpError(ErrorCode.InvalidParams, 'Invalid arguments for fetch-url');
     }
-    return { url: args.url };
+    return parsed.data;
 }
 function throwTaskNotFound() {
     throw new McpError(ErrorCode.InvalidParams, 'Failed to retrieve task: Task not found');
@@ -200,63 +197,92 @@ function buildCreateTaskResult(task) {
         },
     };
 }
+/**
+ * Track in-flight task executions so `tasks/cancel` can actually abort work.
+ * This is intentionally local to this module (no new files, no global singletons elsewhere).
+ */
+const taskAbortControllers = new Map();
+function attachAbortController(taskId) {
+    const existing = taskAbortControllers.get(taskId);
+    if (existing) {
+        // Defensive: should not happen, but avoid leaking the old controller.
+        taskAbortControllers.delete(taskId);
+    }
+    const controller = new AbortController();
+    taskAbortControllers.set(taskId, controller);
+    return controller;
+}
+function abortTaskExecution(taskId) {
+    const controller = taskAbortControllers.get(taskId);
+    if (!controller)
+        return;
+    controller.abort();
+    taskAbortControllers.delete(taskId);
+}
+function clearTaskExecution(taskId) {
+    taskAbortControllers.delete(taskId);
+}
 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
+    return runWithRequestContext({ requestId: taskId, operationId: taskId }, async () => {
+        const controller = attachAbortController(taskId);
+        try {
+            const relatedMeta = buildRelatedTaskMeta(taskId, meta);
+            const result = await fetchUrlToolHandler(args, {
+                signal: controller.signal,
+                requestId: taskId, // Correlation
+                _meta: relatedMeta,
+                ...(sendNotification ? { sendNotification } : {}),
+            });
+            const isToolError = isRecord(result) &&
+                typeof result.isError === 'boolean' &&
+                result.isError;
+            taskManager.updateTask(taskId, {
+                status: isToolError ? 'failed' : 'completed',
+                ...(isToolError
+                    ? {
+                        statusMessage: result
+                            .structuredContent?.error ?? 'Tool execution failed',
+                    }
+                    : {}),
+                result,
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorPayload = error instanceof McpError
                 ? {
-                    statusMessage: result
-                        .structuredContent?.error ?? 'Tool execution failed',
+                    code: error.code,
+                    message: errorMessage,
+                    data: error.data,
                 }
-                : {}),
-            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,
-            }
-            : {
-                code: ErrorCode.InternalError,
-                message: errorMessage,
-            };
-        taskManager.updateTask(taskId, {
-            status: 'failed',
-            statusMessage: errorMessage,
-            error: errorPayload,
-        });
-    }
+                : {
+                    code: ErrorCode.InternalError,
+                    message: errorMessage,
+                };
+            taskManager.updateTask(taskId, {
+                status: 'failed',
+                statusMessage: errorMessage,
+                error: errorPayload,
+            });
+        }
+        finally {
+            clearTaskExecution(taskId);
+        }
+    });
 }
 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 = {
+    void runFetchTaskExecution({
         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,
@@ -269,9 +295,11 @@ function handleTaskToolCall(params, context) {
 }
 async function handleDirectToolCall(params, context) {
     const args = requireFetchUrlArgs(params.arguments);
-    return fetchUrlToolHandler({ url: args.url }, {
+    return fetchUrlToolHandler(args, {
         ...(context.signal ? { signal: context.signal } : {}),
-        ...(context.requestId ? { requestId: context.requestId } : {}),
+        ...(context.requestId !== undefined
+            ? { requestId: context.requestId }
+            : {}),
         ...(context.sendNotification
             ? { sendNotification: context.sendNotification }
             : {}),
@@ -288,22 +316,31 @@ async function handleToolCallRequest(request, context) {
     }
     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${params.name}`);
 }
+/* -------------------------------------------------------------------------------------------------
+ * Register handlers
+ * ------------------------------------------------------------------------------------------------- */
 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');
-        }
-        const result = await handleToolCallRequest(request, context);
-        return result;
+        const requestId = context.requestId !== undefined
+            ? String(context.requestId)
+            : randomUUID();
+        const sessionId = extra?.sessionId;
+        return runWithRequestContext({
+            requestId,
+            operationId: requestId,
+            ...(sessionId ? { sessionId } : {}),
+        }, () => {
+            const parsed = parseExtendedCallToolRequest(request);
+            return handleToolCallRequest(parsed, context);
+        });
     });
     server.server.setRequestHandler(TaskGetSchema, async (request, extra) => {
         const { taskId } = request.params;
         const ownerKey = resolveTaskOwnerKey(extra);
         const task = taskManager.getTask(taskId, ownerKey);
-        if (!task) {
+        if (!task)
             throwTaskNotFound();
-        }
         return Promise.resolve({
             taskId: task.taskId,
             status: task.status,
@@ -318,9 +355,8 @@ function registerTaskHandlers(server) {
         const { taskId } = request.params;
         const ownerKey = resolveTaskOwnerKey(extra);
         const task = await taskManager.waitForTerminalTask(taskId, ownerKey, extra?.signal);
-        if (!task) {
+        if (!task)
             throwTaskNotFound();
-        }
         if (task.status === 'failed') {
             if (task.error) {
                 throw new McpError(task.error.code, task.error.message, task.error.data);
@@ -375,9 +411,10 @@ function registerTaskHandlers(server) {
         const { taskId } = request.params;
         const ownerKey = resolveTaskOwnerKey(extra);
         const task = taskManager.cancelTask(taskId, ownerKey);
-        if (!task) {
+        if (!task)
             throwTaskNotFound();
-        }
+        // Make cancellation actionable: abort any in-flight execution.
+        abortTaskExecution(taskId);
         return Promise.resolve({
             taskId: task.taskId,
             status: task.status,
@@ -389,15 +426,21 @@ function registerTaskHandlers(server) {
         });
     });
 }
+/* -------------------------------------------------------------------------------------------------
+ * Server lifecycle
+ * ------------------------------------------------------------------------------------------------- */
 export async function createMcpServer() {
-    const instructions = await createServerInstructions(config.server.version);
-    const serverInfo = await createServerInfo();
+    const startupSignal = AbortSignal.timeout(5000);
+    const [instructions, localIcons] = await Promise.all([
+        createServerInstructions(config.server.version, startupSignal),
+        getLocalIcons(startupSignal),
+    ]);
+    const serverInfo = createServerInfo(localIcons);
     const server = new McpServer(serverInfo, {
         capabilities: createServerCapabilities(),
         instructions,
     });
     setMcpServer(server);
-    const localIcons = await getLocalIcons();
     registerTools(server);
     registerCachedContentResource(server, localIcons);
     registerInstructionsResource(server, instructions);
@@ -410,19 +453,13 @@ function attachServerErrorHandler(server) {
         logError('[MCP Error]', error instanceof Error ? error : { error });
     };
 }
-function handleShutdownSignal(server, signal) {
+async function shutdownServer(server, signal) {
     process.stderr.write(`\n${signal} received, shutting down superFetch MCP server...\n`);
-    Promise.resolve()
-        .then(async () => {
-        await shutdownTransformWorkerPool();
-        await server.close();
-    })
-        .catch((err) => {
-        logError('Error during shutdown', err instanceof Error ? err : undefined);
-    })
-        .finally(() => {
-        process.exit(0);
-    });
+    // Ensure any in-flight tool executions are aborted promptly.
+    for (const taskId of taskAbortControllers.keys())
+        abortTaskExecution(taskId);
+    await shutdownTransformWorkerPool();
+    await server.close();
 }
 function createShutdownHandler(server) {
     let shuttingDown = false;
@@ -437,7 +474,17 @@ function createShutdownHandler(server) {
         }
         shuttingDown = true;
         initialSignal = signal;
-        handleShutdownSignal(server, signal);
+        Promise.resolve()
+            .then(() => shutdownServer(server, signal))
+            .catch((err) => {
+            const error = err instanceof Error ? err : new Error(String(err));
+            logError('Error during shutdown', error);
+            process.exitCode = 1;
+        })
+            .finally(() => {
+            if (process.exitCode === undefined)
+                process.exitCode = 0;
+        });
     };
 }
 function registerSignalHandlers(handler) {
@@ -454,8 +501,10 @@ async function connectStdioServer(server, transport) {
         logInfo('superFetch MCP server running on stdio');
     }
     catch (error) {
-        logError('Failed to start stdio server', error instanceof Error ? error : undefined);
-        process.exit(1);
+        const err = error instanceof Error ? error : new Error(String(error));
+        throw new Error(`Failed to start stdio server: ${err.message}`, {
+            cause: err,
+        });
     }
 }
 export async function startStdioServer() {

package/dist/observability.js

@@ -1,38 +1,69 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
+import process from 'node:process';
+import { inspect, stripVTControlCharacters } from 'node:util';
 import { config } from './config.js';
-const requestContext = new AsyncLocalStorage();
+const requestContext = new AsyncLocalStorage({
+    name: 'requestContext',
+});
 let mcpServer;
+let stderrAvailable = true;
+process.stderr.on('error', () => {
+    stderrAvailable = false;
+});
 export function setMcpServer(server) {
     mcpServer = server;
 }
 export function runWithRequestContext(context, fn) {
     return requestContext.run(context, fn);
 }
+function getRequestContext() {
+    return requestContext.getStore();
+}
 export function getRequestId() {
-    return requestContext.getStore()?.requestId;
+    return getRequestContext()?.requestId;
 }
 function getSessionId() {
-    return requestContext.getStore()?.sessionId;
+    return getRequestContext()?.sessionId;
 }
 export function getOperationId() {
-    return requestContext.getStore()?.operationId;
+    return getRequestContext()?.operationId;
+}
+function isDebugEnabled() {
+    return config.logging.level === 'debug';
 }
 function buildContextMetadata() {
-    const requestId = getRequestId();
-    const sessionId = getSessionId();
-    const operationId = getOperationId();
-    const contextMeta = {};
+    const ctx = requestContext.getStore();
+    if (!ctx)
+        return undefined;
+    const { requestId, operationId, sessionId } = ctx;
+    const includeSession = sessionId && isDebugEnabled();
+    if (!requestId && !operationId && !includeSession)
+        return undefined;
+    const meta = {};
     if (requestId)
-        contextMeta.requestId = requestId;
-    if (sessionId && config.logging.level === 'debug')
-        contextMeta.sessionId = sessionId;
+        meta.requestId = requestId;
     if (operationId)
-        contextMeta.operationId = operationId;
-    return contextMeta;
+        meta.operationId = operationId;
+    if (includeSession)
+        meta.sessionId = sessionId;
+    return meta;
+}
+function mergeMetadata(meta) {
+    const contextMeta = buildContextMetadata();
+    const hasMeta = meta && Object.keys(meta).length > 0;
+    if (!contextMeta && !hasMeta)
+        return undefined;
+    if (!contextMeta)
+        return meta;
+    if (!hasMeta)
+        return contextMeta;
+    return { ...contextMeta, ...meta };
 }
 function formatMetadata(meta) {
-    const merged = { ...buildContextMetadata(), ...meta };
-    return Object.keys(merged).length > 0 ? ` ${JSON.stringify(merged)}` : '';
+    const merged = mergeMetadata(meta);
+    if (!merged)
+        return '';
+    return ` ${inspect(merged, { breakLength: Infinity, colors: false, compact: true, sorted: true })}`;
 }
 function createTimestamp() {
     return new Date().toISOString();
@@ -43,7 +74,7 @@ function formatLogEntry(level, message, meta) {
 function shouldLog(level) {
     // Debug logs only when LOG_LEVEL=debug
     if (level === 'debug')
-        return config.logging.level === 'debug';
+        return isDebugEnabled();
     // All other levels always log
     return true;
 }
@@ -60,18 +91,55 @@ function mapToMcpLevel(level) {
             return 'info';
     }
 }
+function safeWriteStderr(line) {
+    if (!stderrAvailable)
+        return;
+    if (process.stderr.destroyed || process.stderr.writableEnded) {
+        stderrAvailable = false;
+        return;
+    }
+    try {
+        process.stderr.write(line);
+    }
+    catch {
+        // Logging must never take down the process (e.g. EPIPE).
+        stderrAvailable = false;
+    }
+}
 function writeLog(level, message, meta) {
     if (!shouldLog(level))
         return;
-    process.stderr.write(`${formatLogEntry(level, message, meta)}\n`);
-    if (mcpServer) {
-        const sessionId = getSessionId();
-        mcpServer.server
+    const line = formatLogEntry(level, message, meta);
+    safeWriteStderr(`${stripVTControlCharacters(line)}\n`);
+    const server = mcpServer;
+    if (!server)
+        return;
+    const sessionId = getSessionId();
+    try {
+        server.server
             .sendLoggingMessage({
             level: mapToMcpLevel(level),
+            // Preserve existing behavior: MCP payload includes only message + provided meta (not ALS context meta).
             data: meta ? { message, ...meta } : message,
         }, sessionId)
-            .catch(() => { });
+            .catch((err) => {
+            if (!isDebugEnabled())
+                return;
+            let errorText = 'unknown error';
+            if (err instanceof Error) {
+                errorText = err.message;
+            }
+            else if (typeof err === 'string') {
+                errorText = err;
+            }
+            safeWriteStderr(`[${createTimestamp()}] WARN: Failed to forward log to MCP${sessionId ? ` (sessionId=${sessionId})` : ''}: ${errorText}\n`);
+        });
+    }
+    catch (err) {
+        if (!isDebugEnabled())
+            return;
+        const errorText = err instanceof Error ? err.message : 'unknown error';
+        safeWriteStderr(`[${createTimestamp()}] WARN: Failed to forward log to MCP (sync error): ${errorText}\n`);
     }
 }
 export function logInfo(message, meta) {