ferrum-mcp 1.0.0 → 1.1.0

data/lib/ferrum_mcp/cli/server_runner.rb

@@ -29,16 +29,22 @@ module FerrumMCP
         exit 1
       end
 
+      # Runs the server until STDIN closes (stdio) or a signal arrives (http).
+      # Shutdown always happens here, on the main thread, never inside a trap.
       def start
         validate!
         setup_servers
         setup_signal_handlers
         log_startup_info
         run
+      rescue SignalException
+        config.logger.info 'Signal received, shutting down'
       rescue StandardError => e
         config.logger.error "ERROR: #{e.message}"
         config.logger.error e.backtrace.join("\n")
         exit 1
+      ensure
+        shutdown
       end
 
       private
@@ -59,16 +65,23 @@ module FerrumMCP
         end
       end
 
+      # Trap handlers must not log or take locks (Ruby forbids Mutex use in
+      # trap context), so they only interrupt the main thread; #start does the
+      # actual shutdown.
       def setup_signal_handlers
-        trap('INT') { shutdown }
-        trap('TERM') { shutdown }
+        %w[INT TERM].each do |signal|
+          trap(signal) { raise Interrupt, signal }
+        end
       end
 
       def shutdown
+        return if @shutdown_done
+
+        @shutdown_done = true
         config.logger.info 'Shutting down...'
-        transport_server.stop
-        mcp_server.stop_browser
-        exit 0
+        transport_server&.stop
+        mcp_server&.shutdown
+        config.logger.info 'Shutdown complete'
       end
 
       def log_startup_info
@@ -158,7 +171,7 @@ module FerrumMCP
 
       def run
         transport_server.start
-        # Keep main thread alive for HTTP (stdio blocks automatically)
+        # Keep main thread alive for HTTP (stdio blocks until STDIN closes)
         sleep if @options[:transport] == 'http'
       end
     end

data/lib/ferrum_mcp/configuration.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require 'fileutils'
+require 'tmpdir'
+
 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
+    attr_accessor :headless, :timeout, :server_host, :server_port, :log_level, :log_file, :transport,
+                  :max_sessions, :rate_limit_enabled, :rate_limit_max_requests, :rate_limit_window,
+                  :api_key_enabled, :api_keys, :trust_proxy
+    attr_reader :browsers, :user_profiles, :bot_profiles, :url_policy, :upload_allowed_dirs
 
     # Browser configuration structure
     BrowserConfig = Struct.new(:id, :name, :path, :type, :description, keyword_init: true) do
@@ -34,19 +38,30 @@ module FerrumMCP
       @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
+      @log_level = ENV.fetch('LOG_LEVEL', 'info').to_sym
+      @log_file = ENV.fetch('LOG_FILE', nil)
       @transport = transport
       @max_sessions = ENV.fetch('MAX_CONCURRENT_SESSIONS', '10').to_i
 
+      # Only honour X-Forwarded-For when the server sits behind a trusted proxy
+      @trust_proxy = ENV.fetch('TRUST_PROXY', 'false') == 'true'
+
+      # Optional navigation restrictions (ALLOWED_HOSTS / BLOCKED_HOSTS)
+      @url_policy = UrlPolicy.from_env
+
+      # Directories the upload_file tool may read from (UPLOAD_ALLOWED_DIRS)
+      @upload_allowed_dirs = load_upload_allowed_dirs
+
       # 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
+      # API key authentication configuration
+      @api_key_enabled = ENV.fetch('API_KEY_ENABLED', 'false') == 'true'
+      @api_keys = load_api_keys
+
+      load_browser_configurations
     end
 
     def valid?
@@ -80,14 +95,48 @@ module FerrumMCP
     end
 
     def logger
-      @logger ||= create_multi_logger
+      @logger ||= create_logger
     end
 
     # Environment variable keys to skip when loading browsers
     RESERVED_BROWSER_ENV_KEYS = %w[BROWSER_PATH BROWSER_HEADLESS BROWSER_TIMEOUT].freeze
 
+    # Check if API key authentication is properly configured
+    def api_key_configured?
+      api_key_enabled && api_keys.any?
+    end
+
     private
 
