headless_browser_tool 0.1.1

data/lib/headless_browser_tool/tools/switch_to_window_tool.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "base_tool"
+
+module HeadlessBrowserTool
+  module Tools
+    class SwitchToWindowTool < BaseTool
+      tool_name "switch_to_window"
+      description "Switch to specific browser window/tab"
+
+      arguments do
+        required(:window_handle).filled(:string).description("Handle of the window to switch to")
+      end
+
+      def execute(window_handle:)
+        previous_window = browser.current_window
+        browser.switch_to_window(window_handle)
+
+        {
+          window_handle: window_handle,
+          previous_window: previous_window,
+          current_url: browser.current_url,
+          title: browser.title,
+          total_windows: browser.windows.count,
+          status: "switched"
+        }
+      end
+    end
+  end
+end

data/lib/headless_browser_tool/tools/uncheck_tool.rb

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

data/lib/headless_browser_tool/tools/visit_tool.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "base_tool"
+
+module HeadlessBrowserTool
+  module Tools
+    class VisitTool < BaseTool
+      tool_name "visit"
+      description "Navigate to a URL"
+
+      arguments do
+        required(:url).filled(:string).description("The URL to navigate to")
+      end
+
+      def execute(url:)
+        browser.visit(url)
+
+        {
+          url: url,
+          current_url: browser.current_url,
+          title: browser.title,
+          status: "success"
+        }
+      end
+    end
+  end
+end

