headless_browser_tool 0.1.1

data/lib/headless_browser_tool/session_persistence.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require_relative "logger"
+
+module HeadlessBrowserTool
+  module SessionPersistence # rubocop:disable Metrics/ModuleLength
+    BLANK_URLS = ["about:blank", "data:,"].freeze
+    SESSIONS_DIR = File.join(".hbt", "sessions").freeze
+
+    module_function
+
+    def save_session(session_id, capybara_session)
+      return unless session_id && capybara_session
+
+      FileUtils.mkdir_p(SESSIONS_DIR)
+      session_file = File.join(SESSIONS_DIR, "#{session_id}.json")
+
+      begin
+        state = {
+          session_id: session_id,
+          saved_at: Time.now.iso8601,
+          current_url: capybara_session.current_url,
+          cookies: extract_cookies(capybara_session),
+          local_storage: extract_storage(capybara_session, "localStorage"),
+          session_storage: extract_storage(capybara_session, "sessionStorage"),
+          window_size: extract_window_size(capybara_session)
+        }
+
+        File.write(session_file, JSON.pretty_generate(state))
+        HeadlessBrowserTool::Logger.log.info "Saved session to #{session_file}"
+      rescue StandardError => e
+        HeadlessBrowserTool::Logger.log.info "Error saving session: #{e.message}"
+      end
+    end
+
+    def restore_session(session_id, capybara_session)
+      session_file = File.join(SESSIONS_DIR, "#{session_id}.json")
+      return unless File.exist?(session_file)
+
+      begin
+        state = JSON.parse(File.read(session_file))
+        HeadlessBrowserTool::Logger.log.info "Restoring session from #{session_file}"
+
+        # Visit the URL first (needed to set cookies/storage for the domain)
+        capybara_session.visit(state["current_url"]) if state["current_url"] && !BLANK_URLS.include?(state["current_url"])
+
+        # Restore cookies
+        restore_cookies(capybara_session, state["cookies"]) if state["cookies"]
+
+        # Restore localStorage
+        restore_storage(capybara_session, "localStorage", state["local_storage"]) if state["local_storage"]
+
+        # Restore sessionStorage
+        restore_storage(capybara_session, "sessionStorage", state["session_storage"]) if state["session_storage"]
+
+        # Restore window size
+        if state["window_size"]
+          capybara_session.current_window.resize_to(
+            state["window_size"]["width"],
+            state["window_size"]["height"]
+          )
+        end
+
+        HeadlessBrowserTool::Logger.log.info "Session restored successfully"
+        true
+      rescue StandardError => e
+        HeadlessBrowserTool::Logger.log.info "Error restoring session: #{e.message}"
+        # Delete corrupted state file
+        begin
+          File.delete(session_file)
+        rescue StandardError
+          nil
+        end
+        false
+      end
+    end
+
+    def session_exists?(session_id)
+      File.exist?(File.join(SESSIONS_DIR, "#{session_id}.json"))
+    end
+
+    def delete_session(session_id)
+      session_file = File.join(SESSIONS_DIR, "#{session_id}.json")
+      FileUtils.rm_f(session_file)
+    end
+
+    def extract_cookies(session)
+      session.driver.browser.manage.all_cookies
+    rescue StandardError => e
+      HeadlessBrowserTool::Logger.log.info "Error extracting cookies: #{e.message}"
+      []
+    end
+
+    def extract_storage(session, storage_type)
+      return {} if BLANK_URLS.include?(session.current_url)
+
+      session.evaluate_script(<<~JS)
+        (() => {
+          const items = {};
+          for (let i = 0; i < #{storage_type}.length; i++) {
+            const key = #{storage_type}.key(i);
+            items[key] = #{storage_type}.getItem(key);
+          }
+          return items;
+        })()
+      JS
+    rescue StandardError => e
+      HeadlessBrowserTool::Logger.log.info "Error extracting #{storage_type}: #{e.message}"
+      {}
+    end
+
+    def extract_window_size(session)
+      size = session.current_window.size
+      { "width" => size[0], "height" => size[1] }
+    rescue StandardError => e
+      HeadlessBrowserTool::Logger.log.info "Error extracting window size: #{e.message}"
+      nil
+    end
+
+    def restore_cookies(session, cookies)
+      return if cookies.nil? || cookies.empty?
+
+      cookies.each do |cookie|
+        cookie_hash = cookie.transform_keys(&:to_sym)
+        # Remove browser-specific fields that can't be set
+        cookie_hash.delete(:same_site)
+        cookie_hash.delete(:http_only) unless cookie_hash[:httpOnly]
+        session.driver.browser.manage.add_cookie(cookie_hash)
+      end
+    rescue StandardError => e
+      HeadlessBrowserTool::Logger.log.info "Error restoring cookies: #{e.message}"
+    end
+
+    def restore_storage(session, storage_type, storage_data)
+      return if storage_data.nil? || storage_data.empty? || BLANK_URLS.include?(session.current_url)
+
+      storage_data.each do |key, value|
+        session.execute_script("#{storage_type}.setItem(#{key.to_json}, #{value.to_json})")
+      end
+    rescue StandardError => e
+      HeadlessBrowserTool::Logger.log.info "Error restoring #{storage_type}: #{e.message}"
+    end
+  end
+end

