@j0hanz/fetch-url-mcp 0.0.1

package/dist/mcp.js

@@ -0,0 +1,421 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { CallToolRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { logWarn, runWithRequestContext } from './observability.js';
+import { taskManager } from './tasks.js';
+import { FETCH_URL_TOOL_NAME, fetchUrlInputSchema, fetchUrlToolHandler, } from './tools.js';
+import { isObject } from './type-guards.js';
+/* -------------------------------------------------------------------------------------------------
+ * Tasks API schemas
+ * ------------------------------------------------------------------------------------------------- */
+const TaskGetSchema = z.strictObject({
+    method: z.literal('tasks/get'),
+    params: z.strictObject({ taskId: z.string() }),
+});
+const TaskListSchema = z.strictObject({
+    method: z.literal('tasks/list'),
+    params: z
+        .strictObject({
+        cursor: z.string().optional(),
+    })
+        .optional(),
+});
+const TaskCancelSchema = z.strictObject({
+    method: z.literal('tasks/cancel'),
+    params: z.strictObject({ taskId: z.string() }),
+});
+const TaskResultSchema = z.strictObject({
+    method: z.literal('tasks/result'),
+    params: z.strictObject({ taskId: z.string() }),
+});
+const MIN_TASK_TTL_MS = 1_000;
+const MAX_TASK_TTL_MS = 86_400_000;
+const ExtendedCallToolRequestSchema = z
+    .object({
+    method: z.literal('tools/call'),
+    params: z
+        .object({
+        name: z.string().min(1),
+        arguments: z.record(z.string(), z.unknown()).optional(),
+        task: z
+            .strictObject({
+            ttl: z
+                .number()
+                .int()
+                .min(MIN_TASK_TTL_MS)
+                .max(MAX_TASK_TTL_MS)
+                .optional(),
+        })
+            .optional(),
+        _meta: z
+            .object({
+            progressToken: z.union([z.string(), z.number()]).optional(),
+            'io.modelcontextprotocol/related-task': z
+                .strictObject({
+                taskId: z.string(),
+            })
+                .optional(),
+        })
+            .loose()
+            .optional(),
+    })
+        .loose(),
+})
+    .loose();
+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 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) {
+    const parsed = fetchUrlInputSchema.safeParse(args);
+    if (!parsed.success) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid arguments for fetch-url');
+    }
+    return parsed.data;
+}
+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,
+            },
+        },
+    };
+}
+/**
+ * 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);
+}
+export function cancelTasksForOwner(ownerKey, statusMessage = 'The task was cancelled because its owner session ended.') {
+    if (!ownerKey)
+        return 0;
+    const cancelled = taskManager.cancelTasksByOwner(ownerKey, statusMessage);
+    for (const task of cancelled) {
+        abortTaskExecution(task.taskId);
+    }
+    return cancelled.length;
+}
+export function abortAllTaskExecutions() {
+    for (const taskId of taskAbortControllers.keys())
+        abortTaskExecution(taskId);
+}
+function buildTaskStatusParams(task) {
+    return {
+        taskId: task.taskId,
+        status: task.status,
+        ...(task.statusMessage ? { statusMessage: task.statusMessage } : {}),
+        createdAt: task.createdAt,
+        lastUpdatedAt: task.lastUpdatedAt,
+        ttl: task.ttl,
+        pollInterval: task.pollInterval,
+    };
+}
+function emitTaskStatusNotification(server, task) {
+    if (!server.isConnected())
+        return;
+    void server.server
+        .notification({
+        method: 'notifications/tasks/status',
+        params: buildTaskStatusParams(task),
+    })
+        .catch((error) => {
+        logWarn('Failed to send task status notification', {
+            taskId: task.taskId,
+            status: task.status,
+            error,
+        });
+    });
+}
+function updateWorkingTaskStatus(server, taskId, statusMessage) {
+    const current = taskManager.getTask(taskId);
+    if (current?.status !== 'working')
+        return;
+    if (current.statusMessage === statusMessage)
+        return;
+    taskManager.updateTask(taskId, { statusMessage });
+    const updated = taskManager.getTask(taskId);
+    if (updated)
+        emitTaskStatusNotification(server, updated);
+}
+async function runFetchTaskExecution(params) {
+    const { server, taskId, args, meta, sendNotification } = params;
+    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 } : {}),
+                onProgress: (_progress, message) => {
+                    updateWorkingTaskStatus(server, taskId, message);
+                },
+            });
+            const isToolError = isRecord(result) &&
+                typeof result.isError === 'boolean' &&
+                result.isError;
+            taskManager.updateTask(taskId, {
+                status: isToolError ? 'failed' : 'completed',
+                statusMessage: isToolError
+                    ? (result
+                        .structuredContent?.error ?? 'Tool execution failed')
+                    : 'Task completed successfully.',
+                result,
+            });
+            const task = taskManager.getTask(taskId);
+            if (task)
+                emitTaskStatusNotification(server, task);
+        }
+        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,
+            });
+            const task = taskManager.getTask(taskId);
+            if (task)
+                emitTaskStatusNotification(server, task);
+        }
+        finally {
+            clearTaskExecution(taskId);
+        }
+    });
+}
+function handleTaskToolCall(server, 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);
+    void runFetchTaskExecution({
+        server,
+        taskId: task.taskId,
+        args: validArgs,
+        ...(params._meta ? { meta: params._meta } : {}),
+        ...(context.sendNotification
+            ? { sendNotification: context.sendNotification }
+            : {}),
+    });
+    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);
+    const extra = {
+        ...(context.signal ? { signal: context.signal } : {}),
+        ...(context.requestId !== undefined
+            ? { requestId: context.requestId }
+            : {}),
+        ...(context.sendNotification
+            ? { sendNotification: context.sendNotification }
+            : {}),
+        ...(params._meta ? { _meta: params._meta } : {}),
+    };
+    return fetchUrlToolHandler(args, extra);
+}
+async function handleToolCallRequest(server, request, context) {
+    const { params } = request;
+    if (params.task) {
+        return handleTaskToolCall(server, params, context);
+    }
+    if (params.name === FETCH_URL_TOOL_NAME) {
+        return handleDirectToolCall(params, context);
+    }
+    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${params.name}`);
+}
+/* -------------------------------------------------------------------------------------------------
+ * Register handlers
+ * ------------------------------------------------------------------------------------------------- */
+export function registerTaskHandlers(server) {
+    server.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const context = resolveToolCallContext(extra);
+        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(server, 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)
+            throwTaskNotFound();
+        return Promise.resolve({
+            taskId: task.taskId,
+            status: task.status,
+            statusMessage: task.statusMessage,
+            createdAt: task.createdAt,
+            lastUpdatedAt: task.lastUpdatedAt,
+            ttl: task.ttl,
+            pollInterval: task.pollInterval,
+        });
+    });
+    server.server.setRequestHandler(TaskResultSchema, async (request, extra) => {
+        const { taskId } = request.params;
+        const ownerKey = resolveTaskOwnerKey(extra);
+        const task = await taskManager.waitForTerminalTask(taskId, ownerKey, extra?.signal);
+        if (!task)
+            throwTaskNotFound();
+        if (task.status === 'failed') {
+            if (task.error) {
+                throw new McpError(task.error.code, task.error.message, task.error.data);
+            }
+            const failedResult = (task.result ?? null);
+            const fallback = failedResult ?? {
+                content: [
+                    {
+                        type: 'text',
+                        text: task.statusMessage ?? 'Task execution failed',
+                    },
+                ],
+                isError: true,
+            };
+            return Promise.resolve({
+                ...fallback,
+                _meta: {
+                    ...fallback._meta,
+                    'io.modelcontextprotocol/related-task': { taskId: task.taskId },
+                },
+            });
+        }
+        if (task.status === 'cancelled') {
+            throw new McpError(ErrorCode.InvalidRequest, 'Task was cancelled');
+        }
+        const result = (task.result ?? { content: [] });
+        return Promise.resolve({
+            ...result,
+            _meta: {
+                ...result._meta,
+                'io.modelcontextprotocol/related-task': { taskId: task.taskId },
+            },
+        });
+    });
+    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,
+                status: t.status,
+                createdAt: t.createdAt,
+                lastUpdatedAt: t.lastUpdatedAt,
+                ttl: t.ttl,
+                pollInterval: t.pollInterval,
+            })),
+            nextCursor,
+        });
+    });
+    server.server.setRequestHandler(TaskCancelSchema, async (request, extra) => {
+        const { taskId } = request.params;
+        const ownerKey = resolveTaskOwnerKey(extra);
+        const task = taskManager.cancelTask(taskId, ownerKey);
+        if (!task)
+            throwTaskNotFound();
+        // Make cancellation actionable: abort any in-flight execution.
+        abortTaskExecution(taskId);
+        emitTaskStatusNotification(server, task);
+        return Promise.resolve({
+            taskId: task.taskId,
+            status: task.status,
+            statusMessage: task.statusMessage,
+            createdAt: task.createdAt,
+            lastUpdatedAt: task.lastUpdatedAt,
+            ttl: task.ttl,
+            pollInterval: task.pollInterval,
+        });
+    });
+}

