brave-real-browser-mcp-server 2.9.21 → 2.10.0

package/dist/index.js

@@ -12,6 +12,7 @@ console.error('🔍 [DEBUG] Loading tool definitions...');
 import { TOOLS, SERVER_INFO, CAPABILITIES, TOOL_NAMES } from './tool-definitions.js';
 console.error('🔍 [DEBUG] Loading system utils...');
 import { withErrorHandling } from './system-utils.js';
+import { validateMCPResponse } from './mcp-response-validator.js';
 console.error('🔍 [DEBUG] Loading browser manager...');
 import { closeBrowser, forceKillAllBraveProcesses } from './browser-manager.js';
 console.error('🔍 [DEBUG] Loading core infrastructure...');
@@ -51,6 +52,8 @@ import { handleShadowDOMExtractor, handleCookieManager, handleSessionPersistence
 import { handleProgressTracker, handleErrorLogger, handleSuccessRateReporter, handleDataQualityMetrics, handlePerformanceMonitor, handleGetMonitoringSummary } from './handlers/monitoring-reporting-handlers.js';
 // Import advanced video & media handlers
 import { handleVideoLinkFinder, handleVideoDownloadPage, handleVideoDownloadButton, handleVideoPlayPushSource, handleVideoPlayButtonClick, handleUrlRedirectTraceEndpoints, handleNetworkRecordingFinder, handleNetworkRecordingExtractors, handleVideoLinksFinders, handleVideosSelectors, handleLinkProcessExtracts, handleVideoLinkFindersExtracts, handleVideoDownloadButtonFinders } from './handlers/advanced-video-media-handlers.js';
+// Import advanced extraction handlers (Ad-bypass & Obfuscation)
+import { handleAdvancedVideoExtraction, handleDeobfuscateJS, handleMultiLayerRedirectTrace, handleAdProtectionDetector } from './handlers/advanced-extraction-handlers.js';
 console.error('🔍 [DEBUG] All modules loaded successfully');
 console.error(`🔍 [DEBUG] Server info: ${JSON.stringify(SERVER_INFO)}`);
 console.error(`🔍 [DEBUG] Available tools: ${TOOLS.length} tools loaded`);
@@ -104,238 +107,360 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     console.error(`🔍 [DEBUG] Tool call received: ${name} with args: ${JSON.stringify(args)}`);
     try {
+        let result;
         switch (name) {
             case TOOL_NAMES.BROWSER_INIT:
-                return await handleBrowserInit(args || {});
+                result = await handleBrowserInit(args || {});
+                break;
             case TOOL_NAMES.NAVIGATE:
-                return await handleNavigate(args);
+                result = await handleNavigate(args);
+                break;
             case TOOL_NAMES.GET_CONTENT:
-                return await handleGetContent(args || {});
+                result = await handleGetContent(args || {});
+                break;
             case TOOL_NAMES.CLICK:
-                return await handleClick(args);
+                result = await handleClick(args);
+                break;
             case TOOL_NAMES.TYPE:
-                return await handleType(args);
+                result = await handleType(args);
+                break;
             case TOOL_NAMES.WAIT:
-                return await handleWait(args);
+                result = await handleWait(args);
+                break;
             case TOOL_NAMES.BROWSER_CLOSE:
-                return await handleBrowserClose();
+                result = await handleBrowserClose();
+                break;
             case TOOL_NAMES.SOLVE_CAPTCHA:
-                return await handleSolveCaptcha(args);
+                result = await handleSolveCaptcha(args);
+                break;
             case TOOL_NAMES.RANDOM_SCROLL:
-                return await handleRandomScroll();
+                result = await handleRandomScroll();
+                break;
             case TOOL_NAMES.FIND_SELECTOR:
-                return await handleFindSelector(args);
+                result = await handleFindSelector(args);
+                break;
             case TOOL_NAMES.SAVE_CONTENT_AS_MARKDOWN:
-                return await handleSaveContentAsMarkdown(args);
+                result = await handleSaveContentAsMarkdown(args);
+                break;
             // Smart Data Extractors
             case TOOL_NAMES.SCRAPE_TABLE:
-                return await handleScrapeTable(args || {});
+                result = await handleScrapeTable(args || {});
+                break;
             case TOOL_NAMES.EXTRACT_LIST:
-                return await handleExtractList(args || {});
+                result = await handleExtractList(args || {});
+                break;
             case TOOL_NAMES.EXTRACT_JSON:
-                return await handleExtractJSON(args || {});
+                result = await handleExtractJSON(args || {});
+                break;
             case TOOL_NAMES.SCRAPE_META_TAGS:
-                return await handleScrapeMetaTags(args || {});
+                result = await handleScrapeMetaTags(args || {});
+                break;
             case TOOL_NAMES.EXTRACT_SCHEMA:
-                return await handleExtractSchema(args || {});
+                result = await handleExtractSchema(args || {});
+                break;
             // Multi-Element Extractors
             case TOOL_NAMES.BATCH_ELEMENT_SCRAPER:
-                return await handleBatchElementScraper(args);
+                result = await handleBatchElementScraper(args);
+                break;
             case TOOL_NAMES.NESTED_DATA_EXTRACTION:
-                return await handleNestedDataExtraction(args);
+                result = await handleNestedDataExtraction(args);
+                break;
             case TOOL_NAMES.ATTRIBUTE_HARVESTER:
-                return await handleAttributeHarvester(args);
+                result = await handleAttributeHarvester(args);
+                break;
             // Content Type Specific
             case TOOL_NAMES.IMAGE_SCRAPER:
-                return await handleImageScraper(args || {});
+                result = await handleImageScraper(args || {});
+                break;
             case TOOL_NAMES.LINK_HARVESTER:
-                return await handleLinkHarvester(args || {});
+                result = await handleLinkHarvester(args || {});
+                break;
             case TOOL_NAMES.MEDIA_EXTRACTOR:
-                return await handleMediaExtractor(args || {});
+                result = await handleMediaExtractor(args || {});
+                break;
             case TOOL_NAMES.PDF_LINK_FINDER:
-                return await handlePDFLinkFinder(args || {});
+                result = await handlePDFLinkFinder(args || {});
+                break;
             // Pagination Tools
             case TOOL_NAMES.AUTO_PAGINATION:
-                return await handleAutoPagination(args || {});
+                result = await handleAutoPagination(args || {});
+                break;
             case TOOL_NAMES.INFINITE_SCROLL:
-                return await handleInfiniteScroll(args || {});
+                result = await handleInfiniteScroll(args || {});
+                break;
             case TOOL_NAMES.MULTI_PAGE_SCRAPER:
-                return await handleMultiPageScraper(args);
+                result = await handleMultiPageScraper(args);
+                break;
             case TOOL_NAMES.SITEMAP_PARSER:
-                return await handleSitemapParser(args || {});
+                result = await handleSitemapParser(args || {});
+                break;
             case TOOL_NAMES.BREADCRUMB_NAVIGATOR:
-                return await handleBreadcrumbNavigator(args || {});
+                result = await handleBreadcrumbNavigator(args || {});
+                break;
             // Data Processing Tools
             case TOOL_NAMES.SMART_TEXT_CLEANER:
-                return await handleSmartTextCleaner(args);
+                result = await handleSmartTextCleaner(args);
+                break;
             case TOOL_NAMES.HTML_TO_TEXT:
-                return await handleHTMLToText(args);
+                result = await handleHTMLToText(args);
+                break;
             case TOOL_NAMES.PRICE_PARSER:
-                return await handlePriceParser(args);
+                result = await handlePriceParser(args);
+                break;
             case TOOL_NAMES.DATE_NORMALIZER:
-                return await handleDateNormalizer(args);
+                result = await handleDateNormalizer(args);
+                break;
             case TOOL_NAMES.CONTACT_EXTRACTOR:
-                return await handleContactExtractor(args);
+                result = await handleContactExtractor(args);
+                break;
             // Data Validation Tools
             case TOOL_NAMES.SCHEMA_VALIDATOR:
-                return await handleSchemaValidator(args);
+                result = await handleSchemaValidator(args);
+                break;
             case TOOL_NAMES.REQUIRED_FIELDS_CHECKER:
-                return await handleRequiredFieldsChecker(args);
+                result = await handleRequiredFieldsChecker(args);
+                break;
             case TOOL_NAMES.DUPLICATE_REMOVER:
-                return await handleDuplicateRemover(args);
+                result = await handleDuplicateRemover(args);
+                break;
             // AI-Powered Features
             case TOOL_NAMES.SMART_SELECTOR_GENERATOR:
-                return await handleSmartSelectorGenerator(args);
+                result = await handleSmartSelectorGenerator(args);
+                break;
             case TOOL_NAMES.CONTENT_CLASSIFICATION:
-                return await handleContentClassification(args);
+                result = await handleContentClassification(args);
+                break;
             case TOOL_NAMES.SENTIMENT_ANALYSIS:
-                return await handleSentimentAnalysis(args);
+                result = await handleSentimentAnalysis(args);
+                break;
             case TOOL_NAMES.SUMMARY_GENERATOR:
-                return await handleSummaryGenerator(args);
+                result = await handleSummaryGenerator(args);
+                break;
             case TOOL_NAMES.TRANSLATION_SUPPORT:
-                return await handleTranslationSupport(args);
+                result = await handleTranslationSupport(args);
+                break;
             // Search & Filter Tools
             case TOOL_NAMES.KEYWORD_SEARCH:
-                return await handleKeywordSearch(args);
+                result = await handleKeywordSearch(args);
+                break;
             case TOOL_NAMES.REGEX_PATTERN_MATCHER:
-                return await handleRegexPatternMatcher(args);
+                result = await handleRegexPatternMatcher(args);
+                break;
             case TOOL_NAMES.XPATH_SUPPORT:
-                return await handleXPathSupport(args);
+                result = await handleXPathSupport(args);
+                break;
             case TOOL_NAMES.ADVANCED_CSS_SELECTORS:
-                return await handleAdvancedCSSSelectors(args);
+                result = await handleAdvancedCSSSelectors(args);
+                break;
             case TOOL_NAMES.VISUAL_ELEMENT_FINDER:
-                return await handleVisualElementFinder(args);
+                result = await handleVisualElementFinder(args);
+                break;
             // Data Quality & Validation
             case TOOL_NAMES.DATA_DEDUPLICATION:
-                return await handleDataDeduplication(args);
+                result = await handleDataDeduplication(args);
+                break;
             case TOOL_NAMES.MISSING_DATA_HANDLER:
-                return await handleMissingDataHandler(args);
+                result = await handleMissingDataHandler(args);
+                break;
             case TOOL_NAMES.DATA_TYPE_VALIDATOR:
-                return await handleDataTypeValidator(args);
+                result = await handleDataTypeValidator(args);
+                break;
             case TOOL_NAMES.OUTLIER_DETECTION:
-                return await handleOutlierDetection(args);
+                result = await handleOutlierDetection(args);
+                break;
             case TOOL_NAMES.CONSISTENCY_CHECKER:
-                return await handleConsistencyChecker(args);
+                result = await handleConsistencyChecker(args);
+                break;
             // Advanced Captcha Handling
             case TOOL_NAMES.OCR_ENGINE:
-                return await handleOCREngine(args);
+                result = await handleOCREngine(args);
+                break;
             case TOOL_NAMES.AUDIO_CAPTCHA_SOLVER:
-                return await handleAudioCaptchaSolver(args);
+                result = await handleAudioCaptchaSolver(args);
+                break;
             case TOOL_NAMES.PUZZLE_CAPTCHA_HANDLER:
-                return await handlePuzzleCaptchaHandler(args);
+                result = await handlePuzzleCaptchaHandler(args);
+                break;
             // Screenshot & Visual Tools
             case TOOL_NAMES.FULL_PAGE_SCREENSHOT:
-                return await handleFullPageScreenshot(args);
+                result = await handleFullPageScreenshot(args);
+                break;
             case TOOL_NAMES.ELEMENT_SCREENSHOT:
-                return await handleElementScreenshot(args);
+                result = await handleElementScreenshot(args);
+                break;
             case TOOL_NAMES.PDF_GENERATION:
-                return await handlePDFGeneration(args);
+                result = await handlePDFGeneration(args);
+                break;
             case TOOL_NAMES.VIDEO_RECORDING:
-                return await handleVideoRecording(args);
+                result = await handleVideoRecording(args);
+                break;
             case TOOL_NAMES.VISUAL_COMPARISON:
-                return await handleVisualComparison(args);
+                result = await handleVisualComparison(args);
+                break;
             // Website API Integration
             case TOOL_NAMES.REST_API_ENDPOINT_FINDER:
-                return await handleRESTAPIEndpointFinder(args);
+                result = await handleRESTAPIEndpointFinder(args);
+                break;
             case TOOL_NAMES.WEBHOOK_SUPPORT:
-                return await handleWebhookSupport(args);
+                result = await handleWebhookSupport(args);
+                break;
             case TOOL_NAMES.ALL_WEBSITE_API_FINDER:
-                return await handleAllWebsiteAPIFinder(args);
+                result = await handleAllWebsiteAPIFinder(args);
+                break;
             // Smart Data Extractors (Advanced)
             case 'html_elements_extractor':
-                return await handleHtmlElementsExtractor(args || {});
+                result = await handleHtmlElementsExtractor(args || {});
+                break;
             case 'tags_finder':
-                return await handleTagsFinder(args || {});
+                result = await handleTagsFinder(args || {});
+                break;
             case 'links_finder':
-                return await handleLinksFinder(args || {});
+                result = await handleLinksFinder(args || {});
+                break;
             case 'xpath_links':
-                return await handleXpathLinks(args || {});
+                result = await handleXpathLinks(args || {});
+                break;
             case 'ajax_extractor':
-                return await handleAjaxExtractor(args || {});
+                result = await handleAjaxExtractor(args || {});
+                break;
             case 'fetch_xhr':
-                return await handleFetchXHR(args || {});
+                result = await handleFetchXHR(args || {});
+                break;
             case 'network_recorder':
-                return await handleNetworkRecorder(args || {});
+                result = await handleNetworkRecorder(args || {});
+                break;
             case 'api_finder':
-                return await handleApiFinder(args || {});
+                result = await handleApiFinder(args || {});
+                break;
             case 'regex_pattern_finder':
-                return await handleRegexPatternFinder(args);
+                result = await handleRegexPatternFinder(args);
+                break;
             case 'iframe_extractor':
-                return await handleIframeExtractor(args || {});
+                result = await handleIframeExtractor(args || {});
+                break;
             case 'embed_page_extractor':
-                return await handleEmbedPageExtractor(args || {});
+                result = await handleEmbedPageExtractor(args || {});
+                break;
             case 'image_extractor_advanced':
-                return await handleImageExtractorAdvanced(args || {});
+                result = await handleImageExtractorAdvanced(args || {});
+                break;
             case 'video_source_extractor':
-                return await handleVideoSourceExtractor(args || {});
+                result = await handleVideoSourceExtractor(args || {});
+                break;
             case 'video_player_extractor':
-                return await handleVideoPlayerExtractor(args || {});
+                result = await handleVideoPlayerExtractor(args || {});
+                break;
             case 'video_player_hoster_finder':
-                return await handleVideoPlayerHosterFinder(args || {});
+                result = await handleVideoPlayerHosterFinder(args || {});
+                break;
             case 'original_video_hoster_finder':
-                return await handleOriginalVideoHosterFinder(args || {});
+                result = await handleOriginalVideoHosterFinder(args || {});
+                break;
             case 'url_redirect_tracer':
-                return await handleUrlRedirectTracer(args);
+                result = await handleUrlRedirectTracer(args);
+                break;
             case 'user_agent_extractor':
-                return await handleUserAgentExtractor(args || {});
+                result = await handleUserAgentExtractor(args || {});
+                break;
             // Dynamic Content & Session Handling
             case 'shadow_dom_extractor':
-                return await handleShadowDOMExtractor(args || {});
+                result = await handleShadowDOMExtractor(args || {});
+                break;
             case 'cookie_manager':
-                return await handleCookieManager(args);
+                result = await handleCookieManager(args);
+                break;
             case 'session_persistence':
-                return await handleSessionPersistence(args);
+                result = await handleSessionPersistence(args);
+                break;
             case 'form_auto_fill':
-                return await handleFormAutoFill(args);
+                result = await handleFormAutoFill(args);
+                break;
             case 'ajax_content_waiter':
-                return await handleAjaxContentWaiter(args);
+                result = await handleAjaxContentWaiter(args);
+                break;
             case 'modal_popup_handler':
-                return await handleModalPopupHandler(args);
+                result = await handleModalPopupHandler(args);
+                break;
             case 'login_session_manager':
-                return await handleLoginSessionManager(args);
+                result = await handleLoginSessionManager(args);
+                break;
             // Monitoring & Reporting
             case 'progress_tracker':
-                return await handleProgressTracker(args || {});
+                result = await handleProgressTracker(args || {});
+                break;
             case 'error_logger':
-                return await handleErrorLogger(args || {});
+                result = await handleErrorLogger(args || {});
+                break;
             case 'success_rate_reporter':
-                return await handleSuccessRateReporter(args || {});
+                result = await handleSuccessRateReporter(args || {});
+                break;
             case 'data_quality_metrics':
-                return await handleDataQualityMetrics(args || {});
+                result = await handleDataQualityMetrics(args || {});
+                break;
             case 'performance_monitor':
-                return await handlePerformanceMonitor(args || {});
+                result = await handlePerformanceMonitor(args || {});
+                break;
             case 'monitoring_summary':
-                return await handleGetMonitoringSummary(args || {});
+                result = await handleGetMonitoringSummary(args || {});
+                break;
             // Advanced Video & Media Download Tools
             case 'video_link_finder':
-                return await handleVideoLinkFinder(args || {});
+                result = await handleVideoLinkFinder(args || {});
+                break;
             case 'video_download_page':
-                return await handleVideoDownloadPage(args || {});
+                result = await handleVideoDownloadPage(args || {});
+                break;
             case 'video_download_button':
-                return await handleVideoDownloadButton(args);
+                result = await handleVideoDownloadButton(args);
+                break;
             case 'video_play_push_source':
-                return await handleVideoPlayPushSource(args || {});
+                result = await handleVideoPlayPushSource(args || {});
+                break;
             case 'video_play_button_click':
-                return await handleVideoPlayButtonClick(args || {});
+                result = await handleVideoPlayButtonClick(args || {});
+                break;
             case 'url_redirect_trace_endpoints':
-                return await handleUrlRedirectTraceEndpoints(args);
+                result = await handleUrlRedirectTraceEndpoints(args);
+                break;
             case 'network_recording_finder':
-                return await handleNetworkRecordingFinder(args || {});
+                result = await handleNetworkRecordingFinder(args || {});
+                break;
             case 'network_recording_extractors':
-                return await handleNetworkRecordingExtractors(args || {});
+                result = await handleNetworkRecordingExtractors(args || {});
+                break;
             case 'video_links_finders':
-                return await handleVideoLinksFinders(args || {});
+                result = await handleVideoLinksFinders(args || {});
+                break;
             case 'videos_selectors':
-                return await handleVideosSelectors(args || {});
+                result = await handleVideosSelectors(args || {});
+                break;
             case 'link_process_extracts':
-                return await handleLinkProcessExtracts(args || {});
+                result = await handleLinkProcessExtracts(args || {});
+                break;
             case 'video_link_finders_extracts':
-                return await handleVideoLinkFindersExtracts(args || {});
+                result = await handleVideoLinkFindersExtracts(args || {});
+                break;
             case 'video_download_button_finders':
-                return await handleVideoDownloadButtonFinders(args || {});
+                result = await handleVideoDownloadButtonFinders(args || {});
+                break;
+            // Advanced Extraction Tools (Ad-Bypass & Obfuscation)
+            case 'advanced_video_extraction':
+                result = await handleAdvancedVideoExtraction(args || {});
+                break;
+            case 'deobfuscate_js':
+                result = await handleDeobfuscateJS(args || {});
+                break;
+            case 'multi_layer_redirect_trace':
+                result = await handleMultiLayerRedirectTrace(args);
+                break;
+            case 'ad_protection_detector':
+                result = await handleAdProtectionDetector(args || {});
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
+        // Validate MCP response format universally
+        return validateMCPResponse(result, name);
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);

package/dist/mcp-response-validator.js

@@ -0,0 +1,145 @@
+/**
+ * MCP Response Validator
+ * Ensures all tool responses conform to MCP SDK standards
+ */
+/**
+ * Validates and ensures response is in proper MCP format
+ */
+export function validateMCPResponse(response, toolName) {
+    // If response is null or undefined
+    if (!response) {
+        console.error(`⚠️ Tool ${toolName} returned null/undefined`);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `⚠️ Tool ${toolName} returned no data. This might indicate:
+• The tool completed but found no results
+• An internal error occurred
+• The page state doesn't support this operation
+
+💡 Try: Refresh the page or navigate to the target URL first.`
+                }]
+        };
+    }
+    // If response is empty object
+    if (typeof response === 'object' && Object.keys(response).length === 0) {
+        console.error(`⚠️ Tool ${toolName} returned empty object {}`);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `⚠️ Tool ${toolName} returned empty result. This typically means:
+• No data was found matching the criteria
+• The page needs to be freshly loaded for monitoring tools
+• Network events have already completed
+
+💡 Suggestion: For network monitoring tools, start monitoring before navigating to the page.`
+                }]
+        };
+    }
+    // If response has content array, validate it
+    if (response.content && Array.isArray(response.content)) {
+        // Check if content array is empty
+        if (response.content.length === 0) {
+            console.warn(`⚠️ Tool ${toolName} has empty content array`);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `ℹ️ Tool ${toolName} executed successfully but returned no content.`
+                    }],
+                isError: response.isError
+            };
+        }
+        // Validate each content item
+        const validContent = response.content.filter((item) => {
+            return item && typeof item === 'object' && item.type && (item.text || item.data);
+        });
+        if (validContent.length === 0) {
+            console.error(`❌ Tool ${toolName} has invalid content items`);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `❌ Tool ${toolName} returned malformed content. Please report this issue.`
+                    }],
+                isError: true
+            };
+        }
+        return {
+            content: validContent,
+            isError: response.isError
+        };
+    }
+    // If response is a string, wrap it
+    if (typeof response === 'string') {
+        return {
+            content: [{
+                    type: 'text',
+                    text: response
+                }]
+        };
+    }
+    // If response is in unexpected format
+    console.error(`❌ Tool ${toolName} returned unexpected format:`, typeof response);
+    return {
+        content: [{
+                type: 'text',
+                text: `❌ Tool ${toolName} returned unexpected format: ${typeof response}
+
+Result: ${JSON.stringify(response, null, 2).substring(0, 500)}`
+            }],
+        isError: true
+    };
+}
+/**
+ * Wraps tool execution with response validation
+ */
+export async function executeWithValidation(toolName, handler) {
+    try {
+        const result = await handler();
+        return validateMCPResponse(result, toolName);
+    }
+    catch (error) {
+        console.error(`❌ Tool ${toolName} threw error:`, error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `❌ Tool execution failed: ${toolName}
+
+Error: ${errorMessage}
+
+${error instanceof Error && error.stack ? `Stack:\n${error.stack.substring(0, 500)}` : ''}`
+                }],
+            isError: true
+        };
+    }
+}
+/**
+ * Creates a "no data" response with helpful message
+ */
+export function createNoDataResponse(toolName, dataType, suggestions = []) {
+    let message = `ℹ️ ${toolName}: No ${dataType} found.`;
+    if (suggestions.length > 0) {
+        message += `\n\n💡 Suggestions:\n${suggestions.map(s => `  • ${s}`).join('\n')}`;
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: message
+            }]
+    };
+}
+/**
+ * Creates a success response with data
+ */
+export function createSuccessResponse(toolName, message, data) {
+    let text = `✅ ${message}`;
+    if (data) {
+        text += `\n\n${typeof data === 'string' ? data : JSON.stringify(data, null, 2)}`;
+    }
+    return {
+        content: [{
+                type: 'text',
+                text
+            }]
+    };
+}