@j0hanz/superfetch 2.3.0 → 2.4.1

package/dist/observability.js

@@ -1,6 +1,10 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { config } from './config.js';
 const requestContext = new AsyncLocalStorage();
+let mcpServer;
+export function setMcpServer(server) {
+    mcpServer = server;
+}
 export function runWithRequestContext(context, fn) {
     return requestContext.run(context, fn);
 }
@@ -43,10 +47,31 @@ function shouldLog(level) {
     // All other levels always log
     return true;
 }
+function mapToMcpLevel(level) {
+    switch (level) {
+        case 'warn':
+            return 'warning';
+        case 'error':
+            return 'error';
+        case 'debug':
+            return 'debug';
+        case 'info':
+        default:
+            return 'info';
+    }
+}
 function writeLog(level, message, meta) {
     if (!shouldLog(level))
         return;
     process.stderr.write(`${formatLogEntry(level, message, meta)}\n`);
+    if (mcpServer) {
+        mcpServer.server
+            .sendLoggingMessage({
+            level: mapToMcpLevel(level),
+            data: meta ? { message, ...meta } : message,
+        })
+            .catch(() => { });
+    }
 }
 export function logInfo(message, meta) {
     writeLog('info', message, meta);

package/dist/tools.d.ts

@@ -1,5 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type MarkdownTransformResult } from './transform.js';
+import type { MarkdownTransformResult } from './transform-types.js';
 export interface FetchUrlInput {
     url: string;
 }