data/lib/headless_browser_tool/tools/visual_diff_tool.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require_relative "base_tool"
+
+module HeadlessBrowserTool
+  module Tools
+    class VisualDiffTool < BaseTool
+      tool_name "visual_diff"
+      description "Capture what changed on the page after an action"
+
+      def execute
+        # Capture current state
+        current_state = capture_page_state
+
+        # Compare with previous state if exists
+        previous_state = browser.previous_state || {}
+
+        changes = {
+          url_changed: previous_state[:url] != current_state[:url],
+          title_changed: previous_state[:title] != current_state[:title],
+          new_elements: find_new_elements(previous_state[:elements], current_state[:elements]),
+          removed_elements: find_removed_elements(previous_state[:elements], current_state[:elements]),
+          text_changes: find_text_changes(previous_state[:texts], current_state[:texts]),
+          form_values_changed: compare_form_values(previous_state[:forms], current_state[:forms]),
+          new_images: current_state[:images] - (previous_state[:images] || []),
+          viewport_position: current_state[:scroll]
+        }
+
+        # Store current state for next comparison
+        browser.previous_state = current_state
+
+        # Return human-readable summary
+        summarize_changes(changes, current_state)
+      end
+
+      private
+
+      def capture_page_state
+        state_script = <<~JS
+          (() => {
+            // Get all visible text nodes
+            const texts = [];
+            const walker = document.createTreeWalker(
+              document.body,
+              NodeFilter.SHOW_TEXT,
+              {
+                acceptNode: (node) => {
+                  const parent = node.parentElement;
+                  if (parent && parent.offsetWidth > 0 && parent.offsetHeight > 0) {
+                    const text = node.textContent.trim();
+                    if (text.length > 0) return NodeFilter.FILTER_ACCEPT;
+                  }
+                  return NodeFilter.FILTER_REJECT;
+                }
+              }
+            );
+
+            let node;
+            while (node = walker.nextNode()) {
+              texts.push(node.textContent.trim());
+            }
+
+            // Get form values
+            const forms = {};
+            document.querySelectorAll('input, select, textarea').forEach(el => {
+              if (el.name || el.id) {
+                forms[el.name || el.id] = el.value;
+              }
+            });
+
+            // Get interactive elements count
+            const elements = {
+              buttons: document.querySelectorAll('button, [role="button"]').length,
+              links: document.querySelectorAll('a[href]').length,
+              inputs: document.querySelectorAll('input, textarea, select').length,
+              images: document.querySelectorAll('img').length
+            };
+
+            // Get images
+            const images = Array.from(document.querySelectorAll('img')).map(img => img.alt || img.src);
+
+            return {
+              url: window.location.href,
+              title: document.title,
+              texts: texts,
+              forms: forms,
+              elements: elements,
+              images: images,
+              scroll: { x: window.scrollX, y: window.scrollY }
+            };
+          })();
+        JS
+
+        state = browser.evaluate_script(state_script)
+        state || {}
+      end
+
+      def find_new_elements(old_elements, new_elements)
+        return {} unless old_elements && new_elements
+
+        changes = {}
+        new_elements.each do |key, count|
+          old_count = old_elements[key] || 0
+          changes[key] = count - old_count if count > old_count
+        end
+        changes
+      end
+
+      def find_removed_elements(old_elements, new_elements)
+        return {} unless old_elements && new_elements
+
+        changes = {}
+        old_elements.each do |key, count|
+          new_count = new_elements[key] || 0
+          changes[key] = count - new_count if count > new_count
+        end
+        changes
+      end
+
+      def find_text_changes(old_texts, new_texts)
+        return [] unless old_texts && new_texts
+
+        # Find completely new text blocks
+        new_text_blocks = new_texts - old_texts
+        new_text_blocks.select { |text| text.length > 20 } # Only significant text
+      end
+
+      def compare_form_values(old_forms, new_forms)
+        return {} unless old_forms && new_forms
+
+        changes = {}
+        new_forms.each do |field, value|
+          changes[field] = { from: old_forms[field], to: value } if old_forms[field] != value && !value.empty?
+        end
+        changes
+      end
+
+      def summarize_changes(changes, current_state)
+        summary = []
+
+        # URL change
+        summary << "📍 Navigated to: #{current_state[:url]}" if changes[:url_changed]
+
+        # Title change
+        summary << "📄 Page title: \"#{current_state[:title]}\"" if changes[:title_changed]
+
+        # New elements appeared
+        if changes[:new_elements].any?
+          changes[:new_elements].each do |type, count|
+            summary << "➕ #{count} new #{type} appeared"
+          end
+        end
+
+        # Elements removed
+        if changes[:removed_elements].any?
+          changes[:removed_elements].each do |type, count|
+            summary << "➖ #{count} #{type} removed"
+          end
+        end
+
+        # Form changes
+        summary << "✏️ Form fields updated: #{changes[:form_values_changed].keys.join(", ")}" if changes[:form_values_changed].any?
+
+        # New significant text
+        summary << "💬 New text appeared: \"#{changes[:text_changes].first[0..100]}...\"" if changes[:text_changes].any?
+
+        # Scroll position
+        summary << "📜 Page scrolled to position: #{changes[:viewport_position][:y]}px" if changes[:viewport_position][:y] > 100
+
+        # If no changes detected
+        summary << "No significant visual changes detected" if summary.empty?
+
+        summary.join("\n")
+      end
+    end
+  end
+end

