shared_tools 0.2.3 → 0.3.0

data/lib/shared_tools/{ruby_llm/mcp → mcp}/github_mcp_server.rb

@@ -1,5 +1,22 @@
-# shared_tools/ruby_llm/mcp/github_mcp_server.rb
-# brew install github_mcp_server
+# shared_tools/mcp/github_mcp_server.rb
+#
+# GitHub MCP Server Client Configuration for ruby_llm-mcp >= 0.7.0
+#
+# Provides access to GitHub operations including:
+#   - Repository management
+#   - Issue and PR operations
+#   - Code search
+#   - Branch operations
+#   - And more GitHub API functionality
+#
+# Installation:
+#   brew install github-mcp-server
+#
+# Configuration:
+#   Set environment variable: GITHUB_PERSONAL_ACCESS_TOKEN
+#   export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here
+#
+# Compatible with ruby_llm-mcp v0.7.0+
 
 require "ruby_llm/mcp"
 
@@ -7,7 +24,7 @@ RubyLLM::MCP.add_client(
   name: "github-mcp-server",
   transport_type: :stdio,
   config: {
-    command: "/opt/homebrew/bin/github-mcp-server", # brew install github-mcp-server
+    command: "/opt/homebrew/bin/github-mcp-server",
     args: %w[stdio],
     env: { "GITHUB_PERSONAL_ACCESS_TOKEN" => ENV.fetch("GITHUB_PERSONAL_ACCESS_TOKEN") },
   },

data/lib/shared_tools/mcp/imcp.rb

@@ -0,0 +1,28 @@
+# shared_tools/mcp/imcp.rb
+#
+# iMCP Client Configuration for ruby_llm-mcp >= 0.7.0
+#
+# iMCP is a macOS application that provides MCP access to:
+#   - Notes
+#   - Calendar
+#   - Contacts
+#   - Reminders
+#   - And other macOS native applications
+#
+# Installation:
+#   brew install --cask loopwork/tap/iMCP
+#
+# Documentation:
+#   https://github.com/loopwork/iMCP
+#
+# Compatible with ruby_llm-mcp v0.7.0+
+
+require 'ruby_llm/mcp'
+
+RubyLLM::MCP.add_client(
+  name: "imcp-server",
+  transport_type: :stdio,
+  config: {
+    command: "/Applications/iMCP.app/Contents/MacOS/imcp-server 2> /dev/null"
+  }
+)

data/lib/shared_tools/mcp/tavily_mcp_server.rb

@@ -0,0 +1,44 @@
+# shared_tools/mcp/tavily_mcp_server.rb
+#
+# Tavily MCP Server Client Configuration for ruby_llm-mcp >= 0.7.0
+#
+# Provides AI-powered web search and research capabilities:
+#   - Web search with AI-optimized results
+#   - Research-grade content extraction
+#   - Real-time information gathering
+#   - News and current events search
+#
+# Installation:
+#   Requires Node.js and npx (comes with Node.js)
+#   The mcp-remote package will be installed automatically via npx
+#
+# Configuration:
+#   Set environment variable: TAVILY_API_KEY
+#   export TAVILY_API_KEY=your_api_key_here
+#   Get your API key at: https://tavily.com
+#
+# Compatible with ruby_llm-mcp v0.7.0+
+
+require "ruby_llm/mcp"
+
+RubyLLM::MCP.add_client(
+  name: "tavily",
+  transport_type: :stdio,
+  config: {
+    command: "npx -y mcp-remote https://mcp.tavily.com/mcp/?tavilyApiKey=#{ENV.fetch('TAVILY_API_KEY')}",
+    env: {}
+  }
+)
+
+
+__END__
+
+
+# {
+#   "mcpServers": {
+#     "tavily-remote-mcp": {
+#       "command": "npx -y mcp-remote https://mcp.tavily.com/mcp/?tavilyApiKey=$TAVILY_API_KEY",
+#       "env": {}
+#     }
+#   }
+# }

data/lib/shared_tools/mcp.rb

@@ -0,0 +1,24 @@
+# lib/shared_tools/mcp.rb
+#
+# MCP (Model Context Protocol) support for SharedTools using ruby_llm-mcp gem >= 0.7.0
+#
+# This module provides integration with various MCP servers, allowing Ruby applications
+# to connect to external services and tools through the Model Context Protocol.
+#
+# @see https://github.com/patvice/ruby_llm-mcp RubyLLM MCP documentation
+# @see https://www.rubyllm-mcp.com Official documentation
+#
+# Usage:
+#   require 'shared_tools/mcp/imcp'              # Load iMCP client
+#   require 'shared_tools/mcp/github_mcp_server' # Load GitHub client
+#   require 'shared_tools/mcp/tavily_mcp_server' # Load Tavily client
+#
+# Requirements:
+#   - ruby_llm-mcp >= 0.7.0
+#   - RubyLLM >= 1.9.0
+#
+# Version 0.7.0 Changes:
+#   - Complex parameter support is now enabled by default
+#   - Requires RubyLLM 1.9+
+#   - support_complex_parameters! method is deprecated
+#

data/lib/shared_tools/tools/browser/base_driver.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module SharedTools
+  module Tools
+    module Browser
+      # A base driver intended to be overridden by specific browser drivers (e.g. waitir).
+      class BaseDriver
+        TIMEOUT = Integer(ENV.fetch("OMNIAI_BROWSER_TIMEOUT", 10))
+
+        # @param logger [Logger]
+        def initialize(logger: Logger.new(IO::NULL))
+          @logger = logger
+        end
+
+        def close
+          raise NotImplementedError, "#{self.class.name}#{__method__} undefined"
+        end
+
+        # @return [String]
+        def url
+          raise NotImplementedError, "#{self.class.name}#{__method__} undefined"
+        end
+
+        # @return [String]
+        def title
+          raise NotImplementedError, "#{self.class.name}#{__method__} undefined"
+        end
+
+        # @return [String]
+        def html
+          raise NotImplementedError, "#{self.class.name}#{__method__} undefined"
+        end
+
+        # @yield [file]
+        # @yieldparam file [File]
+        def screenshot
+          raise NotImplementedError, "#{self.class.name}#{__method__} undefined"
+        end
+
+        # @param url [String]
+        #
+        # @return [Hash]
+        def goto(url:)
+          raise NotImplementedError, "#{self.class.name}#{__method__} undefined"
+        end
+
+        # @param selector [String]
+        # @param text [String]
+        #
+        # @return [Hash]
+        def fill_in(selector:, text:)
+          raise NotImplementedError, "#{self.class.name}#{__method__} undefined"
+        end
+
+        # @param selector [String] e.g. "button[type='submit']", "div#parent > span.child", etc
+        #
+        # @return [Hash]
+        def click(selector:)
+          raise NotImplementedError, "#{self.class.name}#{__method__} undefined"
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/browser/base_tool.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "watir"
+
+module SharedTools
+  module Tools
+    module Browser
+      # @example
+      #   class SeleniumTool < BaseTool
+      #     # ...
+      #   end
+      class BaseTool 
+        # @param logger [Logger]
+        # @param driver [BaseDriver]
+        def initialize(driver:, logger: Logger.new(IO::NULL))
+          super()
+          @driver = driver
+          @logger = logger
+        end
+
+      protected
+
+        def wait_for_element
+          return yield if defined?(RSpec) # Skip waiting in tests
+
+          Watir::Wait.until(timeout: 10) do
+            element = yield
+            element if element && element_visible?(element)
+          end
+        rescue Watir::Wait::TimeoutError
+          log_element_timeout
+          nil
+        end
+
+        def element_visible?(element)
+          return true unless element.respond_to?(:visible?)
+
+          element.visible?
+        end
+
+        def log_element_timeout
+          return unless @browser.respond_to?(:elements)
+
+          visible_elements = @browser.elements.select(&:visible?).map(&:text).compact.first(10)
+          @logger.error("Element not found after 10s. Sample visible elements: #{visible_elements}")
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/browser/click_tool.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module SharedTools
+  module Tools
+    module Browser
+      # @example
+      #   browser = Watir::Browser.new(:chrome)
+      #   tool = SharedTools::Tools::Browser::ClickTool.new(browser:)
+      #   tool.execute(selector: "#some-id")
+      #   tool.execute(selector: ".some-class")
+      #   tool.execute(selector: "some text")
+      #   tool.execute(selector: "//div[@role='button']")
+      class ClickTool < ::RubyLLM::Tool
+        def self.name = 'browser_click'
+
+        description "A browser automation tool for clicking any clickable element."
+
+        params do
+          string :selector, description: <<~TEXT.strip
+            A CSS selector to locate or interact with an element on the page:
+
+             * 'form button[type="submit"]': selects a button with type submit
+             * '.example': selects elements with the foo and bar classes
+             * '#example': selects an element by ID
+             * 'div#parent > span.child': selects span elements that are direct children of div elements
+             * 'a[href="/login"]': selects an anchor tag with a specific href attribute
+          TEXT
+        end
+
+        def initialize(driver: nil, logger: nil)
+          @driver = driver || default_driver
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param selector [String] CSS selector, ID, text content, or other identifier for the element to click.
+        def execute(selector:)
+          @logger.info("#{self.class.name}##{__method__} selector=#{selector.inspect}")
+
+          @driver.click(selector:)
+        end
+
+      private
+
+        def default_driver
+          if defined?(Watir)
+            WatirDriver.new(logger: @logger)
+          else
+            raise LoadError, "Browser tools require a driver. Either install the 'watir' gem or pass a driver: parameter"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/browser/elements/element_grouper.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module SharedTools
+  module Tools
+    module Browser
+      module Elements
+        # Groups HTML elements by their relevance for data entry
+        module ElementGrouper
+        module_function
+
+          def group_for_data_entry(elements, text)
+            groups = {
+              inputs: [], # text, number, email inputs - primary targets
+              form_controls: {}, # radio buttons, checkboxes grouped by name
+              labels: [], # labels, headers, spans
+              actions: [], # buttons and actionable elements
+            }
+
+            elements.each do |element|
+              categorize_element(element, groups, text)
+            end
+
+            groups
+          end
+
+          def categorize_element(element, groups, text)
+            case element.name.downcase
+            when "input"
+              categorize_input_element(element, groups)
+            when "textarea", "select"
+              groups[:inputs] << element
+            when "button"
+              groups[:actions] << element if contains_text_match?(element, text)
+            when "label", "span", "div", "th"
+              groups[:labels] << element if contains_text_match?(element, text)
+            end
+          end
+
+          def categorize_input_element(element, groups)
+            if data_entry_input?(element)
+              groups[:inputs] << element
+            else
+              group_form_control(element, groups[:form_controls])
+            end
+          end
+
+          def data_entry_input?(element)
+            # Handle missing type attribute - HTML default is "text"
+            type = (element["type"] || "text").downcase
+
+            # Include common data entry input types
+            %w[text number email tel url date datetime-local time month week
+               password search].include?(type)
+          end
+
+          def group_form_control(element, form_controls)
+            type = (element["type"] || "text").downcase
+            return unless %w[radio checkbox].include?(type)
+
+            name = element["name"] || "unnamed"
+            form_controls[name] ||= []
+            form_controls[name] << element
+          end
+
+          def contains_text_match?(element, text)
+            element.text.downcase.include?(text.downcase) ||
+              element["value"]&.downcase&.include?(text.downcase)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/browser/elements/nearby_element_detector.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module SharedTools
+  module Tools
+    module Browser
+      module Elements
+        # Handles detection of interactive elements near text matches
+        module NearbyElementDetector
+        module_function
+
+          def add_nearby_interactive_elements(elements)
+            nearby_elements = []
+            elements.each do |element|
+              nearby_elements += find_interactive_in_context(element)
+            end
+            combined = elements.to_a + nearby_elements
+            combined.uniq
+          end
+
+          def find_interactive_in_context(element)
+            interactive_elements = []
+            interactive_elements += check_table_context(element)
+            interactive_elements += check_parent_containers(element)
+            interactive_elements.uniq
+          end
+
+          def check_table_context(element)
+            elements = []
+            table_cell = element.ancestors("td").first || element.ancestors("th").first
+            elements += find_interactive_in_container(table_cell) if table_cell
+            table_row = element.ancestors("tr").first
+            elements += find_interactive_in_container(table_row) if table_row
+            if table_cell && table_row
+              table = element.ancestors("table").first
+              elements += find_interactive_in_same_column(table, table_cell, table_row) if table
+            end
+            elements
+          end
+
+          def find_interactive_in_same_column(table, header_cell, header_row)
+            return [] unless table
+
+            column_index = header_row.css("th, td").index(header_cell)
+            return [] unless column_index
+
+            interactive_elements = []
+            table.css("tbody tr").each do |row|
+              interactive_elements += find_column_cell_elements(row, column_index)
+            end
+            interactive_elements
+          end
+
+          def find_column_cell_elements(row, column_index)
+            target_cell = row.css("td, th")[column_index]
+            return [] unless target_cell
+
+            find_interactive_in_container(target_cell) + find_interactive_in_nested_tables(target_cell, column_index)
+          end
+
+          def find_interactive_in_nested_tables(cell, original_column_index)
+            interactive_elements = []
+
+            cell.css("table").each do |nested_table|
+              nested_table.css("tr").each do |nested_row|
+                nested_cells = nested_row.css("td, th")
+                if nested_cells[original_column_index]
+                  interactive_elements += find_interactive_in_container(nested_cells[original_column_index])
+                end
+              end
+            end
+
+            interactive_elements
+          end
+
+          def check_parent_containers(element)
+            interactive_elements = []
+            parent_container = element.parent
+            3.times do
+              break unless parent_container
+              break if parent_container.is_a?(Nokogiri::XML::Document)
+
+              interactive_elements += find_interactive_in_container(parent_container)
+              parent_container = parent_container.parent
+            end
+            interactive_elements
+          end
+
+          def find_interactive_in_container(container)
+            return [] unless container
+
+            container.css("input, textarea, select, button, [role='button'], [tabindex='0']")
+              .reject { |el| non_interactive_element?(el) }
+          end
+
+          def non_interactive_element?(element)
+            return true if element["type"] == "hidden"
+            return true if element["tabindex"] == "-1"
+            return true if element["aria-hidden"] == "true"
+
+            style = element["style"]
+            return true if style&.include?("display: none") || style&.include?("visibility: hidden")
+
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/browser/formatters/action_formatter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SharedTools
+  module Tools
+    module Browser
+      module Formatters
+        # Handles formatting of action elements (buttons, links)
+        module ActionFormatter
+        module_function
+
+          def format_actions(actions)
+            result = "⚡ Available Actions:\n"
+            actions.first(5).each do |action|
+              result += format_action_element(action)
+            end
+            result += "  ... and #{actions.size - 5} more\n" if actions.size > 5
+            result += "\n"
+          end
+
+          def format_action_element(action)
+            text = action.text.strip
+            selector = get_action_selector(action)
+            "  • #{text} (#{selector})\n"
+          end
+
+          def get_action_selector(action)
+            return action["id"] if action["id"] && !action["id"].empty?
+            return "text:#{action.text.strip}" if action.text.strip.length > 2
+            return action["class"].split.first if action["class"]
+
+            "css-needed"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/browser/formatters/data_entry_formatter.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module SharedTools
+  module Tools
+    module Browser
+      module Formatters
+        # Formats grouped elements for optimal data entry display
+        module DataEntryFormatter
+        module_function
+
+          def format_groups(grouped_elements, total_count, text)
+            result = build_header(total_count, text)
+            result += format_each_group(grouped_elements)
+            result
+          end
+
+          def format_inputs(inputs)
+            result = "📝 Data Entry Fields:\n"
+            table_groups = group_by_table_context(inputs)
+            result += format_table_groups(table_groups)
+            "#{result}\n"
+          end
+
+          def format_form_controls(form_controls)
+            result = "🎛️ Form Controls:\n"
+            form_controls.each do |name, controls|
+              result += format_control_group(name, controls)
+            end
+            result += "\n"
+          end
+
+          def format_labels(labels)
+            result = "🏷️ Labels & Headers:\n"
+            labels.first(3).each do |label|
+              result += "  • #{label.name}: #{label.text.strip}\n"
+            end
+            result += "  ... and #{labels.size - 3} more\n" if labels.size > 3
+            result += "\n"
+          end
+
+          def build_header(total_count, text)
+            "Found #{total_count} elements containing '#{text}':\n\n"
+          end
+
+          def format_each_group(grouped_elements)
+            [
+              format_inputs_section(grouped_elements[:inputs]),
+              format_actions_section(grouped_elements[:actions]),
+              format_controls_section(grouped_elements[:form_controls]),
+              format_labels_section(grouped_elements[:labels]),
+            ].join
+          end
+
+          def format_inputs_section(inputs)
+            inputs.any? ? format_inputs(inputs) : ""
+          end
+
+          def format_actions_section(actions)
+            actions.any? ? ActionFormatter.format_actions(actions) : ""
+          end
+
+          def format_controls_section(form_controls)
+            form_controls.any? ? format_form_controls(form_controls) : ""
+          end
+
+          def format_labels_section(labels)
+            labels.any? ? format_labels(labels) : ""
+          end
+
+          def format_control_group(name, controls)
+            result = "\n  #{name.humanize} options:\n"
+            controls.each do |control|
+              checked = control["checked"] ? " \u2713" : ""
+              result += "    • #{control['value']}#{checked}\n"
+            end
+            result
+          end
+
+          def format_table_groups(table_groups)
+            return format_single_group(table_groups.values.first) if table_groups.size == 1
+
+            result = ""
+            table_groups.each do |(context, group_inputs)|
+              result += "\n  #{context}:\n"
+              group_inputs.each { |input| result += InputFormatter.format_input_field(input, "    ") }
+            end
+            result
+          end
+
+          def format_single_group(inputs)
+            result = ""
+            inputs.each { |input| result += InputFormatter.format_input_field(input, "  ") }
+            result
+          end
+
+          def group_by_table_context(inputs)
+            groups = {}
+            inputs.each do |input|
+              context = find_context(input)
+              groups[context] ||= []
+              groups[context] << input
+            end
+            groups
+          end
+
+          def find_context(input)
+            table = input.ancestors("table").first
+            return "Form Fields" unless table
+
+            find_table_context(input)
+          end
+
+          def find_table_context(input)
+            row = input.ancestors("tr").first
+            return "Table" unless row
+
+            find_meaningful_cell_text(row)
+          end
+
+          def find_meaningful_cell_text(row)
+            meaningful_cell = row.css("td, th").find do |cell|
+              cell.text.strip.length > 2 && !cell.text.match?(/^\d+\.?\d*$/)
+            end
+
+            meaningful_cell ? meaningful_cell.text.strip[0..30] : "Table"
+          end
+
+          def humanize(text)
+            text.gsub(/[-_]/, " ").split.map(&:capitalize).join(" ")
+          end
+        end
+      end
+    end
+  end
+end