data/lib/headless_browser_tool/stdio_server.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+require "fileutils"
+require "json"
+require_relative "browser"
+require_relative "tools"
+require_relative "version"
+require_relative "logger"
+require_relative "server"
+require_relative "session_persistence"
+require_relative "directory_setup"
+
+module HeadlessBrowserTool
+  class StdioServer
+    def self.start(options = {})
+      # Setup directory structure with logs FIRST
+      DirectorySetup.setup_directories(include_logs: true)
+
+      # Initialize logger for stdio mode AFTER directories exist
+      HeadlessBrowserTool::Logger.initialize_logger(mode: :stdio)
+
+      # Check for session ID from environment
+      session_id = ENV.fetch("HBT_SESSION_ID", nil)
+
+      # Create MCP server instance
+      server = FastMcp::Server.new(
+        name: "headless-browser-tool",
+        version: HeadlessBrowserTool::VERSION
+      )
+
+      # Create single browser instance
+      # In stdio mode, always single session and headless by default
+      browser = Browser.new(headless: options.fetch(:headless, true))
+
+      # Store browser instance for tools to access
+      Server.browser_instance = browser
+      Server.single_session_mode = true
+
+      # Restore session if session ID provided
+      if session_id
+        HeadlessBrowserTool::Logger.log.info "Session ID provided: #{session_id}"
+        SessionPersistence.restore_session(session_id, browser.session)
+      end
+
+      # Register all browser tools
+      HeadlessBrowserTool::Tools::ALL_TOOLS.each do |tool_class|
+        server.register_tool(tool_class)
+      end
+
+      # Log startup info to log file since stdout is used for MCP protocol
+      HeadlessBrowserTool::Logger.log.info "Starting HeadlessBrowserTool MCP server in stdio mode..."
+      HeadlessBrowserTool::Logger.log.info "Headless: #{options.fetch(:headless, true)}"
+
+      # Store references for shutdown
+      @browser = browser
+      @session_id = session_id
+
+      # Register shutdown hook
+      at_exit do
+        SessionPersistence.save_session(@session_id, @browser.session) if @session_id
+      end
+
+      # Start the server in stdio mode
+      server.start
+    rescue Interrupt
+      HeadlessBrowserTool::Logger.log.info "Shutting down..."
+      SessionPersistence.save_session(session_id, browser.session) if session_id
+    ensure
+      SessionPersistence.save_session(session_id, browser.session) if session_id
+    end
+  end
+end