+    def load_browser_configurations
+      @browsers = load_browsers
+      @user_profiles = load_user_profiles
+      @bot_profiles = load_bot_profiles
+    end
+
+    # Defaults to the current directory and the system temp dir
+    def load_upload_allowed_dirs
+      configured = ENV.fetch('UPLOAD_ALLOWED_DIRS', '').split(',').map(&:strip).reject(&:empty?)
+      dirs = configured.empty? ? [Dir.pwd, Dir.tmpdir] : configured
+      dirs.map { |d| File.expand_path(d) }
+    end
+
+    # Load API keys from environment variables
+    # Supports single key (API_KEY) or multiple keys (API_KEYS=key1,key2,key3)
+    def load_api_keys
+      keys = []
+
+      # Load single API key
+      single_key = ENV.fetch('API_KEY', nil)
+      keys << single_key if single_key && !single_key.empty?
+
+      # Load multiple API keys (comma-separated)
+      multiple_keys = ENV.fetch('API_KEYS', nil)
+      keys.concat(multiple_keys.split(',').map(&:strip).reject(&:empty?)) if multiple_keys && !multiple_keys.empty?
+
+      keys.uniq
+    end
+
     # 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
@@ -213,17 +262,27 @@ module FerrumMCP
       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)
+    # Logs never go to STDOUT: in stdio transport STDOUT carries the protocol.
+    # LOG_FILE=<path> writes to that file, LOG_FILE=stderr writes to STDERR,
+    # unset writes to ./logs/ferrum_mcp.log under the current directory (never
+    # inside the installed gem), falling back to the system temp dir.
+    def create_logger
+      Logger.new(log_device, level: log_level)
+    end
+
+    def log_device
+      target = log_file.to_s.strip
+      return $stderr if target.casecmp('stderr').zero?
+      return prepare_log_path(target) unless target.empty?
 
-      log_file = File.join(log_dir, 'ferrum_mcp.log')
+      prepare_log_path(File.join(Dir.pwd, 'logs', 'ferrum_mcp.log'))
+    rescue SystemCallError
+      File.join(Dir.tmpdir, 'ferrum_mcp.log')
+    end
 
-      # Only write to file, no console output
-      Logger.new(log_file, level: log_level)
+    def prepare_log_path(path)
+      FileUtils.mkdir_p(File.dirname(path))
+      path
     end
   end
 end

data/lib/ferrum_mcp/image_resizer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  # Optional libvips-backed resizing. ruby-vips raises LoadError when the
+  # native library is missing; screenshots are then returned at full size.
+  module ImageResizer
+    module_function
+
+    def available?
+      return @available unless @available.nil?
+
+      @available = begin
+        require 'vips'
+        true
+      rescue LoadError => e
+        warn_once("libvips not available (#{e.message}); large screenshots will not be resized")
+        false
+      end
+    end
+
+    # Scale the image down so both sides fit within max_dimension
+    def fit(image_data, max_dimension, format, logger: nil)
+      image = Vips::Image.new_from_buffer(image_data, '')
+      width = image.width
+      height = image.height
+      return image_data if width <= max_dimension && height <= max_dimension
+
+      scale = [max_dimension.to_f / width, max_dimension.to_f / height].min
+      new_width = (width * scale).to_i
+      new_height = (height * scale).to_i
+      logger&.info "Resizing screenshot from #{width}x#{height} to #{new_width}x#{new_height}"
+
+      image.thumbnail_image(new_width, height: new_height, size: :force).write_to_buffer(".#{format}")
+    end
+
+    def warn_once(message)
+      return if @warned
+
+      @warned = true
+      Kernel.warn "[ferrum-mcp] #{message}"
+    end
+  end
+end

data/lib/ferrum_mcp/server.rb

@@ -24,13 +24,27 @@ module FerrumMCP
       Tools::DragAndDropTool,
       Tools::AcceptCookiesTool,
       Tools::SolveCaptchaTool,
+      Tools::ScrollTool,
+      Tools::SelectOptionTool,
+      Tools::UploadFileTool,
       # Extraction
+      Tools::SnapshotTool,
       Tools::GetTextTool,
       Tools::GetHTMLTool,
       Tools::ScreenshotTool,
       Tools::GetTitleTool,
       Tools::GetURLTool,
       Tools::FindByTextTool,
+      # Waiting
+      Tools::WaitForSelectorTool,
+      Tools::WaitForTextTool,
+      Tools::WaitForNetworkIdleTool,
+      # Tabs & viewport
+      Tools::ListTabsTool,
+      Tools::NewTabTool,
+      Tools::SwitchTabTool,
+      Tools::CloseTabTool,
+      Tools::SetViewportTool,
       # Advanced
       Tools::ExecuteScriptTool,
       Tools::EvaluateJSTool,