package/dist/observability.d.ts

@@ -0,0 +1,21 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export type LogMetadata = Record<string, unknown>;
+interface RequestContext {
+    readonly requestId: string;
+    readonly sessionId?: string;
+    readonly operationId?: string;
+}
+export declare function setMcpServer(server: McpServer): void;
+export declare function registerMcpSessionServer(sessionId: string, server: McpServer): void;
+export declare function unregisterMcpSessionServer(sessionId: string): void;
+export declare function unregisterMcpSessionServerByServer(server: McpServer): void;
+export declare function resolveMcpSessionIdByServer(server: McpServer): string | undefined;
+export declare function runWithRequestContext<T>(context: RequestContext, fn: () => T): T;
+export declare function getRequestId(): string | undefined;
+export declare function getOperationId(): string | undefined;
+export declare function logInfo(message: string, meta?: LogMetadata): void;
+export declare function logDebug(message: string, meta?: LogMetadata): void;
+export declare function logWarn(message: string, meta?: LogMetadata): void;
+export declare function logError(message: string, error?: Error | LogMetadata): void;
+export declare function redactUrl(rawUrl: string): string;
+export {};

package/dist/observability.js

@@ -0,0 +1,211 @@
+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({
+    name: 'requestContext',
+});
+let mcpServer;
+const sessionServers = new Map();
+let stderrAvailable = true;
+process.stderr.on('error', () => {
+    stderrAvailable = false;
+});
+export function setMcpServer(server) {
+    mcpServer = server;
+}
+export function registerMcpSessionServer(sessionId, server) {
+    if (!sessionId)
+        return;
+    sessionServers.set(sessionId, server);
+}
+export function unregisterMcpSessionServer(sessionId) {
+    if (!sessionId)
+        return;
+    sessionServers.delete(sessionId);
+}
+export function unregisterMcpSessionServerByServer(server) {
+    for (const [sessionId, mappedServer] of sessionServers.entries()) {
+        if (mappedServer !== server)
+            continue;
+        sessionServers.delete(sessionId);
+    }
+}
+export function resolveMcpSessionIdByServer(server) {
+    for (const [sessionId, mappedServer] of sessionServers.entries()) {
+        if (mappedServer === server)
+            return sessionId;
+    }
+    return undefined;
+}
+export function runWithRequestContext(context, fn) {
+    return requestContext.run(context, fn);
+}
+function getRequestContext() {
+    return requestContext.getStore();
+}
+export function getRequestId() {
+    return getRequestContext()?.requestId;
+}
+function getSessionId() {
+    return getRequestContext()?.sessionId;
+}
+export function getOperationId() {
+    return getRequestContext()?.operationId;
+}
+function isDebugEnabled() {
+    return config.logging.level === 'debug';
+}
+function buildContextMetadata() {
+    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)
+        meta.requestId = requestId;
+    if (operationId)
+        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 = mergeMetadata(meta);
+    if (!merged)
+        return '';
+    return ` ${inspect(merged, { breakLength: Infinity, colors: false, compact: true, sorted: true })}`;
+}
+function createTimestamp() {
+    return new Date().toISOString();
+}
+function formatLogEntry(level, message, meta) {
+    if (config.logging.format === 'json') {
+        const merged = mergeMetadata(meta);
+        const entry = {
+            timestamp: createTimestamp(),
+            level: level.toUpperCase(),
+            message,
+        };
+        if (merged) {
+            Object.assign(entry, merged);
+        }
+        return JSON.stringify(entry);
+    }
+    return `[${createTimestamp()}] ${level.toUpperCase()}: ${message}${formatMetadata(meta)}`;
+}
+function shouldLog(level) {
+    // Debug logs only when LOG_LEVEL=debug
+    if (level === 'debug')
+        return isDebugEnabled();
+    // All other levels always log
+    return true;
+}
+function mapToMcpLevel(level) {
+    switch (level) {
+        case 'warn':
+            return 'warning';
+        case 'error':
+            return 'error';
+        case 'debug':
+            return 'debug';
+        case 'info':
+        default:
+            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;
+    const line = formatLogEntry(level, message, meta);
+    safeWriteStderr(`${stripVTControlCharacters(line)}\n`);
+    const sessionId = getSessionId();
+    const server = sessionId
+        ? (sessionServers.get(sessionId) ?? mcpServer)
+        : mcpServer;
+    if (!server)
+        return;
+    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((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) {
+    writeLog('info', message, meta);
+}
+export function logDebug(message, meta) {
+    writeLog('debug', message, meta);
+}
+export function logWarn(message, meta) {
+    writeLog('warn', message, meta);
+}
+export function logError(message, error) {
+    const errorMeta = error instanceof Error
+        ? { error: error.message, stack: error.stack }
+        : (error ?? {});
+    writeLog('error', message, errorMeta);
+}
+export function redactUrl(rawUrl) {
+    try {
+        const url = new URL(rawUrl);
+        url.username = '';
+        url.password = '';
+        url.hash = '';
+        url.search = '';
+        return url.toString();
+    }
+    catch {
+        return rawUrl;
+    }
+}

package/dist/prompts.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+interface IconInfo {
+    src: string;
+    mimeType: string;
+}
+export declare function registerGetHelpPrompt(server: McpServer, instructions: string, iconInfo?: IconInfo): void;
+export {};

package/dist/prompts.js

@@ -0,0 +1,28 @@
+export function registerGetHelpPrompt(server, instructions, iconInfo) {
+    const description = 'Return the Fetch URL usage instructions.';
+    server.registerPrompt('get-help', {
+        title: 'Get Help',
+        description,
+        ...(iconInfo
+            ? {
+                icons: [
+                    {
+                        src: iconInfo.src,
+                        mimeType: iconInfo.mimeType,
+                    },
+                ],
+            }
+            : {}),
+    }, () => ({
+        description,
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: instructions,
+                },
+            },
+        ],
+    }));
+}

package/dist/resources.d.ts

@@ -0,0 +1,8 @@
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+interface IconInfo {
+    src: string;
+    mimeType: string;
+}
+export declare function registerInstructionResource(server: McpServer, instructions: string, iconInfo?: IconInfo): void;
+export declare function registerCacheResourceTemplate(server: McpServer, iconInfo?: IconInfo): void;
+export {};