ferrum-mcp 1.0.0

data/lib/ferrum_mcp/browser_manager.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  # Manages Ferrum browser lifecycle with BotBrowser integration
+  class BrowserManager
+    attr_reader :browser, :config, :logger
+
+    def initialize(config)
+      @config = config
+      @logger = config.logger
+      @browser = nil
+    end
+
+    def start
+      raise BrowserError, 'Browser path is invalid' unless config.valid?
+
+      if config.using_botbrowser?
+        logger.info 'Starting browser with BotBrowser (anti-detection mode)...'
+      else
+        logger.info 'Starting browser with standard Chrome/Chromium...'
+      end
+
+      browser_options_hash = {
+        browser_options: computed_browser_options,
+        headless: config.headless,
+        timeout: config.timeout,
+        process_timeout: ENV['CI'] ? 120 : config.timeout,
+        pending_connection_errors: false
+      }
+
+      # Only set browser_path if explicitly configured
+      browser_options_hash[:browser_path] = config.browser_path if config.browser_path
+
+      @browser = Ferrum::Browser.new(**browser_options_hash)
+
+      logger.info 'Browser started successfully'
+      @browser
+    rescue StandardError => e
+      logger.error "Failed to start browser: #{e.message}"
+      raise BrowserError, "Failed to start browser: #{e.message}"
+    end
+
+    def stop
+      return unless @browser
+
+      logger.info 'Stopping browser...'
+      @browser.quit
+      @browser = nil
+      logger.info 'Browser stopped'
+    rescue StandardError => e
+      logger.error "Error stopping browser: #{e.message}"
+    end
+
+    def restart
+      stop
+      start
+    end
+
+    def active?
+      !@browser.nil?
+    end
+
+    private
+
+    # Compute browser options, merging defaults with session-specific options
+    def computed_browser_options
+      # Use merged options if config supports it (SessionConfiguration)
+      options = if config.respond_to?(:merged_browser_options)
+                  config.merged_browser_options
+                else
+                  browser_options
+                end
+
+      # Log BotBrowser profile usage
+      if config.using_botbrowser? && config.botbrowser_profile && File.exist?(config.botbrowser_profile)
+        logger.info "Using BotBrowser profile: #{config.botbrowser_profile}"
+      end
+
+      options
+    end
+
+    def browser_options
+      options = {
+        'no-sandbox' => nil,
+        'disable-dev-shm-usage' => nil,
+        'disable-blink-features' => 'AutomationControlled',
+        'disable-gpu' => nil
+      }
+
+      # Additional options for CI environments
+      options['disable-setuid-sandbox'] = nil if ENV['CI']
+
+      # Add BotBrowser profile if configured
+      if config.using_botbrowser? && config.botbrowser_profile && File.exist?(config.botbrowser_profile)
+        options['bot-profile'] = config.botbrowser_profile
+      end
+
+      options
+    end
+  end
+end