@@ -46,7 +60,6 @@ module FerrumMCP
       @logger = config.logger
       @session_manager = SessionManager.new(config)
       @resource_manager = ResourceManager.new(config)
-      @tool_instances = {}
       @mcp_server = create_mcp_server
 
       setup_tools
@@ -54,20 +67,6 @@ module FerrumMCP
       setup_error_handling
     end
 
-    # Deprecated: For backward compatibility
-    # Sessions must be created explicitly using create_session tool
-    def start_browser
-      raise NotImplementedError, 'start_browser is deprecated. Use create_session tool to create a session.'
-    end
-
-    # Deprecated: For backward compatibility
-    def stop_browser
-      logger.warn 'stop_browser is deprecated, use session_manager.close_all_sessions'
-      session_manager.close_all_sessions
-      @tool_instances = {}
-      logger.info 'All sessions stopped'
-    end
-
     # Shutdown server and cleanup all sessions
     def shutdown
       logger.info 'Shutting down server...'
@@ -140,101 +139,69 @@ module FerrumMCP
     end
 
     def execute_tool(tool_class, params)
+      params = params.except(:server_context)
       logger.debug "Executing tool: #{tool_class.tool_name} with params: #{params.inspect}"
 
-      # Session management tools don't need a browser session
-      if session_management_tool?(tool_class)
-        logger.debug "Executing session management tool: #{tool_class.tool_name}"
-        tool = tool_class.new(session_manager)
-        result = tool.execute(params)
-      else
-        # Extract session_id from params (required)
-        session_id = params[:session_id] || params['session_id']
-
-        unless session_id
-          logger.error "session_id is required for #{tool_class.tool_name}"
-          return error_tool_response('session_id is required. Create a session first using create_session tool.')
-        end
+      result = if tool_class.requires_session?
+                 execute_browser_tool(tool_class, params)
+               else
+                 tool_class.new(session_manager).execute(params)
+               end
 
-        logger.debug "Using session_id: #{session_id}"
+      to_mcp_response(tool_class, result)
+    rescue StandardError => e
+      logger.error "Tool execution error (#{tool_class.tool_name}): #{e.class} - #{e.message}"
+      logger.error e.backtrace.first(10).join("\n")
+      error_tool_response("#{e.class}: #{e.message}")
+    end
 
-        # Execute tool within session context
-        result = session_manager.with_session(session_id) do |browser_manager|
-          logger.debug "Creating tool instance for #{tool_class.tool_name}"
-          tool = tool_class.new(browser_manager)
-          logger.debug "Calling execute on #{tool_class.tool_name}"
-          tool.execute(params)
-        end
+    def execute_browser_tool(tool_class, params)
+      session_id = params[:session_id] || params['session_id']
+      if session_id.nil? || session_id.to_s.empty?
+        logger.error "session_id is required for #{tool_class.tool_name}"
+        return { success: false, error: 'session_id is required. Create a session first using create_session tool.' }
       end
 
-      logger.debug "Tool #{tool_class.tool_name} result: #{result.inspect}"
-
-      # MCP expects a Tool::Response object
-      # Convert our tool result to MCP format
-      if result[:success]
-        logger.debug "Tool succeeded, creating MCP::Tool::Response with data: #{result[:data].inspect}"
-
-        # Check if this is an image response
-        if result[:type] == 'image'
-          logger.debug "Creating image response with mime_type: #{result[:mime_type]}"
-          # Return MCP Tool::Response with image content
-          MCP::Tool::Response.new([{
-                                    type: 'image',
-                                    data: result[:data],
-                                    mimeType: result[:mime_type]
-                                  }])
-        else
-          # Return a proper MCP Tool::Response with the data as text content
-          MCP::Tool::Response.new([{ type: 'text', text: result[:data].to_json }])
-        end
-      else
-        logger.error "Tool failed with error: #{result[:error]}"
-        # Return an error response
-        MCP::Tool::Response.new([{ type: 'text', text: result[:error] }], error: true)
+      session_manager.with_session(session_id) do |browser_manager|
+        tool_class.new(browser_manager).execute(params)
       end