data/lib/headless_browser_tool/strict_session_middleware.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "logger"
+
+module HeadlessBrowserTool
+  class StrictSessionMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      # Log request headers if enabled
+      log_request_headers(env) if HeadlessBrowserTool::Server.show_headers
+
+      # Extract session ID from X-Session-ID header only
+      session_id = env["HTTP_X_SESSION_ID"]
+
+      # For MCP requests, require session ID
+      if mcp_request?(env) && (session_id.nil? || session_id.empty?)
+        return [
+          400,
+          { "Content-Type" => "application/json" },
+          [{ error: "X-Session-ID header is required for multi-session mode" }.to_json]
+        ]
+      end
+
+      # Sanitize session ID
+      if session_id
+        session_id = sanitize_session_id(session_id)
+        if session_id.nil?
+          return [
+            400,
+            { "Content-Type" => "application/json" },
+            [{ error: "Invalid X-Session-ID format" }.to_json]
+          ]
+        end
+      end
+
+      # Store in environment for downstream use
+      env["hbt.session_id"] = session_id || "default"
+
+      # Call the app
+      status, headers, response = @app.call(env)
+
+      # Add session ID to response headers
+      headers["X-Session-ID"] = session_id if session_id
+
+      [status, headers, response]
+    end
+
+    private
+
+    def sanitize_session_id(value)
+      return nil if value.nil? || value.empty?
+
+      # Ensure it's alphanumeric with underscores/hyphens only
+      sanitized = value.gsub(/[^a-zA-Z0-9_\-]/, "")
+
+      # Limit length
+      sanitized = sanitized[0..64]
+
+      # Return nil if invalid
+      return nil if sanitized.empty?
+
+      sanitized
+    end
+
+    def mcp_request?(env)
+      env["PATH_INFO"]&.start_with?("/mcp")
+    end
+
+    def log_request_headers(env)
+      HeadlessBrowserTool::Logger.log.info "\n=== REQUEST HEADERS ==="
+      HeadlessBrowserTool::Logger.log.info "Method: #{env["REQUEST_METHOD"]} #{env["PATH_INFO"]}"
+      HeadlessBrowserTool::Logger.log.info "Remote IP: #{env["REMOTE_ADDR"]}"
+
+      # Log all HTTP headers
+      env.select { |k, _v| k.start_with?("HTTP_") }.each do |key, value|
+        header_name = key.sub("HTTP_", "").split("_").map(&:capitalize).join("-")
+        HeadlessBrowserTool::Logger.log.info "#{header_name}: #{value}"
+      end
+
+      # Log specific session-related info
+      HeadlessBrowserTool::Logger.log.info "Session ID: #{env["HTTP_X_SESSION_ID"] || "NOT PROVIDED"}"
+      HeadlessBrowserTool::Logger.log.info "=====================\n"
+    end
+  end
+end

data/lib/headless_browser_tool/tools/attach_file_tool.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "base_tool"
+
+module HeadlessBrowserTool
+  module Tools
+    class AttachFileTool < BaseTool
+      tool_name "attach_file"
+      description "Upload file to file input field"
+
+      arguments do
+        required(:file_field_selector).filled(:string).description("CSS selector of the file input field")
+        required(:file_path).filled(:string).description("Path to the file to upload")
+      end
+
+      def execute(file_field_selector:, file_path:)
+        file_field = browser.find(file_field_selector)
+
+        # Get file info
+        file_name = File.basename(file_path)
+        file_size = File.size(file_path) if File.exist?(file_path)
+
+        browser.attach_file(file_field_selector, file_path)
+
+        {
+          field_selector: file_field_selector,
+          file_path: file_path,
+          file_name: file_name,
+          file_size: file_size,
+          field: {
+            id: file_field[:id],
+            name: file_field[:name],
+            accept: file_field[:accept]
+          }.compact,
+          status: "attached"
+        }
+      end
+    end
+  end
+end

