ferrum-mcp 1.0.0 → 1.1.0

data/lib/ferrum_mcp/tools/accept_cookies_tool.rb

@@ -6,31 +6,11 @@ module FerrumMCP
     # Uses multiple strategies to find and click accept buttons
     # rubocop:disable Metrics/ClassLength
     class AcceptCookiesTool < BaseTool
-      def self.tool_name
-        'accept_cookies'
-      end
-
-      def self.description
-        'Automatically detect and accept cookie consent banners using multiple detection strategies'
-      end
+      tool_name 'accept_cookies'
+      description 'Automatically detect and accept cookie consent banners using multiple detection strategies'
 
-      def self.input_schema
-        {
-          type: 'object',
-          properties: {
-            wait: {
-              type: 'number',
-              description: 'Seconds to wait for cookie banner to appear (default: 3)',
-              default: 3
-            },
-            session_id: {
-              type: 'string',
-              description: 'Session ID to use for this operation'
-            }
-          },
-          required: %w[session_id]
-        }
-      end
+      param :wait, type: :number, default: 3,
+                   description: 'Seconds to wait for the cookie banner to appear (default: 3)'
 
       # Common text patterns for cookie accept buttons (multiple languages)
       # Patterns are ordered from most specific to least specific to avoid false positives
@@ -59,9 +39,9 @@ module FerrumMCP
         settings options manage gérer
       ].freeze
 
-      def execute(params)
+      def perform(params)
         ensure_browser_active
-        wait_time = param(params, :wait) || 3
+        wait_time = params[:wait]
 
         logger.info 'Attempting to accept cookies using multiple strategies...'
 
@@ -262,13 +242,13 @@ module FerrumMCP
         logger.debug 'Trying iframe detection...'
 
         # Get all iframes
-        iframes = browser.css('iframe')
+        iframes = page.css('iframe')
         return { found: false } if iframes.empty?
 
         logger.debug "Found #{iframes.length} iframe(s), checking for cookie banners..."
 
         # Get frames (includes main frame + all iframes)
-        frames = browser.frames
+        frames = page.frames
         return { found: false } if frames.empty?
 
         # Skip the main frame (index 0), only check iframes
@@ -374,7 +354,7 @@ module FerrumMCP
       # Helper: Try multiple CSS selectors
       def try_selectors(selectors)
         selectors.each do |selector|
-          element = browser.at_css(selector)
+          element = page.at_css(selector)
           next unless element
 
           # Check if element is visible
@@ -405,7 +385,7 @@ module FerrumMCP
         xpath = "//#{tag}[contains(translate(normalize-space(.), 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', " \
                 "'abcdefghijklmnopqrstuvwxyz'), #{escaped_text})]"
 
-        browser.xpath(xpath)
+        page.xpath(xpath)
       rescue StandardError => e
         logger.debug "XPath search for '#{text}' failed: #{e.message}"
         []
@@ -441,7 +421,7 @@ module FerrumMCP
 
         # Fallback to JavaScript click
         begin
-          browser.execute(<<~JAVASCRIPT, element)
+          page.execute(<<~JAVASCRIPT, element)
             arguments[0].scrollIntoView({ behavior: 'instant', block: 'center' });
             arguments[0].click();
           JAVASCRIPT

data/lib/ferrum_mcp/tools/base_tool.rb

@@ -2,65 +2,99 @@
 
 module FerrumMCP
   module Tools
-    # Base class for all MCP tools
+    # Base class for tools that operate on a browser session.
+    #
+    # Subclasses declare their interface with the Definition DSL and implement
+    # #perform(params). Params arrive with symbol keys and defaults applied.
+    #
+    # Selectors accepted everywhere an element is looked up:
+    #   - CSS:            "#login button"
+    #   - XPath:          "xpath://button[@type='submit']" or "//button[...]"
+    #   - Snapshot ref:   "ref:e12" (from the snapshot tool)
     class BaseTool
-      attr_reader :browser, :logger
+      extend Definition
+
+      requires_session true
+
+      REF_SELECTOR = /\Aref:(e\d+)\z/
+      REF_ATTRIBUTE = 'data-fmcp-ref'
+      POLL_INTERVAL = 0.1
+
+      attr_reader :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'
+      # Entry point used by the server and the specs.
+      def execute(raw_params)
+        perform(self.class.normalize_params(raw_params))
       end
 