-    rescue StandardError => e
-      logger.error "Tool execution error (#{tool_class.tool_name}): #{e.class} - #{e.message}"
-      logger.error 'Backtrace:'
-      logger.error e.backtrace.first(10).join("\n")
-      # Return an error response for unexpected exceptions
-      MCP::Tool::Response.new([{ type: 'text', text: "#{e.class}: #{e.message}" }], error: true)
     end
 
-    # Check if tool is a session management tool
-    def session_management_tool?(tool_class)
-      [
-        Tools::CreateSessionTool,
-        Tools::ListSessionsTool,
-        Tools::CloseSessionTool,
-        Tools::GetSessionInfoTool
-      ].include?(tool_class)
+    def to_mcp_response(tool_class, result)
+      unless result[:success]
+        logger.error "Tool #{tool_class.tool_name} failed: #{result[:error]}"
+        return error_tool_response(result[:error])
+      end
+
+      if result[:type] == 'image'
+        MCP::Tool::Response.new([{ type: 'image', data: result[:data], mimeType: result[:mime_type] }])
+      else
+        MCP::Tool::Response.new([{ type: 'text', text: result[:data].to_json }])
+      end
     end
 
     def setup_error_handling
       MCP.configure do |mcp_config|
-        mcp_config.exception_reporter = lambda { |exception, context|
-          logger.error '=' * 80
-          logger.error "MCP Exception: #{exception.class} - #{exception.message}"
-          logger.error "Context: #{context.inspect}"
-
-          # Log the original error if there is one
-          if exception.respond_to?(:original_error) && exception.original_error
-            logger.error "ORIGINAL ERROR: #{exception.original_error.class} - #{exception.original_error.message}"
-            logger.error 'ORIGINAL BACKTRACE:'
-            logger.error exception.original_error.backtrace.first(15).join("\n")
-          end
-
-          logger.error 'Exception backtrace:'
-          logger.error exception.backtrace.join("\n")
-          logger.error '=' * 80
-        }
-
+        mcp_config.exception_reporter = ->(exception, context) { report_exception(exception, context) }
         mcp_config.instrumentation_callback = lambda { |data|
           logger.debug "MCP Method: #{data[:method]}, Duration: #{data[:duration]}s"
         }
       end
     end
 
