ferrum-mcp 1.0.0 → 1.1.0

data/lib/ferrum_mcp/tools/query_shadow_dom_tool.rb

@@ -2,223 +2,68 @@
 
 module FerrumMCP
   module Tools
-    # Tool to interact with Shadow DOM elements
+    # Interact with Shadow DOM elements
     class QueryShadowDOMTool < BaseTool
-      def self.tool_name
-        'query_shadow_dom'
-      end
-
-      def self.description
-        'Query and interact with elements inside Shadow DOM'
-      end
-
-      def self.input_schema
-        {
-          type: 'object',
-          properties: {
-            host_selector: {
-              type: 'string',
-              description: 'CSS selector of the Shadow DOM host element'
-            },
-            shadow_selector: {
-              type: 'string',
-              description: 'CSS selector to find element(s) within the Shadow DOM'
-            },
-            action: {
-              type: 'string',
-              description: 'Action to perform: click, get_text, get_html, or get_attribute',
-              enum: %w[click get_text get_html get_attribute]
-            },
-            attribute: {
-              type: 'string',
-              description: 'Attribute name (required when action is get_attribute)'
-            },
-            multiple: {
-              type: 'boolean',
-              description: 'Return all matching elements (default: false)',
-              default: false
-            },
-            session_id: {
-              type: 'string',
-              description: 'Session ID to use for this operation'
-            }
-          },
-          required: %w[host_selector shadow_selector action session_id]
-        }
-      end
-
-      def execute(params)
-        host_selector = params['host_selector'] || params[:host_selector]
-        shadow_selector = params['shadow_selector'] || params[:shadow_selector]
-        action = params['action'] || params[:action]
-        attribute = params['attribute'] || params[:attribute]
-        multiple = params['multiple'] || params[:multiple] || false
-
-        logger.info "Querying Shadow DOM: #{host_selector} -> #{shadow_selector}, action: #{action}"
-
-        result = case action
-                 when 'click'
-                   click_in_shadow_dom(host_selector, shadow_selector)
-                 when 'get_text'
-                   get_text_from_shadow_dom(host_selector, shadow_selector, multiple)
-                 when 'get_html'
-                   get_html_from_shadow_dom(host_selector, shadow_selector, multiple)
-                 when 'get_attribute'
-                   raise ToolError, 'attribute parameter required for get_attribute action' unless attribute
-
-                   get_attribute_from_shadow_dom(host_selector, shadow_selector, attribute, multiple)
-                 else
-                   raise ToolError, "Unknown action: #{action}"
-                 end
-
-        success_response(result)
+      tool_name 'query_shadow_dom'
+      description 'Query and interact with elements inside a Shadow DOM'
+
+      param :host_selector, type: :string, required: true, description: 'CSS selector of the Shadow DOM host element'
+      param :shadow_selector, type: :string, required: true,
+                              description: 'CSS selector to find element(s) within the Shadow DOM'
+      param :action, type: :string, required: true, enum: %w[click get_text get_html get_attribute],
+                     description: 'Action to perform: click, get_text, get_html, or get_attribute'
+      param :attribute, type: :string, description: 'Attribute name (required when action is get_attribute)'
+      param :multiple, type: :boolean, default: false, description: 'Return all matching elements (default: false)'
+
+      def perform(params)
+        action = params[:action]
+        logger.info "Querying Shadow DOM: #{params[:host_selector]} -> #{params[:shadow_selector]}, action: #{action}"
+
+        if action == 'get_attribute' && params[:attribute].to_s.empty?
+          raise ToolError, 'attribute parameter required for get_attribute action'
+        end
+
+        result = page.evaluate(script_for(action, params[:multiple]),
+                               params[:host_selector], params[:shadow_selector], params[:attribute])
+        success_response(format_result(action, params, result))
       rescue StandardError => e
         logger.error "Shadow DOM query failed: #{e.message}"
         error_response("Failed to query Shadow DOM: #{e.message}")
       end
 