@@ -25,7 +25,6 @@ export interface ToolContentResourceBlock {
 }
 export type ToolContentBlockUnion = ToolContentBlock | ToolContentResourceLinkBlock | ToolContentResourceBlock;
 export interface ToolErrorResponse {
-    [x: string]: unknown;
     content: ToolContentBlockUnion[];
     structuredContent: {
         error: string;
@@ -34,7 +33,6 @@ export interface ToolErrorResponse {
     isError: true;
 }
 export interface ToolResponseBase {
-    [x: string]: unknown;
     content: ToolContentBlockUnion[];
     structuredContent?: Record<string, unknown>;
     isError?: boolean;
@@ -86,6 +84,10 @@ export interface ToolHandlerExtra {
 }
 export declare const FETCH_URL_TOOL_NAME = "fetch-url";
 export declare const FETCH_URL_TOOL_DESCRIPTION = "Fetches a webpage and converts it to clean Markdown format";
+interface ProgressReporter {
+    report: (progress: number, message: string) => Promise<void>;
+}
+export declare function createProgressReporter(extra?: ToolHandlerExtra): ProgressReporter;
 interface InlineContentResult {
     content?: string;
     contentSize: number;
@@ -123,5 +125,5 @@ type MarkdownPipelineResult = MarkdownTransformResult & {
 export declare function parseCachedMarkdownResult(cached: string): MarkdownPipelineResult | undefined;
 export declare function fetchUrlToolHandler(input: FetchUrlInput, extra?: ToolHandlerExtra): Promise<ToolResponseBase>;
 export declare function withRequestContextIfMissing<TParams, TResult, TExtra = unknown>(handler: (params: TParams, extra?: TExtra) => Promise<TResult>): (params: TParams, extra?: TExtra) => Promise<TResult>;
-export declare function registerTools(server: McpServer): void;
+export declare function registerTools(server: McpServer, serverIcon?: string): void;
 export {};

package/dist/tools.js

@@ -5,10 +5,11 @@ import { config } from './config.js';
 import { FetchError, getErrorMessage, isSystemError } from './errors.js';
 import { fetchNormalizedUrl, normalizeUrl, transformToRawUrl, } from './fetch.js';
 import { getRequestId, logDebug, logError, logWarn, runWithRequestContext, } from './observability.js';
-import { transformHtmlToMarkdown, } from './transform.js';
+import { transformHtmlToMarkdown } 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({
     url: z
         .url({ protocol: /^https?$/i })
@@ -46,7 +47,7 @@ const fetchUrlOutputSchema = z.strictObject({
 });
 export const FETCH_URL_TOOL_NAME = 'fetch-url';
 export const FETCH_URL_TOOL_DESCRIPTION = 'Fetches a webpage and converts it to clean Markdown format';
-function createProgressReporter(extra) {
+export function createProgressReporter(extra) {
     const token = extra?._meta?.progressToken ?? null;
     const sendNotification = extra?.sendNotification;
     if (token === null || !sendNotification) {
@@ -55,19 +56,33 @@ function createProgressReporter(extra) {
     return {
         report: async (progress, message) => {
             try {
-                await sendNotification({
-                    method: 'notifications/progress',
-                    params: {
-                        progressToken: token,
-                        progress,
-                        total: FETCH_PROGRESS_TOTAL,
-                        message,
-                    },
-                });
+                await Promise.race([
+                    sendNotification({
+                        method: 'notifications/progress',
+                        params: {
+                            progressToken: token,
+                            progress,
+                            total: FETCH_PROGRESS_TOTAL,
+                            message,
+                        },
+                    }),
+                    new Promise((_, reject) => {
+                        setTimeout(() => {
+                            reject(new Error('Progress notification timeout'));
+                        }, PROGRESS_NOTIFICATION_TIMEOUT_MS);
+                    }),
+                ]);
             }
             catch (error) {
-                logWarn('Failed to send progress notification', {
+                const isTimeout = error instanceof Error &&
+                    error.message === 'Progress notification timeout';
+                const logMessage = isTimeout
+                    ? 'Progress notification timed out'
+                    : 'Failed to send progress notification';
+                logWarn(logMessage, {
                     error: getErrorMessage(error),
+                    progress,
+                    message,
                 });
             }
         },
@@ -467,12 +482,23 @@ function resolveRequestIdFromExtra(extra) {
         return String(requestId);
     return undefined;
 }
-export function registerTools(server) {
+export function registerTools(server, serverIcon) {
     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,
+        ...(serverIcon
+            ? {
+                icons: [
+                    {
+                        src: serverIcon,
+                        mimeType: 'image/svg+xml',
+                        sizes: ['any'],
+                    },
+                ],
+            }
+            : {}),
     }, withRequestContextIfMissing(TOOL_DEFINITION.handler));
 }

package/dist/transform-types.d.ts

@@ -77,4 +77,42 @@ export interface TransformStageContext {
     readonly stage: string;
     readonly startTime: number;
     readonly url: string;
+    readonly budgetMs?: number;
+    readonly totalBudgetMs?: number;
 }
+/**
+ * Worker message types for transform workers.
+ */
+export interface TransformWorkerTransformMessage {
+    type: 'transform';
+    id: string;
+    html: string;
+    url: string;
+    includeMetadata: boolean;
+}
+export interface TransformWorkerCancelMessage {
+    type: 'cancel';
+    id: string;
+}
+export interface TransformWorkerResultMessage {
+    type: 'result';
+    id: string;
+    result: {
+        markdown: string;
+        title?: string;
+        truncated: boolean;
+    };
+}
+export interface TransformWorkerErrorMessage {
+    type: 'error';
+    id: string;
+    error: {
+        name: string;
+        message: string;
+        url: string;
+        statusCode?: number;
+        details?: Record<string, unknown>;
+    };
+}
+export type TransformWorkerIncomingMessage = TransformWorkerTransformMessage | TransformWorkerCancelMessage;
+export type TransformWorkerOutgoingMessage = TransformWorkerResultMessage | TransformWorkerErrorMessage;

package/dist/transform.d.ts

@@ -1,12 +1,12 @@
 import type { ExtractedArticle, ExtractedMetadata, ExtractionResult, MarkdownTransformResult, MetadataBlock, TransformOptions, TransformStageContext } from './transform-types.js';
-export { detectLanguageFromCode, resolveLanguageFromAttributes, } from './language-detection.js';
-export { cleanupMarkdownArtifacts, promoteOrphanHeadings, } from './markdown-cleanup.js';
-export { removeNoiseFromHtml } from './dom-noise-removal.js';
-export type { MetadataBlock, ExtractedArticle, ExtractedMetadata, ExtractionResult, MarkdownTransformResult, TransformOptions, TransformStageEvent, TransformStageContext, } from './transform-types.js';
-export declare function startTransformStage(url: string, stage: string): TransformStageContext | null;
+export interface StageBudget {
+    totalBudgetMs: number;
+    elapsedMs: number;
+}
+export declare function startTransformStage(url: string, stage: string, budget?: StageBudget): TransformStageContext | null;
 export declare function endTransformStage(context: TransformStageContext | null, options?: {
     truncated?: boolean;
-}): void;
+}): number;
 export declare function extractContent(html: string, url: string, options?: {
     extractArticle?: boolean;
     signal?: AbortSignal;
@@ -22,4 +22,10 @@ export declare function determineContentExtractionSource(article: ExtractedArtic
 export declare function createContentMetadataBlock(url: string, article: ExtractedArticle | null, extractedMeta: ExtractedMetadata, shouldExtractFromArticle: boolean, includeMetadata: boolean): MetadataBlock | undefined;
 export declare function transformHtmlToMarkdownInProcess(html: string, url: string, options: TransformOptions): MarkdownTransformResult;
 export declare function shutdownTransformWorkerPool(): Promise<void>;
+export interface TransformPoolStats {
+    queueDepth: number;
+    activeWorkers: number;
+    capacity: number;
+}
+export declare function getTransformPoolStats(): TransformPoolStats | null;
 export declare function transformHtmlToMarkdown(html: string, url: string, options: TransformOptions): Promise<MarkdownTransformResult>;