ferrum-mcp 1.0.0 → 1.1.0

data/lib/ferrum_mcp/tools/close_tab_tool.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Close a tab
+    class CloseTabTool < TabTool
+      tool_name 'close_tab'
+      description 'Close a tab (the current one by default). The last remaining tab cannot be closed.'
+
+      param :tab_id, type: :string, description: 'tab_id of the tab to close (default: current tab)'
+      param :index, type: :integer, description: 'Zero-based index of the tab to close (alternative to tab_id)'
+
+      def perform(params)
+        ensure_browser_active
+        list = tabs
+        raise ToolError, 'Cannot close the last tab of the session' if list.length <= 1
+
+        tab = if params[:tab_id] || params[:index]
+                find_tab(tab_id: params[:tab_id], index: params[:index])
+              else
+                current_tab
+              end
+        closing_current = tab.target_id == current_tab.target_id
+        logger.info "Closing tab #{tab.target_id}"
+        tab.close
+        wait_until_gone(tab.target_id)
+
+        @browser_manager.select_page(tabs.first) if closing_current
+        success_response(closed_tab_id: tab.target_id, current_tab_id: current_tab.target_id, count: tabs.length)
+      rescue StandardError => e
+        logger.error "Close tab failed: #{e.message}"
+        error_response("Failed to close tab: #{e.message}")
+      end
+
+      private
+
+      # Target.closeTarget is asynchronous; wait for the browser to drop it
+      def wait_until_gone(target_id, timeout: 2)
+        deadline = monotonic_now + timeout
+        sleep POLL_INTERVAL while monotonic_now < deadline && tabs.any? { |t| t.target_id == target_id }
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/create_session_tool.rb

@@ -2,73 +2,47 @@
 
 module FerrumMCP
   module Tools
+    # Create a new browser session
     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)
+      tool_name 'create_session'
+      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
+
+      param :browser_id, type: :string,
+                         description: 'Optional: Browser ID to use (from ferrum://browsers resource)'
+      param :user_profile_id, type: :string,
+                              description: 'Optional: User profile ID to use (from ferrum://user-profiles resource)'
+      param :bot_profile_id, type: :string,
+                             description: 'Optional: BotBrowser profile ID to use (from ferrum://bot-profiles resource)'
+      param :browser_path, type: :string,
+                           description: 'Optional: Path to browser executable (legacy, prefer browser_id)'
+      param :botbrowser_profile, type: :string,
+                                 description: 'Optional: Path to BotBrowser profile (legacy, prefer bot_profile_id)'
+      param :headless, type: :boolean,
+                       description: 'Optional: Run browser in headless mode (default: BROWSER_HEADLESS). ' \
+                                    'REQUIRED to be true when running in Docker.'
+      param :timeout, type: :number, description: 'Optional: Browser timeout in seconds (default: 60)'
+      param :browser_options, type: :object,
+                              description: 'Optional: Additional Chrome command-line flags without the leading ' \
+                                           'dashes (e.g. {"window-size": "1920,1080", "lang": "fr-FR"})',
+                              schema: { additionalProperties: { type: 'string' } }
+      param :metadata, type: :object,
+                       description: 'Optional: Custom metadata for this session (e.g., {"user": "john"})',
+                       schema: { additionalProperties: true }
+
+      SESSION_OPTION_KEYS = %i[browser_id user_profile_id bot_profile_id browser_path botbrowser_profile
+                               headless timeout browser_options metadata].freeze
+
+      def perform(params)
         logger.info 'Creating new browser session'
 
-        options = build_options(params)
+        options = params.slice(*SESSION_OPTION_KEYS).compact
         validate_docker_headless!(options)
 
         session_id = session_manager.create_session(options)
@@ -86,61 +60,15 @@ module FerrumMCP
       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