data/lib/headless_browser_tool/tools/auto_narrate_tool.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "base_tool"
+
+module HeadlessBrowserTool
+  module Tools
+    class AutoNarrateTool < BaseTool
+      tool_name "auto_narrate"
+      description "Enable automatic narration of what's happening on the page"
+
+      arguments do
+        optional(:enabled).filled(:bool).description("Enable or disable auto-narration")
+      end
+
+      def execute(enabled: true)
+        if enabled
+          inject_narration_script
+          "Auto-narration enabled. Browser will now describe significant events."
+        else
+          disable_narration
+          "Auto-narration disabled."
+        end
+      end
+
+      private
+
+      def inject_narration_script
+        script = <<~JS
+          (() => {
+            // Store narration state
+            window.__aiNarration = window.__aiNarration || [];
+
+            const narrate = (message) => {
+              const timestamp = new Date().toISOString();
+              window.__aiNarration.push({ timestamp, message });
+              console.log(`[AI Narration] ${message}`);
+
+              // Keep only last 50 events
+              if (window.__aiNarration.length > 50) {
+                window.__aiNarration.shift();
+              }
+            };
+
+            // Monitor page changes
+            const observer = new MutationObserver((mutations) => {
+              const significantChanges = [];
+
+              mutations.forEach((mutation) => {
+                // New nodes added
+                if (mutation.type === 'childList' && mutation.addedNodes.length > 0) {
+                  Array.from(mutation.addedNodes).forEach((node) => {
+                    if (node.nodeType === 1) { // Element node
+                      if (node.tagName === 'DIV' && node.classList.contains('modal')) {
+                        significantChanges.push('A modal dialog appeared');
+                      } else if (node.tagName === 'FORM') {
+                        significantChanges.push('A new form appeared on the page');
+                      } else if (node.classList && node.classList.contains('error')) {
+                        significantChanges.push(`Error message: "${node.textContent.trim()}"`);
+                      } else if (node.classList && node.classList.contains('success')) {
+                        significantChanges.push(`Success message: "${node.textContent.trim()}"`);
+                      }
+                    }
+                  });
+                }
+
+                // Attributes changed
+                if (mutation.type === 'attributes') {
+                  if (mutation.attributeName === 'disabled') {
+                    const element = mutation.target;
+                    if (element.tagName === 'BUTTON' || element.tagName === 'INPUT') {
+                      const action = element.disabled ? 'disabled' : 'enabled';
+                      significantChanges.push(`${element.tagName} "${element.textContent || element.value}" was ${action}`);
+                    }
+                  }
+                }
+              });
+
+              // Narrate significant changes
+              significantChanges.forEach(narrate);
+            });
+
+            // Start observing
+            observer.observe(document.body, {
+              childList: true,
+              attributes: true,
+              subtree: true,
+              attributeFilter: ['disabled', 'hidden', 'style']
+            });
+
+            // Monitor form submissions
+            document.addEventListener('submit', (e) => {
+              const form = e.target;
+              const formName = form.id || form.name || 'unnamed form';
+              narrate(`Form "${formName}" is being submitted`);
+            }, true);
+
+            // Monitor clicks
+            document.addEventListener('click', (e) => {
+              const target = e.target;
+              if (target.tagName === 'BUTTON' || target.tagName === 'A') {
+                const text = target.textContent.trim();
+                if (text) {
+                  narrate(`Clicked on "${text}"`);
+                }
+              }
+            }, true);
+
+            // Monitor page visibility
+            document.addEventListener('visibilitychange', () => {
+              narrate(document.hidden ? 'Page became hidden' : 'Page became visible');
+            });
+
+            // Monitor AJAX requests
+            const originalFetch = window.fetch;
+            window.fetch = function(...args) {
+              const url = args[0];
+              narrate(`Making request to: ${url}`);
+              return originalFetch.apply(this, args)
+                .then(response => {
+                  narrate(`Request completed: ${response.status} ${response.statusText}`);
+                  return response;
+                })
+                .catch(error => {
+                  narrate(`Request failed: ${error.message}`);
+                  throw error;
+                });
+            };
+
+            // Initial narration
+            narrate(`Monitoring page: "${document.title}"`);
+
+            // Function to get narration history
+            window.getAINarration = () => window.__aiNarration;
+          })();
+        JS
+
+        browser.execute_script(script)
+      end
+
+      def disable_narration
+        script = <<~JS
+          (() => {
+            // Remove observers and restore original functions
+            if (window.__aiNarrationObserver) {
+              window.__aiNarrationObserver.disconnect();
+            }
+            window.__aiNarration = [];
+          })();
+        JS
+
+        browser.execute_script(script)
+      end
+    end
+  end
+end