data/lib/headless_browser_tool/tools.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "tools/base_tool"
+require_relative "tools/visit_tool"
+require_relative "tools/refresh_tool"
+require_relative "tools/go_back_tool"
+require_relative "tools/go_forward_tool"
+require_relative "tools/click_tool"
+require_relative "tools/right_click_tool"
+require_relative "tools/double_click_tool"
+require_relative "tools/hover_tool"
+require_relative "tools/drag_tool"
+require_relative "tools/find_element_tool"
+require_relative "tools/find_all_tool"
+require_relative "tools/find_elements_containing_text_tool"
+require_relative "tools/get_text_tool"
+require_relative "tools/get_attribute_tool"
+require_relative "tools/get_value_tool"
+require_relative "tools/is_visible_tool"
+require_relative "tools/has_element_tool"
+require_relative "tools/has_text_tool"
+require_relative "tools/fill_in_tool"
+require_relative "tools/select_tool"
+require_relative "tools/check_tool"
+require_relative "tools/uncheck_tool"
+require_relative "tools/choose_tool"
+require_relative "tools/attach_file_tool"
+require_relative "tools/click_button_tool"
+require_relative "tools/click_link_tool"
+require_relative "tools/get_current_url_tool"
+require_relative "tools/get_current_path_tool"
+require_relative "tools/get_page_title_tool"
+require_relative "tools/get_page_source_tool"
+require_relative "tools/execute_script_tool"
+require_relative "tools/evaluate_script_tool"
+require_relative "tools/save_page_tool"
+require_relative "tools/switch_to_window_tool"
+require_relative "tools/open_new_window_tool"
+require_relative "tools/close_window_tool"
+require_relative "tools/get_window_handles_tool"
+require_relative "tools/maximize_window_tool"
+require_relative "tools/resize_window_tool"
+require_relative "tools/screenshot_tool"
+require_relative "tools/search_page_tool"
+require_relative "tools/search_source_tool"
+require_relative "tools/visual_diff_tool"
+require_relative "tools/get_page_context_tool"
+require_relative "tools/auto_narrate_tool"
+require_relative "tools/get_narration_history_tool"
+require_relative "tools/get_session_info_tool"
+
+module HeadlessBrowserTool
+  module Tools
+    ALL_TOOLS = [
+      VisitTool,
+      RefreshTool,
+      GoBackTool,
+      GoForwardTool,
+      ClickTool,
+      RightClickTool,
+      DoubleClickTool,
+      HoverTool,
+      DragTool,
+      FindElementTool,
+      FindAllTool,
+      FindElementsContainingTextTool,
+      GetTextTool,
+      GetAttributeTool,
+      GetValueTool,
+      IsVisibleTool,
+      HasElementTool,
+      HasTextTool,
+      FillInTool,
+      SelectTool,
+      CheckTool,
+      UncheckTool,
+      ChooseTool,
+      AttachFileTool,
+      ClickButtonTool,
+      ClickLinkTool,
+      GetCurrentUrlTool,
+      GetCurrentPathTool,
+      GetPageTitleTool,
+      GetPageSourceTool,
+      ExecuteScriptTool,
+      EvaluateScriptTool,
+      SavePageTool,
+      SwitchToWindowTool,
+      OpenNewWindowTool,
+      CloseWindowTool,
+      GetWindowHandlesTool,
+      MaximizeWindowTool,
+      ResizeWindowTool,
+      ScreenshotTool,
+      SearchPageTool,
+      SearchSourceTool,
+      VisualDiffTool,
+      GetPageContextTool,
+      AutoNarrateTool,
+      GetNarrationHistoryTool,
+      GetSessionInfoTool
+    ].freeze
+  end
+end

data/lib/headless_browser_tool/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HeadlessBrowserTool
+  VERSION = "0.1.1"
+end

