ferrum-mcp 1.0.0

data/lib/ferrum_mcp/tools/base_tool.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Base class for all MCP tools
+    class BaseTool
+      attr_reader :browser, :logger
+
+      def initialize(browser_manager)
+        @browser_manager = browser_manager
+        @browser = browser_manager.browser
+        @logger = browser_manager.logger
+      end
+
+      def execute(params)
+        raise NotImplementedError, 'Subclasses must implement #execute'
+      end
+
+      def self.tool_name
+        raise NotImplementedError, 'Subclasses must implement .tool_name'
+      end
+
+      def self.description
+        raise NotImplementedError, 'Subclasses must implement .description'
+      end
+
+      def self.input_schema
+        raise NotImplementedError, 'Subclasses must implement .input_schema'
+      end
+
+      protected
+
+      def ensure_browser_active
+        raise BrowserError, 'Browser is not active' unless @browser_manager.active?
+
+        @browser = @browser_manager.browser
+      end
+
+      # Helper to access params consistently (supports both string and symbol keys)
+      def param(params, key)
+        params[key.to_s] || params[key.to_sym]
+      end
+
+      # Find element with improved timeout handling
+      # Uses shorter polling intervals for better responsiveness
+      def find_element(selector, timeout: 5)
+        ensure_browser_active
+        deadline = Time.now + timeout
+
+        loop do
+          element = browser.at_css(selector)
+          return element if element
+
+          raise ToolError, "Element not found: #{selector}" if Time.now > deadline
+
+          # Use shorter sleep for better responsiveness (0.1s instead of 0.5s)
+          sleep 0.1
+        end
+      rescue Ferrum::NodeNotFoundError
+        raise ToolError, "Element not found: #{selector}"
+      end
+
+      # Retry logic for handling stale/moving elements
+      def with_retry(retries: 3)
+        attempts = 0
+        begin
+          attempts += 1
+          yield
+        rescue Ferrum::NodeMovingError => e
+          raise ToolError, "Element became stale after #{retries} retries" unless attempts < retries
+
+          logger.debug "Retry #{attempts}/#{retries} due to: #{e.class}"
+          sleep 0.1
+          retry
+        end
+      end
+
+      # Check if element is actually visible (has dimensions and not hidden)
+      def element_visible?(element)
+        return false unless element
+
+        # Check both CSS visibility and actual rendered dimensions
+        script = <<~JS
+          (function(el) {
+            if (!el) return false;
+            const rect = el.getBoundingClientRect();
+            const style = window.getComputedStyle(el);
+            return rect.width > 0 &&
+                   rect.height > 0 &&
+                   style.visibility !== 'hidden' &&
+                   style.display !== 'none';
+          })(arguments[0])
+        JS
+
+        browser.evaluate(script, element)
+      rescue StandardError => e
+        logger.debug "Error checking element visibility: #{e.message}"
+        false
+      end
+
+      def success_response(data = {})
+        { success: true, data: data }
+      end
+
+      def image_response(base64_data, mime_type = 'image/png')
+        { success: true, type: 'image', data: base64_data, mime_type: mime_type }
+      end
+
+      def error_response(message)
+        { success: false, error: message }
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/clear_cookies_tool.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to clear cookies
+    class ClearCookiesTool < BaseTool
+      def self.tool_name
+        'clear_cookies'
+      end
+
+      def self.description
+        'Clear all cookies or cookies for a specific domain'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            domain: {
+              type: 'string',
+              description: 'Optional: Clear cookies only for this domain'
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: ['session_id']
+        }
+      end
+
+      def execute(params)
+        ensure_browser_active
+        domain = params['domain'] || params[:domain]
+
+        if domain
+          logger.info "Clearing cookies for: #{domain}"
+          # cookies.all returns a hash where keys are cookie names and values can be Cookie objects or strings
+          all_cookies = browser.cookies.all
+          cookies_to_remove = all_cookies.select do |_name, cookie|
+            cookie_str = cookie.is_a?(String) ? cookie : cookie.to_s
+            cookie_str&.match(/Domain=([^;]+)/i) &&
+              Regexp.last_match(1).include?(domain)
+          end
+          # Remove each cookie by name with domain
+          cookies_to_remove.each do |cookie_name, cookie|
+            # Extract domain from cookie string
+            cookie_str = cookie.is_a?(String) ? cookie : cookie.to_s
+            if cookie_str =~ /Domain=([^;]+)/i
+              cookie_domain = Regexp.last_match(1).strip
+              browser.cookies.remove(name: cookie_name, domain: cookie_domain)
+            end
+          end
+          success_response(message: "Cleared #{cookies_to_remove.length} cookies for #{domain}")
+        else
+          logger.info 'Clearing all cookies'
+          browser.cookies.clear
+          success_response(message: 'All cookies cleared')
+        end
+      rescue StandardError => e
+        logger.error "Clear cookies failed: #{e.message}"
+        error_response("Failed to clear cookies: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/click_tool.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to click on an element
+    class ClickTool < BaseTool
+      def self.tool_name
+        'click'
+      end
+
+      def self.description
+        'Click on an element using a CSS selector or XPath'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            selector: {
+              type: 'string',
+              description: 'CSS selector or XPath of the element to click (use xpath: prefix for XPath)'
+            },
+            wait: {
+              type: 'number',
+              description: 'Seconds to wait for element (default: 5)',
+              default: 5
+            },
+            force: {
+              type: 'boolean',
+              description: 'Force click even if element is hidden or not visible (default: false)',
+              default: false
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: %w[selector session_id]
+        }
+      end
+
+      def execute(params)
+        selector = param(params, :selector)
+        wait_time = param(params, :wait) || 5
+        force = param(params, :force) || false
+
+        logger.info "Clicking element: #{selector} (force: #{force})"
+
+        # Use retry logic for stale elements
+        with_retry do
+          element = find_element_robust(selector, wait_time)
+
+          # Scroll element into view before clicking
+          element.scroll_into_view if element.respond_to?(:scroll_into_view)
+
+          # Use native Ferrum click
+          element.click
+        end
+
+        success_response(message: "Clicked on #{selector}")
+      rescue Ferrum::NodeNotFoundError, Ferrum::CoordinatesNotFoundError, Ferrum::NodeMovingError => e
+        # If native click fails and force is enabled, try with JavaScript
+        if force
+          logger.warn "Native click failed, retrying with JavaScript: #{e.message}"
+          click_with_javascript(selector)
+          success_response(message: "Clicked on #{selector} (forced)")
+        else
+          logger.error "Click failed: #{e.message}"
+          error_response("Failed to click: #{e.message}. Try with force: true")
+        end
+      rescue StandardError => e
+        # Handle "Node does not have a layout object" and similar errors
+        if e.message.include?('layout object') || e.message.include?('not visible')
+          if force
+            logger.warn "Element not visible, forcing click with JavaScript: #{e.message}"
+            click_with_javascript(selector)
+            success_response(message: "Clicked on #{selector} (forced)")
+          else
+            logger.error "Click failed: #{e.message}"
+            error_response("Failed to click: #{e.message}. Try with force: true")
+          end
+        else
+          logger.error "Click failed: #{e.message}"
+          error_response("Failed to click: #{e.message}")
+        end
+      end
+
+      private
+
+      def find_element_robust(selector, timeout)
+        deadline = Time.now + timeout
+
+        # Support both CSS and XPath selectors
+        if selector.start_with?('xpath:', '//')
+          xpath = selector.sub(/^xpath:/, '')
+          logger.debug "Using XPath: #{xpath}"
+
+          # Retry XPath search until timeout
+          elements = []
+          loop do
+            elements = browser.xpath(xpath)
+            break unless elements.empty?
+
+            raise ToolError, "Element not found with XPath: #{xpath}" if Time.now > deadline
+
+            sleep 0.2
+          end
+
+          # Prefer visible element
+          element = elements.find { |el| element_visible?(el) } || elements.first
+          visibility = element_visible?(element) ? 'visible' : 'first'
+          logger.debug "Found #{elements.length} XPath matches, using #{visibility} one"
+        else
+          # For CSS selectors, use the base find_element with timeout
+          element = find_element(selector, timeout: timeout)
+        end
+
+        element
+      end
+
+      def click_with_javascript(selector) # rubocop:disable Metrics/MethodLength
+        logger.info "Using JavaScript click for: #{selector}"
+
+        # Build JavaScript to find and click element, even if hidden
+        if selector.start_with?('xpath:', '//')
+          xpath = selector.sub(/^xpath:/, '')
+          script = <<~JAVASCRIPT
+            const xpath = #{xpath.inspect};
+            const result = document.evaluate(xpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+            const elements = [];
+            for (let i = 0; i < result.snapshotLength; i++) {
+              elements.push(result.snapshotItem(i));
+            }
+
+            if (elements.length === 0) {
+              throw new Error('No element found with XPath: ' + xpath);
+            }
+
+            // Find first visible element, or use first element if force clicking
+            const visible = elements.find(el => el.offsetWidth > 0 && el.offsetHeight > 0);
+            const target = visible || elements[0];
+
+            // For hidden elements, temporarily show them, click, then hide again
+            const wasHidden = target.offsetWidth === 0 && target.offsetHeight === 0;
+            const originalDisplay = target.style.display;
+            const originalVisibility = target.style.visibility;
+
+            if (wasHidden) {
+              target.style.display = 'block';
+              target.style.visibility = 'visible';
+            }
+
+            try {
+              target.scrollIntoView({ behavior: 'instant', block: 'center' });
+              target.click();
+            } finally {
+              if (wasHidden) {
+                target.style.display = originalDisplay;
+                target.style.visibility = originalVisibility;
+              }
+            }
+
+            return true;
+          JAVASCRIPT
+        else
+          script = <<~JAVASCRIPT
+            const elements = Array.from(document.querySelectorAll(#{selector.inspect}));
+
+            if (elements.length === 0) {
+              throw new Error('No elements found with selector: #{selector}');
+            }
+
+            // Find first visible element, or use first element if force clicking
+            const visible = elements.find(el => el.offsetWidth > 0 && el.offsetHeight > 0);
+            const target = visible || elements[0];
+
+            // For hidden elements, temporarily show them, click, then hide again
+            const wasHidden = target.offsetWidth === 0 && target.offsetHeight === 0;
+            const originalDisplay = target.style.display;
+            const originalVisibility = target.style.visibility;
+
+            if (wasHidden) {
+              target.style.display = 'block';
+              target.style.visibility = 'visible';
+            }
+
+            try {
+              target.scrollIntoView({ behavior: 'instant', block: 'center' });
+              target.click();
+            } finally {
+              if (wasHidden) {
+                target.style.display = originalDisplay;
+                target.style.visibility = originalVisibility;
+              }
+            }
+
+            return true;
+          JAVASCRIPT
+        end
+
+        browser.execute(script)
+        logger.debug 'JavaScript click executed successfully'
+      end
+
+      def element_visible?(element)
+        return false unless element
+
+        # Use property instead of evaluate to avoid "Node does not have a layout object" errors
+        offset_width = element.property('offsetWidth')
+        offset_height = element.property('offsetHeight')
+        offset_width&.positive? && offset_height&.positive?
+      rescue StandardError => e
+        logger.debug "Cannot check visibility: #{e.message}"
+        false
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/close_session_tool.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Close a specific session
+    class CloseSessionTool < SessionTool
+      def self.tool_name
+        'close_session'
+      end
+
+      def self.description
+        'Close a specific browser session by its ID. The browser will be stopped and the session will be removed.'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            session_id: {
+              type: 'string',
+              description: 'The ID of the session to close'
+            }
+          },
+          required: ['session_id']
+        }
+      end
+
+      def execute(params)
+        session_id = params[:session_id] || params['session_id']
+
+        return error_response('session_id is required') unless session_id
+
+        success = session_manager.close_session(session_id)
+
+        if success
+          success_response(
+            session_id: session_id,
+            message: 'Session closed successfully'
+          )
+        else
+          error_response("Session not found: #{session_id}")
+        end
+      rescue StandardError => e
+        logger.error "Failed to close session: #{e.message}"
+        error_response("Failed to close session: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/create_session_tool.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    class CreateSessionTool < SessionTool
+      def self.tool_name
+        'create_session'
+      end
+
+      def self.description
+        <<~DESC
+          Create a new browser session with custom options.
+          Supports multiple browsers in parallel (Chrome, BotBrowser).
+          Returns a session_id to use with other tools.
+
+          Note: When running in Docker (DOCKER=true), headless mode is mandatory.
+          Attempting to create a non-headless session will result in an error.
+        DESC
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            browser_id: {
+              type: 'string',
+              description: 'Optional: Browser ID to use (from ferrum://browsers resource)'
+            },
+            user_profile_id: {
+              type: 'string',
+              description: 'Optional: User profile ID to use (from ferrum://user-profiles resource)'
+            },
+            bot_profile_id: {
+              type: 'string',
+              description: 'Optional: BotBrowser profile ID to use (from ferrum://bot-profiles resource)'
+            },
+            browser_path: {
+              type: 'string',
+              description: 'Optional: Path to browser executable (legacy, prefer browser_id)'
+            },
+            botbrowser_profile: {
+              type: 'string',
+              description: 'Optional: Path to BotBrowser profile (legacy, prefer bot_profile_id)'
+            },
+            headless: {
+              type: 'boolean',
+              description: 'Optional: Run browser in headless mode (default: false). ' \
+                           'REQUIRED to be true when running in Docker.'
+            },
+            timeout: {
+              type: 'number',
+              description: 'Optional: Browser timeout in seconds (default: 60)'
+            },
+            browser_options: {
+              type: 'object',
+              description: 'Optional: Additional browser command-line options (e.g., {"--window-size": "1920,1080"})',
+              additionalProperties: { type: 'string' }
+            },
+            metadata: {
+              type: 'object',
+              description: 'Optional: Custom metadata for this session (e.g., {"user": "john", "project": "scraping"})',
+              additionalProperties: true
+            }
+          }
+        }
+      end
+
+      def execute(params)
+        logger.info 'Creating new browser session'
+
+        options = build_options(params)
+        validate_docker_headless!(options)
+
+        session_id = session_manager.create_session(options)
+
+        success_response(
+          session_id: session_id,
+          message: 'Session created successfully',
+          options: options.except(:metadata)
+        )
+      rescue StandardError => e
+        logger.error "Failed to create session: #{e.message}"
+        error_response("Failed to create session: #{e.message}")
+      end
+
+      private
+
+      def validate_docker_headless!(options)
+        # Check if running in Docker environment
+        return unless ENV['DOCKER'] == 'true'
+
+        # In Docker, headless mode is mandatory
+        # Check if headless is explicitly set to false
+        if options.key?(:headless) && options[:headless] == false
+          raise 'Headless mode is required when running in Docker. ' \
+                'Cannot create a non-headless session in a containerized environment.'
+        end
+
+        # Force headless to true in Docker if not explicitly set
+        options[:headless] = true unless options.key?(:headless)
+      end
+
+      def build_options(params)
+        options = {}
+
+        # New resource-based parameters (preferred)
+        if params[:browser_id] || params['browser_id']
+          options[:browser_id] =
+            params[:browser_id] || params['browser_id']
+        end
+        if params[:user_profile_id] || params['user_profile_id']
+          options[:user_profile_id] =
+            params[:user_profile_id] || params['user_profile_id']
+        end
+        if params[:bot_profile_id] || params['bot_profile_id']
+          options[:bot_profile_id] =
+            params[:bot_profile_id] || params['bot_profile_id']
+        end
+
+        # Legacy parameters (for backward compatibility)
+        if params[:browser_path] || params['browser_path']
+          options[:browser_path] =
+            params[:browser_path] || params['browser_path']
+        end
+        if params[:botbrowser_profile] || params['botbrowser_profile']
+          options[:botbrowser_profile] =
+            params[:botbrowser_profile] || params['botbrowser_profile']
+        end
+
+        # Other options
+        if params.key?(:headless) || params.key?('headless')
+          # Use fetch to handle false values correctly
+          options[:headless] = params.key?(:headless) ? params[:headless] : params['headless']
+        end
+        options[:timeout] = params[:timeout] || params['timeout'] if params[:timeout] || params['timeout']
+        if params[:browser_options] || params['browser_options']
+          options[:browser_options] =
+            params[:browser_options] || params['browser_options']
+        end
+        options[:metadata] = params[:metadata] || params['metadata'] if params[:metadata] || params['metadata']
+
+        options
+      end
+    end
+  end
+end