@j0hanz/fetch-url-mcp 1.4.0 → 1.5.0

package/dist/server.js

@@ -1,12 +1,12 @@
-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 './lib/config.js';
-import { toError } from './lib/errors.js';
-import { abortAllTaskExecutions, registerTaskHandlers } from './lib/mcp.js';
-import { logError, logInfo, setLogLevel, setMcpServer, } from './lib/observability.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';
@@ -65,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 = {
@@ -75,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);
     }
     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);
@@ -91,22 +98,6 @@ export async function createMcpServerForHttpSession() {
     return createMcpServerWithOptions({ registerObservabilityServer: false });
 }
 function registerLoggingSetLevelHandler(server) {
-    const LoggingLevelSchema = z.enum([
-        'debug',
-        'info',
-        'notice',
-        'warning',
-        'error',
-        'critical',
-        'alert',
-        'emergency',
-    ]);
-    const SetLevelRequestSchema = z
-        .object({
-        method: z.literal('logging/setLevel'),
-        params: z.object({ level: LoggingLevelSchema }).loose(),
-    })
-        .loose();
     server.server.setRequestHandler(SetLevelRequestSchema, (request) => {
         setLogLevel(request.params.level);
         return {};
@@ -151,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);
         });
@@ -175,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,8 +1,8 @@
 import { ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
-import { config } from '../lib/config.js';
-import { getErrorMessage, RESOURCE_NOT_FOUND_ERROR_CODE, } from '../lib/errors.js';
-import { logWarn, runWithRequestContext } from '../lib/observability.js';
-import { isObject } from '../lib/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';
@@ -82,8 +82,9 @@ export function emitTaskStatusNotification(server, task) {
         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',
@@ -161,10 +162,7 @@ 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);
+    updateTaskAndEmitStatus(server, taskId, { statusMessage });
 }
 function updateTaskAndEmitStatus(server, taskId, update) {
     taskManager.updateTask(taskId, update);
@@ -192,6 +190,21 @@ function buildTaskFailureState(error) {
         },
     };
 }
+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({
@@ -211,14 +224,7 @@ async function runTaskToolExecution(params) {
                     updateWorkingTaskStatus(server, taskId, message);
                 },
             });
