mcp-researchpowerpack 3.6.9

package/dist/tools/research.js

@@ -0,0 +1,194 @@
+/**
+ * Deep Research Tool Handler - Batch processing with dynamic token allocation
+ * Implements robust error handling that NEVER crashes
+ */
+import { ResearchClient } from '../clients/research.js';
+import { FileAttachmentService } from '../services/file-attachment.js';
+import { RESEARCH } from '../config/index.js';
+import { classifyError } from '../utils/errors.js';
+import { pMap } from '../utils/concurrency.js';
+import { mcpLog, formatSuccess, formatError, formatBatchHeader, formatDuration, truncateText, TOKEN_BUDGETS, calculateTokenAllocation, } from './utils.js';
+// Constants
+const MIN_QUESTIONS = 1; // Allow single question for flexibility
+const MAX_QUESTIONS = 10;
+const SYSTEM_PROMPT = `You are an expert research consultant. Provide evidence-based, multi-perspective analysis.
+
+METHODOLOGY:
+- SOURCE DIVERSITY: Official docs, papers, blogs, case studies
+- CURRENT + HISTORICAL: Latest developments AND context
+- MULTIPLE PERSPECTIVES: Different approaches with pros/cons
+- EVIDENCE-BASED: Claims backed by citations
+
+FORMAT (high info density):
+- CURRENT STATE: Status quo, what we know
+- KEY INSIGHTS: Most important findings with evidence
+- TRADE-OFFS: Competing priorities honestly analyzed
+- PRACTICAL IMPLICATIONS: Real-world application
+- WHAT'S CHANGING: Recent developments
+
+Be dense with insights, light on filler. Use examples and citations.`;
+/**
+ * Handle deep research request
+ * NEVER throws - always returns a valid response
+ */
+export async function handleDeepResearch(params) {
+    const startTime = Date.now();
+    const questions = params.questions || [];
+    // Validation
+    if (questions.length < MIN_QUESTIONS) {
+        return {
+            content: formatError({
+                code: 'MIN_QUESTIONS',
+                message: `Minimum ${MIN_QUESTIONS} research question(s) required. Received: ${questions.length}`,
+                toolName: 'deep_research',
+                howToFix: ['Add at least one question with detailed context'],
+            }),
+            structuredContent: { error: true, message: `Minimum ${MIN_QUESTIONS} question(s) required` },
+        };
+    }
+    if (questions.length > MAX_QUESTIONS) {
+        return {
+            content: formatError({
+                code: 'MAX_QUESTIONS',
+                message: `Maximum ${MAX_QUESTIONS} research questions allowed. Received: ${questions.length}`,
+                toolName: 'deep_research',
+                howToFix: [`Remove ${questions.length - MAX_QUESTIONS} question(s)`],
+            }),
+            structuredContent: { error: true, message: `Maximum ${MAX_QUESTIONS} questions allowed` },
+        };
+    }
+    const tokensPerQuestion = calculateTokenAllocation(questions.length, TOKEN_BUDGETS.RESEARCH);
+    mcpLog('info', `Starting batch research: ${questions.length} questions, ${tokensPerQuestion.toLocaleString()} tokens/question`, 'research');
+    // Initialize client safely
+    let client;
+    try {
+        client = new ResearchClient();
+    }
+    catch (error) {
+        const err = classifyError(error);
+        return {
+            content: formatError({
+                code: 'CLIENT_INIT_FAILED',
+                message: `Failed to initialize research client: ${err.message}`,
+                toolName: 'deep_research',
+                howToFix: ['Check OPENROUTER_API_KEY is set'],
+            }),
+            structuredContent: { error: true, message: `Failed to initialize: ${err.message}` },
+        };
+    }
+    const fileService = new FileAttachmentService();
+    const results = [];
+    // Process questions with bounded concurrency (max 3 concurrent LLM calls)
+    const allResults = await pMap(questions, async (q, index) => {
+        try {
+            // Enhance question with file attachments if present
+            let enhancedQuestion = q.question;
+            if (q.file_attachments && q.file_attachments.length > 0) {
+                try {
+                    const attachmentsMarkdown = await fileService.formatAttachments(q.file_attachments);
+                    enhancedQuestion = q.question + attachmentsMarkdown;
+                }
+                catch {
+                    // If attachment processing fails, continue with original question
+                    mcpLog('warning', `Failed to process attachments for question ${index + 1}`, 'research');
+                }
+            }
+            // ResearchClient.research() returns error in response instead of throwing
+            const response = await client.research({
+                question: enhancedQuestion,
+                systemPrompt: SYSTEM_PROMPT,
+                reasoningEffort: RESEARCH.REASONING_EFFORT,
+                maxSearchResults: Math.min(RESEARCH.MAX_URLS, 20),
+                maxTokens: tokensPerQuestion,
+            });
+            // Check if response contains an error
+            if (response.error) {
+                return {
+                    question: q.question,
+                    content: response.content || '',
+                    success: false,
+                    error: response.error.message,
+                };
+            }
+            return {
+                question: q.question,
+                content: response.content || '',
+                success: !!response.content,
+                tokensUsed: response.usage?.totalTokens,
+                error: response.content ? undefined : 'Empty response received',
+            };
+        }
+        catch (error) {
+            // Safety net - ResearchClient should not throw
+            const structuredError = classifyError(error);
+            return {
+                question: q.question,
+                content: '',
+                success: false,
+                error: structuredError.message,
+            };
+        }
+    }, 3); // Max 3 concurrent research calls
+    results.push(...allResults);
+    // Build markdown output
+    const successful = results.filter(r => r.success);
+    const failed = results.filter(r => !r.success);
+    const totalTokens = successful.reduce((sum, r) => sum + (r.tokensUsed || 0), 0);
+    const executionTime = Date.now() - startTime;
+    // Build 70/20/10 response
+    const batchHeader = formatBatchHeader({
+        title: `Deep Research Results`,
+        totalItems: questions.length,
+        successful: successful.length,
+        failed: failed.length,
+        tokensPerItem: tokensPerQuestion,
+        extras: {
+            'Total tokens used': totalTokens.toLocaleString(),
+        },
+    });
+    // Build questions data section
+    const questionsData = [];
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        const preview = truncateText(r.question, 100);
+        questionsData.push(`## Question ${i + 1}: ${preview}\n`);
+        if (r.success) {
+            questionsData.push(r.content);
+            if (r.tokensUsed) {
+                questionsData.push(`\n*Tokens used: ${r.tokensUsed.toLocaleString()}*`);
+            }
+        }
+        else {
+            questionsData.push(`**❌ Error:** ${r.error}`);
+        }
+        questionsData.push('\n---\n');
+    }
+    const nextSteps = [
+        successful.length > 0 ? 'Scrape mentioned sources: scrape_links(urls=[...extracted URLs...], use_llm=true)' : null,
+        failed.length > 0 ? 'Retry failed questions with more specific context' : null,
+        'Search Reddit for community perspective: search_reddit(queries=[...related topics...])',
+    ].filter(Boolean);
+    const formattedContent = formatSuccess({
+        title: `Research Complete (${successful.length}/${questions.length})`,
+        summary: batchHeader,
+        data: questionsData.join('\n'),
+        nextSteps,
+        metadata: {
+            'Execution time': formatDuration(executionTime),
+            'Token budget': TOKEN_BUDGETS.RESEARCH.toLocaleString(),
+        },
+    });
+    mcpLog('info', `Research completed: ${successful.length}/${questions.length} successful, ${totalTokens.toLocaleString()} tokens`, 'research');
+    return {
+        content: formattedContent,
+        structuredContent: {
+            totalQuestions: questions.length,
+            successful: successful.length,
+            failed: failed.length,
+            tokensPerQuestion,
+            totalTokensUsed: totalTokens,
+            results,
+        },
+    };
+}
+//# sourceMappingURL=research.js.map

