@j0hanz/fetch-url-mcp 1.3.1 → 1.5.0

package/dist/schemas/outputs.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export declare const fetchUrlOutputSchema: z.ZodObject<{
+    url: z.ZodString;
+    inputUrl: z.ZodOptional<z.ZodString>;
+    resolvedUrl: z.ZodOptional<z.ZodString>;
+    finalUrl: z.ZodOptional<z.ZodString>;
+    cacheResourceUri: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        favicon: z.ZodOptional<z.ZodString>;
+        publishedAt: z.ZodOptional<z.ZodString>;
+        modifiedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    markdown: z.ZodOptional<z.ZodString>;
+    fromCache: z.ZodOptional<z.ZodBoolean>;
+    fetchedAt: z.ZodOptional<z.ZodString>;
+    contentSize: z.ZodOptional<z.ZodNumber>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;

package/dist/schemas/outputs.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { config } from '../lib/core.js';
+export const fetchUrlOutputSchema = z.strictObject({
+    url: z
+        .string()
+        .min(1)
+        .max(config.constants.maxUrlLength)
+        .describe('Fetched URL.'),
+    inputUrl: z
+        .string()
+        .max(config.constants.maxUrlLength)
+        .optional()
+        .describe('Original requested URL.'),
+    resolvedUrl: z
+        .string()
+        .max(config.constants.maxUrlLength)
+        .optional()
+        .describe('Final URL after raw-content transformations.'),
+    finalUrl: z
+        .string()
+        .max(config.constants.maxUrlLength)
+        .optional()
+        .describe('Final URL after HTTP redirects.'),
+    cacheResourceUri: z
+        .string()
+        .max(config.constants.maxUrlLength)
+        .optional()
+        .describe('URI for resources/read to get full markdown.'),
+    title: z.string().max(512).optional().describe('Page title.'),
+    metadata: z
+        .strictObject({
+        title: z.string().max(512).optional().describe('Detected page title.'),
+        description: z
+            .string()
+            .max(2048)
+            .optional()
+            .describe('Detected page description.'),
+        author: z.string().max(512).optional().describe('Detected page author.'),
+        image: z
+            .string()
+            .max(config.constants.maxUrlLength)
+            .optional()
+            .describe('Detected page preview image URL.'),
+        favicon: z
+            .string()
+            .max(config.constants.maxUrlLength)
+            .optional()
+            .describe('Detected page favicon URL.'),
+        publishedAt: z
+            .string()
+            .max(64)
+            .optional()
+            .describe('Detected publication date.'),
+        modifiedAt: z
+            .string()
+            .max(64)
+            .optional()
+            .describe('Detected last modified date.'),
+    })
+        .optional()
+        .describe('Extracted page metadata.'),
+    markdown: (config.constants.maxInlineContentChars > 0
+        ? z.string().max(config.constants.maxInlineContentChars)
+        : z.string())
+        .optional()
+        .describe('Extracted Markdown. May be truncated (check truncated field).'),
+    fromCache: z.boolean().optional().describe('True if served from cache.'),
+    fetchedAt: z.string().max(64).optional().describe('ISO timestamp of fetch.'),
+    contentSize: z
+        .number()
+        .int()
+        .min(0)
+        .max(config.constants.maxHtmlSize * 4)
+        .optional()
+        .describe('Full markdown size before truncation.'),
+    truncated: z.boolean().optional().describe('True if markdown was truncated.'),
+});

package/dist/server.d.ts

@@ -2,4 +2,3 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function createMcpServer(): Promise<McpServer>;
 export declare function createMcpServerForHttpSession(): Promise<McpServer>;
 export declare function startStdioServer(): Promise<void>;
-//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -1,15 +1,16 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import * as fs from 'node:fs/promises';
 import process from 'node:process';
-import { z } from 'zod';
-import { config } from './config.js';
-import { buildServerInstructions } from './instructions.js';
-import { abortAllTaskExecutions, registerTaskHandlers } from './mcp.js';
-import { logError, logInfo, setLogLevel, setMcpServer, } from './observability.js';
-import { registerGetHelpPrompt } from './prompts.js';
-import { registerCacheResourceTemplate, registerInstructionResource, } from './resources.js';
-import { registerTools } from './tools.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { SetLevelRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { config } from './lib/core.js';
+import { logError, logInfo, setLogLevel, setMcpServer } from './lib/core.js';
+import { abortAllTaskExecutions, registerTaskHandlers, } from './lib/mcp-tools.js';
+import { toError } from './lib/utils.js';
+import { registerGetHelpPrompt } from './prompts/index.js';
+import { registerCacheResourceTemplate, registerInstructionResource, } from './resources/index.js';
+import { buildServerInstructions } from './resources/instructions.js';
+import { registerAllTools } from './tools/index.js';
 import { shutdownTransformWorkerPool } from './transform/transform.js';
 async function getLocalIconInfo() {
     const name = 'logo.svg';
@@ -64,6 +65,10 @@ function createServerInfo(icons) {
 export async function createMcpServer() {
     return createMcpServerWithOptions({ registerObservabilityServer: true });
 }
+const SHUTDOWN_SIGNALS = ['SIGINT', 'SIGTERM'];
+function shouldRegisterObservabilityServer(options) {
+    return options?.registerObservabilityServer ?? true;
+}
 async function createMcpServerWithOptions(options) {
     const localIcon = await getLocalIconInfo();
     const serverConfig = {
@@ -74,13 +79,16 @@ async function createMcpServerWithOptions(options) {
     }
     const serverInfo = createServerInfo(localIcon ? [localIcon] : undefined);
     const server = new McpServer(serverInfo, serverConfig);
-    if (options?.registerObservabilityServer ?? true) {
+    if (shouldRegisterObservabilityServer(options)) {
         setMcpServer(server);
     }
-    registerTools(server);
+    registerAllTools(server);
     registerGetHelpPrompt(server, serverInstructions, localIcon);
     registerInstructionResource(server, serverInstructions, localIcon);
     registerCacheResourceTemplate(server, localIcon);
+    // NOTE: Internally patches server.close and server.server.onclose for cleanup
+    // callbacks, and intercepts tools/call via Reflect.get on private SDK state.
+    // See src/lib/task-handlers.ts for risk documentation (S-2, S-3).
     registerTaskHandlers(server);
     registerLoggingSetLevelHandler(server);
     attachServerErrorHandler(server);
@@ -90,20 +98,14 @@ export async function createMcpServerForHttpSession() {
     return createMcpServerWithOptions({ registerObservabilityServer: false });
 }
 function registerLoggingSetLevelHandler(server) {
-    const SetLevelRequestSchema = z
-        .object({
-        method: z.literal('logging/setLevel'),
-        params: z.object({ level: z.string() }).loose(),
-    })
-        .loose();
-    server.server.setRequestHandler(SetLevelRequestSchema, async (request) => {
+    server.server.setRequestHandler(SetLevelRequestSchema, (request) => {
         setLogLevel(request.params.level);
-        return Promise.resolve({});
+        return {};
     });
 }
 function attachServerErrorHandler(server) {
     server.server.onerror = (error) => {
-        logError('[MCP Error]', error instanceof Error ? error : { error });
+        logError('[MCP Error]', toError(error));
     };
 }
 async function shutdownServer(server, signal) {
@@ -129,7 +131,7 @@ function createShutdownHandler(server) {
         Promise.resolve()
             .then(() => shutdownServer(server, signal))
             .catch((err) => {
-            const error = err instanceof Error ? err : new Error(String(err));
+            const error = toError(err);
             logError('Error during shutdown', error);
             process.exitCode = 1;
         })
@@ -140,7 +142,7 @@ function createShutdownHandler(server) {
     };
 }
 function registerSignalHandlers(handler) {
-    for (const signal of ['SIGINT', 'SIGTERM']) {
+    for (const signal of SHUTDOWN_SIGNALS) {
         process.once(signal, () => {
             handler(signal);
         });
@@ -152,7 +154,7 @@ async function connectStdioServer(server, transport) {
         logInfo('Fetch URL MCP server running on stdio');
     }
     catch (error) {
-        const err = error instanceof Error ? error : new Error(String(error));
+        const err = toError(error);
         throw new Error(`Failed to start stdio server: ${err.message}`, {
             cause: error,
         });
@@ -164,4 +166,3 @@ export async function startStdioServer() {
     registerSignalHandlers(createShutdownHandler(server));
     await connectStdioServer(server, transport);
 }
-//# sourceMappingURL=server.js.map

package/dist/tasks/execution.d.ts

@@ -39,4 +39,3 @@ export declare function emitTaskStatusNotification(server: McpServer, task: Task
 export declare function throwTaskNotFound(): never;
 export declare function handleToolCallRequest(server: McpServer, request: ExtendedCallToolRequest, context: ToolCallContext): Promise<ServerResult>;
 export {};
-//# sourceMappingURL=execution.d.ts.map

package/dist/tasks/execution.js

@@ -1,19 +1,25 @@
 import { ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
-import { logWarn, runWithRequestContext } from '../observability.js';
-import { FETCH_URL_TOOL_NAME, fetchUrlInputSchema, fetchUrlToolHandler, } from '../tools.js';
-import { isObject } from '../type-guards.js';
+import { config } from '../lib/core.js';
+import { logWarn, runWithRequestContext } from '../lib/core.js';
+import { getErrorMessage, RESOURCE_NOT_FOUND_ERROR_CODE, } from '../lib/utils.js';
+import { isObject } from '../lib/utils.js';
 import { taskManager, } from './manager.js';
 import { compact, tryReadToolStructuredError, } from './owner.js';
+import { getTaskCapableTool, hasTaskCapableTool, } from './tool-registry.js';
 /* -------------------------------------------------------------------------------------------------
  * Abort-controller management for in-flight task executions
  * ------------------------------------------------------------------------------------------------- */
 // Intentionally process-global (not session-scoped): abortAllTaskExecutions() is called
 // during SIGTERM/SIGINT shutdown to cancel every in-flight task across all sessions.
-// TODO: consider per-session isolation if stricter task-ownership semantics are needed.
+// Keep this process-global so shutdown can cancel all in-flight tasks across sessions.
+// Per-session isolation would require a different cancellation fan-out strategy.
 const taskAbortControllers = new Map();
 function attachAbortController(taskId) {
     const existing = taskAbortControllers.get(taskId);
     if (existing) {
+        // Abort the previous controller before replacing it — avoids stranding
+        // a running fetch that can no longer be cancelled via abortTaskExecution().
+        existing.abort();
         taskAbortControllers.delete(taskId);
     }
     const controller = new AbortController();
@@ -72,43 +78,56 @@ export function withRelatedTaskMeta(result, taskId) {
     };
 }
 export function emitTaskStatusNotification(server, task) {
+    if (!config.tasks.emitStatusNotifications)
+        return;
     if (!server.isConnected())
         return;
-    // NOTE: 'notifications/tasks/status' is not part of the MCP v2025-11-25 specification.
-    // This relies on the experimental task infrastructure in the SDK and may change.
+    // NOTE: 'notifications/tasks/status' is a non-spec extension (not in MCP v2025-11-25).
+    // Gated by config.tasks.emitStatusNotifications (TASKS_STATUS_NOTIFICATIONS env var).
+    // Clients should NOT depend on this for interoperability — behavior may change.
     void server.server
         .notification({
         method: 'notifications/tasks/status',
-        params: toTaskSummary(task),
+        params: buildTaskStatusNotificationParams(task),
     })
         .catch((error) => {
         logWarn('Failed to send task status notification', {
             taskId: task.taskId,
             status: task.status,
-            error,
+            error: getErrorMessage(error),
         });
     });
 }
+function buildTaskStatusNotificationParams(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,
+    };
+}
 /* -------------------------------------------------------------------------------------------------
  * Validation helpers
  * ------------------------------------------------------------------------------------------------- */
-function requireFetchUrlArgs(args) {
-    const parsed = fetchUrlInputSchema.safeParse(args);
-    if (!parsed.success) {
-        throw new McpError(ErrorCode.InvalidParams, 'Invalid arguments for fetch-url');
-    }
-    return parsed.data;
-}
-// -32002 is the MCP extension code for resource-not-found; the SDK ErrorCode enum does not export it.
-const RESOURCE_NOT_FOUND_ERROR_CODE = -32002;
 export function throwTaskNotFound() {
     throw new McpError(RESOURCE_NOT_FOUND_ERROR_CODE, 'Task not found');
 }
-function requireFetchUrlToolName(name) {
-    if (name === FETCH_URL_TOOL_NAME)
-        return;
+function resolveTaskCapableTool(name) {
+    const descriptor = getTaskCapableTool(name);
+    if (descriptor)
+        return descriptor;
     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: '${name}'`);
 }
+// Validates that the tool name is recognized before we attempt to execute it.
+// This ensures that an unknown tool produces a MethodNotFound error, rather than potentially executing and failing with an internal error if the tool handler does not properly validate its input.
+function assertKnownTool(name) {
+    if (!hasTaskCapableTool(name)) {
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: '${name}'`);
+    }
+}
 /* -------------------------------------------------------------------------------------------------
  * Task result builders
  * ------------------------------------------------------------------------------------------------- */
@@ -143,18 +162,60 @@ function updateWorkingTaskStatus(server, taskId, statusMessage) {
         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 () => {
+    updateTaskAndEmitStatus(server, taskId, { statusMessage });
+}
+function updateTaskAndEmitStatus(server, taskId, update) {
+    taskManager.updateTask(taskId, update);
+    const task = taskManager.getTask(taskId);
+    if (task)
+        emitTaskStatusNotification(server, task);
+}
+function buildTaskFailureState(error) {
+    const statusMessage = getErrorMessage(error);
+    if (error instanceof McpError) {
+        return {
+            statusMessage,
+            error: {
+                code: error.code,
+                message: statusMessage,
+                data: error.data,
+            },
+        };
+    }
+    return {
+        statusMessage,
+        error: {
+            code: ErrorCode.InternalError,
+            message: statusMessage,
+        },
+    };
+}
+function resolveToolAndArgs(params) {
+    const tool = resolveTaskCapableTool(params.name);
+    const args = tool.parseArguments(params.arguments);
+    return { tool, args };
+}
+function buildTaskCompletionUpdate(result) {
+    const isToolError = isObject(result) && 'isError' in result && result.isError === true;
+    return {
+        status: isToolError ? 'failed' : 'completed',
+        statusMessage: isToolError
+            ? (tryReadToolStructuredError(result) ?? 'Tool execution failed')
+            : 'Task completed successfully.',
+        result,
+    };
+}
+async function runTaskToolExecution(params) {
+    const { server, taskId, args, tool, meta, sessionId, sendNotification } = params;
+    return runWithRequestContext({
+        requestId: taskId,
+        operationId: taskId,
+        ...(sessionId ? { sessionId } : {}),
+    }, async () => {
         const controller = attachAbortController(taskId);
         try {
             const relatedMeta = buildRelatedTaskMeta(taskId, meta);
-            const result = await fetchUrlToolHandler(args, {
+            const result = await tool.execute(args, {
                 signal: controller.signal,
                 requestId: taskId,
                 _meta: relatedMeta,
@@ -163,40 +224,15 @@ async function runFetchTaskExecution(params) {
                     updateWorkingTaskStatus(server, taskId, message);
                 },
             });
-            const isToolError = isObject(result) &&
-                typeof result['isError'] === 'boolean' &&
-                result['isError'];
-            taskManager.updateTask(taskId, {
-                status: isToolError ? 'failed' : 'completed',
-                statusMessage: isToolError
-                    ? (tryReadToolStructuredError(result) ?? 'Tool execution failed')
-                    : 'Task completed successfully.',
-                result,
-            });
-            const task = taskManager.getTask(taskId);
-            if (task)
-                emitTaskStatusNotification(server, task);
+            updateTaskAndEmitStatus(server, taskId, buildTaskCompletionUpdate(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, {
+            const failure = buildTaskFailureState(error);
+            updateTaskAndEmitStatus(server, taskId, {
                 status: 'failed',
-                statusMessage: errorMessage,
-                error: errorPayload,
+                statusMessage: failure.statusMessage,
+                error: failure.error,
             });
-            const task = taskManager.getTask(taskId);
-            if (task)
-                emitTaskStatusNotification(server, task);
         }
         finally {
             clearTaskExecution(taskId);
@@ -204,38 +240,38 @@ async function runFetchTaskExecution(params) {
     });
 }
 function handleTaskToolCall(server, params, context) {
-    requireFetchUrlToolName(params.name);
-    const validArgs = requireFetchUrlArgs(params.arguments);
+    const { tool, args } = resolveToolAndArgs(params);
     const task = taskManager.createTask(params.task?.ttl !== undefined ? { ttl: params.task.ttl } : undefined, 'Task started', context.ownerKey);
-    void runFetchTaskExecution({
+    void runTaskToolExecution({
         server,
         taskId: task.taskId,
-        args: validArgs,
+        args,
+        tool,
         ...compact({
             meta: params._meta,
+            sessionId: context.sessionId,
             sendNotification: context.sendNotification,
         }),
     });
     return buildCreateTaskResult(toTaskSummary(task));
 }
 async function handleDirectToolCall(params, context) {
-    const args = requireFetchUrlArgs(params.arguments);
+    const { tool, args } = resolveToolAndArgs(params);
     const extra = compact({
         signal: context.signal,
         requestId: context.requestId,
         sendNotification: context.sendNotification,
         _meta: params._meta,
     });
-    return fetchUrlToolHandler(args, extra);
+    return tool.execute(args, extra);
 }
 export async function handleToolCallRequest(server, request, context) {
     const { params } = request;
+    // Validate the tool name first so an unknown tool always produces MethodNotFound,
+    // regardless of whether a task:{} param was supplied (H-4).
+    assertKnownTool(params.name);
     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}`);
+    return handleDirectToolCall(params, context);
 }
-//# sourceMappingURL=execution.js.map

package/dist/tasks/manager.d.ts

@@ -40,15 +40,20 @@ declare class TaskManager {
     private tasks;
     private ownerCounts;
     private waiters;
-    constructor();
-    private startCleanupLoop;
+    private cleanupInterval;
+    private ensureCleanupLoop;
+    private stopCleanupLoop;
     private removeExpiredTasks;
     private removeTask;
+    private applyTaskUpdate;
+    private cancelActiveTask;
+    private releaseOwnerCount;
     private countTasksForOwner;
     private incrementOwnerCount;
     private decrementOwnerCount;
     private assertTaskCapacity;
     createTask(options?: CreateTaskOptions, statusMessage?: string, ownerKey?: string): TaskState;
+    private lookupActiveTask;
     getTask(taskId: string, ownerKey?: string): TaskState | undefined;
     updateTask(taskId: string, updates: Partial<Omit<TaskState, 'taskId' | 'createdAt'>>): void;
     cancelTask(taskId: string, ownerKey?: string): TaskState | undefined;
@@ -62,9 +67,13 @@ declare class TaskManager {
         tasks: TaskState[];
         nextCursor?: string;
     };
+    private resolveAnchorTaskId;
+    private addWaiter;
+    private removeWaiter;
     waitForTerminalTask(taskId: string, ownerKey: string, signal?: AbortSignal): Promise<TaskState | undefined>;
     private notifyWaiters;
     private isExpired;
+    private maybeUpdateLastUpdatedAt;
     shrinkTtlAfterDelivery(taskId: string): void;
     private encodeCursor;
     private decodeCursor;
@@ -72,4 +81,3 @@ declare class TaskManager {
 }
 export declare const taskManager: TaskManager;
 export {};
-//# sourceMappingURL=manager.d.ts.map