-            const isToolError = isObject(result) && 'isError' in result && result.isError === true;
-            updateTaskAndEmitStatus(server, taskId, {
-                status: isToolError ? 'failed' : 'completed',
-                statusMessage: isToolError
-                    ? (tryReadToolStructuredError(result) ?? 'Tool execution failed')
-                    : 'Task completed successfully.',
-                result,
-            });
+            updateTaskAndEmitStatus(server, taskId, buildTaskCompletionUpdate(result));
         }
         catch (error) {
             const failure = buildTaskFailureState(error);
@@ -234,13 +240,12 @@ async function runTaskToolExecution(params) {
     });
 }
 function handleTaskToolCall(server, params, context) {
-    const tool = resolveTaskCapableTool(params.name);
-    const validArgs = tool.parseArguments(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 runTaskToolExecution({
         server,
         taskId: task.taskId,
-        args: validArgs,
+        args,
         tool,
         ...compact({
             meta: params._meta,
@@ -251,8 +256,7 @@ function handleTaskToolCall(server, params, context) {
     return buildCreateTaskResult(toTaskSummary(task));
 }
 async function handleDirectToolCall(params, context) {
-    const tool = resolveTaskCapableTool(params.name);
-    const args = tool.parseArguments(params.arguments);
+    const { tool, args } = resolveToolAndArgs(params);
     const extra = compact({
         signal: context.signal,
         requestId: context.requestId,
@@ -271,4 +275,3 @@ export async function handleToolCallRequest(server, request, context) {
     }
     return handleDirectToolCall(params, context);
 }
-//# sourceMappingURL=execution.js.map

package/dist/tasks/manager.d.ts

@@ -40,10 +40,13 @@ 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;
@@ -64,11 +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;
@@ -76,4 +81,3 @@ declare class TaskManager {
 }
 export declare const taskManager: TaskManager;
 export {};
-//# sourceMappingURL=manager.d.ts.map

package/dist/tasks/manager.js

@@ -1,11 +1,11 @@
-import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { Buffer } from 'node:buffer';
 import { randomUUID } from 'node:crypto';
 import { setInterval } from 'node:timers';
-import { config } from '../lib/config.js';
-import { toError } from '../lib/errors.js';
-import { createUnrefTimeout, } from '../lib/timer-utils.js';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { config } from '../lib/core.js';
+import { RESOURCE_NOT_FOUND_ERROR_CODE, toError } from '../lib/utils.js';
+import { createUnrefTimeout } from '../lib/utils.js';
 const DEFAULT_TTL_MS = 60_000;
 const MIN_TTL_MS = 1_000;
 const MAX_TTL_MS = 86_400_000;
@@ -32,14 +32,23 @@ class TaskManager {
     tasks = new Map();
     ownerCounts = new Map();
     waiters = new Map();
-    constructor() {
-        this.startCleanupLoop();
-    }
-    startCleanupLoop() {
-        const interval = setInterval(() => {
+    cleanupInterval = null;
+    ensureCleanupLoop() {
+        if (this.cleanupInterval)
+            return;
+        this.cleanupInterval = setInterval(() => {
             this.removeExpiredTasks();
+            if (this.tasks.size === 0) {
+                this.stopCleanupLoop();
+            }
         }, CLEANUP_INTERVAL_MS);
-        interval.unref();
+        this.cleanupInterval.unref();
+    }
+    stopCleanupLoop() {
+        if (!this.cleanupInterval)
+            return;
+        clearInterval(this.cleanupInterval);
+        this.cleanupInterval = null;
     }
     removeExpiredTasks() {
         const now = Date.now();
@@ -57,6 +66,18 @@ class TaskManager {
         this.releaseOwnerCount(task);
         return true;
     }
+    applyTaskUpdate(task, updates) {
+        Object.assign(task, updates);
+        task.lastUpdatedAt = new Date().toISOString();
+    }
+    cancelActiveTask(task, statusMessage) {
+        this.applyTaskUpdate(task, {
+            status: 'cancelled',
+            statusMessage,
+        });
+        this.notifyWaiters(task);
+        this.releaseOwnerCount(task);
+    }
     releaseOwnerCount(task) {
         const internal = task;
         if (internal._ownerCounted === false)
@@ -109,6 +130,7 @@ class TaskManager {
         };
         this.tasks.set(task.taskId, task);
         this.incrementOwnerCount(ownerKey);
+        this.ensureCleanupLoop();
         return task;
     }
     lookupActiveTask(taskId, ownerKey) {
@@ -132,22 +154,17 @@ class TaskManager {
             return;
         if (isTerminalStatus(task.status))
             return;
-        Object.assign(task, updates);
-        task.lastUpdatedAt = new Date().toISOString();
+        this.applyTaskUpdate(task, updates);
         this.notifyWaiters(task);
     }
     cancelTask(taskId, ownerKey) {
-        const task = this.getTask(taskId, ownerKey);
+        const task = this.lookupActiveTask(taskId, ownerKey);
         if (!task)
             return undefined;
         if (isTerminalStatus(task.status)) {
             throw new McpError(ErrorCode.InvalidParams, `Cannot cancel task: already in terminal status '${task.status}'`);
         }
-        this.updateTask(taskId, {
-            status: 'cancelled',
-            statusMessage: 'The task was cancelled by request.',
-        });
-        this.releaseOwnerCount(task);
+        this.cancelActiveTask(task, 'The task was cancelled by request.');
         return this.tasks.get(taskId);
     }
     cancelTasksByOwner(ownerKey, statusMessage = 'The task was cancelled because its owner is no longer active.') {
@@ -159,11 +176,7 @@ class TaskManager {
                 continue;
             if (isTerminalStatus(task.status))
                 continue;
-            this.updateTask(task.taskId, {
-                status: 'cancelled',
-                statusMessage,
-            });
-            this.releaseOwnerCount(task);
+            this.cancelActiveTask(task, statusMessage);
             cancelled.push(task);
         }
         return cancelled;
@@ -202,14 +215,7 @@ class TaskManager {
     listTasks(options) {
         const { ownerKey, cursor, limit } = options;
         const pageSize = limit && limit > 0 ? limit : DEFAULT_PAGE_SIZE;
-        let anchorTaskId = null;
-        if (cursor !== undefined) {
-            const decoded = this.decodeCursor(cursor);
-            if (decoded === null) {
-                throw new McpError(ErrorCode.InvalidParams, 'Invalid cursor');
-            }
-            ({ anchorTaskId } = decoded);
-        }
+        const anchorTaskId = this.resolveAnchorTaskId(cursor);
         const page = this.collectPage(ownerKey, anchorTaskId, pageSize);
         const hasMore = page.length > pageSize;
         if (hasMore) {
@@ -218,6 +224,15 @@ class TaskManager {
         const nextCursor = this.resolveNextCursor(page, hasMore);
         return nextCursor ? { tasks: page, nextCursor } : { tasks: page };
     }
+    resolveAnchorTaskId(cursor) {
+        if (cursor === undefined)
+            return null;
+        const decoded = this.decodeCursor(cursor);
+        if (decoded === null) {
+            throw new McpError(ErrorCode.InvalidParams, 'Invalid cursor');
+        }
+        return decoded.anchorTaskId;
+    }
     addWaiter(taskId, waiter) {
         let set = this.waiters.get(taskId);
         if (!set) {
@@ -305,7 +320,9 @@ class TaskManager {
                     cleanup();
                     this.removeWaiter(taskId, waiter);
                     this.removeTask(taskId);
-                    resolveInContext(undefined);
+                    rejectInContext(new McpError(RESOURCE_NOT_FOUND_ERROR_CODE, 'Task expired', {
+                        taskId,
+                    }));
                 });
             })
                 .catch(rejectInContext);
@@ -324,6 +341,9 @@ class TaskManager {
     isExpired(task, now = Date.now()) {
         return now - task._createdAtMs > task.ttl;
     }
+    maybeUpdateLastUpdatedAt(task) {
+        task.lastUpdatedAt = new Date().toISOString();
+    }
     shrinkTtlAfterDelivery(taskId) {
         const task = this.tasks.get(taskId);
         if (!task)
@@ -334,7 +354,7 @@ class TaskManager {
         const newTtl = elapsed + RESULT_DELIVERY_GRACE_MS;
         if (newTtl < task.ttl) {
             task.ttl = newTtl;
-            task.lastUpdatedAt = new Date().toISOString();
+            this.maybeUpdateLastUpdatedAt(task);
         }
     }
     encodeCursor(taskId) {
@@ -381,4 +401,3 @@ function isValidBase64UrlCursor(cursor) {
     return cursor.length % 4 !== 1;
 }
 export const taskManager = new TaskManager();
-//# sourceMappingURL=manager.js.map

package/dist/tasks/owner.d.ts

@@ -1,5 +1,5 @@
 import type { ServerResult } from '@modelcontextprotocol/sdk/types.js';
-import type { ProgressNotification } from '../lib/tool-progress.js';
+import type { ProgressNotification } from '../lib/mcp-tools.js';
 interface HandlerExtra {
     sessionId?: string;
     authInfo?: {
@@ -30,4 +30,3 @@ export declare function resolveToolCallContext(extra?: HandlerExtra): ToolCallCo
 export declare function isServerResult(value: unknown): value is ServerResult;
 export declare function tryReadToolStructuredError(value: unknown): string | undefined;
 export {};
-//# sourceMappingURL=owner.d.ts.map

package/dist/tasks/owner.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { isObject } from '../lib/type-guards.js';
+import { isObject } from '../lib/utils.js';
 export function compact(obj) {
     const result = {};
     for (const key of Object.keys(obj)) {
@@ -90,4 +90,3 @@ export function tryReadToolStructuredError(value) {
         return undefined;
     }
 }
-//# sourceMappingURL=owner.js.map

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

@@ -1,5 +1,5 @@
 import type { ServerResult } from '@modelcontextprotocol/sdk/types.js';
-import type { ToolHandlerExtra } from '../lib/tool-progress.js';
+import type { ToolHandlerExtra } from '../lib/mcp-tools.js';
 export interface TaskCapableToolDescriptor<TArgs = unknown> {
     name: string;
     parseArguments: (args: unknown) => TArgs;
@@ -9,4 +9,3 @@ export declare function registerTaskCapableTool<TArgs>(descriptor: TaskCapableTo
 export declare function unregisterTaskCapableTool(name: string): void;
 export declare function getTaskCapableTool(name: string): TaskCapableToolDescriptor | undefined;
 export declare function hasTaskCapableTool(name: string): boolean;
-//# sourceMappingURL=tool-registry.d.ts.map

package/dist/tasks/tool-registry.js

@@ -11,4 +11,3 @@ export function getTaskCapableTool(name) {
 export function hasTaskCapableTool(name) {
     return taskCapableTools.has(name);
 }
-//# sourceMappingURL=tool-registry.js.map

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

@@ -1,6 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ContentBlock } from '@modelcontextprotocol/sdk/types.js';
-import { type ToolHandlerExtra } from '../lib/tool-progress.js';
+import { type ToolHandlerExtra } from '../lib/mcp-tools.js';
 interface FetchUrlInput {
     url: string;
     skipNoiseRemoval?: boolean | undefined;
@@ -26,4 +26,3 @@ export declare function fetchUrlToolHandler(input: FetchUrlInput, extra?: ToolHa
 export declare function withRequestContextIfMissing<TParams, TResult, TExtra = unknown>(handler: (params: TParams, extra?: TExtra) => Promise<TResult>): (params: TParams, extra?: TExtra) => Promise<TResult>;
 export declare function registerTools(server: McpServer): void;
 export {};
-//# sourceMappingURL=fetch-url.d.ts.map

package/dist/tools/fetch-url.js

@@ -1,15 +1,14 @@
-import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { randomUUID } from 'node:crypto';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import * as cache from '../lib/cache.js';
-import { config } from '../lib/config.js';
-import { generateSafeFilename } from '../lib/download.js';
-import { isAbortError, toError } from '../lib/errors.js';
-import { getRequestId, logDebug, logError, logWarn, runWithRequestContext, } from '../lib/observability.js';
-import { handleToolError } from '../lib/tool-errors.js';
-import { appendTruncationMarker, markdownTransform, parseCachedMarkdownResult, performSharedFetch, readNestedRecord, readString, serializeMarkdownResult, TRUNCATION_MARKER, withSignal, } from '../lib/tool-pipeline.js';
-import { createProgressReporter, } from '../lib/tool-progress.js';
-import { isObject } from '../lib/type-guards.js';
+import * as cache from '../lib/core.js';
+import { config } from '../lib/core.js';
+import { getRequestId, logDebug, logError, logWarn, runWithRequestContext, } from '../lib/core.js';
+import { generateSafeFilename } from '../lib/http.js';
+import { handleToolError } from '../lib/mcp-tools.js';
+import { appendTruncationMarker, markdownTransform, parseCachedMarkdownResult, performSharedFetch, readNestedRecord, readString, serializeMarkdownResult, TRUNCATION_MARKER, withSignal, } from '../lib/mcp-tools.js';
+import { createProgressReporter, } from '../lib/mcp-tools.js';
+import { isAbortError, isObject, toError } from '../lib/utils.js';
 import { fetchUrlInputSchema } from '../schemas/inputs.js';
 import { fetchUrlOutputSchema } from '../schemas/outputs.js';
 import { registerTaskCapableTool, unregisterTaskCapableTool, } from '../tasks/tool-registry.js';
@@ -83,11 +82,11 @@ function appendIfPresent(items, value) {
 /* -------------------------------------------------------------------------------------------------
  * Tool abort signal
  * ------------------------------------------------------------------------------------------------- */
+const HARD_TOOL_TIMEOUT_MS = 300_000;
 function buildToolAbortSignal(extraSignal) {
     const { timeoutMs } = config.tools;
-    if (timeoutMs <= 0)
-        return extraSignal;
-    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const effectiveTimeout = timeoutMs > 0 ? timeoutMs : HARD_TOOL_TIMEOUT_MS;
+    const timeoutSignal = AbortSignal.timeout(effectiveTimeout);
     if (!extraSignal)
         return timeoutSignal;
     return AbortSignal.any([extraSignal, timeoutSignal]);
@@ -107,11 +106,11 @@ const METADATA_FIELD_LIMITS = {
 };
 function truncateMetadata(metadata) {
     const result = { ...metadata };
-    for (const [key, limit] of Object.entries(METADATA_FIELD_LIMITS)) {
-        const field = key;
-        const value = result[field];
+    for (const [field, limit] of Object.entries(METADATA_FIELD_LIMITS)) {
+        const key = field;
+        const value = result[key];
         if (typeof value === 'string' && value.length > limit) {
-            result[field] = value.slice(0, limit);
+            result[key] = value.slice(0, limit);
         }
     }
     return result;
@@ -228,11 +227,7 @@ function getUrlContext(urlStr) {
     }
 }
 async function fetchPipeline(url, signal, progress, skipNoiseRemoval, forceRefresh, maxInlineChars) {
-    const reportProgress = (step, message) => {
-        if (!progress)
-            return;
-        progress.report(step, message);
-    };
+    const contextStr = getUrlContext(url);
     return performSharedFetch({
         url,
         ...withSignal(signal),
@@ -240,33 +235,43 @@ async function fetchPipeline(url, signal, progress, skipNoiseRemoval, forceRefre
         ...(forceRefresh ? { forceRefresh: true } : {}),
         ...(maxInlineChars !== undefined ? { maxInlineChars } : {}),
         transform: async ({ buffer, encoding, truncated }, normalizedUrl) => {
-            const contextStr = getUrlContext(url);
-            reportProgress(2, `fetch-url: ${contextStr} [converting to Markdown]`);
+            reportFetchProgress(progress, 2, contextStr, 'converting to Markdown');
             return markdownTransform({ buffer, encoding, ...(truncated ? { truncated } : {}) }, normalizedUrl, signal, skipNoiseRemoval);
         },
         serialize: serializeMarkdownResult,
         deserialize: parseCachedMarkdownResult,
     });
 }
+function buildFetchProgressMessage(context, state) {
+    if (state === 'completed' || state === 'cancelled' || state === 'failed') {
+        return `fetch-url: ${context} • ${state}`;
+    }
+    return `fetch-url: ${context} [${state}]`;
+}
+function reportFetchProgress(progress, step, context, state) {
+    if (!progress)
+        return;
+    progress.report(step, buildFetchProgressMessage(context, state));
+}
 async function executeFetch(input, extra) {
     const { url } = input;
     const signal = buildToolAbortSignal(extra?.signal);
     const progress = createProgressReporter(extra);
     const contextStr = getUrlContext(url);
-    progress.report(0, `fetch-url: ${contextStr} [starting]`);
+    reportFetchProgress(progress, 0, contextStr, 'starting');
     logDebug('Fetching URL', { url });
     try {
-        progress.report(1, `fetch-url: ${contextStr} [fetching HTML]`);
+        reportFetchProgress(progress, 1, contextStr, 'fetching HTML');
         const { pipeline, inlineResult } = await fetchPipeline(url, signal, progress, input.skipNoiseRemoval, input.forceRefresh, input.maxInlineChars);
         if (pipeline.fromCache) {
-            progress.report(3, `fetch-url: ${contextStr} [loaded from cache]`);
+            reportFetchProgress(progress, 3, contextStr, 'loaded from cache');
         }
-        progress.report(4, `fetch-url: ${contextStr} • completed`);
+        reportFetchProgress(progress, 4, contextStr, 'completed');
         return buildResponse(pipeline, inlineResult, url);
     }
     catch (error) {
         const isAbort = isAbortError(error);
-        progress.report(4, `fetch-url: ${contextStr} • ${isAbort ? 'cancelled' : 'failed'}`);
+        reportFetchProgress(progress, 4, contextStr, isAbort ? 'cancelled' : 'failed');
         throw error;
     }
 }
@@ -359,7 +364,11 @@ export function registerTools(server) {
         parseArguments: (args) => {
             const parsed = fetchUrlInputSchema.safeParse(args);
             if (!parsed.success) {
-                throw new McpError(ErrorCode.InvalidParams, 'Invalid arguments for fetch-url');
+                const flat = z.flattenError(parsed.error);
+                const details = Object.entries(flat.fieldErrors)
+                    .map(([k, v]) => `${k}: ${v.join(', ')}`)
+                    .join('; ') || flat.formErrors.join('; ');
+                throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for ${FETCH_URL_TOOL_NAME}: ${details}`);
             }
             return parsed.data;
         },
@@ -378,4 +387,3 @@ export function registerTools(server) {
     // registered tool type includes this field.
     applyRegisteredToolExecutionMetadata(registeredTool, TOOL_DEFINITION.execution);
 }
-//# sourceMappingURL=fetch-url.js.map

package/dist/tools/index.d.ts

@@ -1,3 +1,2 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerAllTools(server: McpServer): void;
-//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -2,4 +2,3 @@ import { registerTools as registerFetchUrlTool } from './fetch-url.js';
 export function registerAllTools(server) {
     registerFetchUrlTool(server);
 }
-//# sourceMappingURL=index.js.map

package/dist/transform/html-translators.d.ts

@@ -0,0 +1 @@
+export declare function translateHtmlFragmentToMarkdown(html: string): string;