@j0hanz/fetch-url-mcp 1.2.0 → 1.3.1

package/dist/tools.js

@@ -2,400 +2,131 @@ import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import * as cache from './cache.js';
 import { config } from './config.js';
-import { FetchError, getErrorMessage, isSystemError } from './errors.js';
-import { fetchNormalizedUrlBuffer, normalizeUrl, transformToRawUrl, } from './fetch.js';
+import { generateSafeFilename } from './download.js';
 import { getRequestId, logDebug, logError, logWarn, runWithRequestContext, } from './observability.js';
-import { transformBufferToMarkdown } from './transform.js';
+import { handleToolError } from './tool-errors.js';
+import { appendTruncationMarker, markdownTransform, parseCachedMarkdownResult, performSharedFetch, readNestedRecord, readString, serializeMarkdownResult, TRUNCATION_MARKER, withSignal, } from './tool-pipeline.js';
+import { createProgressReporter, } from './tool-progress.js';
 import { isObject } from './type-guards.js';
-const TRUNCATION_MARKER = '...[truncated]';
-const FETCH_PROGRESS_TOTAL = 4;
-const PROGRESS_NOTIFICATION_TIMEOUT_MS = 5000;
+// Re-export public API so existing consumers keep working.
+export { createToolErrorResponse, handleToolError } from './tool-errors.js';
+export { executeFetchPipeline, parseCachedMarkdownResult, performSharedFetch, } from './tool-pipeline.js';
+export { createProgressReporter, } from './tool-progress.js';
 export const fetchUrlInputSchema = z.strictObject({
     url: z
         .url({ protocol: /^https?$/i })
         .min(1)
         .max(config.constants.maxUrlLength)
-        .describe('The URL of the webpage to fetch and convert to Markdown'),
+        .describe(`Target URL. Max ${config.constants.maxUrlLength} chars.`),
     skipNoiseRemoval: z
         .boolean()
         .optional()
-        .describe('When true, preserves navigation, footers, and other elements normally filtered as noise'),
+        .describe('Preserve navigation/footers (disable noise filtering).'),
     forceRefresh: z
         .boolean()
         .optional()
-        .describe('When true, bypasses the cache and fetches fresh content from the URL'),
+        .describe('Bypass cache and fetch fresh content.'),
     maxInlineChars: z
         .number()
         .int()
         .min(0)
         .max(config.constants.maxHtmlSize)
         .optional()
-        .describe('Optional per-call inline markdown limit. 0 means unlimited. If a global inline limit is configured, the lower value is used.'),
+        .describe(`Inline markdown limit (0-${config.constants.maxHtmlSize}, 0=unlimited). Lower of this or global limit applies.`),
 });
