@j0hanz/superfetch 2.5.2 → 2.6.0

package/dist/tools.js

@@ -3,19 +3,27 @@ import { z } from 'zod';
 import * as cache from './cache.js';
 import { config } from './config.js';
 import { FetchError, getErrorMessage, isSystemError } from './errors.js';
-import { fetchNormalizedUrl, normalizeUrl, transformToRawUrl, } from './fetch.js';
+import { fetchNormalizedUrlBuffer, normalizeUrl, transformToRawUrl, } from './fetch.js';
 import { getRequestId, logDebug, logError, logWarn, runWithRequestContext, } from './observability.js';
-import { transformHtmlToMarkdown } from './transform.js';
+import { transformBufferToMarkdown } from './transform.js';
 import { isObject } from './type-guards.js';
 const TRUNCATION_MARKER = '...[truncated]';
 const FETCH_PROGRESS_TOTAL = 4;
 const PROGRESS_NOTIFICATION_TIMEOUT_MS = 5000;
-const fetchUrlInputSchema = z.strictObject({
+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'),
+    skipNoiseRemoval: z
+        .boolean()
+        .optional()
+        .describe('When true, preserves navigation, footers, and other elements normally filtered as noise'),
+    forceRefresh: z
+        .boolean()
+        .optional()
+        .describe('When true, bypasses the cache and fetches fresh content from the URL'),
 });
 const fetchUrlOutputSchema = z.strictObject({
     url: z
@@ -34,16 +42,29 @@ const fetchUrlOutputSchema = z.strictObject({
         .optional()
         .describe('The normalized or transformed URL that was fetched'),
     title: z.string().max(512).optional().describe('Page title'),
-    markdown: z
-        .string()
-        .max(config.constants.maxInlineContentChars)
+    markdown: (config.constants.maxInlineContentChars > 0
+        ? z.string().max(config.constants.maxInlineContentChars)
+        : z.string())
         .optional()
         .describe('The extracted content in Markdown format'),
+    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'),
 });
 export const FETCH_URL_TOOL_NAME = 'fetch-url';
 const FETCH_URL_TOOL_DESCRIPTION = `
@@ -55,7 +76,7 @@ This tool is useful for:
 - Caching content to speed up repeated queries.
 
 Limitations:
-- Returns truncated content if it exceeds ${config.constants.maxInlineContentChars} characters.
+- Inline output may be truncated when MAX_INLINE_CONTENT_CHARS is set.
 - Does not execute complex client-side JavaScript interactions.
 `.trim();
 // Specific icon for the fetch-url tool (download cloud / web)
@@ -63,17 +84,53 @@ 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) {
-    if (!meta)
-        return undefined;
-    const related = meta['io.modelcontextprotocol/related-task'];
-    if (!isObject(related))
-        return undefined;
-    const { taskId } = related;
-    return typeof taskId === 'string' ? { taskId } : undefined;
+    const related = readUnknown(meta, 'io.modelcontextprotocol/related-task');
+    const taskId = readString(related, 'taskId');
+    return taskId ? { taskId } : undefined;
 }
 class ToolProgressReporter {
     token;
@@ -94,79 +151,138 @@ class ToolProgressReporter {
         return new ToolProgressReporter(token, sendNotification, relatedTaskMeta);
     }
     async report(progress, message) {
+        const notification = {
+            method: 'notifications/progress',
+            params: {
+                progressToken: this.token,
+                progress,
+                total: FETCH_PROGRESS_TOTAL,
+                message,
+                ...(this.relatedTaskMeta
+                    ? {
+                        _meta: {
+                            'io.modelcontextprotocol/related-task': this.relatedTaskMeta,
+                        },
+                    }
+                    : {}),
+            },
+        };
+        let timeoutId;
+        const timeoutPromise = new Promise((resolve) => {
+            timeoutId = setTimeout(() => {
+                resolve({ timeout: true });
+            }, PROGRESS_NOTIFICATION_TIMEOUT_MS);
+            timeoutId.unref();
+        });
         try {
-            let timeoutId;
-            const timeoutPromise = new Promise((_, reject) => {
-                timeoutId = setTimeout(() => {
-                    reject(new Error('Progress notification timeout'));
-                }, PROGRESS_NOTIFICATION_TIMEOUT_MS);
-                timeoutId.unref();
-            });
-            const sendPromise = this.sendNotification({
-                method: 'notifications/progress',
-                params: {
-                    progressToken: this.token,
-                    progress,
-                    total: FETCH_PROGRESS_TOTAL,
-                    message,
-                    ...(this.relatedTaskMeta
-                        ? {
-                            _meta: {
-                                'io.modelcontextprotocol/related-task': this.relatedTaskMeta,
-                            },
-                        }
-                        : {}),
-                },
-            }).finally(() => {
-                if (timeoutId)
-                    clearTimeout(timeoutId);
-            });
-            await Promise.race([sendPromise, timeoutPromise]);
+            const outcome = await Promise.race([
+                this.sendNotification(notification).then(() => ({ ok: true })),
+                timeoutPromise,
+            ]);
+            if ('timeout' in outcome) {
+                logWarn('Progress notification timed out', { progress, message });
+            }
         }
         catch (error) {
-            const isTimeout = error instanceof Error &&
-                error.message === 'Progress notification timeout';
-            const logMessage = isTimeout
-                ? 'Progress notification timed out'
-                : 'Failed to send progress notification';
-            logWarn(logMessage, {
+            logWarn('Failed to send progress notification', {
                 error: getErrorMessage(error),
                 progress,
                 message,
             });
         }
+        finally {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+        }
     }
 }
 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}`;
+}
 class InlineContentLimiter {
     apply(content, cacheKey) {
         const contentSize = content.length;
         const inlineLimit = config.constants.maxInlineContentChars;
+        if (inlineLimit <= 0) {
+            return { content, contentSize };
+        }
         if (contentSize <= inlineLimit) {
             return { content, contentSize };
         }
-        const resourceUri = this.resolveResourceUri(cacheKey);
-        if (!resourceUri) {
-            return this.buildTruncatedFallback(content, contentSize, inlineLimit);
+        const isTruncated = contentSize > inlineLimit;
+        const resourceUri = cacheKey && (cache.isEnabled() || isTruncated)
+            ? cache.toResourceUri(cacheKey)
+            : null;
+        const truncatedContent = truncateWithMarker(content, inlineLimit, TRUNCATION_MARKER);
+        if (resourceUri) {
+            return {
+                content: truncatedContent,
+                contentSize,
+                resourceUri,
+                resourceMimeType: 'text/markdown',
+                truncated: true,
+            };
         }
-        return {
-            contentSize,
-            resourceUri,
-            resourceMimeType: 'text/markdown',
-        };
-    }
-    resolveResourceUri(cacheKey) {
-        if (!cache.isEnabled() || !cacheKey)
-            return null;
-        return cache.toResourceUri(cacheKey);
-    }
-    buildTruncatedFallback(content, contentSize, inlineLimit) {
-        const maxContentLength = Math.max(0, inlineLimit - TRUNCATION_MARKER.length);
-        const truncatedContent = content.length > inlineLimit
-            ? `${content.substring(0, maxContentLength)}${TRUNCATION_MARKER}`
-            : content;
         return {
             content: truncatedContent,
             contentSize,
@@ -181,13 +297,10 @@ function applyInlineContentLimit(content, cacheKey) {
 /* -------------------------------------------------------------------------------------------------
  * Tool response blocks (text + optional resource + optional link)
  * ------------------------------------------------------------------------------------------------- */
-function serializeStructuredContent(structuredContent) {
-    return JSON.stringify(structuredContent);
-}
 function buildTextBlock(structuredContent) {
     return {
         type: 'text',
-        text: serializeStructuredContent(structuredContent),
+        text: JSON.stringify(structuredContent),
     };
 }
 function buildResourceLink(inlineResult, name) {
@@ -208,7 +321,7 @@ function buildEmbeddedResource(content, url, title) {
     if (!content)
         return null;
     const filename = cache.generateSafeFilename(url, title, undefined, '.md');
-    const uri = `file:///${filename}`;
+    const uri = new URL(filename, 'file:///').href;
     return {
         type: 'resource',
         resource: {
@@ -232,21 +345,20 @@ function appendResourceBlocks(params) {
     if (link)
         blocks.push(link);
 }
-function buildToolContentBlocks(structuredContent, _fromCache, inlineResult, resourceName, _cacheKey, fullContent, url, title) {
-    const blocks = [buildTextBlock(structuredContent)];
+function buildToolContentBlocks(params) {
+    const blocks = [
+        buildTextBlock(params.structuredContent),
+    ];
     appendResourceBlocks({
         blocks,
-        inlineResult,
-        resourceName,
-        url,
-        title,
-        fullContent,
+        inlineResult: params.inlineResult,
+        resourceName: params.resourceName,
+        url: params.url,
+        title: params.title,
+        fullContent: params.fullContent,
     });
     return blocks;
 }
-/* -------------------------------------------------------------------------------------------------
- * Fetch pipeline executor (normalize → raw-transform → cache → fetch → transform → persist)
- * ------------------------------------------------------------------------------------------------- */
 function resolveNormalizedUrl(url) {
     const { normalizedUrl: validatedUrl } = normalizeUrl(url);
     const { url: normalizedUrl, transformed } = transformToRawUrl(validatedUrl);
@@ -260,16 +372,16 @@ function logRawUrlTransformation(resolvedUrl) {
     });
 }
 function extractTitle(value) {
-    if (!isObject(value))
-        return undefined;
-    const { title } = value;
+    const record = asRecord(value);
+    const title = record ? record.title : undefined;
     return typeof title === 'string' ? title : undefined;
 }
-function logCacheMiss(reason, cacheNamespace, normalizedUrl) {
-    const log = reason === 'deserialize failure' ? logWarn : logDebug;
+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) {
@@ -283,7 +395,14 @@ function attemptCacheRetrieval(params) {
         logCacheMiss('missing deserializer', cacheNamespace, normalizedUrl);
         return null;
     }
-    const data = deserialize(cached.content);
+    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;
@@ -298,7 +417,7 @@ function attemptCacheRetrieval(params) {
     };
 }
 function persistCache(params) {
-    const { cacheKey, data, serialize, normalizedUrl } = params;
+    const { cacheKey, data, serialize, normalizedUrl, cacheNamespace, force } = params;
     if (!cacheKey)
         return;
     const serializer = serialize ?? JSON.stringify;
@@ -307,36 +426,49 @@ function persistCache(params) {
         url: normalizedUrl,
         ...(title === undefined ? {} : { title }),
     };
-    cache.set(cacheKey, serializer(data), metadata);
+    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);
-    const cachedResult = attemptCacheRetrieval({
-        cacheKey,
-        deserialize: options.deserialize,
-        cacheNamespace: options.cacheNamespace,
-        normalizedUrl: resolvedUrl.normalizedUrl,
-    });
-    if (cachedResult)
-        return cachedResult;
+    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 fetchOptions = options.signal === undefined ? {} : { signal: options.signal };
-    const html = await fetchNormalizedUrl(resolvedUrl.normalizedUrl, fetchOptions);
-    const data = await options.transform(html, resolvedUrl.normalizedUrl);
+    const { buffer, encoding } = await fetchNormalizedUrlBuffer(resolvedUrl.normalizedUrl, withSignal(options.signal));
+    const data = await options.transform({ buffer, encoding }, resolvedUrl.normalizedUrl);
     if (cache.isEnabled()) {
         persistCache({
             cacheKey,
             data,
             serialize: options.serialize,
             normalizedUrl: resolvedUrl.normalizedUrl,
+            cacheNamespace: options.cacheNamespace,
         });
     }
     return {
         data,
         fromCache: false,
         url: resolvedUrl.normalizedUrl,
+        originalUrl: resolvedUrl.originalUrl,
         fetchedAt: new Date().toISOString(),
         cacheKey,
     };
@@ -346,22 +478,38 @@ export async function performSharedFetch(options, deps = {}) {
     const pipelineOptions = {
         url: options.url,
         cacheNamespace: 'markdown',
-        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...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, pipeline.cacheKey ?? null);
+    if (inlineResult.truncated && !pipeline.fromCache && !cache.isEnabled()) {
+        persistCache({
+            cacheKey: pipeline.cacheKey ?? null,
+            data: pipeline.data,
+            serialize: options.serialize,
+            normalizedUrl: pipeline.url,
+            cacheNamespace: 'markdown',
+            force: true,
+        });
+    }
     return { pipeline, inlineResult };
 }
 /* -------------------------------------------------------------------------------------------------
  * Tool error mapping
  * ------------------------------------------------------------------------------------------------- */
-export function createToolErrorResponse(message, url) {
+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)],
@@ -385,57 +533,44 @@ function resolveToolErrorMessage(error, fallbackMessage) {
 }
 export function handleToolError(error, url, fallbackMessage = 'Operation failed') {
     const message = resolveToolErrorMessage(error, fallbackMessage);
-    return createToolErrorResponse(message, url);
-}
-function parseJsonRecord(input) {
-    try {
-        const parsed = JSON.parse(input);
-        return isObject(parsed) ? parsed : undefined;
-    }
-    catch {
-        return undefined;
+    if (error instanceof FetchError) {
+        return createToolErrorResponse(message, url, {
+            statusCode: error.statusCode,
+            details: error.details,
+        });
     }
+    return createToolErrorResponse(message, url);
 }
-function resolveMarkdownContent(parsed) {
-    const { markdown } = parsed;
-    if (typeof markdown === 'string')
-        return markdown;
-    const { content } = parsed;
-    if (typeof content === 'string')
-        return content;
-    return undefined;
-}
-function resolveOptionalTitle(parsed) {
-    const { title } = parsed;
-    if (title === undefined)
-        return undefined;
-    return typeof title === 'string' ? title : undefined;
-}
-function resolveTruncatedFlag(parsed) {
-    const { truncated } = parsed;
-    return typeof truncated === 'boolean' ? truncated : false;
-}
+const cachedMarkdownSchema = z
+    .object({
+    markdown: z.string().optional(),
+    content: z.string().optional(),
+    title: z.string().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 = parseJsonRecord(cached);
-    if (!parsed)
+    const parsed = safeJsonParse(cached);
+    const result = cachedMarkdownSchema.safeParse(parsed);
+    if (!result.success)
         return undefined;
-    const resolvedContent = resolveMarkdownContent(parsed);
-    if (resolvedContent === undefined)
-        return undefined;
-    const title = resolveOptionalTitle(parsed);
-    if (parsed.title !== undefined && title === undefined)
+    const markdown = result.data.markdown ?? result.data.content;
+    if (typeof markdown !== 'string')
         return undefined;
     return {
-        content: resolvedContent,
-        markdown: resolvedContent,
-        title,
-        truncated: resolveTruncatedFlag(parsed),
+        content: markdown,
+        markdown,
+        title: result.data.title,
+        truncated: result.data.truncated ?? false,
     };
 }
-const markdownTransform = async (html, url, signal) => {
-    const result = await transformHtmlToMarkdown(html, url, {
+const markdownTransform = async (input, url, signal, skipNoiseRemoval) => {
+    const result = await transformBufferToMarkdown(input.buffer, url, {
         includeMetadata: true,
-        ...(signal === undefined ? {} : { signal }),
+        encoding: input.encoding,
+        ...withSignal(signal),
+        ...(skipNoiseRemoval ? { skipNoiseRemoval: true } : {}),
     });
     return { ...result, content: result.markdown };
 };
@@ -450,16 +585,25 @@ function serializeMarkdownResult(result) {
  * fetch-url tool implementation
  * ------------------------------------------------------------------------------------------------- */
 function buildStructuredContent(pipeline, inlineResult, inputUrl) {
+    const truncated = inlineResult.truncated ?? pipeline.data.truncated;
     return {
-        url: pipeline.url,
+        url: pipeline.originalUrl ?? pipeline.url,
         resolvedUrl: pipeline.url,
         inputUrl,
         title: pipeline.data.title,
         markdown: inlineResult.content,
+        ...(truncated ? { truncated: true } : {}),
     };
 }
 function buildFetchUrlContentBlocks(structuredContent, pipeline, inlineResult) {
-    return buildToolContentBlocks(structuredContent, pipeline.fromCache, inlineResult, 'Fetched markdown', pipeline.cacheKey, pipeline.data.content, pipeline.url, pipeline.data.title);
+    return buildToolContentBlocks({
+        structuredContent,
+        inlineResult,
+        resourceName: 'Fetched markdown',
+        url: pipeline.url,
+        ...(pipeline.data.title !== undefined && { title: pipeline.data.title }),
+        fullContent: pipeline.data.content,
+    });
 }
 function buildResponse(pipeline, inlineResult, inputUrl) {
     const structuredContent = buildStructuredContent(pipeline, inlineResult, inputUrl);
@@ -469,15 +613,17 @@ function buildResponse(pipeline, inlineResult, inputUrl) {
         structuredContent,
     };
 }
-async function fetchPipeline(url, signal, progress) {
+async function fetchPipeline(url, signal, progress, skipNoiseRemoval, forceRefresh) {
     return performSharedFetch({
         url,
-        ...(signal === undefined ? {} : { signal }),
-        transform: async (html, normalizedUrl) => {
+        ...withSignal(signal),
+        ...(skipNoiseRemoval ? { cacheVary: { skipNoiseRemoval: true } } : {}),
+        ...(forceRefresh ? { forceRefresh: true } : {}),
+        transform: async ({ buffer, encoding }, normalizedUrl) => {
             if (progress) {
-                await progress.report(3, 'Transforming content');
+                void progress.report(3, 'Transforming content');
             }
-            return markdownTransform(html, normalizedUrl, signal);
+            return markdownTransform({ buffer, encoding }, normalizedUrl, signal, skipNoiseRemoval);
         },
         serialize: serializeMarkdownResult,
         deserialize: parseCachedMarkdownResult,
@@ -488,26 +634,19 @@ async function executeFetch(input, extra) {
     if (!url) {
         return createToolErrorResponse('URL is required', '');
     }
-    const { signal: extraSignal } = extra ?? {};
-    const { timeoutMs } = config.tools;
-    const signal = timeoutMs > 0
-        ? AbortSignal.any([
-            ...(extraSignal ? [extraSignal] : []),
-            AbortSignal.timeout(timeoutMs),
-        ])
-        : extraSignal;
+    const signal = buildToolAbortSignal(extra?.signal);
     const progress = createProgressReporter(extra);
-    await progress.report(1, 'Validating URL');
+    void progress.report(1, 'Validating URL');
     logDebug('Fetching URL', { url });
-    await progress.report(2, 'Fetching content');
-    const { pipeline, inlineResult } = await fetchPipeline(url, signal, progress);
+    void progress.report(2, 'Fetching content');
+    const { pipeline, inlineResult } = await fetchPipeline(url, signal, progress, input.skipNoiseRemoval, input.forceRefresh);
     if (pipeline.fromCache) {
-        await progress.report(3, 'Using cached content');
+        void progress.report(3, 'Using cached content');
     }
     if (inlineResult.error) {
         return createToolErrorResponse(inlineResult.error, url);
     }
-    await progress.report(4, 'Finalizing response');
+    void progress.report(4, 'Finalizing response');
     return buildResponse(pipeline, inlineResult, url);
 }
 export async function fetchUrlToolHandler(input, extra) {
@@ -564,26 +703,21 @@ function resolveSessionIdFromExtra(extra) {
     const { sessionId } = extra;
     if (typeof sessionId === 'string')
         return sessionId;
-    const { requestInfo } = extra;
-    if (!isObject(requestInfo))
-        return undefined;
-    const { headers } = requestInfo;
-    if (!isObject(headers))
-        return undefined;
-    const headerValue = headers['mcp-session-id'];
+    const headers = readNestedRecord(extra, ['requestInfo', 'headers']);
+    const headerValue = headers ? headers['mcp-session-id'] : undefined;
     return typeof headerValue === 'string' ? headerValue : undefined;
 }
 export function registerTools(server) {
-    if (config.tools.enabled.includes(FETCH_URL_TOOL_NAME)) {
-        server.registerTool(TOOL_DEFINITION.name, {
-            title: TOOL_DEFINITION.title,
-            description: TOOL_DEFINITION.description,
-            inputSchema: TOOL_DEFINITION.inputSchema,
-            outputSchema: TOOL_DEFINITION.outputSchema,
-            annotations: TOOL_DEFINITION.annotations,
-            execution: TOOL_DEFINITION.execution,
-            // Use specific tool icon here
-            icons: [TOOL_ICON],
-        }, withRequestContextIfMissing(TOOL_DEFINITION.handler));
-    }
+    if (!config.tools.enabled.includes(FETCH_URL_TOOL_NAME))
+        return;
+    server.registerTool(TOOL_DEFINITION.name, {
+        title: TOOL_DEFINITION.title,
+        description: TOOL_DEFINITION.description,
+        inputSchema: TOOL_DEFINITION.inputSchema,
+        outputSchema: TOOL_DEFINITION.outputSchema,
+        annotations: TOOL_DEFINITION.annotations,
+        execution: TOOL_DEFINITION.execution,
+        // Use specific tool icon here
+        icons: [TOOL_ICON],
+    }, withRequestContextIfMissing(TOOL_DEFINITION.handler));
 }