data/lib/ferrum_mcp/tools/definition.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Class-level DSL shared by every tool.
+    #
+    #   class ClickTool < BaseTool
+    #     tool_name 'click'
+    #     description 'Click on an element'
+    #     param :selector, type: :string, required: true, description: 'CSS selector'
+    #     param :wait, type: :number, default: 5, description: 'Seconds to wait'
+    #   end
+    #
+    # The JSON schema handed to MCP is generated from these declarations, the
+    # session_id parameter is injected for tools that need a browser, and
+    # incoming params are normalized (symbol keys, defaults applied) before
+    # reaching #perform.
+    module Definition
+      SESSION_ID_SCHEMA = {
+        type: 'string',
+        description: 'Session ID to use for this operation (returned by create_session)'
+      }.freeze
+
+      TYPES = %i[string number integer boolean array object].freeze
+
+      def tool_name(value = nil)
+        return @tool_name = value.to_s if value
+
+        @tool_name || raise(NotImplementedError, "#{name} must declare tool_name")
+      end
+
+      def description(value = nil)
+        return @description = value if value
+
+        @description || raise(NotImplementedError, "#{name} must declare description")
+      end
+
+      # Whether the tool operates on a browser session (session_id injected and
+      # required). Session-management tools set this to false.
+      def requires_session(value)
+        @requires_session = value
+      end
+
+      def requires_session?
+        return @requires_session unless @requires_session.nil?
+
+        superclass.respond_to?(:requires_session?) ? superclass.requires_session? : true
+      end
+
+      # Declare an input parameter.
+      # @param schema [Hash] extra JSON schema keywords (items, additionalProperties, ...)
+      def param(name, type:, description:, required: false, default: nil, enum: nil, schema: {}) # rubocop:disable Metrics/ParameterLists
+        raise ArgumentError, "Unknown param type #{type.inspect}" unless TYPES.include?(type.to_sym)
+
+        param_definitions[name.to_sym] = {
+          type: type.to_sym, description: description, required: required,
+          default: default, enum: enum, schema: schema
+        }
+      end
+
+      def param_definitions
+        @param_definitions ||= {}
+      end
+
+      def input_schema
+        properties = {}
+        properties[:session_id] = SESSION_ID_SCHEMA if requires_session?
+        param_definitions.each { |name, definition| properties[name] = json_schema_for(definition) }
+
+        required = []
+        required << 'session_id' if requires_session?
+        required.concat(param_definitions.select { |_, d| d[:required] }.keys.map(&:to_s))
+
+        schema = { type: 'object', properties: properties }
+        schema[:required] = required.uniq unless required.empty?
+        schema
+      end
+
+      # Symbol keys (recursively) and declared defaults applied.
+      def normalize_params(raw_params)
+        params = deep_symbolize(raw_params || {})
+        param_definitions.each do |name, definition|
+          params[name] = definition[:default] if params[name].nil? && !definition[:default].nil?
+        end
+        params
+      end
+
+      private
+
+      def json_schema_for(definition)
+        schema = { type: definition[:type].to_s, description: definition[:description] }
+        schema[:default] = definition[:default] unless definition[:default].nil?
+        schema[:enum] = definition[:enum] if definition[:enum]
+        schema.merge(definition[:schema])
+      end
+
+      def deep_symbolize(value)
+        case value
+        when Hash then value.to_h { |k, v| [k.to_sym, deep_symbolize(v)] }
+        when Array then value.map { |v| deep_symbolize(v) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/drag_and_drop_tool.rb

@@ -2,119 +2,34 @@
 
 module FerrumMCP
   module Tools
-    # Tool to perform drag and drop operations
+    # Drag and drop
     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})"
