crucible 0.1.2

data/lib/crucible/tools/stealth.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Crucible
+  module Tools
+    # MCP tools for stealth mode management
+    module Stealth
+      extend Helpers
+
+      VALID_PROFILES = %w[minimal moderate maximum].freeze
+
+      module_function
+
+      # Returns all stealth tools
+      # @param sessions [SessionManager]
+      # @param config [Configuration]
+      # @return [Array<MCP::Tool>]
+      def tools(sessions, config)
+        [
+          enable_stealth_tool(sessions, config),
+          disable_stealth_tool(sessions),
+          get_stealth_status_tool(sessions),
+          set_stealth_profile_tool(sessions, config)
+        ]
+      end
+
+      # Tool: Enable stealth mode for a session
+      def enable_stealth_tool(sessions, _config)
+        MCP::Tool.new(
+          name: 'enable_stealth',
+          description: 'Enable stealth mode for a browser session. Stealth mode applies various ' \
+                       'evasion techniques to make the browser appear as a regular user browser ' \
+                       'to bot detection systems.',
+          input_schema: {
+            type: 'object',
+            properties: {
+              session: {
+                type: 'string',
+                description: 'Session name',
+                default: 'default'
+              },
+              profile: {
+                type: 'string',
+                enum: VALID_PROFILES,
+                description: 'Stealth profile: minimal (basic evasions), moderate (common evasions), ' \
+                             'or maximum (all evasions for strictest detection)'
+              }
+            },
+            required: []
+          }
+        ) do |args|
+          session = args['session'] || 'default'
+          profile = args['profile']&.to_sym
+
+          sessions.enable_stealth(session, profile: profile)
+
+          info = sessions.stealth_info(session)
+          build_result("Stealth mode enabled for session '#{session}' with profile: #{info[:profile]}")
+        rescue Crucible::SessionNotFoundError => e
+          build_error(e.message)
+        rescue Crucible::Error => e
+          build_error(e.message)
+        end
+      end
+
+      # Tool: Disable stealth mode for a session
+      def disable_stealth_tool(sessions)
+        MCP::Tool.new(
+          name: 'disable_stealth',
+          description: 'Disable stealth mode for a browser session. Note: Already-applied evasions ' \
+                       'cannot be removed, but this prevents new evasions from being applied.',
+          input_schema: {
+            type: 'object',
+            properties: {
+              session: {
+                type: 'string',
+                description: 'Session name',
+                default: 'default'
+              }
+            },
+            required: []
+          }
+        ) do |args|
+          session = args['session'] || 'default'
+
+          sessions.disable_stealth(session)
+
+          build_result("Stealth mode disabled for session '#{session}'")
+        rescue Crucible::SessionNotFoundError => e
+          build_error(e.message)
+        end
+      end
+
+      # Tool: Get stealth status for a session
+      def get_stealth_status_tool(sessions)
+        MCP::Tool.new(
+          name: 'get_stealth_status',
+          description: 'Get the current stealth mode status for a browser session.',
+          input_schema: {
+            type: 'object',
+            properties: {
+              session: {
+                type: 'string',
+                description: 'Session name',
+                default: 'default'
+              }
+            },
+            required: []
+          }
+        ) do |args|
+          session = args['session'] || 'default'
+
+          info = sessions.stealth_info(session)
+
+          status = {
+            session: session,
+            stealth_enabled: info[:enabled],
+            profile: info[:profile]
+          }
+
+          build_result(JSON.pretty_generate(status))
+        rescue Crucible::SessionNotFoundError => e
+          build_error(e.message)
+        end
+      end
+
+      # Tool: Set stealth profile (change profile for existing session)
+      def set_stealth_profile_tool(sessions, _config)
+        MCP::Tool.new(
+          name: 'set_stealth_profile',
+          description: 'Change the stealth profile for a session. This enables stealth mode with ' \
+                       'the new profile if not already enabled.',
+          input_schema: {
+            type: 'object',
+            properties: {
+              session: {
+                type: 'string',
+                description: 'Session name',
+                default: 'default'
+              },
+              profile: {
+                type: 'string',
+                enum: VALID_PROFILES,
+                description: 'Stealth profile: minimal, moderate, or maximum'
+              }
+            },
+            required: ['profile']
+          }
+        ) do |args|
+          session = args['session'] || 'default'
+          profile = args['profile']&.to_sym
+
+          unless VALID_PROFILES.include?(args['profile'])
+            raise Crucible::Error, "Invalid profile: #{args['profile']}. Must be one of: #{VALID_PROFILES.join(', ')}"
+          end
+
+          sessions.enable_stealth(session, profile: profile)
+
+          build_result("Stealth profile set to '#{profile}' for session '#{session}'")
+        rescue Crucible::SessionNotFoundError => e
+          build_error(e.message)
+        rescue Crucible::Error => e
+          build_error(e.message)
+        end
+      end
+    end
+  end
+end