-      private
+      EXTRACTORS = {
+        'click' => 'el.scrollIntoView({ behavior: "instant", block: "center" }); el.click(); return true;',
+        'get_text' => 'return el.textContent;',
+        'get_html' => 'return el.innerHTML;',
+        'get_attribute' => 'return el.getAttribute(attribute);'
+      }.freeze
 
-      def click_in_shadow_dom(host_selector, shadow_selector)
-        host_js = host_selector.inspect
-        shadow_js = shadow_selector.inspect
+      private
 
-        script = <<~JS.strip
-          (function() {
-            var host = document.querySelector(#{host_js});
-            if (!host || !host.shadowRoot) {
-              throw new Error('Shadow DOM host not found or has no shadowRoot');
+      def script_for(action, multiple)
+        extractor = EXTRACTORS.fetch(action) { raise ToolError, "Unknown action: #{action}" }
+        <<~JS
+          (function(hostSelector, shadowSelector, attribute) {
+            const host = document.querySelector(hostSelector);
+            if (!host || !host.shadowRoot) throw new Error('Shadow DOM host not found or has no shadowRoot');
+            const extract = (el) => { #{extractor} };
+            if (#{multiple ? 'true' : 'false'}) {
+              return Array.from(host.shadowRoot.querySelectorAll(shadowSelector)).map(extract);
             }
-            var element = host.shadowRoot.querySelector(#{shadow_js});
-            if (!element) {
-              throw new Error('Element not found in Shadow DOM');
-            }
-            element.scrollIntoView({ behavior: 'instant', block: 'center' });
-            element.click();
-            return true;
-          })()
+            const el = host.shadowRoot.querySelector(shadowSelector);
+            if (!el) throw new Error('Element not found in Shadow DOM');
+            return extract(el);
+          })(arguments[0], arguments[1], arguments[2])
         JS
-
-        browser.execute(script)
-        { message: "Clicked element in Shadow DOM: #{shadow_selector}" }
-      end
-
-      def get_text_from_shadow_dom(host_selector, shadow_selector, multiple)
-        host_js = host_selector.inspect
-        shadow_js = shadow_selector.inspect
-
-        script = if multiple
-                   <<~JS.strip
-                     (function() {
-                       var host = document.querySelector(#{host_js});
-                       if (!host || !host.shadowRoot) {
-                         throw new Error('Shadow DOM host not found or has no shadowRoot');
-                       }
-                       var elements = Array.from(host.shadowRoot.querySelectorAll(#{shadow_js}));
-                       var texts = [];
-                       for (var i = 0; i < elements.length; i++) {
-                         texts.push(elements[i].textContent);
-                       }
-                       return texts;
-                     })()
-                   JS
-                 else
-                   <<~JS.strip
-                     (function() {
-                       var host = document.querySelector(#{host_js});
-                       if (!host || !host.shadowRoot) {
-                         throw new Error('Shadow DOM host not found or has no shadowRoot');
-                       }
-                       var element = host.shadowRoot.querySelector(#{shadow_js});
-                       if (!element) {
-                         throw new Error('Element not found in Shadow DOM');
-                       }
-                       return element.textContent;
-                     })()
-                   JS
-                 end
-
-        result = browser.evaluate(script)
-        multiple ? { texts: result, count: result.length } : { text: result }
       end
 
-      def get_html_from_shadow_dom(host_selector, shadow_selector, multiple)
-        host_js = host_selector.inspect
-        shadow_js = shadow_selector.inspect
-
-        script = if multiple
-                   <<~JS.strip
-                     (function() {
-                       var host = document.querySelector(#{host_js});
-                       if (!host || !host.shadowRoot) {
-                         throw new Error('Shadow DOM host not found or has no shadowRoot');
-                       }
-                       var elements = Array.from(host.shadowRoot.querySelectorAll(#{shadow_js}));
-                       var htmls = [];
-                       for (var i = 0; i < elements.length; i++) {
-                         htmls.push(elements[i].innerHTML);
-                       }
-                       return htmls;
-                     })()
-                   JS
-                 else
-                   <<~JS.strip
-                     (function() {
-                       var host = document.querySelector(#{host_js});
-                       if (!host || !host.shadowRoot) {
-                         throw new Error('Shadow DOM host not found or has no shadowRoot');
-                       }
-                       var element = host.shadowRoot.querySelector(#{shadow_js});
-                       if (!element) {
-                         throw new Error('Element not found in Shadow DOM');
-                       }
-                       return element.innerHTML;
-                     })()
-                   JS
-                 end
-
-        result = browser.evaluate(script)
-        multiple ? { html: result, count: result.length } : { html: result }
-      end
-
-      def get_attribute_from_shadow_dom(host_selector, shadow_selector, attribute, multiple)
-        host_js = host_selector.inspect
-        shadow_js = shadow_selector.inspect
-        attr_js = attribute.inspect
-
-        script = if multiple
-                   <<~JS.strip
-                     (function() {
-                       var host = document.querySelector(#{host_js});
-                       if (!host || !host.shadowRoot) {
-                         throw new Error('Shadow DOM host not found or has no shadowRoot');
-                       }
-                       var elements = Array.from(host.shadowRoot.querySelectorAll(#{shadow_js}));
-                       var values = [];
-                       for (var i = 0; i < elements.length; i++) {
-                         values.push(elements[i].getAttribute(#{attr_js}));
-                       }
-                       return values;
-                     })()
-                   JS
-                 else
-                   <<~JS.strip
-                     (function() {
-                       var host = document.querySelector(#{host_js});
-                       if (!host || !host.shadowRoot) {
-                         throw new Error('Shadow DOM host not found or has no shadowRoot');
-                       }
-                       var element = host.shadowRoot.querySelector(#{shadow_js});
-                       if (!element) {
-                         throw new Error('Element not found in Shadow DOM');
-                       }
-                       return element.getAttribute(#{attr_js});
-                     })()
-                   JS
-                 end
-
-        result = browser.evaluate(script)
-        multiple ? { values: result, count: result.length } : { value: result }
+      def format_result(action, params, result)
+        case action
+        when 'click' then { message: "Clicked element in Shadow DOM: #{params[:shadow_selector]}" }
+        when 'get_text' then params[:multiple] ? { texts: result, count: result.length } : { text: result }
+        when 'get_html' then params[:multiple] ? { html: result, count: result.length } : { html: result }
+        else params[:multiple] ? { values: result, count: result.length } : { value: result }
+        end
       end
     end
   end

data/lib/ferrum_mcp/tools/refresh_tool.rb

@@ -2,41 +2,18 @@
 
 module FerrumMCP
   module Tools
-    # Tool to refresh the current page
+    # Refresh the current page
     class RefreshTool < BaseTool
-      def self.tool_name
-        'refresh'
-      end
-
-      def self.description
-        'Refresh the current page'
-      end
+      tool_name 'refresh'
+      description 'Refresh the current page'
 
-      def self.input_schema
-        {
-          type: 'object',
-          properties: {
-            session_id: {
-              type: 'string',
-              description: 'Session ID to use for this operation'
-            }
-          },
-          required: ['session_id']
-        }
-      end
-
-      def execute(_params)
+      def perform(_params)
         ensure_browser_active
         logger.info 'Refreshing page'
-        browser.refresh
-
-        # Wait for network to be idle to ensure page is reloaded
-        browser.network.wait_for_idle(timeout: 30)
+        page.refresh
+        page.network.wait_for_idle(timeout: 30)
 
-        success_response(
-          url: browser.url,
-          title: browser.title
-        )
+        success_response(url: page.url, title: page.title)
       rescue Ferrum::TimeoutError => e
         logger.error "Refresh timeout: #{e.message}"
         error_response("Refresh timed out: #{e.message}")

data/lib/ferrum_mcp/tools/screenshot_tool.rb

@@ -1,83 +1,37 @@
 # frozen_string_literal: true
 
-require 'vips'
+require 'base64'
 
 module FerrumMCP
   module Tools
-    # Tool to take screenshots
+    # Take screenshots
     class ScreenshotTool < BaseTool
       # Claude API has a maximum dimension of 8000 pixels per side
       MAX_DIMENSION = 8000
-      def self.tool_name
-        'screenshot'
-      end
 
-      def self.description
-        'Take a screenshot of the page or a specific element'
-      end
+      tool_name 'screenshot'
+      description 'Take a screenshot of the page or of a specific element (returned as an image)'
 
-      def self.input_schema
-        {
-          type: 'object',
-          properties: {
-            selector: {
-              type: 'string',
-              description: 'Optional: CSS selector to screenshot specific element'
-            },
-            full_page: {
-              type: 'boolean',
-              description: 'Capture full scrollable page (default: false)',
-              default: false
-            },
-            format: {
-              type: 'string',
-              enum: %w[png jpeg],
-              description: 'Image format (default: png)',
-              default: 'png'
-            },
-            session_id: {
-              type: 'string',
-              description: 'Session ID to use for this operation'
-            }
-          },
-          required: ['session_id']
-        }
-      end
+      param :selector, type: :string, description: 'Optional: selector of the element to screenshot'
+      param :full_page, type: :boolean, default: false, description: 'Capture the full scrollable page (default: false)'
+      param :format, type: :string, default: 'png', enum: %w[png jpeg], description: 'Image format (default: png)'
 
-      def execute(params)
+      def perform(params)
         ensure_browser_active
-        selector = param(params, :selector)
-        full_page = param(params, :full_page) || false
-        format = param(params, :format) || 'png'
-
+        selector = params[:selector]
+        format = params[:format]
         logger.info 'Taking screenshot'
 
-        # If selector provided, verify element exists and is visible
+        options = { format: format, full: params[:full_page], encoding: :binary }
         if selector
           element = find_element(selector)
-          element.scroll_into_view if element.respond_to?(:scroll_into_view)
-
-          # Small delay to ensure element is fully rendered
-          sleep 0.1
+          element.scroll_into_view
+          sleep 0.1 # let the element render after scrolling
+          options[:selector] = css_selector_for(selector, element)
         end
 
-        # Request binary encoding from Ferrum (by default it returns base64)
-        options = { format: format, full: full_page, encoding: :binary }
-
-        # Add selector to options if provided
-        options[:selector] = selector if selector
-
-        screenshot_data = browser.screenshot(**options)
-
-        # Resize if dimensions exceed Claude API limits
-        screenshot_data = resize_if_needed(screenshot_data, format)
-
-        # Now encode the binary data to base64 for MCP
-        base64_data = Base64.strict_encode64(screenshot_data)
-        mime_type = format == 'png' ? 'image/png' : 'image/jpeg'
-
-        # Use image_response for MCP image injection
-        image_response(base64_data, mime_type)
+        data = resize_if_needed(page.screenshot(**options), format)
+        image_response(Base64.strict_encode64(data), format == 'png' ? 'image/png' : 'image/jpeg')
       rescue StandardError => e
         logger.error "Screenshot failed: #{e.message}"
         error_response("Failed to take screenshot: #{e.message}")
@@ -85,33 +39,22 @@ module FerrumMCP
 
       private
 
-      # Resize image if any dimension exceeds MAX_DIMENSION
-      # @param image_data [String] Binary image data
-      # @param format [String] Image format ('png' or 'jpeg')
-      # @return [String] Resized binary image data (or original if no resize needed)
-      def resize_if_needed(image_data, format)
-        image = Vips::Image.new_from_buffer(image_data, '')
-        width = image.width
-        height = image.height
-
-        # Check if resize is needed
-        if width <= MAX_DIMENSION && height <= MAX_DIMENSION
-          logger.debug "Screenshot dimensions (#{width}x#{height}) within limits, no resize needed"
-          return image_data
-        end
-
-        # Calculate scaling factor to fit within MAX_DIMENSION
-        scale = [MAX_DIMENSION.to_f / width, MAX_DIMENSION.to_f / height].min
-        new_width = (width * scale).to_i
-        new_height = (height * scale).to_i
+      # Ferrum's screenshot(selector:) only takes CSS; map refs/xpath to a CSS
+      # selector by tagging the resolved element.
+      def css_selector_for(selector, element)
+        kind, expression = resolve_selector(selector)
+        return expression if kind == :css
 
-        logger.info "Resizing screenshot from #{width}x#{height} to #{new_width}x#{new_height}"
+        page.execute("arguments[0].setAttribute('data-fmcp-shot', '1')", element)
+        '[data-fmcp-shot="1"]'
+      end
 
-        # Resize image (using high quality Lanczos3 interpolation)
-        resized = image.thumbnail_image(new_width, height: new_height, size: :force)
+      # Resize image if any dimension exceeds MAX_DIMENSION. Needs libvips; when
+      # it is not installed the original image is returned untouched.
+      def resize_if_needed(image_data, format)
+        return image_data unless ImageResizer.available?
 
-        # Return resized binary data in the correct format
-        resized.write_to_buffer(".#{format}")
+        ImageResizer.fit(image_data, MAX_DIMENSION, format, logger: logger)
       rescue StandardError => e
         logger.warn "Failed to resize screenshot: #{e.message}, returning original"
         image_data

data/lib/ferrum_mcp/tools/scroll_tool.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Scroll the window, a scrollable element, or an element into view
+    class ScrollTool < BaseTool
+      tool_name 'scroll'
+      description 'Scroll the page (or a scrollable element) by direction/amount, to absolute coordinates, ' \
+                  'or bring an element into view'
+
+      param :selector, type: :string,
+                       description: 'Optional: element to scroll into view, or the scrollable container to scroll ' \
+                                    'when a direction is given'
+      param :direction, type: :string, enum: %w[up down left right top bottom],
+                        description: 'Direction to scroll (top/bottom jump to the extremes)'
+      param :amount, type: :number, default: 500, description: 'Pixels to scroll for up/down/left/right (default: 500)'
+      param :x, type: :number, description: 'Absolute horizontal scroll position'
+      param :y, type: :number, description: 'Absolute vertical scroll position'
+
+      def perform(params)
+        ensure_browser_active
+        selector = params[:selector]
+        element = selector ? find_element(selector) : nil
+        logger.info "Scrolling #{selector || 'window'} #{params[:direction] || ''}".strip
+
+        position = page.evaluate(SCROLL_SCRIPT, element, params[:direction], params[:amount].to_f,
+                                 params[:x], params[:y])
+
+        success_response(x: position['x'], y: position['y'], target: position['target'])
+      rescue StandardError => e
+        logger.error "Scroll failed: #{e.message}"
+        error_response("Failed to scroll: #{e.message}")
+      end
+
+      SCROLL_SCRIPT = <<~JS
+        (function(el, direction, amount, x, y) {
+          if (el && !direction && x == null && y == null) {
+            el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'instant' });
+            return { x: window.scrollX, y: window.scrollY, target: 'window' };
+          }
+          const isWindow = !el;
+          const current = () => isWindow ? { x: window.scrollX, y: window.scrollY } : { x: el.scrollLeft, y: el.scrollTop };
+          const max = isWindow
+            ? { x: document.documentElement.scrollWidth, y: document.documentElement.scrollHeight }
+            : { x: el.scrollWidth, y: el.scrollHeight };
+          let next = current();
+          if (x != null) next.x = x;
+          if (y != null) next.y = y;
+          switch (direction) {
+            case 'up': next.y -= amount; break;
+            case 'down': next.y += amount; break;
+            case 'left': next.x -= amount; break;
+            case 'right': next.x += amount; break;
+            case 'top': next.y = 0; break;
+            case 'bottom': next.y = max.y; break;
+          }
+          if (isWindow) window.scrollTo(next.x, next.y); else el.scrollTo(next.x, next.y);
+          const after = current();
+          return { x: after.x, y: after.y, target: isWindow ? 'window' : 'element' };
+        })(arguments[0], arguments[1], arguments[2], arguments[3], arguments[4])
+      JS
+    end
+  end
+end

data/lib/ferrum_mcp/tools/select_option_tool.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Select option(s) in a <select>
+    class SelectOptionTool < BaseTool
+      tool_name 'select_option'
+      description 'Select an option in a <select> element by value, label or index (values for multiple selects)'
+
+      param :selector, type: :string, required: true, description: 'Selector of the <select> element'
+      param :value, type: :string, description: 'Option value to select'
+      param :label, type: :string, description: 'Option visible text to select'
+      param :index, type: :integer, description: 'Zero-based option index to select'
+      param :values, type: :array, description: 'Several option values (multiple selects)',
+                     schema: { items: { type: 'string' } }
+
+      def perform(params)
+        ensure_browser_active
+        selector = params[:selector]
+        criteria = params.slice(:value, :label, :index, :values).compact
+        raise ToolError, 'Provide one of value, label, index or values' if criteria.empty?
+
+        logger.info "Selecting option in #{selector}: #{criteria.inspect}"
+        element = find_element(selector)
+        selected = page.evaluate(SELECT_SCRIPT, element, criteria.to_json)
+
+        success_response(selector: selector,
+                         selected: selected.map { |o| { value: o['value'], label: o['label'] } })
+      rescue StandardError => e
+        logger.error "Select option failed: #{e.message}"
+        error_response("Failed to select option: #{e.message}")
+      end
+
+      SELECT_SCRIPT = <<~JS
+        (function(select, json) {
+          const criteria = JSON.parse(json);
+          if (!select || select.tagName.toLowerCase() !== 'select') throw new Error('Element is not a <select>');
+          const options = Array.from(select.options);
+          const norm = (s) => (s || '').replace(/\\s+/g, ' ').trim();
+          let wanted = [];
+          if (criteria.values) wanted = options.filter(o => criteria.values.includes(o.value));
+          else if (criteria.value != null) wanted = options.filter(o => o.value === criteria.value).slice(0, 1);
+          else if (criteria.label != null) wanted = options.filter(o => norm(o.textContent) === norm(criteria.label)).slice(0, 1);
+          else if (criteria.index != null) wanted = options[criteria.index] ? [options[criteria.index]] : [];
+          if (wanted.length === 0) throw new Error('No option matches ' + json);
+          if (!select.multiple) wanted = wanted.slice(0, 1);
+          options.forEach(o => { o.selected = wanted.includes(o); });
+          if (!select.multiple) select.value = wanted[0].value;
+          select.dispatchEvent(new Event('input', { bubbles: true }));
+          select.dispatchEvent(new Event('change', { bubbles: true }));
+          return wanted.map(o => ({ value: o.value, label: norm(o.textContent) }));
+        })(arguments[0], arguments[1])
+      JS
+    end
+  end
+end

data/lib/ferrum_mcp/tools/session_tool.rb

@@ -2,8 +2,13 @@
 
 module FerrumMCP
   module Tools
-    # Base class for session management tools
+    # Base class for session management tools: they talk to the SessionManager
+    # and do not need a running browser.
     class SessionTool
+      extend Definition
+
+      requires_session false
+
       attr_reader :session_manager, :logger
 
       def initialize(session_manager)
@@ -11,16 +16,12 @@ module FerrumMCP
         @logger = session_manager.logger
       end
 
-      def self.tool_name
-        raise NotImplementedError, 'Subclasses must implement .tool_name'
-      end
-
-      def self.description
-        raise NotImplementedError, 'Subclasses must implement .description'
+      def execute(raw_params)
+        perform(self.class.normalize_params(raw_params))
       end
 
-      def self.input_schema
-        raise NotImplementedError, 'Subclasses must implement .input_schema'
+      def perform(_params)
+        raise NotImplementedError, 'Subclasses must implement #perform'
       end
 
       protected