ferrum-mcp 1.0.0

data/lib/ferrum_mcp/tools/drag_and_drop_tool.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to perform drag and drop operations
+    class DragAndDropTool < BaseTool
+      def self.tool_name
+        'drag_and_drop'
+      end
+
+      def self.description
+        'Drag an element and drop it onto another element or coordinates'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            source_selector: {
+              type: 'string',
+              description: 'CSS selector or XPath of the element to drag (use xpath: prefix for XPath)'
+            },
+            target_selector: {
+              type: 'string',
+              description: 'CSS selector or XPath of the drop target (optional if using coordinates)'
+            },
+            target_x: {
+              type: 'number',
+              description: 'X coordinate to drop at (alternative to target_selector)'
+            },
+            target_y: {
+              type: 'number',
+              description: 'Y coordinate to drop at (alternative to target_selector)'
+            },
+            steps: {
+              type: 'number',
+              description: 'Number of steps for smooth dragging (default: 10)',
+              default: 10
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: %w[source_selector session_id]
+        }
+      end
+
+      def execute(params) # rubocop:disable Metrics/MethodLength
+        source_selector = param(params, :source_selector)
+        target_selector = param(params, :target_selector)
+        target_x = param(params, :target_x)
+        target_y = param(params, :target_y)
+        steps = param(params, :steps) || 10
+
+        logger.info "Dragging #{source_selector} to #{target_selector || "(#{target_x}, #{target_y})"}"
+
+        # Wait for source element to exist using find_element
+        begin
+          find_element_for_drag(source_selector)
+        rescue StandardError => e
+          raise ToolError, "Source element not found: #{source_selector} - #{e.message}"
+        end
+
+        # Get position using JavaScript
+        selector_js = source_selector.inspect
+        script = <<~JS.strip
+          (function() {
+            var el = document.querySelector(#{selector_js});
+            if (!el) return null;
+            var rect = el.getBoundingClientRect();
+            var result = {};
+            result.x = rect.left + rect.width / 2;
+            result.y = rect.top + rect.height / 2;
+            return result;
+          })()
+        JS
+
+        source_pos = browser.evaluate(script)
+        raise ToolError, "Failed to get position for: #{source_selector}" if source_pos.nil?
+
+        source_x = source_pos['x']
+        source_y = source_pos['y']
+
+        # Determine target coordinates
+        if target_selector
+          selector_js = target_selector.inspect
+          script = <<~JS.strip
+            (function() {
+              var el = document.querySelector(#{selector_js});
+              if (!el) return null;
+              var rect = el.getBoundingClientRect();
+              var result = {};
+              result.x = rect.left + rect.width / 2;
+              result.y = rect.top + rect.height / 2;
+              return result;
+            })()
+          JS
+
+          target_pos = browser.evaluate(script)
+          raise ToolError, "Target element not found: #{target_selector}" if target_pos.nil?
+
+          final_x = target_pos['x']
+          final_y = target_pos['y']
+        elsif target_x && target_y
+          final_x = target_x
+          final_y = target_y
+        else
+          raise ToolError, 'Either target_selector or both target_x and target_y must be provided'
+        end
+
+        # Perform drag and drop using mouse operations
+        perform_drag_and_drop(source_x, source_y, final_x, final_y, steps)
+
+        success_response(
+          message: "Dragged from (#{source_x.round}, #{source_y.round}) to (#{final_x.round}, #{final_y.round})"
+        )
+      rescue StandardError => e
+        logger.error "Drag and drop failed: #{e.message}"
+        error_response("Failed to drag and drop: #{e.message}")
+      end
+
+      private
+
+      def find_element_for_drag(selector)
+        if selector.start_with?('xpath:', '//')
+          xpath = selector.sub(/^xpath:/, '')
+          elements = browser.xpath(xpath)
+          raise "Element not found with XPath: #{xpath}" if elements.empty?
+
+          elements.first
+        else
+          find_element(selector)
+        end
+      end
+
+      def perform_drag_and_drop(from_x, from_y, to_x, to_y, steps)
+        mouse = browser.mouse
+
+        # Move to source element
+        mouse.move(x: from_x, y: from_y)
+        sleep 0.05
+
+        # Press mouse button
+        mouse.down
+        sleep 0.05 # Small delay to ensure mousedown registers
+
+        # Calculate step size for smooth drag
+        step_x = (to_x - from_x) / steps.to_f
+        step_y = (to_y - from_y) / steps.to_f
+
+        # Calculate delay per step (aim for ~300ms total drag time)
+        delay_per_step = [0.3 / steps, 0.01].max # At least 10ms per step
+
+        # Perform smooth drag
+        (1..steps).each do |step|
+          current_x = from_x + (step_x * step)
+          current_y = from_y + (step_y * step)
+          mouse.move(x: current_x, y: current_y)
+          sleep delay_per_step
+        end
+
+        # Release mouse button
+        sleep 0.05 # Small delay before release
+        mouse.up
+
+        logger.debug 'Drag and drop completed'
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/evaluate_js_tool.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to evaluate JavaScript
+    class EvaluateJSTool < BaseTool
+      def self.tool_name
+        'evaluate_js'
+      end
+
+      def self.description
+        'Evaluate JavaScript expression and return the result'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            expression: {
+              type: 'string',
+              description: 'JavaScript expression to evaluate'
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: %w[expression session_id]
+        }
+      end
+
+      def execute(params)
+        ensure_browser_active
+        expression = params['expression'] || params[:expression]
+
+        logger.info 'Evaluating JavaScript'
+        result = browser.evaluate(expression)
+
+        success_response(result: result)
+      rescue StandardError => e
+        logger.error "Evaluate JS failed: #{e.message}"
+        error_response("Failed to evaluate JS: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/execute_script_tool.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to execute JavaScript code
+    class ExecuteScriptTool < BaseTool
+      def self.tool_name
+        'execute_script'
+      end
+
+      def self.description
+        'Execute JavaScript code in the browser context'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            script: {
+              type: 'string',
+              description: 'JavaScript code to execute'
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: %w[script session_id]
+        }
+      end
+
+      def execute(params)
+        ensure_browser_active
+        script = param(params, :script)
+
+        logger.info 'Executing JavaScript'
+        # Use execute for side effects (doesn't return value)
+        # For getting return values, users should use EvaluateJSTool
+        browser.execute(script)
+
+        success_response(message: 'Script executed successfully')
+      rescue StandardError => e
+        logger.error "Execute script failed: #{e.message}"
+        error_response("Failed to execute script: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/fill_form_tool.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to fill form fields
+    class FillFormTool < BaseTool
+      def self.tool_name
+        'fill_form'
+      end
+
+      def self.description
+        'Fill one or more form fields with values'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            fields: {
+              type: 'array',
+              description: 'Array of fields to fill',
+              items: {
+                type: 'object',
+                properties: {
+                  selector: { type: 'string', description: 'CSS selector' },
+                  value: { type: 'string', description: 'Value to fill' }
+                },
+                required: %w[selector value]
+              }
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: %w[fields session_id]
+        }
+      end
+
+      def execute(params)
+        fields = param(params, :fields)
+        results = []
+
+        fields.each_with_index do |field, index|
+          selector = field['selector'] || field[:selector]
+          value = field['value'] || field[:value]
+
+          logger.info "Filling field: #{selector}"
+
+          # Use retry logic for stale elements
+          with_retry do
+            element = find_element(selector)
+
+            # Scroll into view to ensure element is visible
+            element.scroll_into_view if element.respond_to?(:scroll_into_view)
+
+            # Focus with small delay to allow focus event to register
+            element.focus
+            sleep 0.05
+
+            # Type the value
+            element.type(value)
+          end
+
+          results << { selector: selector, filled: true }
+
+          # Small delay between fields to allow validation/autocomplete/onChange handlers
+          sleep 0.1 unless index == fields.length - 1
+        end
+
+        success_response(fields: results)
+      rescue StandardError => e
+        logger.error "Fill form failed: #{e.message}"
+        error_response("Failed to fill form: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/find_by_text_tool.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to find elements by their text content
+    class FindByTextTool < BaseTool
+      def self.tool_name
+        'find_by_text'
+      end
+
+      def self.description
+        'Find elements by their text content using XPath'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            text: {
+              type: 'string',
+              description: 'Text to search for (exact match or contains)'
+            },
+            tag: {
+              type: 'string',
+              description: 'HTML tag to search within (e.g., "button", "a", "div"). Use "*" for any tag (default)',
+              default: '*'
+            },
+            exact: {
+              type: 'boolean',
+              description: 'Whether to match exact text (true) or partial text (false, default)',
+              default: false
+            },
+            multiple: {
+              type: 'boolean',
+              description: 'Return all matching elements (true) or just the first visible one (false, default)',
+              default: false
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: %w[text session_id]
+        }
+      end
+
+      def execute(params)
+        ensure_browser_active
+
+        text = param(params, :text)
+        tag = param(params, :tag) || '*'
+        exact = param(params, :exact) || false
+        multiple = param(params, :multiple) || false
+
+        logger.info "Finding elements with text: '#{text}' in <#{tag}> tags (exact: #{exact}, multiple: #{multiple})"
+
+        # Escape text for XPath using concat() to handle quotes safely
+        # This prevents XPath injection while maintaining the original text
+        escaped_text = escape_xpath_string(text)
+
+        # Build XPath query with escaped text
+        xpath = if exact
+                  "//#{tag}[normalize-space(text())=#{escaped_text}]"
+                else
+                  "//#{tag}[contains(normalize-space(.), #{escaped_text})]"
+                end
+
+        logger.debug "Using XPath: #{xpath}"
+
+        elements = browser.xpath(xpath)
+        return error_response("No elements found with text: '#{text}'") if elements.empty?
+
+        if multiple
+          # Find all matching elements
+
+          results = elements.map.with_index do |element, index|
+            {
+              index: index,
+              tag: element.tag_name,
+              text: element.text.strip,
+              visible: element_visible?(element),
+              selector: generate_css_selector(element)
+            }
+          end
+
+          success_response(
+            found: results.length,
+            elements: results,
+            xpath: xpath
+          )
+        else
+          # Find first visible element
+
+          # Find first visible element
+          visible_element = elements.find { |el| element_visible?(el) }
+          element = visible_element || elements.first
+
+          success_response(
+            tag: element.tag_name,
+            text: element.text.strip,
+            visible: element_visible?(element),
+            selector: generate_css_selector(element),
+            xpath: xpath,
+            total_found: elements.length
+          )
+        end
+      rescue StandardError => e
+        logger.error "Find by text failed: #{e.message}"
+        error_response("Failed to find elements: #{e.message}")
+      end
+
+      private
+
+      # Escape string for XPath using concat() to handle quotes
+      # This prevents injection while preserving the original text
+      def escape_xpath_string(text)
+        # If text contains no quotes, simple quoting works
+        return "'#{text}'" unless text.include?("'")
+
+        # If text contains quotes, use concat() function
+        # Split on single quotes and join with concat
+        parts = text.split("'")
+        quoted_parts = parts.map { |part| "'#{part}'" }
+        "concat(#{quoted_parts.join(", \"'\", ")})"
+      end
+
+      def element_visible?(element)
+        rect = element.evaluate('el => el.getBoundingClientRect()')
+        rect['width'].positive? && rect['height'].positive?
+      rescue StandardError
+        false
+      end
+
+      def generate_css_selector(element)
+        # Try to generate a useful CSS selector
+        tag = element.tag_name
+        id = element.property('id')
+        classes = element.property('className')
+
+        if id && !id.empty?
+          "##{id}"
+        elsif classes && !classes.empty?
+          class_list = classes.split.join('.')
+          "#{tag}.#{class_list}"
+        else
+          tag
+        end
+      rescue StandardError
+        element.tag_name
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/get_attribute_tool.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to get element attributes
+    class GetAttributeTool < BaseTool
+      def self.tool_name
+        'get_attribute'
+      end
+
+      def self.description
+        'Get attribute value(s) from an element'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            selector: {
+              type: 'string',
+              description: 'CSS selector of the element'
+            },
+            attribute: {
+              type: 'string',
+              description: 'Attribute name to get'
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: %w[selector attribute session_id]
+        }
+      end
+
+      def execute(params)
+        ensure_browser_active
+        selector = params['selector'] || params[:selector]
+        attribute = params['attribute'] || params[:attribute]
+
+        logger.info "Getting attribute '#{attribute}' from: #{selector}"
+        element = find_element(selector)
+        value = element.attribute(attribute)
+
+        success_response(
+          selector: selector,
+          attribute: attribute,
+          value: value
+        )
+      rescue StandardError => e
+        logger.error "Get attribute failed: #{e.message}"
+        error_response("Failed to get attribute: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/get_cookies_tool.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to get cookies
+    class GetCookiesTool < BaseTool
+      def self.tool_name
+        'get_cookies'
+      end
+
+      def self.description
+        'Get all cookies or cookies for a specific domain'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            domain: {
+              type: 'string',
+              description: 'Optional: Filter cookies by domain'
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: ['session_id']
+        }
+      end
+
+      def execute(params)
+        ensure_browser_active
+        domain = param(params, :domain)
+
+        logger.info "Getting cookies#{" for #{domain}" if domain}"
+        all_cookies = browser.cookies.all
+
+        # Convert cookies to structured format
+        cookies_array = []
+
+        all_cookies.each do |name, cookie|
+          # Get structured cookie data if available
+          cookie_data = if cookie.respond_to?(:to_h)
+                          cookie.to_h
+                        elsif cookie.is_a?(Hash)
+                          cookie
+                        else
+                          # Fallback to basic format
+                          { name: name, value: cookie.to_s }
+                        end
+
+          # Ensure name is set
+          cookie_data[:name] ||= name
+
+          # Filter by domain if specified
+          cookies_array << cookie_data if domain.nil? || cookie_data[:domain]&.include?(domain)
+        end
+
+        success_response(
+          cookies: cookies_array,
+          count: cookies_array.length
+        )
+      rescue StandardError => e
+        logger.error "Get cookies failed: #{e.message}"
+        error_response("Failed to get cookies: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/get_html_tool.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to get HTML content
+    class GetHTMLTool < BaseTool
+      def self.tool_name
+        'get_html'
+      end
+
+      def self.description
+        'Get HTML content of the page or a specific element'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            selector: {
+              type: 'string',
+              description: 'Optional: CSS selector to get HTML of specific element'
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: ['session_id']
+        }
+      end
+
+      def execute(params)
+        ensure_browser_active
+        selector = params['selector'] || params[:selector]
+
+        if selector
+          logger.info "Getting HTML of element: #{selector}"
+          element = find_element(selector)
+          html = element.property('outerHTML')
+          success_response(html: html, selector: selector)
+        else
+          logger.info 'Getting page HTML'
+          html = browser.body
+          success_response(html: html, url: browser.url)
+        end
+      rescue StandardError => e
+        logger.error "Get HTML failed: #{e.message}"
+        error_response("Failed to get HTML: #{e.message}")
+      end
+    end
+  end
+end