-      def self.tool_name
-        raise NotImplementedError, 'Subclasses must implement .tool_name'
+      def perform(_params)
+        raise NotImplementedError, 'Subclasses must implement #perform'
       end
 
-      def self.description
-        raise NotImplementedError, 'Subclasses must implement .description'
-      end
+      protected
 
-      def self.input_schema
-        raise NotImplementedError, 'Subclasses must implement .input_schema'
+      # Ferrum::Browser of the session
+      def browser
+        @browser_manager.browser
       end
 
-      protected
+      # Current tab (Ferrum::Page). Tools act on the page, not the browser, so
+      # tab switching works.
+      def page
+        @browser_manager.page
+      end
 
       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]
+      # Resolve a selector string into [:css, selector] or [:xpath, expression]
+      def resolve_selector(selector)
+        selector = selector.to_s.strip
+        if (match = REF_SELECTOR.match(selector))
+          [:css, %([#{REF_ATTRIBUTE}="#{match[1]}"])]
+        elsif selector.start_with?('xpath:')
+          [:xpath, selector.delete_prefix('xpath:')]
+        elsif selector.start_with?('//', '(//')
+          [:xpath, selector]
+        else
+          [:css, selector]
+        end
       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
+      # Find the first element matching the selector, polling until timeout.
+      def find_element(selector, timeout: 5, within: page)
+        deadline = monotonic_now + timeout.to_f
 
         loop do
-          element = browser.at_css(selector)
+          element = first_match(selector, within)
           return element if element
 
-          raise ToolError, "Element not found: #{selector}" if Time.now > deadline
+          raise ToolError, "Element not found: #{selector}" if monotonic_now > deadline
 
-          # Use shorter sleep for better responsiveness (0.1s instead of 0.5s)
-          sleep 0.1
+          sleep POLL_INTERVAL
         end
       rescue Ferrum::NodeNotFoundError
         raise ToolError, "Element not found: #{selector}"
       end
 
-      # Retry logic for handling stale/moving elements
+      # All elements matching the selector (no waiting)
+      def find_elements(selector, within: page)
+        kind, expression = resolve_selector(selector)
+        kind == :xpath ? within.xpath(expression) : within.css(expression)
+      end
+
+      def first_match(selector, within = page)
+        kind, expression = resolve_selector(selector)
+        kind == :xpath ? within.at_xpath(expression) : within.at_css(expression)
+      end
+
+      # Retry logic for stale/moving elements
       def with_retry(retries: 3)
         attempts = 0
         begin
@@ -70,34 +104,41 @@ module FerrumMCP
           raise ToolError, "Element became stale after #{retries} retries" unless attempts < retries
 
           logger.debug "Retry #{attempts}/#{retries} due to: #{e.class}"
-          sleep 0.1
+          sleep POLL_INTERVAL
           retry
         end
       end
 
-      # Check if element is actually visible (has dimensions and not hidden)
+      # Visible = rendered with a size and not hidden through CSS
       def element_visible?(element)
         return false unless element
 
-        # Check both CSS visibility and actual rendered dimensions
-        script = <<~JS
+        page.evaluate(<<~JS, element)
           (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';
+            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
 
+      # Escape a string for use inside an XPath expression
+      def xpath_literal(text)
+        return "'#{text}'" unless text.include?("'")
+
+        parts = text.split("'", -1).map { |part| "'#{part}'" }
+        "concat(#{parts.join(%(, "'", ))})"
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
       def success_response(data = {})
         { success: true, data: data }
       end

data/lib/ferrum_mcp/tools/clear_cookies_tool.rb

@@ -2,59 +2,30 @@
 
 module FerrumMCP
   module Tools
-    # Tool to clear cookies
+    # 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
+      tool_name 'clear_cookies'
+      description 'Clear all cookies, or only the cookies whose domain contains the given string'
 
-      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
+      param :domain, type: :string, description: 'Optional: clear cookies only for this domain (substring match)'
 
-      def execute(params)
+      def perform(params)
         ensure_browser_active
-        domain = params['domain'] || params[:domain]
+        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
+          removed = 0
+          page.cookies.all.each_value do |cookie|
+            next unless cookie.respond_to?(:domain) && cookie.domain.to_s.include?(domain)
+
+            page.cookies.remove(name: cookie.name, domain: cookie.domain, path: cookie.path)
+            removed += 1
           end
-          success_response(message: "Cleared #{cookies_to_remove.length} cookies for #{domain}")
+          success_response(message: "Cleared #{removed} cookies for #{domain}", count: removed)
         else
           logger.info 'Clearing all cookies'
-          browser.cookies.clear
+          page.cookies.clear
           success_response(message: 'All cookies cleared')
         end
       rescue StandardError => e

data/lib/ferrum_mcp/tools/click_tool.rb

@@ -2,83 +2,35 @@
 
 module FerrumMCP
   module Tools
-    # Tool to click on an element
+    # Click on an element
     class ClickTool < BaseTool
-      def self.tool_name
-        'click'
-      end
+      tool_name 'click'
+      description 'Click on an element using a CSS selector, an XPath (xpath: prefix) or a snapshot ref (ref:eN)'
 
-      def self.description
-        'Click on an element using a CSS selector or XPath'
-      end
+      param :selector, type: :string, required: true,
+                       description: 'CSS selector, XPath (xpath: prefix) or snapshot ref (ref:e12) of the element'
+      param :wait, type: :number, default: 5, description: 'Seconds to wait for the element (default: 5)'
+      param :force, type: :boolean, default: false,
+                    description: 'Force click through JavaScript when the element is hidden (default: false)'
 
-      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
+      def perform(params)
+        selector = params[:selector]
+        force = params[:force]
 
         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 = find_clickable(selector, params[:wait])
+          element.scroll_into_view
           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
+        forced_click(selector, e, force)
       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
+          forced_click(selector, e, force)
         else
           logger.error "Click failed: #{e.message}"
           error_response("Failed to click: #{e.message}")
@@ -87,131 +39,56 @@ module FerrumMCP
 
       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)
+      def forced_click(selector, error, force)
+        unless force
+          logger.error "Click failed: #{error.message}"
+          return error_response("Failed to click: #{error.message}. Try with force: true")
         end
 
-        element
+        logger.warn "Native click failed, retrying with JavaScript: #{error.message}"
+        click_with_javascript(selector)
+        success_response(message: "Clicked on #{selector} (forced)")
       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));
-            }
+      # Prefer a visible match when several elements match
+      def find_clickable(selector, timeout)
+        element = find_element(selector, timeout: timeout)
+        return element if element_visible?(element)
 