-const fetchUrlOutputSchema = z.strictObject({
+export const fetchUrlOutputSchema = z.strictObject({
     url: z
         .string()
         .min(1)
         .max(config.constants.maxUrlLength)
-        .describe('The fetched URL'),
+        .describe('Fetched URL.'),
     inputUrl: z
         .string()
         .max(config.constants.maxUrlLength)
         .optional()
-        .describe('The original URL provided by the caller'),
+        .describe('Original requested URL.'),
     resolvedUrl: z
         .string()
         .max(config.constants.maxUrlLength)
         .optional()
-        .describe('The normalized or transformed URL that was fetched'),
+        .describe('Final URL after raw-content transformations.'),
     finalUrl: z
         .string()
         .max(config.constants.maxUrlLength)
         .optional()
-        .describe('The final response URL after redirects'),
+        .describe('Final URL after HTTP redirects.'),
     cacheResourceUri: z
         .string()
         .max(config.constants.maxUrlLength)
         .optional()
-        .describe('Internal cache resource URI for retrieving full markdown via resources/read'),
-    title: z.string().max(512).optional().describe('Page title'),
+        .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'),
+        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'),
+            .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'),
+            .describe('Detected page preview image URL.'),
         favicon: z
             .string()
             .max(config.constants.maxUrlLength)
             .optional()
-            .describe('Detected page favicon URL'),
+            .describe('Detected page favicon URL.'),
         publishedAt: z
             .string()
             .max(64)
             .optional()
-            .describe('Detected publication date (if present)'),
+            .describe('Detected publication date.'),
         modifiedAt: z
             .string()
             .max(64)
             .optional()
-            .describe('Detected last modified date (if present)'),
+            .describe('Detected last modified date.'),
     })
         .optional()
-        .describe('Detected metadata extracted from page markup'),
+        .describe('Extracted page metadata.'),
     markdown: (config.constants.maxInlineContentChars > 0
         ? z.string().max(config.constants.maxInlineContentChars)
         : z.string())
         .optional()
-        .describe('The extracted content in Markdown format'),
-    fromCache: z
-        .boolean()
-        .optional()
-        .describe('Whether this response was served from cache'),
-    fetchedAt: z
-        .string()
-        .max(64)
-        .optional()
-        .describe('ISO timestamp of fetch/cache retrieval time'),
+        .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 in characters before inline truncation'),
-    truncated: z
-        .boolean()
-        .optional()
-        .describe('Whether the returned markdown was truncated'),
-    error: z
-        .string()
-        .max(2048)
-        .optional()
-        .describe('Error message if the request failed'),
-    statusCode: z
-        .number()
-        .int()
-        .optional()
-        .describe('HTTP status code for failed requests'),
-    details: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe('Additional error details when available'),
+        .describe('Full markdown size before truncation.'),
+    truncated: z.boolean().optional().describe('True if markdown was truncated.'),
 });
 export const FETCH_URL_TOOL_NAME = 'fetch-url';
 const FETCH_URL_TOOL_DESCRIPTION = `
-Fetches a webpage and converts it to clean Markdown format optimized for LLM context.
-
-This tool is useful for:
-- Reading documentation, blog posts, or articles.
-- Extracting main content while removing navigation and ads (noise removal).
-- Caching content to speed up repeated queries.
-
-Limitations:
-- Inline output may be truncated when MAX_INLINE_CONTENT_CHARS is set.
-- Does not execute complex client-side JavaScript interactions.
+<role>Web Content Extractor</role>
+<task>Fetch public webpages and convert HTML to clean Markdown.</task>
+<constraints>
+- READ-ONLY. No JavaScript execution.
+- GitHub/GitLab/Bitbucket URLs auto-transform to raw endpoints (check resolvedUrl).
+- If truncated=true, use cacheResourceUri with resources/read for full content.
+- For large pages/timeouts, use task mode (task: {}).
+- If error queue_full, retry with task mode.
+</constraints>
 `.trim();
-// Specific icon for the fetch-url tool (download cloud / web)
 const TOOL_ICON = {
     src: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIj48cGF0aCBkPSJNMjEgMTV2NGEyIDIgMCAwIDEtMiAySDVhMiAyIDAgMCAxLTItMnYtNCIvPjxwb2x5bGluZSBwb2ludHM9IjcgMTAgMTIgMTUgMTcgMTAiLz48bGluZSB4MT0iMTIiIHkxPSIxNSIgeDI9IjEyIiB5Mj0iMyIvPjwvc3ZnPg==',
     mimeType: 'image/svg+xml',
 };
