brave-real-browser-mcp-server 2.0.6 → 2.0.8

package/README.md

@@ -184,6 +184,73 @@ complex web automation tasks with human-like behavior.
   ```
 - Install xvfb for headless operation: `sudo apt-get install -y xvfb`
 
+## 🚀 Auto-Update Feature
+
+This package **automatically updates all dependencies to their latest versions** whenever you run `npm install` during development. This ensures you always have the most recent bug fixes, security patches, and feature improvements from the underlying Brave browser packages.
+
+### How it works:
+- ✅ Automatically checks for outdated dependencies on every `npm install`
+- ✅ Updates core Brave packages (`brave-real-browser`, `brave-real-launcher`, `brave-real-puppeteer-core`) with `--force`
+- ✅ Updates other dependencies (`@modelcontextprotocol/sdk`, `turndown`) separately  
+- ✅ Works in CI/CD environments (GitHub Actions workflow)
+- ✅ Can be disabled if needed via environment variable
+- ✅ Smart recursion prevention to avoid loops
+
+### For End Users (Using NPX):
+If you're using this package via `npx` (as recommended in Claude Desktop config), you don't need to worry about updates - `npx` with `@latest` always fetches the newest version automatically. This auto-update feature is primarily for developers.
+
+### For Developers:
+
+**Auto-update is enabled by default:**
+```bash
+npm install
+```
+This will automatically update all dependencies to their latest versions.
+
+**To disable auto-update temporarily:**
+```bash
+# On Windows (PowerShell)
+$env:SKIP_AUTO_UPDATE="true"; npm install
+
+# On Windows (CMD)
+set SKIP_AUTO_UPDATE=true && npm install
+
+# On macOS/Linux
+SKIP_AUTO_UPDATE=true npm install
+```
+
+**Manual update commands:**
+```bash
+# Check for outdated dependencies
+npm run check-updates
+
+# Update all core Brave packages
+npm run update-brave-packages
+
+# Update using ensure-latest script (with verification)
+npm run ensure-latest-packages
+
+# Run auto-update script manually
+npm run upgrade-all
+
+# Complete fresh install with latest packages
+npm run fresh-install
+```
+
+**In CI/CD:**
+The GitHub Actions workflow automatically updates dependencies during the build process using the `ensure-latest-packages` script.
+
+### Why Auto-Update?
+
+The underlying `brave-real-browser` ecosystem is actively maintained with frequent updates for:
+- 🐛 Bug fixes
+- 🔒 Security patches  
+- 🎯 Anti-detection improvements
+- 🚀 New features
+- 🌐 Browser compatibility updates
+
+Auto-updates ensure you're always running the most stable and secure version.
+
 ## Platform-Specific Installation
 
 > **🎯 Choose Your Platform:** Select the installation method that matches your operating system. Each section includes complete setup commands for both Brave Browser and MCP server configuration.

package/dist/browser-manager.js

@@ -2,6 +2,7 @@ import { connect } from 'brave-real-browser';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as net from 'net';
+import { categorizeError as categorizeErrorMCP, ErrorCategory as MCPErrorCategory } from './errors/index.js';
 // Browser error categorization
 export var BrowserErrorType;
 (function (BrowserErrorType) {
@@ -52,28 +53,31 @@ export async function initializeBrowserForTesting(options) {
     return await initializeBrowser(options);
 }
 let sessionValidationInProgress = false;
-// Error handling functions
+// Error handling functions - now uses centralized error system
+// Legacy function kept for backward compatibility
 export function categorizeError(error) {
-    const message = error.message.toLowerCase();
-    if (message.includes('navigating frame was detached')) {
-        return BrowserErrorType.FRAME_DETACHED;
-    }
-    if (message.includes('session closed')) {
-        return BrowserErrorType.SESSION_CLOSED;
-    }
-    if (message.includes('target closed')) {
-        return BrowserErrorType.TARGET_CLOSED;
-    }
-    if (message.includes('protocol error')) {
-        return BrowserErrorType.PROTOCOL_ERROR;
-    }
-    if (message.includes('navigation timeout') || message.includes('timeout')) {
-        return BrowserErrorType.NAVIGATION_TIMEOUT;
-    }
-    if (message.includes('element not found') || message.includes('no node found')) {
-        return BrowserErrorType.ELEMENT_NOT_FOUND;
+    const mcpError = categorizeErrorMCP(error);
+    // Map MCPError categories to BrowserErrorType for backward compatibility
+    switch (mcpError.category) {
+        case MCPErrorCategory.FRAME_DETACHED:
+            return BrowserErrorType.FRAME_DETACHED;
+        case MCPErrorCategory.SESSION_CLOSED:
+            return BrowserErrorType.SESSION_CLOSED;
+        case MCPErrorCategory.TARGET_CLOSED:
+            return BrowserErrorType.TARGET_CLOSED;
+        case MCPErrorCategory.PROTOCOL_ERROR:
+            return BrowserErrorType.PROTOCOL_ERROR;
+        case MCPErrorCategory.NAVIGATION_TIMEOUT:
+            return BrowserErrorType.NAVIGATION_TIMEOUT;
+        case MCPErrorCategory.ELEMENT_NOT_FOUND:
+            return BrowserErrorType.ELEMENT_NOT_FOUND;
+        default:
+            return BrowserErrorType.UNKNOWN;
     }
-    return BrowserErrorType.UNKNOWN;
+}
+// New function that returns MCPError for better error handling
+export function categorizeBrowserError(error) {
+    return categorizeErrorMCP(error);
 }
 // Timeout wrapper for operations that may hang
 export async function withTimeout(operation, timeoutMs, context = 'unknown') {

package/dist/constants.js

@@ -0,0 +1,127 @@
+/**
+ * Constants for Brave Real Browser MCP Server
+ * Centralizes all magic numbers and configuration values
+ */
+// Timeout configurations (in milliseconds)
+export const TIMEOUTS = {
+    NAVIGATION: 30000, // 30 seconds for page navigation
+    ELEMENT_WAIT: 10000, // 10 seconds to wait for elements
+    BROWSER_LAUNCH: 60000, // 60 seconds for browser launch
+    CAPTCHA_SOLVE: 300000, // 5 minutes for captcha solving
+    SCRIPT_EXECUTION: 30000, // 30 seconds for script execution
+    PAGE_LOAD: 30000, // 30 seconds for page load
+};
+// Retry configurations
+export const RETRIES = {
+    MAX_ATTEMPTS: 3,
+    BACKOFF_MULTIPLIER: 2,
+    INITIAL_DELAY: 1000, // 1 second initial delay
+    MAX_DELAY: 10000, // 10 seconds max delay
+};
+// Browser configurations
+export const BROWSER = {
+    DEFAULT_VIEWPORT: {
+        width: 1920,
+        height: 1080,
+    },
+    USER_AGENT: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+    DEFAULT_ARGS: [
+        '--no-sandbox',
+        '--disable-setuid-sandbox',
+        '--disable-dev-shm-usage',
+        '--disable-blink-features=AutomationControlled',
+    ],
+};
+// Content extraction limits
+export const CONTENT = {
+    MAX_TEXT_LENGTH: 1000000, // 1MB max text content
+    MAX_HTML_LENGTH: 5000000, // 5MB max HTML content
+    MAX_SCREENSHOT_SIZE: 10000000, // 10MB max screenshot
+    MARKDOWN_MAX_LENGTH: 2000000, // 2MB max markdown
+};
+// Selector timeouts
+export const SELECTORS = {
+    WAIT_TIMEOUT: 10000, // 10 seconds
+    POLL_INTERVAL: 100, // 100ms polling
+    MAX_RETRIES: 3,
+};
+// File operation limits
+export const FILES = {
+    MAX_FILE_SIZE: 50000000, // 50MB max file size
+    ALLOWED_EXTENSIONS: ['.md', '.txt', '.html', '.json'],
+    TEMP_DIR: '.temp',
+};
+// Error codes
+export const ERROR_CODES = {
+    // Browser errors (1xxx)
+    BROWSER_NOT_INITIALIZED: 'MCP_1001',
+    BROWSER_LAUNCH_FAILED: 'MCP_1002',
+    BROWSER_CONNECTION_LOST: 'MCP_1003',
+    // Navigation errors (2xxx)
+    NAVIGATION_FAILED: 'MCP_2001',
+    NAVIGATION_TIMEOUT: 'MCP_2002',
+    PAGE_NOT_FOUND: 'MCP_2003',
+    // Element errors (3xxx)
+    ELEMENT_NOT_FOUND: 'MCP_3001',
+    ELEMENT_NOT_VISIBLE: 'MCP_3002',
+    ELEMENT_NOT_CLICKABLE: 'MCP_3003',
+    // Content errors (4xxx)
+    CONTENT_TOO_LARGE: 'MCP_4001',
+    CONTENT_EXTRACTION_FAILED: 'MCP_4002',
+    INVALID_SELECTOR: 'MCP_4003',
+    // File errors (5xxx)
+    FILE_NOT_FOUND: 'MCP_5001',
+    FILE_TOO_LARGE: 'MCP_5002',
+    FILE_WRITE_FAILED: 'MCP_5003',
+    INVALID_FILE_TYPE: 'MCP_5004',
+    // General errors (9xxx)
+    UNKNOWN_ERROR: 'MCP_9001',
+    INVALID_ARGUMENTS: 'MCP_9002',
+    OPERATION_TIMEOUT: 'MCP_9003',
+};
+// HTTP status codes for common scenarios
+export const HTTP_STATUS = {
+    OK: 200,
+    MOVED_PERMANENTLY: 301,
+    FOUND: 302,
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    TIMEOUT: 408,
+    INTERNAL_ERROR: 500,
+    BAD_GATEWAY: 502,
+    SERVICE_UNAVAILABLE: 503,
+};
+// Logging levels
+export const LOG_LEVELS = {
+    DEBUG: 0,
+    INFO: 1,
+    WARN: 2,
+    ERROR: 3,
+    SILENT: 4,
+};
+// MCP Server configuration
+export const MCP_CONFIG = {
+    SERVER_NAME: 'brave-real-browser-mcp-server',
+    SERVER_VERSION: '2.0.0',
+    PROTOCOL_VERSION: '2024-11-05',
+    MAX_TOOLS: 50,
+    MAX_RESOURCES: 100,
+};
+// Performance monitoring thresholds
+export const PERFORMANCE = {
+    SLOW_OPERATION_THRESHOLD: 5000, // 5 seconds
+    MEMORY_WARNING_THRESHOLD: 500 * 1024 * 1024, // 500MB
+    CPU_WARNING_THRESHOLD: 80, // 80%
+};
+// Type guards for constants
+export function isValidErrorCode(code) {
+    return code in ERROR_CODES;
+}
+export function isValidTimeout(timeout) {
+    return timeout > 0 && timeout <= 300000; // Max 5 minutes
+}
+export function isValidRetryCount(count) {
+    return count >= 0 && count <= 10;
+}

package/dist/errors/index.js

@@ -0,0 +1,385 @@
+/**
+ * Centralized Error Handling System for MCP Server
+ *
+ * This module provides a comprehensive error handling framework with:
+ * - Custom error classes for different error categories
+ * - Error factory functions for consistent error creation
+ * - Error recovery strategies
+ * - Error serialization for MCP protocol
+ */
+// ============================================================================
+// ERROR CATEGORIES
+// ============================================================================
+export var ErrorCategory;
+(function (ErrorCategory) {
+    // Browser-related errors
+    ErrorCategory["BROWSER_NOT_INITIALIZED"] = "BROWSER_NOT_INITIALIZED";
+    ErrorCategory["BROWSER_INITIALIZATION_FAILED"] = "BROWSER_INITIALIZATION_FAILED";
+    ErrorCategory["BROWSER_CONNECTION_FAILED"] = "BROWSER_CONNECTION_FAILED";
+    ErrorCategory["BROWSER_CLOSED"] = "BROWSER_CLOSED";
+    // Navigation errors
+    ErrorCategory["NAVIGATION_FAILED"] = "NAVIGATION_FAILED";
+    ErrorCategory["NAVIGATION_TIMEOUT"] = "NAVIGATION_TIMEOUT";
+    ErrorCategory["PAGE_LOAD_FAILED"] = "PAGE_LOAD_FAILED";
+    // Element interaction errors
+    ErrorCategory["ELEMENT_NOT_FOUND"] = "ELEMENT_NOT_FOUND";
+    ErrorCategory["ELEMENT_NOT_INTERACTABLE"] = "ELEMENT_NOT_INTERACTABLE";
+    ErrorCategory["SELECTOR_INVALID"] = "SELECTOR_INVALID";
+    ErrorCategory["CLICK_FAILED"] = "CLICK_FAILED";
+    ErrorCategory["TYPE_FAILED"] = "TYPE_FAILED";
+    // Content retrieval errors
+    ErrorCategory["CONTENT_RETRIEVAL_FAILED"] = "CONTENT_RETRIEVAL_FAILED";
+    ErrorCategory["SCREENSHOT_FAILED"] = "SCREENSHOT_FAILED";
+    // File operation errors
+    ErrorCategory["FILE_NOT_FOUND"] = "FILE_NOT_FOUND";
+    ErrorCategory["FILE_READ_ERROR"] = "FILE_READ_ERROR";
+    ErrorCategory["FILE_WRITE_ERROR"] = "FILE_WRITE_ERROR";
+    ErrorCategory["INVALID_FILE_PATH"] = "INVALID_FILE_PATH";
+    // Validation errors
+    ErrorCategory["INVALID_INPUT"] = "INVALID_INPUT";
+    ErrorCategory["VALIDATION_FAILED"] = "VALIDATION_FAILED";
+    ErrorCategory["WORKFLOW_VIOLATION"] = "WORKFLOW_VIOLATION";
+    // Protocol errors
+    ErrorCategory["FRAME_DETACHED"] = "FRAME_DETACHED";
+    ErrorCategory["SESSION_CLOSED"] = "SESSION_CLOSED";
+    ErrorCategory["TARGET_CLOSED"] = "TARGET_CLOSED";
+    ErrorCategory["PROTOCOL_ERROR"] = "PROTOCOL_ERROR";
+    // System errors
+    ErrorCategory["NETWORK_ERROR"] = "NETWORK_ERROR";
+    ErrorCategory["TIMEOUT_ERROR"] = "TIMEOUT_ERROR";
+    ErrorCategory["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+})(ErrorCategory || (ErrorCategory = {}));
+// ============================================================================
+// ERROR SEVERITY LEVELS
+// ============================================================================
+export var ErrorSeverity;
+(function (ErrorSeverity) {
+    ErrorSeverity["LOW"] = "LOW";
+    ErrorSeverity["MEDIUM"] = "MEDIUM";
+    ErrorSeverity["HIGH"] = "HIGH";
+    ErrorSeverity["CRITICAL"] = "CRITICAL";
+})(ErrorSeverity || (ErrorSeverity = {}));
+// ============================================================================
+// CUSTOM ERROR CLASSES
+// ============================================================================
+/**
+ * Base error class for all MCP Server errors
+ */
+export class MCPError extends Error {
+    category;
+    severity;
+    isRecoverable;
+    timestamp;
+    context;
+    suggestedAction;
+    constructor(message, category, severity, isRecoverable = false, context, suggestedAction) {
+        super(message);
+        this.name = 'MCPError';
+        this.category = category;
+        this.severity = severity;
+        this.isRecoverable = isRecoverable;
+        this.timestamp = new Date();
+        this.context = context;
+        this.suggestedAction = suggestedAction;
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Serialize error for MCP protocol response
+     */
+    toMCPResponse() {
+        let errorText = `❌ Error: ${this.message}\n\n`;
+        errorText += `📋 Category: ${this.category}\n`;
+        errorText += `⚠️ Severity: ${this.severity}\n`;
+        if (this.suggestedAction) {
+            errorText += `\n💡 Suggested Action:\n${this.suggestedAction}\n`;
+        }
+        if (this.context && Object.keys(this.context).length > 0) {
+            errorText += `\n🔍 Context:\n${JSON.stringify(this.context, null, 2)}\n`;
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: errorText,
+                },
+            ],
+        };
+    }
+}
+/**
+ * Browser initialization and lifecycle errors
+ */
+export class BrowserError extends MCPError {
+    constructor(message, category = ErrorCategory.BROWSER_INITIALIZATION_FAILED, context, suggestedAction) {
+        const severity = category === ErrorCategory.BROWSER_NOT_INITIALIZED
+            ? ErrorSeverity.HIGH
+            : ErrorSeverity.CRITICAL;
+        const isRecoverable = category === ErrorCategory.BROWSER_NOT_INITIALIZED;
+        super(message, category, severity, isRecoverable, context, suggestedAction);
+        this.name = 'BrowserError';
+    }
+}
+/**
+ * Navigation-related errors
+ */
+export class NavigationError extends MCPError {
+    constructor(message, category = ErrorCategory.NAVIGATION_FAILED, context, suggestedAction) {
+        const severity = category === ErrorCategory.NAVIGATION_TIMEOUT
+            ? ErrorSeverity.MEDIUM
+            : ErrorSeverity.HIGH;
+        super(message, category, severity, true, context, suggestedAction);
+        this.name = 'NavigationError';
+    }
+}
+/**
+ * Element interaction errors
+ */
+export class InteractionError extends MCPError {
+    constructor(message, category = ErrorCategory.ELEMENT_NOT_FOUND, context, suggestedAction) {
+        super(message, category, ErrorSeverity.MEDIUM, true, context, suggestedAction);
+        this.name = 'InteractionError';
+    }
+}
+/**
+ * Content retrieval errors
+ */
+export class ContentError extends MCPError {
+    constructor(message, category = ErrorCategory.CONTENT_RETRIEVAL_FAILED, context, suggestedAction) {
+        super(message, category, ErrorSeverity.MEDIUM, true, context, suggestedAction);
+        this.name = 'ContentError';
+    }
+}
+/**
+ * File operation errors
+ */
+export class FileError extends MCPError {
+    constructor(message, category = ErrorCategory.FILE_WRITE_ERROR, context, suggestedAction) {
+        const severity = category === ErrorCategory.INVALID_FILE_PATH
+            ? ErrorSeverity.HIGH
+            : ErrorSeverity.MEDIUM;
+        super(message, category, severity, false, context, suggestedAction);
+        this.name = 'FileError';
+    }
+}
+/**
+ * Validation errors
+ */
+export class ValidationError extends MCPError {
+    constructor(message, category = ErrorCategory.VALIDATION_FAILED, context, suggestedAction) {
+        super(message, category, ErrorSeverity.HIGH, false, context, suggestedAction);
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Protocol-level errors
+ */
+export class ProtocolError extends MCPError {
+    constructor(message, category = ErrorCategory.PROTOCOL_ERROR, context, suggestedAction) {
+        const severity = [
+            ErrorCategory.FRAME_DETACHED,
+            ErrorCategory.SESSION_CLOSED,
+            ErrorCategory.TARGET_CLOSED
+        ].includes(category) ? ErrorSeverity.CRITICAL : ErrorSeverity.HIGH;
+        const isRecoverable = category === ErrorCategory.FRAME_DETACHED;
+        super(message, category, severity, isRecoverable, context, suggestedAction);
+        this.name = 'ProtocolError';
+    }
+}
+// ============================================================================
+// ERROR FACTORY FUNCTIONS
+// ============================================================================
+/**
+ * Create browser not initialized error
+ */
+export function createBrowserNotInitializedError() {
+    return new BrowserError('Browser is not initialized', ErrorCategory.BROWSER_NOT_INITIALIZED, {}, 'Please call browser_init first to initialize the browser instance.');
+}
+/**
+ * Create browser initialization failed error
+ */
+export function createBrowserInitializationError(originalError, context) {
+    return new BrowserError(`Failed to initialize browser: ${originalError.message}`, ErrorCategory.BROWSER_INITIALIZATION_FAILED, { originalError: originalError.message, ...context }, 'Check browser installation and ensure all dependencies are installed. Try running with different configuration options.');
+}
+/**
+ * Create navigation error
+ */
+export function createNavigationError(url, originalError) {
+    return new NavigationError(`Failed to navigate to ${url}: ${originalError.message}`, ErrorCategory.NAVIGATION_FAILED, { url, originalError: originalError.message }, 'Verify the URL is correct and accessible. Check network connectivity.');
+}
+/**
+ * Create navigation timeout error
+ */
+export function createNavigationTimeoutError(url, timeout) {
+    return new NavigationError(`Navigation to ${url} timed out after ${timeout}ms`, ErrorCategory.NAVIGATION_TIMEOUT, { url, timeout }, 'Try increasing the timeout value or use a different waitUntil option.');
+}
+/**
+ * Create element not found error
+ */
+export function createElementNotFoundError(selector, context) {
+    return new InteractionError(`Element not found: ${selector}`, ErrorCategory.ELEMENT_NOT_FOUND, { selector, ...context }, 'Use get_content to analyze the page first, then use find_selector to locate elements by text content.');
+}
+/**
+ * Create element not interactable error
+ */
+export function createElementNotInteractableError(selector, reason) {
+    return new InteractionError(`Element not interactable: ${selector}. Reason: ${reason}`, ErrorCategory.ELEMENT_NOT_INTERACTABLE, { selector, reason }, 'Wait for the element to become visible and enabled using the wait tool.');
+}
+/**
+ * Create invalid selector error
+ */
+export function createInvalidSelectorError(selector, originalError) {
+    return new InteractionError(`Invalid CSS selector: ${selector}. ${originalError.message}`, ErrorCategory.SELECTOR_INVALID, { selector, originalError: originalError.message }, 'Ensure the selector follows valid CSS syntax. Use find_selector to generate selectors from text content.');
+}
+/**
+ * Create content retrieval error
+ */
+export function createContentRetrievalError(originalError, context) {
+    return new ContentError(`Failed to retrieve content: ${originalError.message}`, ErrorCategory.CONTENT_RETRIEVAL_FAILED, { originalError: originalError.message, ...context }, 'Ensure the page is fully loaded. Try waiting for specific elements before retrieving content.');
+}
+/**
+ * Create file operation error
+ */
+export function createFileWriteError(filePath, originalError) {
+    return new FileError(`Failed to write file ${filePath}: ${originalError.message}`, ErrorCategory.FILE_WRITE_ERROR, { filePath, originalError: originalError.message }, 'Check file permissions and ensure the directory exists.');
+}
+/**
+ * Create invalid file path error
+ */
+export function createInvalidFilePathError(filePath, reason) {
+    return new FileError(`Invalid file path: ${filePath}. ${reason}`, ErrorCategory.INVALID_FILE_PATH, { filePath, reason }, 'Ensure the file path is absolute and uses the correct format for your operating system.');
+}
+/**
+ * Create validation error
+ */
+export function createValidationError(fieldName, value, expectedType) {
+    return new ValidationError(`Validation failed for field '${fieldName}': expected ${expectedType}, got ${typeof value}`, ErrorCategory.INVALID_INPUT, { fieldName, value, expectedType }, `Provide a valid ${expectedType} value for ${fieldName}.`);
+}
+/**
+ * Create workflow violation error
+ */
+export function createWorkflowViolationError(toolName, currentState, requiredState) {
+    return new ValidationError(`Workflow violation: Cannot execute '${toolName}' in current state '${currentState}'`, ErrorCategory.WORKFLOW_VIOLATION, { toolName, currentState, requiredState }, `Execute the following steps first: ${requiredState}`);
+}
+/**
+ * Create protocol error from puppeteer error
+ */
+export function createProtocolErrorFromPuppeteer(originalError) {
+    const message = originalError.message.toLowerCase();
+    let category = ErrorCategory.PROTOCOL_ERROR;
+    let suggestedAction = 'Try refreshing the page or reinitializing the browser.';
+    if (message.includes('frame') && message.includes('detached')) {
+        category = ErrorCategory.FRAME_DETACHED;
+        suggestedAction = 'The page frame was detached. Navigate to a new page or refresh.';
+    }
+    else if (message.includes('session closed')) {
+        category = ErrorCategory.SESSION_CLOSED;
+        suggestedAction = 'Browser session was closed. Reinitialize the browser using browser_init.';
+    }
+    else if (message.includes('target closed')) {
+        category = ErrorCategory.TARGET_CLOSED;
+        suggestedAction = 'Browser target was closed. Reinitialize the browser using browser_init.';
+    }
+    return new ProtocolError(originalError.message, category, { originalError: originalError.message }, suggestedAction);
+}
+// ============================================================================
+// ERROR CATEGORIZATION UTILITIES
+// ============================================================================
+/**
+ * Categorize a generic error into appropriate MCP error
+ */
+export function categorizeError(error) {
+    // Already an MCP error
+    if (error instanceof MCPError) {
+        return error;
+    }
+    // Convert to Error if not already
+    const err = error instanceof Error ? error : new Error(String(error));
+    const message = err.message.toLowerCase();
+    // Browser errors
+    if (message.includes('browser not initialized')) {
+        return createBrowserNotInitializedError();
+    }
+    // Navigation errors
+    if (message.includes('navigation') || message.includes('navigate')) {
+        if (message.includes('timeout')) {
+            return new NavigationError(err.message, ErrorCategory.NAVIGATION_TIMEOUT);
+        }
+        return new NavigationError(err.message, ErrorCategory.NAVIGATION_FAILED);
+    }
+    // Protocol errors
+    if (message.includes('frame') && message.includes('detached')) {
+        return createProtocolErrorFromPuppeteer(err);
+    }
+    if (message.includes('session closed') || message.includes('target closed')) {
+        return createProtocolErrorFromPuppeteer(err);
+    }
+    // Element errors
+    if (message.includes('element') || message.includes('selector')) {
+        if (message.includes('not found') || message.includes('no node')) {
+            return new InteractionError(err.message, ErrorCategory.ELEMENT_NOT_FOUND);
+        }
+        if (message.includes('not visible') || message.includes('not interactable')) {
+            return new InteractionError(err.message, ErrorCategory.ELEMENT_NOT_INTERACTABLE);
+        }
+    }
+    // File errors
+    if (message.includes('enoent') || message.includes('file not found')) {
+        return new FileError(err.message, ErrorCategory.FILE_NOT_FOUND);
+    }
+    if (message.includes('eacces') || message.includes('permission')) {
+        return new FileError(err.message, ErrorCategory.FILE_WRITE_ERROR);
+    }
+    // Network errors
+    if (message.includes('network') || message.includes('econnrefused') || message.includes('enotfound')) {
+        return new MCPError(err.message, ErrorCategory.NETWORK_ERROR, ErrorSeverity.HIGH, true, { originalError: err.message }, 'Check network connectivity and firewall settings.');
+    }
+    // Timeout errors
+    if (message.includes('timeout')) {
+        return new MCPError(err.message, ErrorCategory.TIMEOUT_ERROR, ErrorSeverity.MEDIUM, true, { originalError: err.message }, 'Try increasing timeout values or check if the operation is blocking.');
+    }
+    // Default unknown error
+    return new MCPError(err.message, ErrorCategory.UNKNOWN_ERROR, ErrorSeverity.MEDIUM, false, { originalError: err.message, stack: err.stack });
+}
+// ============================================================================
+// ERROR RECOVERY UTILITIES
+// ============================================================================
+/**
+ * Determine if an error is recoverable
+ */
+export function isRecoverableError(error) {
+    if (error instanceof MCPError) {
+        return error.isRecoverable;
+    }
+    const categorized = categorizeError(error);
+    return categorized.isRecoverable;
+}
+/**
+ * Get recovery strategy for an error
+ */
+export function getRecoveryStrategy(error) {
+    if (!error.isRecoverable) {
+        return null;
+    }
+    switch (error.category) {
+        case ErrorCategory.BROWSER_NOT_INITIALIZED:
+            return 'initialize_browser';
+        case ErrorCategory.NAVIGATION_TIMEOUT:
+        case ErrorCategory.NAVIGATION_FAILED:
+            return 'retry_navigation';
+        case ErrorCategory.ELEMENT_NOT_FOUND:
+            return 'use_self_healing_locators';
+        case ErrorCategory.FRAME_DETACHED:
+            return 'refresh_page';
+        case ErrorCategory.TIMEOUT_ERROR:
+            return 'retry_with_increased_timeout';
+        default:
+            return 'retry_operation';
+    }
+}
+// ============================================================================
+// EXPORTS
+// ============================================================================
+export { MCPError as default, };