data/lib/headless_browser_tool.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "headless_browser_tool/version"
+require_relative "headless_browser_tool/cli"
+
+module HeadlessBrowserTool
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,256 @@
+--- !ruby/object:Gem::Specification
+name: headless_browser_tool
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Paulo Arruda
+bindir: exe
+cert_chain: []
+date: 2025-05-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fast-mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rackup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: selenium-webdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sinatra-contrib
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides an MCP server with tools to control a headless browser using
+  Capybara and Selenium
+email:
+- parrudaj@gmail.com
+executables:
+- hbt
+extensions: []
+extra_rdoc_files: []
+files:
+- ".claude/settings.json"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.md
+- README.md
+- Rakefile
+- config.ru
+- exe/hbt
+- lib/headless_browser_tool.rb
+- lib/headless_browser_tool/browser.rb
+- lib/headless_browser_tool/browser_adapter.rb
+- lib/headless_browser_tool/cli.rb
+- lib/headless_browser_tool/directory_setup.rb
+- lib/headless_browser_tool/logger.rb
+- lib/headless_browser_tool/server.rb
+- lib/headless_browser_tool/session_manager.rb
+- lib/headless_browser_tool/session_middleware.rb
+- lib/headless_browser_tool/session_persistence.rb
+- lib/headless_browser_tool/stdio_server.rb
+- lib/headless_browser_tool/strict_session_middleware.rb
+- lib/headless_browser_tool/tools.rb
+- lib/headless_browser_tool/tools/attach_file_tool.rb
+- lib/headless_browser_tool/tools/auto_narrate_tool.rb
+- lib/headless_browser_tool/tools/base_tool.rb
+- lib/headless_browser_tool/tools/check_tool.rb
+- lib/headless_browser_tool/tools/choose_tool.rb
+- lib/headless_browser_tool/tools/click_button_tool.rb
+- lib/headless_browser_tool/tools/click_link_tool.rb
+- lib/headless_browser_tool/tools/click_tool.rb
+- lib/headless_browser_tool/tools/close_window_tool.rb
+- lib/headless_browser_tool/tools/double_click_tool.rb
+- lib/headless_browser_tool/tools/drag_tool.rb
+- lib/headless_browser_tool/tools/evaluate_script_tool.rb
+- lib/headless_browser_tool/tools/execute_script_tool.rb
+- lib/headless_browser_tool/tools/fill_in_tool.rb
+- lib/headless_browser_tool/tools/find_all_tool.rb
+- lib/headless_browser_tool/tools/find_element_tool.rb
+- lib/headless_browser_tool/tools/find_elements_containing_text_tool.rb
+- lib/headless_browser_tool/tools/get_attribute_tool.rb
+- lib/headless_browser_tool/tools/get_current_path_tool.rb
+- lib/headless_browser_tool/tools/get_current_url_tool.rb
+- lib/headless_browser_tool/tools/get_narration_history_tool.rb
+- lib/headless_browser_tool/tools/get_page_context_tool.rb
+- lib/headless_browser_tool/tools/get_page_source_tool.rb
+- lib/headless_browser_tool/tools/get_page_title_tool.rb
+- lib/headless_browser_tool/tools/get_session_info_tool.rb
+- lib/headless_browser_tool/tools/get_text_tool.rb
+- lib/headless_browser_tool/tools/get_value_tool.rb
+- lib/headless_browser_tool/tools/get_window_handles_tool.rb
+- lib/headless_browser_tool/tools/go_back_tool.rb
+- lib/headless_browser_tool/tools/go_forward_tool.rb
+- lib/headless_browser_tool/tools/has_element_tool.rb
+- lib/headless_browser_tool/tools/has_text_tool.rb
+- lib/headless_browser_tool/tools/hover_tool.rb
+- lib/headless_browser_tool/tools/is_visible_tool.rb
+- lib/headless_browser_tool/tools/maximize_window_tool.rb
+- lib/headless_browser_tool/tools/open_new_window_tool.rb
+- lib/headless_browser_tool/tools/refresh_tool.rb
+- lib/headless_browser_tool/tools/resize_window_tool.rb
+- lib/headless_browser_tool/tools/right_click_tool.rb
+- lib/headless_browser_tool/tools/save_page_tool.rb
+- lib/headless_browser_tool/tools/screenshot_tool.rb
+- lib/headless_browser_tool/tools/search_page_tool.rb
+- lib/headless_browser_tool/tools/search_source_tool.rb
+- lib/headless_browser_tool/tools/select_tool.rb
+- lib/headless_browser_tool/tools/switch_to_window_tool.rb
+- lib/headless_browser_tool/tools/uncheck_tool.rb
+- lib/headless_browser_tool/tools/visit_tool.rb
+- lib/headless_browser_tool/tools/visual_diff_tool.rb
+- lib/headless_browser_tool/version.rb
+homepage: https://github.com/parruda/headless-browser-tool
+licenses: []
+metadata:
+  homepage_uri: https://github.com/parruda/headless-browser-tool
+  source_code_uri: https://github.com/parruda/headless-browser-tool
+  changelog_uri: https://github.com/parruda/headless-browser-tool/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A headless browser control tool with MCP server
+test_files: []