@j0hanz/fetch-url-mcp 0.0.1

package/dist/tools.js

@@ -0,0 +1,812 @@
+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 { getRequestId, logDebug, logError, logWarn, runWithRequestContext, } from './observability.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;
+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'),
+    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.'),
+});
+const fetchUrlOutputSchema = z.strictObject({
+    url: z
+        .string()
+        .min(1)
+        .max(config.constants.maxUrlLength)
+        .describe('The fetched URL'),
+    inputUrl: z
+        .string()
+        .max(config.constants.maxUrlLength)
+        .optional()
+        .describe('The original URL provided by the caller'),
+    resolvedUrl: z
+        .string()
+        .max(config.constants.maxUrlLength)
+        .optional()
+        .describe('The normalized or transformed URL that was fetched'),
+    finalUrl: z
+        .string()
+        .max(config.constants.maxUrlLength)
+        .optional()
+        .describe('The final response URL after redirects'),
+    title: z.string().max(512).optional().describe('Page title'),
+    metadata: z
+        .strictObject({
+        title: z.string().max(512).optional().describe('Detected page title'),
+        description: z
+            .string()
+            .max(2048)
+            .optional()
+            .describe('Detected page description'),
+        author: z.string().max(512).optional().describe('Detected page author'),
+        image: z
+            .string()
+            .max(config.constants.maxUrlLength)
+            .optional()
+            .describe('Detected page preview image URL'),
+        favicon: z
+            .string()
+            .max(config.constants.maxUrlLength)
+            .optional()
+            .describe('Detected page favicon URL'),
+        publishedAt: z
+            .string()
+            .max(64)
+            .optional()
+            .describe('Detected publication date (if present)'),
+        modifiedAt: z
+            .string()
+            .max(64)
+            .optional()
+            .describe('Detected last modified date (if present)'),
+    })
+        .optional()
+        .describe('Detected metadata extracted from page markup'),
+    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'),
+    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'),
+});
+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.
+`.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 only)
+ * ------------------------------------------------------------------------------------------------- */
+function buildTextBlock(structuredContent) {
+    return {
+        type: 'text',
+        text: JSON.stringify(structuredContent),
+    };
+}
+function buildToolContentBlocks(structuredContent) {
+    return [buildTextBlock(structuredContent)];
+}
+function resolveNormalizedUrl(url) {
+    const { normalizedUrl: validatedUrl } = normalizeUrl(url);
+    const { url: normalizedUrl, transformed } = transformToRawUrl(validatedUrl);
+    return { normalizedUrl, originalUrl: validatedUrl, transformed };
+}
+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 });
+    return {
+        data,
+        fromCache: true,
+        url: normalizedUrl,
+        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 };
+}
+/* -------------------------------------------------------------------------------------------------
+ * Tool error mapping
+ * ------------------------------------------------------------------------------------------------- */
+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 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;
+}
+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);
+    return {
+        content: markdown,
+        markdown,
+        title: result.data.title,
+        ...(metadata ? { metadata } : {}),
+        truncated: result.data.truncated ?? false,
+    };
+}
+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) {
+    return JSON.stringify({
+        markdown: result.markdown,
+        title: result.title,
+        metadata: result.metadata,
+        truncated: result.truncated,
+    });
+}
+/* -------------------------------------------------------------------------------------------------
+ * fetch-url tool implementation
+ * ------------------------------------------------------------------------------------------------- */
+function buildStructuredContent(pipeline, inlineResult, inputUrl) {
+    const truncated = inlineResult.truncated ?? pipeline.data.truncated;
+    let markdown = inlineResult.content;
+    if (pipeline.data.truncated &&
+        !inlineResult.truncated &&
+        typeof markdown === 'string') {
+        markdown = appendTruncationMarker(markdown, TRUNCATION_MARKER);
+    }
+    const { metadata } = pipeline.data;
+    return {
+        url: pipeline.originalUrl ?? pipeline.url,
+        resolvedUrl: pipeline.url,
+        ...(pipeline.finalUrl ? { finalUrl: pipeline.finalUrl } : {}),
+        inputUrl,
+        title: pipeline.data.title,
+        ...(metadata ? { metadata } : {}),
+        markdown,
+        fromCache: pipeline.fromCache,
+        fetchedAt: pipeline.fetchedAt,
+        contentSize: inlineResult.contentSize,
+        ...(truncated ? { truncated: true } : {}),
+    };
+}
+function buildFetchUrlContentBlocks(structuredContent) {
+    return buildToolContentBlocks(structuredContent);
+}
+function buildResponse(pipeline, inlineResult, inputUrl) {
+    const structuredContent = buildStructuredContent(pipeline, inlineResult, inputUrl);
+    const content = buildFetchUrlContentBlocks(structuredContent);
+    // 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,
+        });
+    }
+    return {
+        content,
+        structuredContent,
+    };
+}
+async function fetchPipeline(url, signal, progress, skipNoiseRemoval, forceRefresh, maxInlineChars) {
+    return performSharedFetch({
+        url,
+        ...withSignal(signal),
+        ...(skipNoiseRemoval ? { cacheVary: { skipNoiseRemoval: true } } : {}),
+        ...(forceRefresh ? { forceRefresh: true } : {}),
+        ...(maxInlineChars !== undefined ? { maxInlineChars } : {}),
+        transform: async ({ buffer, encoding, truncated }, normalizedUrl) => {
+            if (progress) {
+                void progress.report(3, 'Transforming content');
+            }
+            return markdownTransform({ buffer, encoding, ...(truncated ? { truncated } : {}) }, normalizedUrl, signal, skipNoiseRemoval);
+        },
+        serialize: serializeMarkdownResult,
+        deserialize: parseCachedMarkdownResult,
+    });
+}
+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');
+    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');
+    }
+    void progress.report(4, 'Finalizing response');
+    return buildResponse(pipeline, inlineResult, url);
+}
+export async function fetchUrlToolHandler(input, extra) {
+    return executeFetch(input, extra).catch((error) => {
+        logError('fetch-url tool error', error instanceof Error ? error : undefined);
+        return handleToolError(error, input.url, 'Failed to fetch URL');
+    });
+}
+const TOOL_DEFINITION = {
+    name: FETCH_URL_TOOL_NAME,
+    title: 'Fetch URL',
+    description: FETCH_URL_TOOL_DESCRIPTION,
+    inputSchema: fetchUrlInputSchema,
+    outputSchema: fetchUrlOutputSchema,
+    handler: fetchUrlToolHandler,
+    execution: {
+        taskSupport: 'optional',
+    },
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+};
+export function withRequestContextIfMissing(handler) {
+    return async (params, extra) => {
+        const existingRequestId = getRequestId();
+        if (existingRequestId) {
+            return handler(params, extra);
+        }
+        const derivedRequestId = resolveRequestIdFromExtra(extra) ?? randomUUID();
+        const derivedSessionId = resolveSessionIdFromExtra(extra);
+        return runWithRequestContext({
+            requestId: derivedRequestId,
+            operationId: derivedRequestId,
+            ...(derivedSessionId ? { sessionId: derivedSessionId } : {}),
+        }, () => handler(params, extra));
+    };
+}
+function resolveRequestIdFromExtra(extra) {
+    if (!isObject(extra))
+        return undefined;
+    const { requestId } = extra;
+    if (typeof requestId === 'string')
+        return requestId;
+    if (typeof requestId === 'number')
+        return String(requestId);
+    return undefined;
+}
+function resolveSessionIdFromExtra(extra) {
+    if (!isObject(extra))
+        return undefined;
+    const { sessionId } = extra;
+    if (typeof sessionId === 'string')
+        return sessionId;
+    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))
+        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));
+}