package/dist/tools/research.js.map

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

package/dist/tools/scrape.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Scrape Links Tool Handler
+ * Implements robust error handling that NEVER crashes the MCP server
+ */
+import type { ScrapeLinksParams, ScrapeLinksOutput } from '../schemas/scrape-links.js';
+/**
+ * Handle scrape links request
+ * NEVER throws - always returns a valid response with content and metadata
+ */
+export declare function handleScrapeLinks(params: ScrapeLinksParams): Promise<{
+    content: string;
+    structuredContent: ScrapeLinksOutput;
+}>;
+//# sourceMappingURL=scrape.d.ts.map

package/dist/tools/scrape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrape.d.ts","sourceRoot":"","sources":["../../src/tools/scrape.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAiCvF;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,iBAAiB,CAAA;CAAE,CAAC,CAoNpE"}

package/dist/tools/scrape.js

@@ -0,0 +1,201 @@
+/**
+ * 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 { getToolConfig } from '../config/loader.js';
+import { classifyError } from '../utils/errors.js';
+import { pMap } from '../utils/concurrency.js';
+import { mcpLog, formatSuccess, formatError, formatBatchHeader, formatDuration, TOKEN_BUDGETS, calculateTokenAllocation, } from './utils.js';
+// Module-level singleton - MarkdownCleaner is stateless
+const markdownCleaner = new MarkdownCleaner();
+// Get extraction suffix from YAML config (fallback to hardcoded if not found)
+function getExtractionSuffix() {
+    const config = getToolConfig('scrape_links');
+    return config?.limits?.extraction_suffix || SCRAPER.EXTRACTION_SUFFIX;
+}
+function enhanceExtractionInstruction(instruction) {
+    const base = instruction || 'Extract the main content and key information from this page.';
+    return `${base}\n\n${getExtractionSuffix()}`;
+}
+/**
+ * Handle scrape links request
+ * NEVER throws - always returns a valid response with content and metadata
+ */
+export async function handleScrapeLinks(params) {
+    const startTime = Date.now();
+    // Helper to create error response
+    const createErrorResponse = (code, message, retryable = false) => ({
+        content: formatError({
+            code,
+            message,
+            retryable,
+            toolName: 'scrape_links',
+            howToFix: code === 'NO_URLS' ? ['Provide at least one valid URL'] : undefined,
+        }),
+        structuredContent: {
+            content: message,
+            metadata: {
+                total_urls: params.urls?.length || 0,
+                successful: 0,
+                failed: params.urls?.length || 0,
+                total_credits: 0,
+                execution_time_ms: Date.now() - startTime,
+            },
+        },
+    });
+    // Validate params
+    if (!params.urls || params.urls.length === 0) {
+        return createErrorResponse('NO_URLS', 'No URLs provided');
+    }
+    // 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('INVALID_URLS', `All ${params.urls.length} URLs are invalid`);
+    }
+    const tokensPerUrl = calculateTokenAllocation(validUrls.length, TOKEN_BUDGETS.SCRAPER);
+    const totalBatches = Math.ceil(validUrls.length / SCRAPER.BATCH_SIZE);
+    mcpLog('info', `Starting scrape: ${validUrls.length} URL(s), ${tokensPerUrl} tokens/URL, ${totalBatches} batch(es)`, 'scrape');
+    // Initialize clients safely
+    let client;
+    try {
+        client = new ScraperClient();
+    }
+    catch (error) {
+        const err = classifyError(error);
+        return createErrorResponse('CLIENT_INIT_FAILED', `Failed to initialize scraper: ${err.message}`);
+    }
+    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 });
+    mcpLog('info', `Scraping complete. Processing ${results.length} results...`, 'scrape');
+    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`);
+    }
+    const successItems = [];
+    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;
+        }
+        mcpLog('debug', `[${i + 1}/${results.length}] Processing ${result.url}`, 'scrape');
+        // 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}`);
+            mcpLog('warning', `[${i + 1}/${results.length}] Failed: ${errorMsg}`, 'scrape');
+            continue;
+        }
+        // Success case
+        successful++;
+        totalCredits += result.credits;
+        // Process content safely (CPU-bound, fast)
+        let content;
+        try {
+            content = markdownCleaner.processContent(result.content);
+        }
+        catch {
+            content = result.content;
+        }
+        successItems.push({ url: result.url, content, index: i });
+    }
+    // Pass 2: Parallel LLM extraction for successful results (I/O-bound)
+    if (params.use_llm && llmProcessor && successItems.length > 0) {
+        mcpLog('info', `Starting parallel LLM extraction for ${successItems.length} pages (concurrency: 3)`, 'scrape');
+        const llmResults = await pMap(successItems, async (item) => {
+            mcpLog('debug', `LLM extracting ${item.url} (${tokensPerUrl} tokens)...`, 'scrape');
+            const llmResult = await processContentWithLLM(item.content, { use_llm: params.use_llm, what_to_extract: enhancedInstruction, max_tokens: tokensPerUrl }, llmProcessor);
+            if (llmResult.processed) {
+                mcpLog('debug', `LLM extraction complete for ${item.url}`, 'scrape');
+                return { ...item, content: llmResult.content };
+            }
+            llmErrors++;
+            mcpLog('warning', `LLM extraction skipped for ${item.url}: ${llmResult.error || 'unknown reason'}`, 'scrape');
+            return item; // Graceful degradation — use original cleaned content
+        }, 3);
+        // Update successItems with LLM-processed content
+        for (let i = 0; i < llmResults.length; i++) {
+            successItems[i] = llmResults[i];
+        }
+    }
+    // Pass 3: Final assembly — remove meta tags and build content entries
+    for (const item of successItems) {
+        let content = item.content;
+        try {
+            content = removeMetaTags(content);
+        }
+        catch {
+            // If this fails, just use the content as-is
+        }
+        contents.push(`## ${item.url}\n\n${content}`);
+    }
+    const executionTime = Date.now() - startTime;
+    mcpLog('info', `Completed: ${successful} successful, ${failed} failed, ${totalCredits} credits used`, 'scrape');
+    // Build 70/20/10 response
+    const batchHeader = formatBatchHeader({
+        title: `Scraped Content (${params.urls.length} URLs)`,
+        totalItems: params.urls.length,
+        successful,
+        failed,
+        tokensPerItem: tokensPerUrl,
+        batches: totalBatches,
+        extras: {
+            'Credits used': totalCredits,
+            ...(llmErrors > 0 ? { 'LLM extraction failures': llmErrors } : {}),
+        },
+    });
+    const nextSteps = [
+        successful > 0 ? `Extract specific data: scrape_links(urls=[...], use_llm=true, what_to_extract="Extract pricing | features | testimonials")` : null,
+        failed > 0 ? `Retry failed URLs with longer timeout: scrape_links(urls=[...], timeout=60)` : null,
+        'Research further: deep_research(questions=[{question: "Based on scraped content..."}])',
+    ].filter(Boolean);
+    const formattedContent = formatSuccess({
+        title: 'Scraping Complete',
+        summary: batchHeader,
+        data: contents.join('\n\n---\n\n'),
+        nextSteps,
+        metadata: {
+            'Execution time': formatDuration(executionTime),
+            'Token budget': TOKEN_BUDGETS.SCRAPER.toLocaleString(),
+        },
+    });
+    const metadata = {
+        total_urls: params.urls.length,
+        successful,
+        failed,
+        total_credits: totalCredits,
+        execution_time_ms: executionTime,
+        tokens_per_url: tokensPerUrl,
+        total_token_budget: TOKEN_BUDGETS.SCRAPER,
+        batches_processed: totalBatches,
+    };
+    return { content: formattedContent, structuredContent: { content: formattedContent, metadata } };
+}
+//# sourceMappingURL=scrape.js.map