-            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'
+        visible = find_elements(selector).find { |el| element_visible?(el) }
+        visible || element
       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
+      def click_with_javascript(selector)
+        logger.info "Using JavaScript click for: #{selector}"
+        kind, expression = resolve_selector(selector)
+        finder = if kind == :xpath
+                   <<~JS
+                     const result = document.evaluate(#{expression.inspect}, document, null,
+                       XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+                     const elements = [];
+                     for (let i = 0; i < result.snapshotLength; i++) elements.push(result.snapshotItem(i));
+                   JS
+                 else
+                   "const elements = Array.from(document.querySelectorAll(#{expression.inspect}));"
+                 end
+
+        page.execute(<<~JS)
+          #{finder}
+          if (elements.length === 0) throw new Error('No element found for ' + #{selector.inspect});
+          const visible = elements.find(el => el.offsetWidth > 0 && el.offsetHeight > 0);
+          const target = visible || elements[0];
+          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; }
+          }
+        JS
       end
     end
   end

data/lib/ferrum_mcp/tools/close_session_tool.rb

@@ -4,39 +4,17 @@ 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']
+      tool_name 'close_session'
+      description 'Close a specific browser session by its ID. The browser will be stopped and the session removed.'
 
-        return error_response('session_id is required') unless session_id
+      param :session_id, type: :string, required: true, description: 'The ID of the session to close'
 
-        success = session_manager.close_session(session_id)
+      def perform(params)
+        session_id = params[:session_id]
+        return error_response('session_id is required') if session_id.to_s.empty?
 
-        if success
-          success_response(
-            session_id: session_id,
-            message: 'Session closed successfully'
-          )
+        if session_manager.close_session(session_id)
+          success_response(session_id: session_id, message: 'Session closed successfully')
         else
           error_response("Session not found: #{session_id}")
         end