data/lib/crucible/tools.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Crucible
+  # Tool registry and loader for MCP browser automation tools
+  #
+  # Tools are organized by domain:
+  # - Navigation: navigate, wait_for, back, forward, refresh
+  # - Interaction: click, type, fill_form, select_option, scroll, hover
+  # - Extraction: screenshot, get_content, pdf, evaluate, get_url, get_title
+  # - Cookies: get_cookies, set_cookies, clear_cookies
+  # - Sessions: list_sessions, close_session
+  # - Downloads: set_download_path, list_downloads, wait_for_download, clear_downloads
+  #
+  module Tools
+    autoload :Helpers, 'crucible/tools/helpers'
+    autoload :Navigation, 'crucible/tools/navigation'
+    autoload :Interaction, 'crucible/tools/interaction'
+    autoload :Extraction, 'crucible/tools/extraction'
+    autoload :Cookies, 'crucible/tools/cookies'
+    autoload :Sessions, 'crucible/tools/sessions'
+    autoload :Downloads, 'crucible/tools/downloads'
+    autoload :Stealth, 'crucible/tools/stealth'
+
+    class << self
+      # Returns all tool definitions for the MCP server
+      # @param session_manager [SessionManager] the session manager instance
+      # @param config [Configuration] the server configuration
+      # @return [Array] array of MCP tool definitions
+      def all(session_manager, config)
+        [
+          *Navigation.tools(session_manager, config),
+          *Interaction.tools(session_manager, config),
+          *Extraction.tools(session_manager, config),
+          *Cookies.tools(session_manager, config),
+          *Sessions.tools(session_manager, config),
+          *Downloads.tools(session_manager, config),
+          *Stealth.tools(session_manager, config)
+        ]
+      end
+    end
+  end
+end

data/lib/crucible/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Crucible
+  VERSION = '0.1.2'
+end

data/lib/crucible.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'crucible/version'
+
+# Crucible: MCP server for browser automation using Ferrum/Chrome
+#
+# Provides browser automation tools for AI agents via the Model Context Protocol.
+# Supports multiple named sessions, navigation, screenshots, form interaction,
+# JavaScript evaluation, cookie management, and PDF generation.
+#
+# @example Basic usage
+#   Crucible.configure do |config|
+#     config.headless = true
+#     config.timeout = 30
+#   end
+#   Crucible.run
+#
+module Crucible
+  class Error < StandardError; end
+  class SessionNotFoundError < Error; end
+  class ElementNotFoundError < Error; end
+  class TimeoutError < Error; end
+  class BrowserError < Error; end
+
+  autoload :Configuration, 'crucible/configuration'
+  autoload :Server, 'crucible/server'
+  autoload :SessionManager, 'crucible/session_manager'
+  autoload :Stealth, 'crucible/stealth'
+  autoload :Tools, 'crucible/tools'
+
+  class << self
+    attr_writer :configuration
+
+    # Returns the current configuration, initializing with defaults if needed
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the configuration for modification
+    # @yield [Configuration] the configuration instance
+    # @return [Configuration]
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Starts the MCP server with the given options
+    # @param options [Hash] configuration overrides
+    def run(**options)
+      config = options.empty? ? configuration : configuration.merge(options)
+      Server.new(config).run
+    end
+
+    # Resets configuration to defaults (mainly for testing)
+    def reset!
+      @configuration = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,201 @@
+--- !ruby/object:Gem::Specification
+name: crucible
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Josh Frye
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ferrum
+  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: 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: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  An MCP (Model Context Protocol) server that provides browser automation tools
+  for AI agents using Ferrum and headless Chrome. Features 25 tools covering
+  navigation, screenshots, form interaction, JavaScript evaluation, cookies,
+  file downloads, and multi-session management.
+email:
+- me@joshfrye.dev
+executables:
+- crucible
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- TESTING.md
+- config.sample.yml
+- crucible.gemspec
+- exe/crucible
+- lib/crucible.rb
+- lib/crucible/configuration.rb
+- lib/crucible/server.rb
+- lib/crucible/session_manager.rb
+- lib/crucible/stealth.rb
+- lib/crucible/stealth/evasions/chrome_app.js
+- lib/crucible/stealth/evasions/chrome_csi.js
+- lib/crucible/stealth/evasions/chrome_load_times.js
+- lib/crucible/stealth/evasions/chrome_runtime.js
+- lib/crucible/stealth/evasions/iframe_content_window.js
+- lib/crucible/stealth/evasions/media_codecs.js
+- lib/crucible/stealth/evasions/navigator_hardware_concurrency.js
+- lib/crucible/stealth/evasions/navigator_languages.js
+- lib/crucible/stealth/evasions/navigator_permissions.js
+- lib/crucible/stealth/evasions/navigator_plugins.js
+- lib/crucible/stealth/evasions/navigator_vendor.js
+- lib/crucible/stealth/evasions/navigator_webdriver.js
+- lib/crucible/stealth/evasions/webgl_vendor.js
+- lib/crucible/stealth/evasions/window_outerdimensions.js
+- lib/crucible/stealth/utils.js
+- lib/crucible/tools.rb
+- lib/crucible/tools/cookies.rb
+- lib/crucible/tools/downloads.rb
+- lib/crucible/tools/extraction.rb
+- lib/crucible/tools/helpers.rb
+- lib/crucible/tools/interaction.rb
+- lib/crucible/tools/navigation.rb
+- lib/crucible/tools/sessions.rb
+- lib/crucible/tools/stealth.rb
+- lib/crucible/version.rb
+homepage: https://github.com/joshfng/crucible
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/joshfng/crucible
+  source_code_uri: https://github.com/joshfng/crucible
+  changelog_uri: https://github.com/joshfng/crucible/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: MCP server for browser automation using Ferrum/Chrome
+test_files: []