data/lib/ferrum_mcp/cli/command_handler.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative 'server_runner'
+require_relative '../version'
+
+module FerrumMCP
+  module CLI
+    # Handles CLI commands (help, version, start)
+    class CommandHandler
+      def self.handle(command, options)
+        case command
+        when 'start', nil
+          start_server(options)
+        when 'version', '-v', '--version'
+          show_version
+        when 'help', '-h', '--help'
+          show_help
+        else
+          show_unknown_command(command)
+        end
+      end
+
+      def self.start_server(options)
+        # Load dependencies only when starting server
+        require 'bundler/setup'
+        require 'dotenv/load'
+
+        # Set environment variables from options
+        ENV['MCP_SERVER_HOST'] = options[:host]
+        ENV['MCP_SERVER_PORT'] = options[:port].to_s
+        ENV['LOG_LEVEL'] = options[:log_level]
+
+        runner = ServerRunner.new(options)
+        runner.start
+      end
+
+      def self.show_version
+        puts "FerrumMCP #{VERSION}"
+      end
+
+      def self.show_help
+        puts <<~HELP
+          FerrumMCP - Browser Automation Server for Model Context Protocol
+
+          USAGE:
+              ferrum-mcp [COMMAND] [OPTIONS]
+
+          COMMANDS:
+              start       Start the FerrumMCP server (default)
+              version     Show version information
+              help        Show this help message
+
+          OPTIONS:
+              -t, --transport TYPE        Transport type: http or stdio (default: http)
+              -H, --host HOST             Server host (default: 0.0.0.0)
+              -p, --port PORT             Server port (default: 3000)
+              -l, --log-level LEVEL       Log level: debug, info, warn, error (default: info)
+              -h, --help                  Show this help message
+              -v, --version               Show version
+
+          EXAMPLES:
+              # Start HTTP server on default port
+              ferrum-mcp start
+
+              # Start HTTP server on custom port
+              ferrum-mcp start --port 8080
+
+              # Start STDIO server (for Claude Desktop)
+              ferrum-mcp start --transport stdio
+
+              # Start with debug logging
+              ferrum-mcp start --log-level debug
+
+          ENVIRONMENT VARIABLES:
+              MCP_SERVER_HOST             Server host (default: 0.0.0.0)
+              MCP_SERVER_PORT             Server port (default: 3000)
+              BROWSER_HEADLESS            Run browser in headless mode (default: true)
+              BROWSER_TIMEOUT             Browser timeout in seconds (default: 60)
+              LOG_LEVEL                   Log level (default: info)
+
+              See .env.example for all configuration options.
+
+          DOCUMENTATION:
+              Getting Started: https://github.com/Eth3rnit3/FerrumMCP/blob/main/docs/GETTING_STARTED.md
+              API Reference:   https://github.com/Eth3rnit3/FerrumMCP/blob/main/docs/API_REFERENCE.md
+              Configuration:   https://github.com/Eth3rnit3/FerrumMCP/blob/main/docs/CONFIGURATION.md
+
+          For more information, visit: https://github.com/Eth3rnit3/FerrumMCP
+        HELP
+      end
+
+      def self.show_unknown_command(command)
+        warn "Unknown command: #{command}"
+        warn "Run 'ferrum-mcp help' for usage information"
+        exit 1
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/cli/server_runner.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+# NOTE: ferrum_mcp is loaded in bin/ferrum-mcp before this file
+require_relative '../transport/http_server'
+require_relative '../transport/stdio_server'
+
+module FerrumMCP
+  module CLI
+    # Handles server startup and lifecycle
+    class ServerRunner
+      attr_reader :config, :mcp_server, :transport_server
+
+      def initialize(options = {})
+        @options = options
+        @config = Configuration.new(transport: options[:transport])
+      end
+
+      def validate!
+        return if config.valid?
+
+        puts 'ERROR: Invalid browser configuration'
+        puts 'The specified BROWSER_PATH does not exist'
+        puts ''
+        puts 'Options:'
+        puts '  1. Remove BROWSER_PATH to use system Chrome/Chromium'
+        puts '  2. Set BROWSER_PATH to a valid browser executable'
+        puts ''
+        puts 'Example: export BROWSER_PATH=/path/to/chrome'
+        exit 1
+      end
+
+      def start
+        validate!
+        setup_servers
+        setup_signal_handlers
+        log_startup_info
+        run
+      rescue StandardError => e
+        config.logger.error "ERROR: #{e.message}"
+        config.logger.error e.backtrace.join("\n")
+        exit 1
+      end
+
+      private
+
+      def setup_servers
+        @mcp_server = Server.new(config)
+        @transport_server = create_transport
+      end
+
+      def create_transport
+        case @options[:transport]
+        when 'stdio'
+          Transport::StdioServer.new(mcp_server, config)
+        when 'http'
+          Transport::HTTPServer.new(mcp_server, config)
+        else
+          raise "Unknown transport: #{@options[:transport]}"
+        end
+      end
+
+      def setup_signal_handlers
+        trap('INT') { shutdown }
+        trap('TERM') { shutdown }
+      end
+
+      def shutdown
+        config.logger.info 'Shutting down...'
+        transport_server.stop
+        mcp_server.stop_browser
+        exit 0
+      end
+
+      def log_startup_info
+        logger = config.logger
+        logger.info '=' * 60
+        logger.info "Ferrum MCP Server v#{VERSION}"
+        logger.info '=' * 60
+        logger.info ''
+
+        log_configuration
+        log_transport_info
+
+        logger.info ''
+        logger.info '=' * 60
+        logger.info 'Server starting...'
+        logger.info '=' * 60
+        logger.info ''
+      end
+
+      def log_configuration
+        logger = config.logger
+        logger.info 'Configuration:'
+
+        log_browsers
+        log_user_profiles
+        log_bot_profiles
+        log_browser_options
+      end
+
+      def log_browsers
+        logger = config.logger
+        logger.info "  Browsers (#{config.browsers.count}):"
+        config.browsers.each do |browser|
+          default_marker = browser == config.default_browser ? ' [default]' : ''
+          browser_path = browser.path || 'auto-detect'
+          logger.info "    - #{browser.id}: #{browser.name} (#{browser.type})#{default_marker}"
+          logger.info "      Path: #{browser_path}"
+        end
+      end
+
+      def log_user_profiles
+        return unless config.user_profiles.any?
+
+        logger = config.logger
+        logger.info "  User Profiles (#{config.user_profiles.count}):"
+        config.user_profiles.each do |profile|
+          logger.info "    - #{profile.id}: #{profile.name}"
+          logger.info "      Path: #{profile.path}"
+        end
+      end
+
+      def log_bot_profiles
+        logger = config.logger
+        if config.bot_profiles.any?
+          logger.info '  BotBrowser (anti-detection enabled) ✓'
+          logger.info "  Bot Profiles (#{config.bot_profiles.count}):"
+          config.bot_profiles.each do |profile|
+            encrypted_marker = profile.encrypted ? ' [encrypted]' : ''
+            logger.info "    - #{profile.id}: #{profile.name}#{encrypted_marker}"
+            logger.info "      Path: #{profile.path}"
+          end
+        else
+          logger.info '  BotBrowser: Not configured (consider using for better stealth)'
+        end
+      end
+
+      def log_browser_options
+        logger = config.logger
+        logger.info "  Headless: #{config.headless}"
+        logger.info "  Timeout: #{config.timeout}s"
+        logger.info ''
+      end
+
+      def log_transport_info
+        logger = config.logger
+        logger.info 'Transport:'
+        logger.info "  Protocol: #{@options[:transport].upcase}"
+
+        if @options[:transport] == 'http'
+          logger.info "  Host: #{config.server_host}"
+          logger.info "  Port: #{config.server_port}"
+          logger.info "  MCP Endpoint: http://#{config.server_host}:#{config.server_port}/mcp"
+        else
+          logger.info '  Mode: Standard input/output'
+        end
+      end
+
+      def run
+        transport_server.start
+        # Keep main thread alive for HTTP (stdio blocks automatically)
+        sleep if @options[:transport] == 'http'
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/configuration.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  # Configuration class for Ferrum MCP Server
+  class Configuration
+    attr_accessor :headless, :timeout, :server_host, :server_port, :log_level, :transport, :max_sessions,
+                  :rate_limit_enabled, :rate_limit_max_requests, :rate_limit_window
+    attr_reader :browsers, :user_profiles, :bot_profiles
+
+    # Browser configuration structure
+    BrowserConfig = Struct.new(:id, :name, :path, :type, :description, keyword_init: true) do
+      def to_h
+        super.compact
+      end
+    end
+
+    # User profile configuration structure
+    UserProfileConfig = Struct.new(:id, :name, :path, :description, keyword_init: true) do
+      def to_h
+        super.compact
+      end
+    end
+
+    # BotBrowser profile configuration structure
+    BotProfileConfig = Struct.new(:id, :name, :path, :encrypted, :description, keyword_init: true) do
+      def to_h
+        super.compact
+      end
+    end
+
+    def initialize(transport: 'http')
+      # Server configuration
+      @headless = ENV.fetch('BROWSER_HEADLESS', 'false') == 'true'
+      @timeout = ENV.fetch('BROWSER_TIMEOUT', '60').to_i
+      @server_host = ENV.fetch('MCP_SERVER_HOST', '0.0.0.0')
+      @server_port = ENV.fetch('MCP_SERVER_PORT', '3000').to_i
+      @log_level = ENV.fetch('LOG_LEVEL', 'debug').to_sym
+      @transport = transport
+      @max_sessions = ENV.fetch('MAX_CONCURRENT_SESSIONS', '10').to_i
+
+      # Rate limiting configuration
+      @rate_limit_enabled = ENV.fetch('RATE_LIMIT_ENABLED', 'true') == 'true'
+      @rate_limit_max_requests = ENV.fetch('RATE_LIMIT_MAX_REQUESTS', '100').to_i
+      @rate_limit_window = ENV.fetch('RATE_LIMIT_WINDOW', '60').to_i
+
+      # Load multi-browser configurations
+      @browsers = load_browsers
+      @user_profiles = load_user_profiles
+      @bot_profiles = load_bot_profiles
+    end
+
+    def valid?
+      # Valid if at least one browser is configured
+      browsers.any? && browsers.all? { |b| b.path.nil? || File.exist?(b.path) }
+    end
+
+    # Get default browser (first in list or system Chrome)
+    def default_browser
+      browsers.first
+    end
+
+    # Find browser by ID
+    def find_browser(id)
+      browsers.find { |b| b.id == id }
+    end
+
+    # Find user profile by ID
+    def find_user_profile(id)
+      user_profiles.find { |p| p.id == id }
+    end
+
+    # Find bot profile by ID
+    def find_bot_profile(id)
+      bot_profiles.find { |p| p.id == id }
+    end
+
+    # Check if any BotBrowser profile is configured
+    def using_botbrowser?
+      bot_profiles.any?
+    end
+
+    def logger
+      @logger ||= create_multi_logger
+    end
+
+    # Environment variable keys to skip when loading browsers
+    RESERVED_BROWSER_ENV_KEYS = %w[BROWSER_PATH BROWSER_HEADLESS BROWSER_TIMEOUT].freeze
+
+    private
+
+    # Load browser configurations from environment variables
+    # Format: BROWSER_<ID>=type:path:name:description
+    # Example: BROWSER_CHROME=chrome:/usr/bin/google-chrome:Google Chrome:Standard Chrome browser
+    # Example: BROWSER_BOTBROWSER=botbrowser:/opt/botbrowser/chrome:BotBrowser:Anti-detection browser
+    def load_browsers
+      browsers = []
+      browsers.concat(load_custom_browsers)
+      browsers << load_legacy_browser if legacy_browser_configured?
+      browsers << create_system_browser if browsers.empty?
+      browsers
+    end
+
+    def load_custom_browsers
+      ENV.each_with_object([]) do |(key, value), browsers|
+        next unless key.start_with?('BROWSER_')
+        next if RESERVED_BROWSER_ENV_KEYS.include?(key)
+
+        browsers << parse_browser_config(key, value)
+      end
+    end
+
+    def parse_browser_config(key, value)
+      id = key.sub('BROWSER_', '').downcase
+      type, path, name, description = value.split(':', 4)
+
+      BrowserConfig.new(
+        id: id,
+        name: name || id.capitalize,
+        path: path.empty? ? nil : path,
+        type: type || 'chrome',
+        description: description
+      )
+    end
+
+    def legacy_browser_configured?
+      ENV['BROWSER_PATH'] || ENV.fetch('BOTBROWSER_PATH', nil)
+    end
+
+    def load_legacy_browser
+      legacy_path = ENV.fetch('BROWSER_PATH', nil) || ENV.fetch('BOTBROWSER_PATH', nil)
+      legacy_type = ENV['BOTBROWSER_PATH'] ? 'botbrowser' : 'chrome'
+
+      BrowserConfig.new(
+        id: 'default',
+        name: 'Default Browser',
+        path: legacy_path,
+        type: legacy_type,
+        description: 'Legacy browser configuration'
+      )
+    end
+
+    def create_system_browser
+      BrowserConfig.new(
+        id: 'system',
+        name: 'System Chrome',
+        path: nil,
+        type: 'chrome',
+        description: 'Auto-detected system Chrome/Chromium'
+      )
+    end
+
+    # Load user profile configurations from environment variables
+    # Format: USER_PROFILE_<ID>=path:name:description
+    # Example: USER_PROFILE_DEV=/home/user/.chrome-dev:Development:Dev profile with extensions
+    def load_user_profiles
+      profiles = []
+
+      ENV.each do |key, value|
+        next unless key.start_with?('USER_PROFILE_')
+
+        id = key.sub('USER_PROFILE_', '').downcase
+        path, name, description = value.split(':', 3)
+
+        next if path.nil? || path.empty?
+
+        profiles << UserProfileConfig.new(
+          id: id,
+          name: name || id.capitalize,
+          path: path,
+          description: description
+        )
+      end
+
+      profiles
+    end
+
+    # Load BotBrowser profile configurations from environment variables
+    # Format: BOT_PROFILE_<ID>=path:name:description
+    # Example: BOT_PROFILE_US=/profiles/us_chrome.enc:US Chrome:US-based Chrome profile
+    def load_bot_profiles
+      profiles = []
+
+      ENV.each do |key, value|
+        next unless key.start_with?('BOT_PROFILE_')
+
+        id = key.sub('BOT_PROFILE_', '').downcase
+        path, name, description = value.split(':', 3)
+
+        next if path.nil? || path.empty?
+
+        profiles << BotProfileConfig.new(
+          id: id,
+          name: name || id.capitalize,
+          path: path,
+          encrypted: path.end_with?('.enc'),
+          description: description
+        )
+      end
+
+      # Add legacy BOTBROWSER_PROFILE for backward compatibility
+      if ENV['BOTBROWSER_PROFILE'] && !ENV['BOTBROWSER_PROFILE'].empty?
+        legacy_path = ENV['BOTBROWSER_PROFILE']
+
+        profiles << BotProfileConfig.new(
+          id: 'default',
+          name: 'Default BotBrowser Profile',
+          path: legacy_path,
+          encrypted: legacy_path.end_with?('.enc'),
+          description: 'Legacy BotBrowser profile'
+        )
+      end
+
+      profiles
+    end
+
+    def create_multi_logger
+      # Create log directory relative to the project root
+      # Use __FILE__ to get the gem's location, then go up to project root
+      project_root = File.expand_path('../..', __dir__)
+      log_dir = File.join(project_root, 'logs')
+      FileUtils.mkdir_p(log_dir) unless File.directory?(log_dir)
+
+      log_file = File.join(log_dir, 'ferrum_mcp.log')
+
+      # Only write to file, no console output
+      Logger.new(log_file, level: log_level)
+    end
+  end
+end