-        )
+      tool_name 'drag_and_drop'
+      description 'Drag an element and drop it onto another element or at coordinates'
+
+      param :source_selector, type: :string, required: true, description: 'Selector of the element to drag'
+      param :target_selector, type: :string, description: 'Selector of the drop target (or use target_x/target_y)'
+      param :target_x, type: :number, description: 'X coordinate to drop at (alternative to target_selector)'
+      param :target_y, type: :number, description: 'Y coordinate to drop at (alternative to target_selector)'
+      param :steps, type: :number, default: 10, description: 'Number of intermediate mouse moves (default: 10)'
+
+      def perform(params)
+        source = params[:source_selector]
+        target = params[:target_selector]
+        logger.info "Dragging #{source} to #{target || "(#{params[:target_x]}, #{params[:target_y]})"}"
+
+        from_x, from_y = center_of(find_element(source))
+        to_x, to_y = if target
+                       center_of(find_element(target))
+                     elsif params[:target_x] && params[:target_y]
+                       [params[:target_x], params[:target_y]]
+                     else
+                       raise ToolError, 'Either target_selector or both target_x and target_y must be provided'
+                     end
+
+        perform_drag(from_x, from_y, to_x, to_y, params[:steps].to_i.clamp(1, 200))
+
+        success_response(message: "Dragged from (#{from_x.round}, #{from_y.round}) to (#{to_x.round}, #{to_y.round})")
       rescue StandardError => e
         logger.error "Drag and drop failed: #{e.message}"
         error_response("Failed to drag and drop: #{e.message}")
@@ -122,49 +37,32 @@ module FerrumMCP
 
       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
+      def center_of(element)
+        center = page.evaluate(<<~JS, element)
+          (function(el) {
+            const rect = el.getBoundingClientRect();
+            return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+          })(arguments[0])
+        JS
+        [center['x'], center['y']]
       end
 
-      def perform_drag_and_drop(from_x, from_y, to_x, to_y, steps)
-        mouse = browser.mouse
-
-        # Move to source element
+      def perform_drag(from_x, from_y, to_x, to_y, steps)
+        mouse = page.mouse
         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
+        sleep 0.05
 
-        # Perform smooth drag
+        delay = [0.3 / steps, 0.01].max
         (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
+          progress = step / steps.to_f
+          mouse.move(x: from_x + ((to_x - from_x) * progress), y: from_y + ((to_y - from_y) * progress))
+          sleep delay
         end
 
-        # Release mouse button
-        sleep 0.05 # Small delay before release
+        sleep 0.05
         mouse.up
-
-        logger.debug 'Drag and drop completed'
       end
     end
   end

data/lib/ferrum_mcp/tools/evaluate_js_tool.rb

@@ -2,39 +2,17 @@
 
 module FerrumMCP
   module Tools
-    # Tool to evaluate JavaScript
+    # Evaluate JavaScript and return the result
     class EvaluateJSTool < BaseTool
-      def self.tool_name
-        'evaluate_js'
-      end
+      tool_name 'evaluate_js'
+      description 'Evaluate a JavaScript expression in the page and return its (JSON-serializable) result'
 
-      def self.description
-        'Evaluate JavaScript expression and return the result'
-      end
+      param :expression, type: :string, required: true, description: 'JavaScript expression to evaluate'
 
-      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)
+      def perform(params)
         ensure_browser_active
-        expression = params['expression'] || params[:expression]
-
         logger.info 'Evaluating JavaScript'
-        result = browser.evaluate(expression)
+        result = page.evaluate(params[:expression].to_s)
 
         success_response(result: result)
       rescue StandardError => e

data/lib/ferrum_mcp/tools/execute_script_tool.rb

@@ -2,41 +2,17 @@
 
 module FerrumMCP
   module Tools
-    # Tool to execute JavaScript code
+    # Execute JavaScript for side effects
     class ExecuteScriptTool < BaseTool
-      def self.tool_name
-        'execute_script'
-      end
+      tool_name 'execute_script'
+      description 'Execute JavaScript code in the page for its side effects (use evaluate_js to get a value back)'
 
-      def self.description
-        'Execute JavaScript code in the browser context'
-      end
+      param :script, type: :string, required: true, description: 'JavaScript code to execute'
 
-      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)
+      def perform(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)
+        page.execute(params[:script].to_s)
 
         success_response(message: 'Script executed successfully')
       rescue StandardError => e