-function asRecord(value) {
-    return isObject(value) ? value : undefined;
-}
-function readUnknown(obj, key) {
-    const record = asRecord(obj);
-    return record ? record[key] : undefined;
-}
-function readString(obj, key) {
-    const value = readUnknown(obj, key);
-    return typeof value === 'string' ? value : undefined;
-}
-function readNestedRecord(obj, keys) {
-    let current = obj;
-    for (const key of keys) {
-        current = readUnknown(current, key);
-        if (current === undefined)
-            return undefined;
-    }
-    return asRecord(current);
-}
-function safeJsonParse(value) {
-    try {
-        return JSON.parse(value);
-    }
-    catch {
-        return undefined;
-    }
-}
-function withSignal(signal) {
-    return signal === undefined ? {} : { signal };
-}
-function buildToolAbortSignal(extraSignal) {
-    const { timeoutMs } = config.tools;
-    if (timeoutMs <= 0)
-        return extraSignal;
-    const timeoutSignal = AbortSignal.timeout(timeoutMs);
-    if (!extraSignal)
-        return timeoutSignal;
-    return AbortSignal.any([extraSignal, timeoutSignal]);
-}
 /* -------------------------------------------------------------------------------------------------
- * Progress reporting
- * ------------------------------------------------------------------------------------------------- */
-function resolveRelatedTaskMeta(meta) {
-    const related = readUnknown(meta, 'io.modelcontextprotocol/related-task');
-    const taskId = readString(related, 'taskId');
-    return taskId ? { taskId } : undefined;
-}
-class ToolProgressReporter {
-    token;
-    sendNotification;
-    relatedTaskMeta;
-    onProgress;
-    reportQueue = Promise.resolve();
-    constructor(token, sendNotification, relatedTaskMeta, onProgress) {
-        this.token = token;
-        this.sendNotification = sendNotification;
-        this.relatedTaskMeta = relatedTaskMeta;
-        this.onProgress = onProgress;
-    }
-    static create(extra) {
-        const token = extra?._meta?.progressToken ?? null;
-        const sendNotification = extra?.sendNotification;
-        const relatedTaskMeta = resolveRelatedTaskMeta(extra?._meta);
-        const onProgress = extra?.onProgress;
-        if (token === null && !onProgress) {
-            return { report: async () => { } };
-        }
-        return new ToolProgressReporter(token, sendNotification, relatedTaskMeta, onProgress);
-    }
-    async report(progress, message) {
-        if (this.onProgress) {
-            try {
-                this.onProgress(progress, message);
-            }
-            catch (error) {
-                logWarn('Progress callback failed', {
-                    error: getErrorMessage(error),
-                    progress,
-                    message,
-                });
-            }
-        }
-        if (this.token === null || !this.sendNotification)
-            return;
-        const { sendNotification } = this;
-        const notification = {
-            method: 'notifications/progress',
-            params: {
-                progressToken: this.token,
-                progress,
-                total: FETCH_PROGRESS_TOTAL,
-                message,
-                ...(this.relatedTaskMeta
-                    ? {
-                        _meta: {
-                            'io.modelcontextprotocol/related-task': this.relatedTaskMeta,
-                        },
-                    }
-                    : {}),
-            },
-        };
-        this.reportQueue = this.reportQueue.then(async () => {
-            let timeoutId;
-            const timeoutPromise = new Promise((resolve) => {
-                timeoutId = setTimeout(() => {
-                    resolve({ timeout: true });
-                }, PROGRESS_NOTIFICATION_TIMEOUT_MS);
-                timeoutId.unref();
-            });
-            try {
-                const outcome = await Promise.race([
-                    sendNotification(notification).then(() => ({ ok: true })),
-                    timeoutPromise,
-                ]);
-                if ('timeout' in outcome) {
-                    logWarn('Progress notification timed out', { progress, message });
-                }
-            }
-            catch (error) {
-                logWarn('Failed to send progress notification', {
-                    error: getErrorMessage(error),
-                    progress,
-                    message,
-                });
-            }
-            finally {
-                if (timeoutId)
-                    clearTimeout(timeoutId);
-            }
-        });
-        await this.reportQueue;
-    }
-}
-export function createProgressReporter(extra) {
-    return ToolProgressReporter.create(extra);
-}
-function getOpenCodeFence(content) {
-    const FENCE_PATTERN = /^([ \t]*)(`{3,}|~{3,})/gm;
-    let match;
-    let inFence = false;
-    let fenceChar = null;
-    let fenceLength = 0;
-    while ((match = FENCE_PATTERN.exec(content)) !== null) {
-        const marker = match[2];
-        if (!marker)
-            continue;
-        const [char] = marker;
-        if (!char)
-            continue;
-        const { length } = marker;
-        if (!inFence) {
-            inFence = true;
-            fenceChar = char;
-            fenceLength = length;
-        }
-        else if (char === fenceChar && length >= fenceLength) {
-            inFence = false;
-            fenceChar = null;
-            fenceLength = 0;
-        }
-    }
-    if (inFence && fenceChar) {
-        return { fenceChar, fenceLength };
-    }
-    return null;
-}
-function findSafeLinkBoundary(content, limit) {
-    const lastBracket = content.lastIndexOf('[', limit);
-    if (lastBracket === -1)
-        return limit;
-    const afterBracket = content.substring(lastBracket, limit);
-    const closedPattern = /^\[[^\]]*\]\([^)]*\)/;
-    if (closedPattern.test(afterBracket))
-        return limit;
-    const start = lastBracket > 0 && content[lastBracket - 1] === '!'
-        ? lastBracket - 1
-        : lastBracket;
-    return start;
-}
-function truncateWithMarker(content, limit, marker) {
-    if (content.length <= limit)
-        return content;
-    const maxContentLength = Math.max(0, limit - marker.length);
-    const tentativeContent = content.substring(0, maxContentLength);
-    const openFence = getOpenCodeFence(tentativeContent);
-    if (openFence) {
-        const fenceCloser = `\n${openFence.fenceChar.repeat(openFence.fenceLength)}\n`;
-        const adjustedLength = Math.max(0, limit - marker.length - fenceCloser.length);
-        return `${content.substring(0, adjustedLength)}${fenceCloser}${marker}`;
-    }
-    const safeBoundary = findSafeLinkBoundary(content, maxContentLength);
-    if (safeBoundary < maxContentLength) {
-        return `${content.substring(0, safeBoundary)}${marker}`;
-    }
-    return `${tentativeContent}${marker}`;
-}
-function appendTruncationMarker(content, marker) {
-    if (!content)
-        return marker;
-    if (content.endsWith(marker))
-        return content;
-    const openFence = getOpenCodeFence(content);
-    const contentWithFence = openFence
-        ? `${content}\n${openFence.fenceChar.repeat(openFence.fenceLength)}\n`
-        : content;
-    const safeBoundary = findSafeLinkBoundary(contentWithFence, contentWithFence.length);
-    if (safeBoundary < contentWithFence.length) {
-        return `${contentWithFence.substring(0, safeBoundary)}${marker}`;
-    }
-    return `${contentWithFence}${marker}`;
-}
-class InlineContentLimiter {
-    apply(content, inlineLimitOverride) {
-        const contentSize = content.length;
-        const inlineLimit = this.resolveInlineLimit(inlineLimitOverride);
-        if (inlineLimit <= 0) {
-            return { content, contentSize };
-        }
-        if (contentSize <= inlineLimit) {
-            return { content, contentSize };
-        }
-        const truncatedContent = truncateWithMarker(content, inlineLimit, TRUNCATION_MARKER);
-        return {
-            content: truncatedContent,
-            contentSize,
-            truncated: true,
-        };
-    }
-    resolveInlineLimit(inlineLimitOverride) {
-        const globalLimit = config.constants.maxInlineContentChars;
-        if (inlineLimitOverride === undefined)
-            return globalLimit;
-        if (globalLimit > 0 && inlineLimitOverride > 0) {
-            return Math.min(inlineLimitOverride, globalLimit);
-        }
-        if (globalLimit > 0 && inlineLimitOverride === 0)
-            return globalLimit;
-        return inlineLimitOverride;
-    }
-}
-const inlineLimiter = new InlineContentLimiter();
-function applyInlineContentLimit(content, inlineLimitOverride) {
-    return inlineLimiter.apply(content, inlineLimitOverride);
-}
-/* -------------------------------------------------------------------------------------------------
- * Tool response blocks (text + optional embedded resource)
+ * Tool response builders
  * ------------------------------------------------------------------------------------------------- */
 function buildTextBlock(structuredContent) {
     return {
@@ -406,7 +137,7 @@ function buildTextBlock(structuredContent) {
 function buildEmbeddedResource(content, url, title) {
     if (!content)
         return null;
-    const filename = cache.generateSafeFilename(url, title, undefined, '.md');
+    const filename = generateSafeFilename(url, title, undefined, '.md');
     const uri = new URL(filename, 'file:///').href;
     const resource = {
         uri,
@@ -436,297 +167,48 @@ function buildCacheResourceLink(cacheResourceUri, contentSize, fetchedAt) {
 }
 function buildToolContentBlocks(structuredContent, resourceLink, embeddedResource) {
     const blocks = [buildTextBlock(structuredContent)];
-    if (resourceLink) {
-        blocks.push(resourceLink);
-    }
-    if (embeddedResource) {
-        blocks.push(embeddedResource);
-    }
+    appendIfPresent(blocks, resourceLink);
+    appendIfPresent(blocks, embeddedResource);
     return blocks;
 }
-function resolveNormalizedUrl(url) {
-    const { normalizedUrl: validatedUrl } = normalizeUrl(url);
-    const transformedResult = transformToRawUrl(validatedUrl);
-    if (!transformedResult.transformed) {
-        return {
-            normalizedUrl: validatedUrl,
-            originalUrl: validatedUrl,
-            transformed: false,
-        };
-    }
-    // Re-validate transformed URLs so blocked-host and length policies still apply.
-    const { normalizedUrl: transformedUrl } = normalizeUrl(transformedResult.url);
-    return {
-        normalizedUrl: transformedUrl,
-        originalUrl: validatedUrl,
-        transformed: true,
-    };
-}
-function logRawUrlTransformation(resolvedUrl) {
-    if (!resolvedUrl.transformed)
-        return;
-    logDebug('Using transformed raw content URL', {
-        original: resolvedUrl.originalUrl,
-    });
-}
-function extractTitle(value) {
-    const record = asRecord(value);
-    const title = record ? record['title'] : undefined;
-    return typeof title === 'string' ? title : undefined;
-}
-function logCacheMiss(reason, cacheNamespace, normalizedUrl, error) {
-    const log = reason.startsWith('deserialize') ? logWarn : logDebug;
-    log(`Cache miss due to ${reason}`, {
-        namespace: cacheNamespace,
-        url: normalizedUrl,
-        ...(error ? { error: getErrorMessage(error) } : {}),
-    });
-}
-function attemptCacheRetrieval(params) {
-    const { cacheKey, deserialize, cacheNamespace, normalizedUrl } = params;
-    if (!cacheKey)
-        return null;
-    const cached = cache.get(cacheKey);
-    if (!cached)
-        return null;
-    if (!deserialize) {
-        logCacheMiss('missing deserializer', cacheNamespace, normalizedUrl);
-        return null;
-    }
-    let data;
-    try {
-        data = deserialize(cached.content);
-    }
-    catch (error) {
-        logCacheMiss('deserialize exception', cacheNamespace, normalizedUrl, error);
-        return null;
-    }
-    if (data === undefined) {
-        logCacheMiss('deserialize failure', cacheNamespace, normalizedUrl);
-        return null;
-    }
-    logDebug('Cache hit', { namespace: cacheNamespace, url: normalizedUrl });
-    const finalUrl = cached.url !== normalizedUrl ? cached.url : undefined;
-    return {
-        data,
-        fromCache: true,
-        url: normalizedUrl,
-        ...(finalUrl ? { finalUrl } : {}),
-        fetchedAt: cached.fetchedAt,
-        cacheKey,
-    };
-}
-function persistCache(params) {
-    const { cacheKey, data, serialize, normalizedUrl, cacheNamespace, force } = params;
-    if (!cacheKey)
-        return;
-    const serializer = serialize ?? JSON.stringify;
-    const title = extractTitle(data);
-    const metadata = {
-        url: normalizedUrl,
-        ...(title === undefined ? {} : { title }),
-    };
-    try {
-        cache.set(cacheKey, serializer(data), metadata, force ? { force: true } : undefined);
-    }
-    catch (error) {
-        logWarn('Failed to persist cache entry', {
-            namespace: cacheNamespace,
-            url: normalizedUrl,
-            error: getErrorMessage(error),
-        });
-    }
-}
-export async function executeFetchPipeline(options) {
-    const resolvedUrl = resolveNormalizedUrl(options.url);
-    logRawUrlTransformation(resolvedUrl);
-    const cacheKey = cache.createCacheKey(options.cacheNamespace, resolvedUrl.normalizedUrl, options.cacheVary);
-    if (!options.forceRefresh) {
-        const cachedResult = attemptCacheRetrieval({
-            cacheKey,
-            deserialize: options.deserialize,
-            cacheNamespace: options.cacheNamespace,
-            normalizedUrl: resolvedUrl.normalizedUrl,
-        });
-        if (cachedResult) {
-            return { ...cachedResult, originalUrl: resolvedUrl.originalUrl };
-        }
-    }
-    logDebug('Fetching URL', { url: resolvedUrl.normalizedUrl });
-    const { buffer, encoding, truncated, finalUrl } = await fetchNormalizedUrlBuffer(resolvedUrl.normalizedUrl, withSignal(options.signal));
-    const transformUrl = finalUrl || resolvedUrl.normalizedUrl;
-    const data = await options.transform({ buffer, encoding, ...(truncated ? { truncated: true } : {}) }, transformUrl);
-    if (cache.isEnabled()) {
-        persistCache({
-            cacheKey,
-            data,
-            serialize: options.serialize,
-            normalizedUrl: finalUrl || resolvedUrl.normalizedUrl,
-            cacheNamespace: options.cacheNamespace,
-        });
-        if (finalUrl && finalUrl !== resolvedUrl.normalizedUrl) {
-            const finalCacheKey = cache.createCacheKey(options.cacheNamespace, finalUrl, options.cacheVary);
-            if (finalCacheKey && finalCacheKey !== cacheKey) {
-                persistCache({
-                    cacheKey: finalCacheKey,
-                    data,
-                    serialize: options.serialize,
-                    normalizedUrl: finalUrl,
-                    cacheNamespace: options.cacheNamespace,
-                });
-            }
-        }
-    }
-    return {
-        data,
-        fromCache: false,
-        url: resolvedUrl.normalizedUrl,
-        originalUrl: resolvedUrl.originalUrl,
-        finalUrl,
-        fetchedAt: new Date().toISOString(),
-        cacheKey,
-    };
-}
-export async function performSharedFetch(options, deps = {}) {
-    const executePipeline = deps.executeFetchPipeline ?? executeFetchPipeline;
-    const pipelineOptions = {
-        url: options.url,
-        cacheNamespace: 'markdown',
-        ...withSignal(options.signal),
-        ...(options.cacheVary ? { cacheVary: options.cacheVary } : {}),
-        ...(options.forceRefresh ? { forceRefresh: true } : {}),
-        transform: options.transform,
-        ...(options.serialize ? { serialize: options.serialize } : {}),
-        ...(options.deserialize ? { deserialize: options.deserialize } : {}),
-    };
-    const pipeline = await executePipeline(pipelineOptions);
-    const inlineResult = applyInlineContentLimit(pipeline.data.content, options.maxInlineChars);
-    return { pipeline, inlineResult };
+function appendIfPresent(items, value) {
+    if (value !== null && value !== undefined)
+        items.push(value);
 }
 /* -------------------------------------------------------------------------------------------------
- * Tool error mapping
+ * Tool abort signal
  * ------------------------------------------------------------------------------------------------- */
-export function createToolErrorResponse(message, url, extra) {
-    const structuredContent = {
-        error: message,
-        url,
-        ...(extra?.statusCode !== undefined
-            ? { statusCode: extra.statusCode }
-            : {}),
-        ...(extra?.details ? { details: extra.details } : {}),
-    };
-    return {
-        content: [buildTextBlock(structuredContent)],
-        structuredContent,
-        isError: true,
-    };
-}
-function isValidationError(error) {
-    return (error instanceof Error &&
-        isSystemError(error) &&
-        error.code === 'VALIDATION_ERROR');
-}
-function resolveToolErrorMessage(error, fallbackMessage) {
-    if (isValidationError(error) || error instanceof FetchError) {
-        return error.message;
-    }
-    if (error instanceof Error) {
-        return `${fallbackMessage}: ${error.message}`;
-    }
-    return `${fallbackMessage}: Unknown error`;
-}
-export function handleToolError(error, url, fallbackMessage = 'Operation failed') {
-    const message = resolveToolErrorMessage(error, fallbackMessage);
-    if (error instanceof FetchError) {
-        return createToolErrorResponse(message, url, {
-            statusCode: error.statusCode,
-            details: error.details,
-        });
-    }
-    return createToolErrorResponse(message, url);
+function buildToolAbortSignal(extraSignal) {
+    const { timeoutMs } = config.tools;
+    if (timeoutMs <= 0)
+        return extraSignal;
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    if (!extraSignal)
+        return timeoutSignal;
+    return AbortSignal.any([extraSignal, timeoutSignal]);
 }
-function normalizeExtractedMetadata(metadata) {
-    if (!metadata)
-        return undefined;
-    const normalized = {
-        ...(metadata.title ? { title: metadata.title } : {}),
-        ...(metadata.description ? { description: metadata.description } : {}),
-        ...(metadata.author ? { author: metadata.author } : {}),
-        ...(metadata.image ? { image: metadata.image } : {}),
-        ...(metadata.favicon ? { favicon: metadata.favicon } : {}),
-        ...(metadata.publishedAt ? { publishedAt: metadata.publishedAt } : {}),
-        ...(metadata.modifiedAt ? { modifiedAt: metadata.modifiedAt } : {}),
-    };
-    if (Object.keys(normalized).length === 0)
-        return undefined;
-    return normalized;
+/* -------------------------------------------------------------------------------------------------
+ * Structured response assembly
+ * ------------------------------------------------------------------------------------------------- */
+function truncateStr(value, max) {
+    if (value === undefined || value.length <= max)
+        return value;
+    return value.slice(0, max);
 }
-const cachedMarkdownSchema = z
-    .object({
-    markdown: z.string().optional(),
-    content: z.string().optional(),
-    title: z.string().optional(),
-    metadata: z
-        .strictObject({
-        title: z.string().optional(),
-        description: z.string().optional(),
-        author: z.string().optional(),
-        image: z.string().optional(),
-        favicon: z.string().optional(),
-        publishedAt: z.string().optional(),
-        modifiedAt: z.string().optional(),
-    })
-        .optional(),
-    truncated: z.boolean().optional(),
-})
-    .catchall(z.unknown())
-    .refine((value) => typeof value.markdown === 'string' || typeof value.content === 'string', { message: 'Missing markdown/content' });
-export function parseCachedMarkdownResult(cached) {
-    const parsed = safeJsonParse(cached);
-    const result = cachedMarkdownSchema.safeParse(parsed);
-    if (!result.success)
-        return undefined;
-    const markdown = result.data.markdown ?? result.data.content;
-    if (typeof markdown !== 'string')
-        return undefined;
-    const metadata = normalizeExtractedMetadata(result.data.metadata);
-    const truncated = result.data.truncated ?? false;
-    const persistedMarkdown = truncated
-        ? appendTruncationMarker(markdown, TRUNCATION_MARKER)
-        : markdown;
+function truncateMetadata(metadata) {
     return {
-        content: persistedMarkdown,
-        markdown: persistedMarkdown,
-        title: result.data.title,
-        ...(metadata ? { metadata } : {}),
-        truncated,
+        ...metadata,
+        ...(metadata.title !== undefined
+            ? { title: truncateStr(metadata.title, 512) }
+            : {}),
+        ...(metadata.description !== undefined
+            ? { description: truncateStr(metadata.description, 2048) }
+            : {}),
+        ...(metadata.author !== undefined
+            ? { author: truncateStr(metadata.author, 512) }
+            : {}),
     };
 }
-const markdownTransform = async (input, url, signal, skipNoiseRemoval) => {
-    const result = await transformBufferToMarkdown(input.buffer, url, {
-        includeMetadata: true,
-        encoding: input.encoding,
-        ...withSignal(signal),
-        ...(skipNoiseRemoval ? { skipNoiseRemoval: true } : {}),
-        ...(input.truncated ? { inputTruncated: true } : {}),
-    });
-    const truncated = Boolean(result.truncated || input.truncated);
-    return { ...result, content: result.markdown, truncated };
-};
-function serializeMarkdownResult(result) {
-    const persistedMarkdown = result.truncated
-        ? appendTruncationMarker(result.markdown, TRUNCATION_MARKER)
-        : result.markdown;
-    return JSON.stringify({
-        markdown: persistedMarkdown,
-        title: result.title,
-        metadata: result.metadata,
-        truncated: result.truncated,
-    });
-}
-/* -------------------------------------------------------------------------------------------------
- * fetch-url tool implementation
- * ------------------------------------------------------------------------------------------------- */
 function buildStructuredContent(pipeline, inlineResult, inputUrl) {
     const cacheResourceUri = resolveCacheResourceUri(pipeline.cacheKey);
     const truncated = inlineResult.truncated ?? pipeline.data.truncated;
@@ -738,8 +220,8 @@ function buildStructuredContent(pipeline, inlineResult, inputUrl) {
         ...(pipeline.finalUrl ? { finalUrl: pipeline.finalUrl } : {}),
         ...(cacheResourceUri ? { cacheResourceUri } : {}),
         inputUrl,
-        title: pipeline.data.title,
-        ...(metadata ? { metadata } : {}),
+        title: truncateStr(pipeline.data.title, 512),
+        ...(metadata ? { metadata: truncateMetadata(metadata) } : {}),
         markdown,
         fromCache: pipeline.fromCache,
         fetchedAt: pipeline.fetchedAt,
@@ -780,20 +262,70 @@ function buildFetchUrlContentBlocks(structuredContent, pipeline, inlineResult) {
 function buildResponse(pipeline, inlineResult, inputUrl) {
     const structuredContent = buildStructuredContent(pipeline, inlineResult, inputUrl);
     const content = buildFetchUrlContentBlocks(structuredContent, pipeline, inlineResult);
-    // Runtime validation guard: verify output matches schema
     const validation = fetchUrlOutputSchema.safeParse(structuredContent);
     if (!validation.success) {
         logWarn('Tool output schema validation failed', {
             url: inputUrl,
             issues: validation.error.issues,
         });
+        // Omit structuredContent so the SDK does not receive data that fails its
+        // output schema validation. The client still gets the payload via content[0].text.
+        return { content };
     }
     return {
         content,
         structuredContent,
     };
 }
+/* -------------------------------------------------------------------------------------------------
+ * fetch-url tool implementation
+ * ------------------------------------------------------------------------------------------------- */
+export function getUrlContext(urlStr) {
+    try {
+        const u = new URL(urlStr);
+        const host = u.hostname.replace(/^www\./, '');
+        const path = u.pathname;
+        if (path === '/' || path === '')
+            return host;
+        const parts = path.split('/').filter(Boolean);
+        if (parts.length === 0)
+            return host;
+        // Special case for GitHub/GitLab/Bitbucket
+        if (host === 'github.com' ||
+            host === 'gitlab.com' ||
+            host === 'bitbucket.org') {
+            if (parts.length >= 2) {
+                const p0 = parts[0] ?? '';
+                const p1 = parts[1] ?? '';
+                return `${host}/${p0}/${p1}`;
+            }
+        }
+        // Special case for Wikipedia
+        if (host.endsWith('wikipedia.org') &&
+            parts[0] === 'wiki' &&
+            parts.length >= 2) {
+            const p1 = parts[1] ?? '';
+            return `wikipedia.org/${p1}`;
+        }
+        let basename = parts.pop() ?? '';
+        if (basename && basename.length > 20) {
+            basename = `${basename.substring(0, 17)}...`;
+        }
+        if (parts.length === 0) {
+            return `${host}/${basename}`;
+        }
+        return basename ? `${host}/…/${basename}` : host;
+    }
+    catch {
+        return 'unknown';
+    }
+}
 async function fetchPipeline(url, signal, progress, skipNoiseRemoval, forceRefresh, maxInlineChars) {
+    const reportProgress = (step, message) => {
+        if (!progress)
+            return;
+        progress.report(step, message);
+    };
     return performSharedFetch({
         url,
         ...withSignal(signal),
@@ -801,9 +333,8 @@ async function fetchPipeline(url, signal, progress, skipNoiseRemoval, forceRefre
         ...(forceRefresh ? { forceRefresh: true } : {}),
         ...(maxInlineChars !== undefined ? { maxInlineChars } : {}),
         transform: async ({ buffer, encoding, truncated }, normalizedUrl) => {
-            if (progress) {
-                void progress.report(3, 'Transforming content');
-            }
+            const contextStr = getUrlContext(url);
+            reportProgress(2, `fetch-url: ${contextStr} [converting to Markdown]`);
             return markdownTransform({ buffer, encoding, ...(truncated ? { truncated } : {}) }, normalizedUrl, signal, skipNoiseRemoval);
         },
         serialize: serializeMarkdownResult,
@@ -812,20 +343,25 @@ async function fetchPipeline(url, signal, progress, skipNoiseRemoval, forceRefre
 }
 async function executeFetch(input, extra) {
     const { url } = input;
-    if (!url) {
-        return createToolErrorResponse('URL is required', '');
-    }
     const signal = buildToolAbortSignal(extra?.signal);
     const progress = createProgressReporter(extra);
-    void progress.report(1, 'Validating URL');
+    const contextStr = getUrlContext(url);
+    progress.report(0, `fetch-url: ${contextStr} [starting]`);
     logDebug('Fetching URL', { url });
-    void progress.report(2, 'Fetching content');
-    const { pipeline, inlineResult } = await fetchPipeline(url, signal, progress, input.skipNoiseRemoval, input.forceRefresh, input.maxInlineChars);
-    if (pipeline.fromCache) {
-        void progress.report(3, 'Using cached content');
+    try {
+        progress.report(1, `fetch-url: ${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]`);
+        }
+        progress.report(4, `fetch-url: ${contextStr} • completed`);
+        return buildResponse(pipeline, inlineResult, url);
+    }
+    catch (error) {
+        const isAbort = error instanceof Error && error.name === 'AbortError';
+        progress.report(4, `fetch-url: ${contextStr} • ${isAbort ? 'cancelled' : 'failed'}`);
+        throw error;
     }
-    void progress.report(4, 'Finalizing response');
-    return buildResponse(pipeline, inlineResult, url);
 }
 export async function fetchUrlToolHandler(input, extra) {
     return executeFetch(input, extra).catch((error) => {
@@ -838,7 +374,7 @@ const TOOL_DEFINITION = {
     title: 'Fetch URL',
     description: FETCH_URL_TOOL_DESCRIPTION,
     inputSchema: fetchUrlInputSchema,
-    outputSchema: fetchUrlOutputSchema,
+    outputSchema: z.toJSONSchema(fetchUrlOutputSchema),
     handler: fetchUrlToolHandler,
     execution: {
         taskSupport: 'optional',
@@ -897,5 +433,9 @@ export function registerTools(server) {
         execution: TOOL_DEFINITION.execution,
         icons: [TOOL_ICON],
     }, withRequestContextIfMissing(TOOL_DEFINITION.handler));
+    // SDK workaround: RegisteredTool does not expose `execution` in its public type, so we
+    // assign it directly post-registration to enable task-augmented tool calls (taskSupport).
+    // TODO: Remove when @modelcontextprotocol/sdk exposes `execution` in RegisteredTool type.
     registeredTool.execution = TOOL_DEFINITION.execution;
 }
+//# sourceMappingURL=tools.js.map