+    def report_exception(exception, context)
+      logger.error '=' * 80
+      logger.error "MCP Exception: #{exception.class} - #{exception.message}"
+      logger.error "Context: #{context.inspect}"
+      original = exception.respond_to?(:original_error) ? exception.original_error : nil
+      if original
+        logger.error "ORIGINAL ERROR: #{original.class} - #{original.message}"
+        logger.error original.backtrace.first(15).join("\n")
+      end
+      logger.error exception.backtrace.join("\n")
+      logger.error '=' * 80
+    end
+
     def error_response(message)
       {
         jsonrpc: '2.0',

data/lib/ferrum_mcp/session.rb

@@ -15,14 +15,23 @@ module FerrumMCP
       @last_used_at = Time.now
       @metadata = options[:metadata] || {}
       @mutex = Mutex.new
+      @closed = false
       @session_config, @browser_manager = create_browser_manager
     end
 
-    # Execute a block with thread-safe access to the browser
+    # Execute a block with thread-safe access to the browser.
+    # A dead browser detected during the block leaves the session inactive so
+    # the next call restarts it instead of failing forever.
     def with_browser
       @mutex.synchronize do
         @last_used_at = Time.now
-        yield @browser_manager
+        begin
+          yield @browser_manager
+        rescue Ferrum::DeadBrowserError
+          logger.warn "Browser for session #{@id} died during a tool call"
+          @browser_manager.stop
+          raise
+        end
       end
     end
 
@@ -31,21 +40,41 @@ module FerrumMCP
       @browser_manager.active?
     end
 
+    def closed?
+      @closed
+    end
+
     # Start the browser for this session
     def start
+      @mutex.synchronize { start_browser }
+    end
+
+    # Make sure a live browser is available, restarting it if its process died.
+    def ensure_started
       @mutex.synchronize do
-        @browser_manager.start unless @browser_manager.active?
-        @last_used_at = Time.now
+        if @browser_manager.active? && !@browser_manager.healthy?
+          logger.warn "Restarting dead browser for session #{@id}"
+          @browser_manager.stop
+        end
+        start_browser
       end
     end
 
-    # Stop the browser for this session
+    # Stop the browser for this session (the session can be started again)
     def stop
       @mutex.synchronize do
         @browser_manager.stop if @browser_manager.active?
       end
     end
 
+    # Close the session for good: stops the browser and refuses any restart
+    def close
+      @mutex.synchronize do
+        @closed = true
+        @browser_manager.stop if @browser_manager.active?
+      end
+    end
+
     # Check if session is idle (not used for a while)
     def idle?(timeout_seconds)
       Time.now - @last_used_at > timeout_seconds
@@ -56,6 +85,7 @@ module FerrumMCP
       {
         id: @id,
         active: active?,
+        closed: closed?,
         created_at: @created_at.iso8601,
         last_used_at: @last_used_at.iso8601,
         idle_seconds: (Time.now - @last_used_at).to_i,
@@ -85,6 +115,18 @@ module FerrumMCP
 
     private
 
+    def logger
+      @config.logger
+    end
+
+    # Caller must hold @mutex
+    def start_browser
+      raise SessionError, "Session #{@id} is closed" if @closed
+
+      @browser_manager.start unless @browser_manager.active?
+      @last_used_at = Time.now
+    end
+
     def normalize_options(options)
       {
         browser_id: options[:browser_id] || options['browser_id'],
@@ -157,6 +199,21 @@ module FerrumMCP
       @base_config.logger
     end
 
+    def url_policy
+      @base_config.url_policy
+    end
+
+    def upload_allowed_dirs
+      @base_config.upload_allowed_dirs
+    end
+
+    # Browser flags handed to Ferrum: defaults merged with session-specific
+    # options. Ferrum prefixes every key with "--" itself, so keys are stored
+    # without dashes ("window-size", not "--window-size").
+    def merged_browser_options
+      default_browser_options.merge(normalized_browser_options)
+    end
+
     private
 
     def resolve_browser(overrides, base_config)
@@ -200,10 +257,10 @@ module FerrumMCP
       end
     end
 
-    # Merge session-specific browser options with base options
-    def merged_browser_options
-      base_options = default_browser_options
-      base_options.merge(@browser_options)
+    def normalized_browser_options
+      @browser_options.to_h.transform_keys do |key|
+        key.to_s.sub(/\A-+/, '')
+      end
     end
 
     def default_browser_options
@@ -215,6 +272,7 @@ module FerrumMCP
       }
 
       options['disable-setuid-sandbox'] = nil if ENV['CI']
+      options['user-data-dir'] = user_profile.path if user_profile
 
       # Add BotBrowser profile if configured
       if using_botbrowser? && botbrowser_profile && File.exist?(botbrowser_profile)

data/lib/ferrum_mcp/session_manager.rb

@@ -62,17 +62,15 @@ module FerrumMCP
     # Close a specific session
     # @param session_id [String] Session ID
     # @return [Boolean] Success
-    def close_session(session_id)
-      @mutex.synchronize do
-        session = @sessions[session_id]
-        return false unless session
-
-        logger.info "Closing session #{session_id}"
-        session.stop
-        @sessions.delete(session_id)
-
-        true
-      end
+    def close_session(session_id) # rubocop:disable Naming/PredicateMethod
+      # Remove under the global lock, stop outside of it: stopping Chrome can
+      # take seconds and must not block every other session meanwhile.
+      session = @mutex.synchronize { @sessions.delete(session_id) }
+      return false unless session
+
+      logger.info "Closing session #{session_id}"
+      session.close
+      true
     end
 
     # List all active sessions
@@ -91,11 +89,13 @@ module FerrumMCP
 
     # Close all sessions
     def close_all_sessions
-      @mutex.synchronize do
+      sessions = @mutex.synchronize do
         logger.info "Closing all #{@sessions.size} sessions"
-        @sessions.each_value(&:stop)
+        removed = @sessions.values
         @sessions.clear
+        removed
       end
+      sessions.each(&:close)
     end
 
     # Execute a block with a session (thread-safe)
@@ -107,8 +107,8 @@ module FerrumMCP
       session = get_session(session_id)
       raise SessionError, "Session not found: #{session_id}" unless session
 
-      # Start browser if not active
-      session.start unless session.active?
+      # Start the browser if needed (or restart it if its process died)
+      session.ensure_started
 
       # Execute with thread-safe access
       session.with_browser(&)