package/dist/tools/scrape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrape.js","sourceRoot":"","sources":["../../src/tools/scrape.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACzF,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAC/C,OAAO,EACL,MAAM,EACN,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB,wDAAwD;AACxD,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;AAE9C,8EAA8E;AAC9E,SAAS,mBAAmB;IAC1B,MAAM,MAAM,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;IAC7C,OAAO,MAAM,EAAE,MAAM,EAAE,iBAA2B,IAAI,OAAO,CAAC,iBAAiB,CAAC;AAClF,CAAC;AAED,SAAS,4BAA4B,CAAC,WAA+B;IACnE,MAAM,IAAI,GAAG,WAAW,IAAI,8DAA8D,CAAC;IAC3F,OAAO,GAAG,IAAI,OAAO,mBAAmB,EAAE,EAAE,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAyB;IAEzB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,kCAAkC;IAClC,MAAM,mBAAmB,GAAG,CAAC,IAAY,EAAE,OAAe,EAAE,SAAS,GAAG,KAAK,EAA6D,EAAE,CAAC,CAAC;QAC5I,OAAO,EAAE,WAAW,CAAC;YACnB,IAAI;YACJ,OAAO;YACP,SAAS;YACT,QAAQ,EAAE,cAAc;YACxB,QAAQ,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAC,CAAC,CAAC,SAAS;SAC9E,CAAC;QACF,iBAAiB,EAAE;YACjB,OAAO,EAAE,OAAO;YAChB,QAAQ,EAAE;gBACR,UAAU,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;gBACpC,UAAU,EAAE,CAAC;gBACb,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;gBAChC,aAAa,EAAE,CAAC;gBAChB,iBAAiB,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aAC1C;SACF;KACF,CAAC,CAAC;IAEH,kBAAkB;IAClB,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,mBAAmB,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;IAC5D,CAAC;IAED,gCAAgC;IAChC,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,WAAW,GAAa,EAAE,CAAC;IAEjC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YACb,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,mBAAmB,CAAC,cAAc,EAAE,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,mBAAmB,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,YAAY,GAAG,wBAAwB,CAAC,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACvF,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEtE,MAAM,CAAC,MAAM,EAAE,oBAAoB,SAAS,CAAC,MAAM,YAAY,YAAY,gBAAgB,YAAY,YAAY,EAAE,QAAQ,CAAC,CAAC;IAE/H,4BAA4B;IAC5B,IAAI,MAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QACjC,OAAO,mBAAmB,CAAC,oBAAoB,EAAE,iCAAiC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACnG,CAAC;IAED,MAAM,YAAY,GAAG,kBAAkB,EAAE,CAAC,CAAC,iCAAiC;IAE5E,MAAM,mBAAmB,GAAG,MAAM,CAAC,OAAO;QACxC,CAAC,CAAC,4BAA4B,CAAC,MAAM,CAAC,eAAe,CAAC;QACtD,CAAC,CAAC,SAAS,CAAC;IAEd,4CAA4C;IAC5C,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAEpF,MAAM,CAAC,MAAM,EAAE,iCAAiC,OAAO,CAAC,MAAM,aAAa,EAAE,QAAQ,CAAC,CAAC;IAEvF,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,mCAAmC;IACnC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,EAAE,CAAC;QACT,QAAQ,CAAC,IAAI,CAAC,MAAM,UAAU,0BAA0B,CAAC,CAAC;IAC5D,CAAC;IAQD,MAAM,YAAY,GAAsB,EAAE,CAAC;IAE3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,EAAE,CAAC;YACT,QAAQ,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;YACxD,SAAS;QACX,CAAC;QAED,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,MAAM,gBAAgB,MAAM,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;QAEnF,6BAA6B;QAC7B,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,UAAU,GAAG,GAAG,IAAI,MAAM,CAAC,UAAU,IAAI,GAAG,EAAE,CAAC;YACxE,MAAM,EAAE,CAAC;YACT,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,EAAE,OAAO,IAAI,MAAM,CAAC,OAAO,IAAI,QAAQ,MAAM,CAAC,UAAU,EAAE,CAAC;YACxF,QAAQ,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,GAAG,2BAA2B,QAAQ,EAAE,CAAC,CAAC;YACrE,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,MAAM,aAAa,QAAQ,EAAE,EAAE,QAAQ,CAAC,CAAC;YAChF,SAAS;QACX,CAAC;QAED,eAAe;QACf,UAAU,EAAE,CAAC;QACb,YAAY,IAAI,MAAM,CAAC,OAAO,CAAC;QAE/B,2CAA2C;QAC3C,IAAI,OAAe,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,GAAG,eAAe,CAAC,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC3B,CAAC;QAED,YAAY,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,qEAAqE;IACrE,IAAI,MAAM,CAAC,OAAO,IAAI,YAAY,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9D,MAAM,CAAC,MAAM,EAAE,wCAAwC,YAAY,CAAC,MAAM,yBAAyB,EAAE,QAAQ,CAAC,CAAC;QAE/G,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACzD,MAAM,CAAC,OAAO,EAAE,kBAAkB,IAAI,CAAC,GAAG,KAAK,YAAY,aAAa,EAAE,QAAQ,CAAC,CAAC;YAEpF,MAAM,SAAS,GAAG,MAAM,qBAAqB,CAC3C,IAAI,CAAC,OAAO,EACZ,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,UAAU,EAAE,YAAY,EAAE,EAC3F,YAAY,CACb,CAAC;YAEF,IAAI,SAAS,CAAC,SAAS,EAAE,CAAC;gBACxB,MAAM,CAAC,OAAO,EAAE,+BAA+B,IAAI,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;gBACrE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;YACjD,CAAC;YAED,SAAS,EAAE,CAAC;YACZ,MAAM,CAAC,SAAS,EAAE,8BAA8B,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,KAAK,IAAI,gBAAgB,EAAE,EAAE,QAAQ,CAAC,CAAC;YAC9G,OAAO,IAAI,CAAC,CAAC,sDAAsD;QACrE,CAAC,EAAE,CAAC,CAAC,CAAC;QAEN,iDAAiD;QACjD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,YAAY,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC3B,IAAI,CAAC;YACH,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;QAC9C,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG,OAAO,OAAO,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IAE7C,MAAM,CAAC,MAAM,EAAE,cAAc,UAAU,gBAAgB,MAAM,YAAY,YAAY,eAAe,EAAE,QAAQ,CAAC,CAAC;IAEhH,0BAA0B;IAC1B,MAAM,WAAW,GAAG,iBAAiB,CAAC;QACpC,KAAK,EAAE,oBAAoB,MAAM,CAAC,IAAI,CAAC,MAAM,QAAQ;QACrD,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM;QAC9B,UAAU;QACV,MAAM;QACN,aAAa,EAAE,YAAY;QAC3B,OAAO,EAAE,YAAY;QACrB,MAAM,EAAE;YACN,cAAc,EAAE,YAAY;YAC5B,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,yBAAyB,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnE;KACF,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG;QAChB,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,4HAA4H,CAAC,CAAC,CAAC,IAAI;QACpJ,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,6EAA6E,CAAC,CAAC,CAAC,IAAI;QACjG,wFAAwF;KACzF,CAAC,MAAM,CAAC,OAAO,CAAa,CAAC;IAE9B,MAAM,gBAAgB,GAAG,aAAa,CAAC;QACrC,KAAK,EAAE,mBAAmB;QAC1B,OAAO,EAAE,WAAW;QACpB,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC;QAClC,SAAS;QACT,QAAQ,EAAE;YACR,gBAAgB,EAAE,cAAc,CAAC,aAAa,CAAC;YAC/C,cAAc,EAAE,aAAa,CAAC,OAAO,CAAC,cAAc,EAAE;SACvD;KACF,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG;QACf,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM;QAC9B,UAAU;QACV,MAAM;QACN,aAAa,EAAE,YAAY;QAC3B,iBAAiB,EAAE,aAAa;QAChC,cAAc,EAAE,YAAY;QAC5B,kBAAkB,EAAE,aAAa,CAAC,OAAO;QACzC,iBAAiB,EAAE,YAAY;KAChC,CAAC;IAEF,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,EAAE,CAAC;AACnG,CAAC"}

