research-powerpack-mcp 3.0.14 → 3.1.1

package/dist/tools/scrape.js

@@ -1,111 +1,174 @@
 /**
  * Scrape Links Tool Handler
+ * Implements robust error handling that NEVER crashes the MCP server
  */
 import { ScraperClient } from '../clients/scraper.js';
 import { MarkdownCleaner } from '../services/markdown-cleaner.js';
 import { createLLMProcessor, processContentWithLLM } from '../services/llm-processor.js';
 import { removeMetaTags } from '../utils/markdown-formatter.js';
 import { SCRAPER } from '../config/index.js';
+import { classifyError } from '../utils/errors.js';
 function calculateTokenAllocation(urlCount) {
+    if (urlCount <= 0)
+        return SCRAPER.MAX_TOKENS_BUDGET;
     return Math.floor(SCRAPER.MAX_TOKENS_BUDGET / urlCount);
 }
 function enhanceExtractionInstruction(instruction) {
     const base = instruction || 'Extract the main content and key information from this page.';
     return `${base}\n\n${SCRAPER.EXTRACTION_SUFFIX}`;
 }
+/**
+ * Safe logger wrapper - NEVER throws
+ */
+async function safeLog(logger, sessionId, level, message) {
+    if (!logger || !sessionId)
+        return;
+    try {
+        await logger(level, message, sessionId);
+    }
+    catch {
+        // Silently ignore logger errors - they should never crash the tool
+        console.error(`[Scrape Tool] Logger failed: ${message}`);
+    }
+}
+/**
+ * Handle scrape links request
+ * NEVER throws - always returns a valid response with content and metadata
+ */
 export async function handleScrapeLinks(params, options = {}) {
     const { sessionId, logger } = options;
     const startTime = Date.now();
+    // Helper to create error response
+    const createErrorResponse = (message, executionTime) => ({
+        content: `# ❌ Scraping Failed\n\n${message}`,
+        structuredContent: {
+            content: `# ❌ Scraping Failed\n\n${message}`,
+            metadata: {
+                total_urls: params.urls?.length || 0,
+                successful: 0,
+                failed: params.urls?.length || 0,
+                total_credits: 0,
+                execution_time_ms: executionTime,
+            },
+        },
+    });
+    // Validate params
+    if (!params.urls || params.urls.length === 0) {
+        return createErrorResponse('No URLs provided', Date.now() - startTime);
+    }
+    // Filter out invalid URLs early
+    const validUrls = [];
+    const invalidUrls = [];
+    for (const url of params.urls) {
+        try {
+            new URL(url);
+            validUrls.push(url);
+        }
+        catch {
+            invalidUrls.push(url);
+        }
+    }
+    if (validUrls.length === 0) {
+        return createErrorResponse(`All ${params.urls.length} URLs are invalid`, Date.now() - startTime);
+    }
+    const tokensPerUrl = calculateTokenAllocation(validUrls.length);
+    const totalBatches = Math.ceil(validUrls.length / SCRAPER.BATCH_SIZE);
+    await safeLog(logger, sessionId, 'info', `Starting scrape: ${validUrls.length} URL(s), ${tokensPerUrl} tokens/URL, ${totalBatches} batch(es)`);
+    // Initialize clients safely
+    let client;
     try {
-        const tokensPerUrl = calculateTokenAllocation(params.urls.length);
-        const totalBatches = Math.ceil(params.urls.length / SCRAPER.BATCH_SIZE);
-        if (sessionId && logger) {
-            await logger('info', `Starting scrape: ${params.urls.length} URL(s), ${tokensPerUrl} tokens/URL, ${totalBatches} batch(es)`, sessionId);
+        client = new ScraperClient();
+    }
+    catch (error) {
+        const err = classifyError(error);
+        return createErrorResponse(`Failed to initialize scraper: ${err.message}`, Date.now() - startTime);
+    }
+    const markdownCleaner = new MarkdownCleaner();
+    const llmProcessor = createLLMProcessor(); // Returns null if not configured
+    const enhancedInstruction = params.use_llm
+        ? enhanceExtractionInstruction(params.what_to_extract)
+        : undefined;
+    // Scrape URLs - scrapeMultiple NEVER throws
+    const results = await client.scrapeMultiple(validUrls, { timeout: params.timeout });
+    await safeLog(logger, sessionId, 'info', `Scraping complete. Processing ${results.length} results...`);
+    let successful = 0;
+    let failed = 0;
+    let totalCredits = 0;
+    let llmErrors = 0;
+    const contents = [];
+    // Add invalid URLs to failed count
+    for (const invalidUrl of invalidUrls) {
+        failed++;
+        contents.push(`## ${invalidUrl}\n\n❌ Invalid URL format`);
+    }
+    // Process each result
+    for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        if (!result) {
+            failed++;
+            contents.push(`## Unknown URL\n\n❌ No result returned`);
+            continue;
         }
-        const client = new ScraperClient();
-        const markdownCleaner = new MarkdownCleaner();
-        const llmProcessor = createLLMProcessor();
-        const enhancedInstruction = params.use_llm
-            ? enhanceExtractionInstruction(params.what_to_extract)
-            : undefined;
-        const results = await client.scrapeMultiple(params.urls, { timeout: params.timeout });
-        if (sessionId && logger) {
-            await logger('info', `Scraping complete. Processing ${results.length} results...`, sessionId);
+        await safeLog(logger, sessionId, 'info', `[${i + 1}/${results.length}] Processing ${result.url}`);
+        // Check for errors in result
+        if (result.error || result.statusCode < 200 || result.statusCode >= 300) {
+            failed++;
+            const errorMsg = result.error?.message || result.content || `HTTP ${result.statusCode}`;
+            contents.push(`## ${result.url}\n\n❌ Failed to scrape: ${errorMsg}`);
+            await safeLog(logger, sessionId, 'error', `[${i + 1}/${results.length}] Failed: ${errorMsg}`);
+            continue;
         }
-        let successful = 0;
-        let failed = 0;
-        let totalCredits = 0;
-        const contents = [];
-        for (let i = 0; i < results.length; i++) {
-            const result = results[i];
-            if (!result)
-                continue;
-            if (sessionId && logger) {
-                await logger('info', `[${i + 1}/${results.length}] Processing ${result.url}`, sessionId);
-            }
-            if (result.statusCode >= 200 && result.statusCode < 300) {
-                successful++;
-                totalCredits += result.credits;
-                let content = markdownCleaner.processContent(result.content);
-                if (params.use_llm && llmProcessor) {
-                    if (sessionId && logger) {
-                        await logger('info', `[${i + 1}/${results.length}] Applying LLM extraction (${tokensPerUrl} tokens)...`, sessionId);
-                    }
-                    const llmResult = await processContentWithLLM(content, { use_llm: params.use_llm, what_to_extract: enhancedInstruction, max_tokens: tokensPerUrl }, llmProcessor);
-                    content = llmResult.content;
-                    if (sessionId && logger) {
-                        await logger('info', `[${i + 1}/${results.length}] LLM processing ${llmResult.processed ? 'complete' : 'skipped'}`, sessionId);
-                    }
-                }
-                content = removeMetaTags(content);
-                contents.push(`## ${result.url}\n\n${content}`);
+        // Success case
+        successful++;
+        totalCredits += result.credits;
+        // Process content safely
+        let content;
+        try {
+            content = markdownCleaner.processContent(result.content);
+        }
+        catch {
+            // If markdown cleaning fails, use raw content
+            content = result.content;
+        }
+        // Apply LLM extraction if enabled - processContentWithLLM NEVER throws
+        if (params.use_llm && llmProcessor) {
+            await safeLog(logger, sessionId, 'info', `[${i + 1}/${results.length}] Applying LLM extraction (${tokensPerUrl} tokens)...`);
+            const llmResult = await processContentWithLLM(content, { use_llm: params.use_llm, what_to_extract: enhancedInstruction, max_tokens: tokensPerUrl }, llmProcessor);
+            if (llmResult.processed) {
+                content = llmResult.content;
+                await safeLog(logger, sessionId, 'info', `[${i + 1}/${results.length}] LLM extraction complete`);
             }
             else {
-                failed++;
-                contents.push(`## ${result.url}\n\n❌ Failed to scrape: ${result.content}`);
-                if (sessionId && logger) {
-                    await logger('error', `[${i + 1}/${results.length}] Failed: ${result.statusCode}`, sessionId);
-                }
+                llmErrors++;
+                await safeLog(logger, sessionId, 'info', `[${i + 1}/${results.length}] LLM extraction skipped: ${llmResult.error || 'unknown reason'}`);
+                // Continue with original content - graceful degradation
             }
         }
-        const executionTime = Date.now() - startTime;
-        if (sessionId && logger) {
-            await logger('info', `Completed: ${successful} successful, ${failed} failed, ${totalCredits} credits used`, sessionId);
+        // Remove meta tags safely
+        try {
+            content = removeMetaTags(content);
         }
-        const allocationHeader = `**Token Allocation:** ${tokensPerUrl.toLocaleString()} tokens/URL (${params.urls.length} URLs, ${SCRAPER.MAX_TOKENS_BUDGET.toLocaleString()} total budget)`;
-        const statusHeader = `**Status:** ✅ ${successful} successful | ❌ ${failed} failed | 📦 ${totalBatches} batch(es)`;
-        const formattedContent = `# Scraped Content (${params.urls.length} URLs)\n\n${allocationHeader}\n${statusHeader}\n\n---\n\n${contents.join('\n\n---\n\n')}`;
-        const metadata = {
-            total_urls: params.urls.length,
-            successful,
-            failed,
-            total_credits: totalCredits,
-            execution_time_ms: executionTime,
-            tokens_per_url: tokensPerUrl,
-            total_token_budget: SCRAPER.MAX_TOKENS_BUDGET,
-            batches_processed: totalBatches,
-        };
-        return { content: formattedContent, structuredContent: { content: formattedContent, metadata } };
-    }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        if (sessionId && logger) {
-            await logger('error', errorMessage, sessionId);
+        catch {
+            // If this fails, just use the content as-is
         }
-        const executionTime = Date.now() - startTime;
-        return {
-            content: `# ❌ Scraping Failed\n\n${errorMessage}`,
-            structuredContent: {
-                content: `# ❌ Scraping Failed\n\n${errorMessage}`,
-                metadata: {
-                    total_urls: params.urls.length,
-                    successful: 0,
-                    failed: params.urls.length,
-                    total_credits: 0,
-                    execution_time_ms: executionTime,
-                },
-            },
-        };
+        contents.push(`## ${result.url}\n\n${content}`);
     }
+    const executionTime = Date.now() - startTime;
+    await safeLog(logger, sessionId, 'info', `Completed: ${successful} successful, ${failed} failed, ${totalCredits} credits used`);
+    // Build response
+    const allocationHeader = `**Token Allocation:** ${tokensPerUrl.toLocaleString()} tokens/URL (${params.urls.length} URLs, ${SCRAPER.MAX_TOKENS_BUDGET.toLocaleString()} total budget)`;
+    const statusHeader = `**Status:** ✅ ${successful} successful | ❌ ${failed} failed | 📦 ${totalBatches} batch(es)${llmErrors > 0 ? ` | ⚠️ ${llmErrors} LLM extraction failures` : ''}`;
+    const formattedContent = `# Scraped Content (${params.urls.length} URLs)\n\n${allocationHeader}\n${statusHeader}\n\n---\n\n${contents.join('\n\n---\n\n')}`;
+    const metadata = {
+        total_urls: params.urls.length,
+        successful,
+        failed,
+        total_credits: totalCredits,
+        execution_time_ms: executionTime,
+        tokens_per_url: tokensPerUrl,
+        total_token_budget: SCRAPER.MAX_TOKENS_BUDGET,
+        batches_processed: totalBatches,
+    };
+    return { content: formattedContent, structuredContent: { content: formattedContent, metadata } };
 }
 //# sourceMappingURL=scrape.js.map

package/dist/tools/scrape.js.map

@@ -1 +1 @@
-{"version":3,"file":"scrape.js","sourceRoot":"","sources":["../../src/tools/scrape.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scrape.js","sourceRoot":"","sources":["../../src/tools/scrape.ts"],"names":[],"mappings":"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"}

package/dist/utils/errors.d.ts

@@ -1,5 +1,83 @@
 /**
- * Simple error handling for API requests
+ * Robust error handling utilities for MCP server
+ * Ensures the server NEVER crashes and always returns structured responses
+ */
+export declare const ErrorCode: {
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly AUTH_ERROR: "AUTH_ERROR";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly QUOTA_EXCEEDED: "QUOTA_EXCEEDED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly PARSE_ERROR: "PARSE_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+export type ErrorCodeType = typeof ErrorCode[keyof typeof ErrorCode];
+export interface StructuredError {
+    code: ErrorCodeType;
+    message: string;
+    retryable: boolean;
+    statusCode?: number;
+    cause?: string;
+}
+export interface RetryOptions {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    retryableStatuses: number[];
+    onRetry?: (attempt: number, error: StructuredError, delayMs: number) => void;
+}
+export declare const DEFAULT_RETRY_OPTIONS: RetryOptions;
+/**
+ * Classify any error into a structured format
+ * NEVER throws - always returns a valid StructuredError
+ */
+export declare function classifyError(error: unknown): StructuredError;
+/**
+ * Calculate delay with exponential backoff and jitter
+ */
+export declare function calculateBackoff(attempt: number, options: RetryOptions): number;
+/**
+ * Sleep utility that respects abort signals
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Execute a function with retry logic
+ * NEVER throws on final failure - returns error result instead
+ */
+export declare function withRetry<T>(fn: (signal: AbortSignal) => Promise<T>, options?: Partial<RetryOptions>): Promise<{
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: StructuredError;
+    attempts: number;
+}>;
+/**
+ * Wrap a fetch call with timeout via AbortController
+ */
+export declare function fetchWithTimeout(url: string, options?: RequestInit & {
+    timeoutMs?: number;
+}): Promise<Response>;
+/**
+ * Safely execute any function, NEVER throws
+ */
+export declare function safeExecute<T>(fn: () => Promise<T>, fallback: T): Promise<{
+    data: T;
+    error?: StructuredError;
+}>;
+/**
+ * Safely parse JSON, NEVER throws
+ */
+export declare function safeJsonParse<T>(text: string, fallback: T): {
+    data: T;
+    error?: string;
+};
+/**
+ * @deprecated Use classifyError instead
  */
 export declare function createSimpleError(error: unknown): {
     message: string;

package/dist/utils/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA6BnF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,eAAO,MAAM,SAAS;;;;;;;;;;;;CAiBZ,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,OAAO,SAAS,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAMrE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9E;AAED,eAAO,MAAM,qBAAqB,EAAE,YAKnC,CAAC;AAMF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CA4F7D;AAyCD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,CAI/E;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAcrE;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EACvC,OAAO,GAAE,OAAO,CAAC,YAAY,CAAM,GAClC,OAAO,CAAC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAqCpG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,WAAW,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACjD,OAAO,CAAC,QAAQ,CAAC,CAcnB;AAMD;;GAEG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,QAAQ,EAAE,CAAC,GACV,OAAO,CAAC;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,eAAe,CAAA;CAAE,CAAC,CAO/C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAMvF;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAGnF"}