data/lib/headless_browser_tool/tools/base_tool.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+require_relative "../logger"
+
+module HeadlessBrowserTool
+  module Tools
+    class BaseTool < FastMcp::Tool
+      protected
+
+      def browser
+        if HeadlessBrowserTool::Server.single_session_mode
+          # Use the single shared browser instance
+          HeadlessBrowserTool::Server.browser_instance
+        else
+          # Get session-specific browser
+          session_id = Thread.current[:hbt_session_id]
+          raise "No session ID provided. X-Session-ID header is required in multi-session mode" if session_id.nil? || session_id == "default"
+
+          capybara_session = HeadlessBrowserTool::Server.session_manager.get_or_create_session(session_id)
+          HeadlessBrowserTool::BrowserAdapter.new(capybara_session, session_id)
+        end
+      end
+
+      def execute(*args, **kwargs)
+        raise NotImplementedError, "Subclasses must implement the execute method"
+      end
+
+      def call(*args, **kwargs)
+        result = execute(*args, **kwargs)
+        HeadlessBrowserTool::Logger.log.info "CALL: #{self.class.name} #{args.inspect} #{kwargs.inspect} -> #{result.inspect}"
+        result
+      rescue StandardError => e
+        HeadlessBrowserTool::Logger.log.error "ERROR: #{self.class.name} #{args.inspect} #{kwargs.inspect} -> #{e.message}"
+        e.message
+      end
+    end
+  end
+end

data/lib/headless_browser_tool/tools/check_tool.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "base_tool"
+
+module HeadlessBrowserTool
+  module Tools
+    class CheckTool < BaseTool
+      tool_name "check"
+      description "Check a checkbox by selector"
+
+      arguments do
+        required(:checkbox_selector).filled(:string).description("CSS selector of the checkbox to check")
+      end
+
+      def execute(checkbox_selector:)
+        element = browser.find(checkbox_selector)
+        was_checked = element.checked?
+        browser.check(checkbox_selector)
+
+        {
+          selector: checkbox_selector,
+          was_checked: was_checked,
+          is_checked: true,
+          element: {
+            id: element[:id],
+            name: element[:name],
+            value: element[:value],
+            type: element[:type]
+          }.compact,
+          status: "checked"
+        }
+      end
+    end
+  end
+end

data/lib/headless_browser_tool/tools/choose_tool.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "base_tool"
+
+module HeadlessBrowserTool
+  module Tools
+    class ChooseTool < BaseTool
+      tool_name "choose"
+      description "Select a radio button by selector"
+
+      arguments do
+        required(:radio_button_selector).filled(:string).description("CSS selector of the radio button to select")
+      end
+
+      def execute(radio_button_selector:)
+        radio = browser.find(radio_button_selector)
+
+        # Get radio group info
+        name = radio[:name]
+        radio_group = browser.all("input[type='radio'][name='#{name}']") if name
+
+        radio_info = {
+          id: radio[:id],
+          name: name,
+          value: radio[:value],
+          was_checked: radio.checked?
+        }.compact
+
+        browser.choose(radio_button_selector)
+
+        # Get all radio buttons in the same group
+        group_info = radio_group&.map&.with_index do |r, index|
+          selector = if r[:id] && !r[:id].empty?
+                       "##{r[:id]}"
+                     else
+                       "input[type='radio'][name='#{name}']:nth-of-type(#{index + 1})"
+                     end
+
+          {
+            selector: selector,
+            value: r[:value],
+            checked: r.checked?,
+            id: r[:id]
+          }.compact
+        end
+
+        {
+          selector: radio_button_selector,
+          radio: radio_info,
+          group: group_info,
+          status: "selected"
+        }
+      end
+    end
+  end
+end

data/lib/headless_browser_tool/tools/click_button_tool.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "base_tool"
+
+module HeadlessBrowserTool
+  module Tools
+    class ClickButtonTool < BaseTool
+      tool_name "click_button"
+      description "Click button by text or selector"
+
+      arguments do
+        required(:button_text_or_selector).filled(:string).description("Button text or CSS selector")
+      end
+
+      def execute(button_text_or_selector:)
+        url_before = browser.current_url
+        browser.title
+
+        # Find the button element first
+        button = begin
+          browser.find_button(button_text_or_selector)
+        rescue Capybara::ElementNotFound
+          browser.find(button_text_or_selector)
+        end
+
+        button_info = {
+          text: button.text.strip,
+          value: button[:value],
+          type: button[:type],
+          disabled: button.disabled?
+        }.compact
+
+        browser.click_button(button_text_or_selector)
+
+        {
+          button: button_text_or_selector,
+          element: button_info,
+          navigation: {
+            navigated: browser.current_url != url_before,
+            from: url_before,
+            to: browser.current_url,
+            title: browser.title
+          },
+          status: "clicked"
+        }
+      end
+    end
+  end
+end