package/dist/tools/search.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Web Search Tool Handler
+ * NEVER throws - always returns structured response for graceful degradation
+ */
+import type { WebSearchParams, WebSearchOutput } from '../schemas/web-search.js';
+export declare function handleWebSearch(params: WebSearchParams): Promise<{
+    content: string;
+    structuredContent: WebSearchOutput;
+}>;
+//# sourceMappingURL=search.d.ts.map

package/dist/tools/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/tools/search.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAyBjF,wBAAsB,eAAe,CACnC,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,eAAe,CAAA;CAAE,CAAC,CA2JlE"}

package/dist/tools/search.js

@@ -0,0 +1,137 @@
+/**
+ * Web Search Tool Handler
+ * NEVER throws - always returns structured response for graceful degradation
+ */
+import { SearchClient } from '../clients/search.js';
+import { aggregateAndRank, buildUrlLookup, lookupUrl, generateEnhancedOutput, markConsensus, } from '../utils/url-aggregator.js';
+import { CTR_WEIGHTS } from '../config/index.js';
+import { classifyError } from '../utils/errors.js';
+import { mcpLog, formatError, formatDuration, } from './utils.js';
+function getPositionScore(position) {
+    if (position >= 1 && position <= 10) {
+        return CTR_WEIGHTS[position] ?? 0;
+    }
+    return Math.max(0, 10 - (position - 10) * 0.5);
+}
+export async function handleWebSearch(params) {
+    const startTime = Date.now();
+    try {
+        mcpLog('info', `Searching for ${params.keywords.length} keyword(s)`, 'search');
+        const client = new SearchClient();
+        const response = await client.searchMultiple(params.keywords);
+        const aggregation = aggregateAndRank(response.searches, 5);
+        const urlLookup = buildUrlLookup(aggregation.rankedUrls);
+        const consensusUrls = aggregation.rankedUrls.filter(url => url.frequency >= aggregation.frequencyThreshold);
+        let markdown = '';
+        if (consensusUrls.length > 0) {
+            markdown += generateEnhancedOutput(consensusUrls, params.keywords, aggregation.totalUniqueUrls, aggregation.frequencyThreshold, aggregation.thresholdNote);
+            markdown += '\n---\n\n';
+        }
+        else {
+            markdown += `## The Perfect Search Results (Aggregated from ${response.totalKeywords} Queries)\n\n`;
+            markdown += `> *No high-consensus URLs found across searches. Results may be highly diverse.*\n\n`;
+            markdown += `---\n\n`;
+        }
+        // Limit output based on number of queries to keep under ~20k tokens
+        const MAX_QUERIES_SHOWN = 15;
+        const MAX_RESULTS_PER_QUERY = response.totalKeywords > 10 ? 5 : 10;
+        const queriesToShow = response.searches.slice(0, MAX_QUERIES_SHOWN);
+        const queriesOmitted = response.searches.length - queriesToShow.length;
+        markdown += `## 📊 Full Search Results by Query`;
+        if (queriesOmitted > 0) {
+            markdown += ` (showing ${queriesToShow.length} of ${response.searches.length})`;
+        }
+        markdown += `\n\n`;
+        let totalResults = 0;
+        queriesToShow.forEach((search, index) => {
+            markdown += `### Query ${index + 1}: "${search.keyword}"\n\n`;
+            search.results.slice(0, MAX_RESULTS_PER_QUERY).forEach((result, resultIndex) => {
+                const position = resultIndex + 1;
+                const positionScore = getPositionScore(position);
+                const rankedUrl = lookupUrl(result.link, urlLookup);
+                const frequency = rankedUrl?.frequency ?? 1;
+                const consensusMark = markConsensus(frequency);
+                const consensusInfo = rankedUrl
+                    ? `${consensusMark} (${frequency} searches)`
+                    : `${consensusMark} (1 search)`;
+                markdown += `${position}. **[${result.title}](${result.link})** — Position ${position} | Score: ${positionScore.toFixed(1)} | Consensus: ${consensusInfo}\n`;
+                if (result.snippet) {
+                    let snippet = result.snippet;
+                    if (snippet.length > 150) {
+                        snippet = snippet.substring(0, 147) + '...';
+                    }
+                    if (result.date) {
+                        markdown += `   - *${result.date}* — ${snippet}\n`;
+                    }
+                    else {
+                        markdown += `   - ${snippet}\n`;
+                    }
+                }
+                markdown += '\n';
+                totalResults++;
+            });
+            if (search.related && search.related.length > 0) {
+                const relatedSuggestions = search.related
+                    .slice(0, 5)
+                    .map((r) => `\`${r}\``)
+                    .join(', ');
+                markdown += `*Related:* ${relatedSuggestions}\n\n`;
+            }
+            if (index < queriesToShow.length - 1) {
+                markdown += `---\n\n`;
+            }
+        });
+        if (queriesOmitted > 0) {
+            markdown += `\n---\n\n> *${queriesOmitted} additional queries not shown. Consensus URLs above include all ${response.searches.length} queries.*\n`;
+        }
+        const executionTime = Date.now() - startTime;
+        mcpLog('info', `Search completed: ${totalResults} results, ${aggregation.totalUniqueUrls} unique URLs, ${consensusUrls.length} consensus`, 'search');
+        // Add Next Steps section
+        const nextSteps = [
+            consensusUrls.length > 0 ? `Scrape top consensus URLs: scrape_links(urls=[${consensusUrls.slice(0, 3).map(u => `"${u.url}"`).join(', ')}], use_llm=true)` : null,
+            'Get Reddit perspective: search_reddit(queries=[...related terms...])',
+            'Deep research: deep_research(questions=[{question: "Based on search results..."}])',
+        ].filter(Boolean);
+        markdown += '\n\n---\n\n**Next Steps:**\n';
+        nextSteps.forEach(step => { markdown += `→ ${step}\n`; });
+        markdown += `\n---\n*${formatDuration(executionTime)} | ${aggregation.totalUniqueUrls} unique URLs | ${consensusUrls.length} consensus*`;
+        const metadata = {
+            total_keywords: response.totalKeywords,
+            total_results: totalResults,
+            execution_time_ms: executionTime,
+            total_unique_urls: aggregation.totalUniqueUrls,
+            consensus_url_count: consensusUrls.length,
+            frequency_threshold: aggregation.frequencyThreshold,
+        };
+        return { content: markdown, structuredContent: { content: markdown, metadata } };
+    }
+    catch (error) {
+        const structuredError = classifyError(error);
+        const executionTime = Date.now() - startTime;
+        mcpLog('error', `web_search: ${structuredError.message}`, 'search');
+        const errorContent = formatError({
+            code: structuredError.code,
+            message: structuredError.message,
+            retryable: structuredError.retryable,
+            toolName: 'web_search',
+            howToFix: ['Verify SERPER_API_KEY is set correctly'],
+            alternatives: [
+                'search_reddit(queries=[...]) for Reddit-specific results',
+                'deep_research(questions=[...]) for AI-synthesized research',
+            ],
+        });
+        return {
+            content: errorContent,
+            structuredContent: {
+                content: errorContent,
+                metadata: {
+                    total_keywords: params.keywords.length,
+                    total_results: 0,
+                    execution_time_ms: executionTime,
+                    errorCode: structuredError.code,
+                },
+            },
+        };
+    }
+}
+//# sourceMappingURL=search.js.map

package/dist/tools/search.js.map

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