ferrum-mcp 1.0.0

data/lib/ferrum_mcp/tools/query_shadow_dom_tool.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to 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)
+      rescue StandardError => e
+        logger.error "Shadow DOM query failed: #{e.message}"
+        error_response("Failed to query Shadow DOM: #{e.message}")
+      end
+
+      private
+
+      def click_in_shadow_dom(host_selector, shadow_selector)
+        host_js = host_selector.inspect
+        shadow_js = shadow_selector.inspect
+
+        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');
+            }
+            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;
+          })()
+        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 }
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/refresh_tool.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to refresh the current page
+    class RefreshTool < BaseTool
+      def self.tool_name
+        'refresh'
+      end
+
+      def self.description
+        'Refresh the current page'
+      end
+
+      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)
+        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)
+
+        success_response(
+          url: browser.url,
+          title: browser.title
+        )
+      rescue Ferrum::TimeoutError => e
+        logger.error "Refresh timeout: #{e.message}"
+        error_response("Refresh timed out: #{e.message}")
+      rescue StandardError => e
+        logger.error "Refresh failed: #{e.message}"
+        error_response("Failed to refresh: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/screenshot_tool.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'vips'
+
+module FerrumMCP
+  module Tools
+    # Tool to 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
+
+      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
+
+      def execute(params)
+        ensure_browser_active
+        selector = param(params, :selector)
+        full_page = param(params, :full_page) || false
+        format = param(params, :format) || 'png'
+
+        logger.info 'Taking screenshot'
+
+        # If selector provided, verify element exists and is visible
+        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
+        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)
+      rescue StandardError => e
+        logger.error "Screenshot failed: #{e.message}"
+        error_response("Failed to take screenshot: #{e.message}")
+      end
+
+      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
+
+        logger.info "Resizing screenshot from #{width}x#{height} to #{new_width}x#{new_height}"
+
+        # Resize image (using high quality Lanczos3 interpolation)
+        resized = image.thumbnail_image(new_width, height: new_height, size: :force)
+
+        # Return resized binary data in the correct format
+        resized.write_to_buffer(".#{format}")
+      rescue StandardError => e
+        logger.warn "Failed to resize screenshot: #{e.message}, returning original"
+        image_data
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/session_tool.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Base class for session management tools
+    class SessionTool
+      attr_reader :session_manager, :logger
+
+      def initialize(session_manager)
+        @session_manager = session_manager
+        @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'
+      end
+
+      def self.input_schema
+        raise NotImplementedError, 'Subclasses must implement .input_schema'
+      end
+
+      protected
+
+      def success_response(data = {})
+        { success: true, data: data }
+      end
+
+      def error_response(message)
+        { success: false, error: message }
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/set_cookie_tool.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to set a cookie
+    class SetCookieTool < BaseTool
+      def self.tool_name
+        'set_cookie'
+      end
+
+      def self.description
+        'Set a cookie in the browser'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              description: 'Cookie name'
+            },
+            value: {
+              type: 'string',
+              description: 'Cookie value'
+            },
+            domain: {
+              type: 'string',
+              description: 'Cookie domain'
+            },
+            path: {
+              type: 'string',
+              description: 'Cookie path (default: /)',
+              default: '/'
+            },
+            secure: {
+              type: 'boolean',
+              description: 'Secure flag (default: false)',
+              default: false
+            },
+            httponly: {
+              type: 'boolean',
+              description: 'HttpOnly flag (default: false)',
+              default: false
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: %w[name value domain session_id]
+        }
+      end
+
+      def execute(params)
+        ensure_browser_active
+
+        cookie = {
+          name: params['name'] || params[:name],
+          value: params['value'] || params[:value],
+          domain: params['domain'] || params[:domain],
+          path: params['path'] || params[:path] || '/',
+          secure: params['secure'] || params[:secure] || false,
+          httpOnly: params['httponly'] || params[:httponly] || false
+        }
+
+        logger.info "Setting cookie: #{cookie[:name]}"
+        browser.cookies.set(**cookie)
+
+        success_response(message: "Cookie set: #{cookie[:name]}")
+      rescue StandardError => e
+        logger.error "Set cookie failed: #{e.message}"
+        error_response("Failed to set cookie: #{e.message}")
+      end
+    end
+  end
+end