ferrum-mcp 1.0.0

data/lib/ferrum_mcp/tools/get_session_info_tool.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Get information about a specific session
+    class GetSessionInfoTool < SessionTool
+      def self.tool_name
+        'get_session_info'
+      end
+
+      def self.description
+        'Get detailed information about a specific browser session'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            session_id: {
+              type: 'string',
+              description: 'The ID of the session (omit for default session)'
+            }
+          }
+        }
+      end
+
+      def execute(params)
+        session_id = params[:session_id] || params['session_id']
+        session = session_manager.get_session(session_id)
+
+        return error_response("Session not found: #{session_id}") unless session
+
+        success_response(session.info)
+      rescue StandardError => e
+        logger.error "Failed to get session info: #{e.message}"
+        error_response("Failed to get session info: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/get_text_tool.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to extract text from elements
+    class GetTextTool < BaseTool
+      def self.tool_name
+        'get_text'
+      end
+
+      def self.description
+        'Extract text content from one or more elements'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            selector: {
+              type: 'string',
+              description: 'CSS selector or XPath of element(s) to extract text from (use xpath: prefix for XPath)'
+            },
+            multiple: {
+              type: 'boolean',
+              description: 'Extract from all matching elements (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)
+        ensure_browser_active
+        selector = param(params, :selector)
+        multiple = param(params, :multiple) || false
+
+        logger.info "Extracting text from: #{selector}"
+
+        # Support both CSS and XPath selectors
+        if selector.start_with?('xpath:', '//')
+          xpath = selector.sub(/^xpath:/, '')
+          logger.debug "Using XPath: #{xpath}"
+          elements = browser.xpath(xpath)
+          raise ToolError, "Element not found with XPath: #{xpath}" if elements.empty?
+        else
+          elements = browser.css(selector)
+          raise ToolError, "Element not found: #{selector}" if elements.empty?
+        end
+
+        if multiple
+          texts = elements.map(&:text)
+          success_response(texts: texts, count: texts.length)
+        else
+          success_response(text: elements.first.text)
+        end
+      rescue StandardError => e
+        logger.error "Get text failed: #{e.message}"
+        error_response("Failed to get text: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/get_title_tool.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to get page title
+    class GetTitleTool < BaseTool
+      def self.tool_name
+        'get_title'
+      end
+
+      def self.description
+        'Get the title of 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 'Getting page title'
+
+        success_response(
+          title: browser.title,
+          url: browser.url
+        )
+      rescue StandardError => e
+        logger.error "Get title failed: #{e.message}"
+        error_response("Failed to get title: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/get_url_tool.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to get current URL
+    class GetURLTool < BaseTool
+      def self.tool_name
+        'get_url'
+      end
+
+      def self.description
+        'Get the current URL of the 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 'Getting current URL'
+        success_response(url: browser.url)
+      rescue StandardError => e
+        logger.error "Get URL failed: #{e.message}"
+        error_response("Failed to get URL: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/go_back_tool.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to go back in browser history
+    class GoBackTool < BaseTool
+      def self.tool_name
+        'go_back'
+      end
+
+      def self.description
+        'Go back to the previous page in browser history'
+      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 'Going back'
+        browser.back
+
+        # Wait for network to be idle to ensure page is loaded
+        browser.network.wait_for_idle(timeout: 30)
+
+        success_response(
+          url: browser.url,
+          title: browser.title
+        )
+      rescue Ferrum::TimeoutError => e
+        logger.error "Go back timeout: #{e.message}"
+        error_response("Go back timed out: #{e.message}")
+      rescue StandardError => e
+        logger.error "Go back failed: #{e.message}"
+        error_response("Failed to go back: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/go_forward_tool.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to go forward in browser history
+    class GoForwardTool < BaseTool
+      def self.tool_name
+        'go_forward'
+      end
+
+      def self.description
+        'Go forward to the next page in browser history'
+      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 'Going forward'
+        browser.forward
+
+        # Wait for network to be idle to ensure page is loaded
+        browser.network.wait_for_idle(timeout: 30)
+
+        success_response(
+          url: browser.url,
+          title: browser.title
+        )
+      rescue Ferrum::TimeoutError => e
+        logger.error "Go forward timeout: #{e.message}"
+        error_response("Go forward timed out: #{e.message}")
+      rescue StandardError => e
+        logger.error "Go forward failed: #{e.message}"
+        error_response("Failed to go forward: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/hover_tool.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to hover over an element
+    class HoverTool < BaseTool
+      def self.tool_name
+        'hover'
+      end
+
+      def self.description
+        'Hover over an element using a CSS selector'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            selector: {
+              type: 'string',
+              description: 'CSS selector of the element to hover over'
+            },
+            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)
+
+        logger.info "Hovering over element: #{selector}"
+
+        # First ensure element exists and is ready
+        element = find_element(selector)
+
+        # Scroll into view if supported
+        element.scroll_into_view if element.respond_to?(:scroll_into_view)
+
+        # Try native hover first, fallback to JavaScript
+        begin
+          element.hover
+          logger.debug 'Native hover successful'
+        rescue StandardError => e
+          logger.debug "Native hover failed, using JavaScript: #{e.message}"
+          hover_with_javascript(selector)
+        end
+
+        success_response(message: "Hovered over #{selector}")
+      rescue StandardError => e
+        logger.error "Hover failed: #{e.message}"
+        error_response("Failed to hover: #{e.message}")
+      end
+
+      private
+
+      def hover_with_javascript(selector)
+        # Use inspect to properly escape the selector for JavaScript (prevents XSS)
+        script = <<~JS
+          const element = document.querySelector(#{selector.inspect});
+          if (!element) {
+            throw new Error('Element not found: ' + #{selector.inspect});
+          }
+          const event = new MouseEvent('mouseover', { bubbles: true, cancelable: true, view: window });
+          element.dispatchEvent(event);
+        JS
+
+        browser.execute(script)
+        logger.debug 'JavaScript hover successful'
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/list_sessions_tool.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    class ListSessionsTool < SessionTool
+      def self.tool_name
+        'list_sessions'
+      end
+
+      def self.description
+        'List all active browser sessions with their information (id, status, type, uptime, etc.)'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {}
+        }
+      end
+
+      def execute(_params)
+        sessions = session_manager.list_sessions
+        success_response(
+          count: sessions.size,
+          sessions: sessions
+        )
+      rescue StandardError => e
+        logger.error "Failed to list sessions: #{e.message}"
+        error_response("Failed to list sessions: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/navigate_tool.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to navigate to a URL
+    class NavigateTool < BaseTool
+      def self.tool_name
+        'navigate'
+      end
+
+      def self.description
+        'Navigate to a specific URL in the browser'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            url: {
+              type: 'string',
+              description: 'The URL to navigate to (must include protocol: http:// or https://)'
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: %w[url session_id]
+        }
+      end
+
+      def execute(params)
+        ensure_browser_active
+        url = param(params, :url)
+
+        # Validate URL format
+        raise ToolError, 'URL must start with http:// or https://' unless %r{^https?://}.match?(url)
+
+        logger.info "Navigating to: #{url}"
+        browser.goto(url)
+
+        # Wait for network to be idle to ensure page is loaded
+        # This prevents race conditions with subsequent tool calls
+        browser.network.wait_for_idle(timeout: 30)
+
+        success_response(
+          url: browser.url,
+          title: browser.title
+        )
+      rescue Ferrum::TimeoutError => e
+        logger.error "Navigation timeout: #{e.message}"
+        error_response("Navigation timed out: #{e.message}")
+      rescue StandardError => e
+        logger.error "Navigation failed: #{e.message}"
+        error_response("Failed to navigate: #{e.message}")
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/tools/press_key_tool.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  module Tools
+    # Tool to press keyboard keys
+    class PressKeyTool < BaseTool
+      def self.tool_name
+        'press_key'
+      end
+
+      def self.description
+        'Press keyboard keys (e.g., Enter, Tab, Escape)'
+      end
+
+      def self.input_schema
+        {
+          type: 'object',
+          properties: {
+            key: {
+              type: 'string',
+              description: 'Key to press (Enter, Tab, Escape, ArrowDown, etc.)'
+            },
+            selector: {
+              type: 'string',
+              description: 'Optional: CSS selector to focus before pressing key'
+            },
+            session_id: {
+              type: 'string',
+              description: 'Session ID to use for this operation'
+            }
+          },
+          required: %w[key session_id]
+        }
+      end
+
+      def execute(params)
+        key = param(params, :key)
+        selector = param(params, :selector)
+
+        if selector
+          logger.info "Focusing element: #{selector}"
+          element = find_element(selector)
+          element.focus
+        end
+
+        logger.info "Pressing key: #{key}"
+        normalized_key = normalize_key(key)
+
+        # Use keyboard.type for key presses
+        # This handles both special keys and regular characters correctly
+        browser.keyboard.type(normalized_key)
+
+        success_response(message: "Pressed key: #{key}")
+      rescue StandardError => e
+        logger.error "Press key failed: #{e.message}"
+        error_response("Failed to press key: #{e.message}")
+      end
+
+      private
+
+      def normalize_key(key)
+        # Convert common key names to Ferrum format
+        case key.to_s.downcase
+        when 'enter', 'return'
+          :Enter
+        when 'tab'
+          :Tab
+        when 'escape', 'esc'
+          :Escape
+        when 'backspace'
+          :Backspace
+        when 'delete', 'del'
+          :Delete
+        when 'arrowdown', 'down'
+          :Down
+        when 'arrowup', 'up'
+          :Up
+        when 'arrowleft', 'left'
+          :Left
+        when 'arrowright', 'right'
+          :Right
+        when 'space'
+          ' '
+        else
+          # If already a symbol, return as-is, otherwise try to convert
+          key.is_a?(Symbol) ? key : key.to_sym
+        end
+      end
+    end
+  end
+end