ferrum-mcp 1.0.0

data/lib/ferrum_mcp/resource_manager.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  # Manages MCP resources for browser configurations, profiles, and capabilities
+  class ResourceManager
+    attr_reader :config, :logger
+
+    def initialize(config)
+      @config = config
+      @logger = config.logger
+    end
+
+    # Get all available resources
+    def resources
+      @resources ||= build_resources
+    end
+
+    # Read a specific resource by URI
+    def read_resource(uri)
+      case uri
+      when 'ferrum://browsers'
+        read_browsers_resource
+      when 'ferrum://user-profiles'
+        read_user_profiles_resource
+      when 'ferrum://bot-profiles'
+        read_bot_profiles_resource
+      when 'ferrum://capabilities'
+        read_capabilities_resource
+      when %r{^ferrum://browsers/(.+)$}
+        read_browser_detail(::Regexp.last_match(1))
+      when %r{^ferrum://user-profiles/(.+)$}
+        read_user_profile_detail(::Regexp.last_match(1))
+      when %r{^ferrum://bot-profiles/(.+)$}
+        read_bot_profile_detail(::Regexp.last_match(1))
+      else
+        logger.error "Unknown resource URI: #{uri}"
+        nil
+      end
+    end
+
+    private
+
+    def build_resources
+      resources = []
+      resources.concat(build_browser_resources)
+      resources.concat(build_user_profile_resources)
+      resources.concat(build_bot_profile_resources)
+      resources << build_capabilities_resource
+      resources
+    end
+
+    def build_browser_resources
+      resources = [create_resource('ferrum://browsers', 'available-browsers',
+                                   'List of all available browser configurations')]
+
+      config.browsers.each do |browser|
+        resources << create_resource("ferrum://browsers/#{browser.id}", "browser-#{browser.id}",
+                                     "Configuration for #{browser.name}")
+      end
+
+      resources
+    end
+
+    def build_user_profile_resources
+      resources = [create_resource('ferrum://user-profiles', 'user-profiles',
+                                   'List of all available Chrome user profiles')]
+
+      config.user_profiles.each do |profile|
+        resources << create_resource("ferrum://user-profiles/#{profile.id}", "user-profile-#{profile.id}",
+                                     "Details for user profile: #{profile.name}")
+      end
+
+      resources
+    end
+
+    def build_bot_profile_resources
+      resources = [create_resource('ferrum://bot-profiles', 'bot-profiles',
+                                   'List of all available BotBrowser profiles')]
+
+      config.bot_profiles.each do |profile|
+        resources << create_resource("ferrum://bot-profiles/#{profile.id}", "bot-profile-#{profile.id}",
+                                     "Details for BotBrowser profile: #{profile.name}")
+      end
+
+      resources
+    end
+
+    def build_capabilities_resource
+      create_resource('ferrum://capabilities', 'server-capabilities',
+                      'Server capabilities and feature flags')
+    end
+
+    def create_resource(uri, name, description)
+      MCP::Resource.new(
+        uri: uri,
+        name: name,
+        description: description,
+        mime_type: 'application/json'
+      )
+    end
+
+    def read_browsers_resource
+      {
+        uri: 'ferrum://browsers',
+        mimeType: 'application/json',
+        text: JSON.pretty_generate({
+                                     browsers: config.browsers.map(&:to_h),
+                                     default: config.default_browser&.id,
+                                     total: config.browsers.count
+                                   })
+      }
+    end
+
+    def read_browser_detail(browser_id)
+      browser = config.find_browser(browser_id)
+      return nil unless browser
+
+      {
+        uri: "ferrum://browsers/#{browser_id}",
+        mimeType: 'application/json',
+        text: JSON.pretty_generate(browser.to_h.merge(
+                                     is_default: browser == config.default_browser,
+                                     exists: browser.path.nil? || File.exist?(browser.path),
+                                     usage: {
+                                       session_param: 'browser_id',
+                                       example: "create_session(browser_id: '#{browser.id}')"
+                                     }
+                                   ))
+      }
+    end
+
+    def read_user_profiles_resource
+      {
+        uri: 'ferrum://user-profiles',
+        mimeType: 'application/json',
+        text: JSON.pretty_generate({
+                                     profiles: config.user_profiles.map(&:to_h),
+                                     total: config.user_profiles.count,
+                                     note: 'User profiles are standard Chrome user data directories'
+                                   })
+      }
+    end
+
+    def read_user_profile_detail(profile_id)
+      profile = config.find_user_profile(profile_id)
+      return nil unless profile
+
+      {
+        uri: "ferrum://user-profiles/#{profile_id}",
+        mimeType: 'application/json',
+        text: JSON.pretty_generate(profile.to_h.merge(
+                                     exists: File.directory?(profile.path),
+                                     usage: {
+                                       session_param: 'user_profile_id',
+                                       example: "create_session(user_profile_id: '#{profile.id}')"
+                                     }
+                                   ))
+      }
+    end
+
+    def read_bot_profiles_resource
+      {
+        uri: 'ferrum://bot-profiles',
+        mimeType: 'application/json',
+        text: JSON.pretty_generate({
+                                     profiles: config.bot_profiles.map(&:to_h),
+                                     total: config.bot_profiles.count,
+                                     note: 'BotBrowser profiles contain anti-detection fingerprints',
+                                     using_botbrowser: config.using_botbrowser?
+                                   })
+      }
+    end
+
+    def read_bot_profile_detail(profile_id)
+      profile = config.find_bot_profile(profile_id)
+      return nil unless profile
+
+      {
+        uri: "ferrum://bot-profiles/#{profile_id}",
+        mimeType: 'application/json',
+        text: JSON.pretty_generate(profile.to_h.merge(
+                                     exists: File.exist?(profile.path),
+                                     usage: {
+                                       session_param: 'bot_profile_id',
+                                       example: "create_session(bot_profile_id: '#{profile.id}')"
+                                     },
+                                     features: %w[
+                                       canvas_fingerprinting
+                                       webgl_protection
+                                       audio_context_hardening
+                                       webrtc_leak_prevention
+                                     ]
+                                   ))
+      }
+    end
+
+    def read_capabilities_resource
+      {
+        uri: 'ferrum://capabilities',
+        mimeType: 'application/json',
+        text: JSON.pretty_generate({
+                                     version: FerrumMCP::VERSION,
+                                     features: {
+                                       multi_browser: config.browsers.count > 1,
+                                       user_profiles: config.user_profiles.any?,
+                                       bot_profiles: config.bot_profiles.any?,
+                                       botbrowser_integration: config.using_botbrowser?,
+                                       session_management: true,
+                                       screenshot: true,
+                                       javascript_execution: true,
+                                       cookie_management: true,
+                                       form_interaction: true,
+                                       captcha_solving: true
+                                     },
+                                     transport: config.transport,
+                                     browsers_count: config.browsers.count,
+                                     user_profiles_count: config.user_profiles.count,
+                                     bot_profiles_count: config.bot_profiles.count
+                                   })
+      }
+    end
+  end
+end

data/lib/ferrum_mcp/server.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module FerrumMCP
+  # Main MCP Server implementation
+  class Server
+    attr_reader :mcp_server, :session_manager, :resource_manager, :config, :logger
+
+    TOOL_CLASSES = [
+      # Session Management
+      Tools::CreateSessionTool,
+      Tools::ListSessionsTool,
+      Tools::CloseSessionTool,
+      Tools::GetSessionInfoTool,
+      # Navigation
+      Tools::NavigateTool,
+      Tools::GoBackTool,
+      Tools::GoForwardTool,
+      Tools::RefreshTool,
+      # Interaction
+      Tools::ClickTool,
+      Tools::FillFormTool,
+      Tools::PressKeyTool,
+      Tools::HoverTool,
+      Tools::DragAndDropTool,
+      Tools::AcceptCookiesTool,
+      Tools::SolveCaptchaTool,
+      # Extraction
+      Tools::GetTextTool,
+      Tools::GetHTMLTool,
+      Tools::ScreenshotTool,
+      Tools::GetTitleTool,
+      Tools::GetURLTool,
+      Tools::FindByTextTool,
+      # Advanced
+      Tools::ExecuteScriptTool,
+      Tools::EvaluateJSTool,
+      Tools::GetCookiesTool,
+      Tools::SetCookieTool,
+      Tools::ClearCookiesTool,
+      Tools::GetAttributeTool,
+      Tools::QueryShadowDOMTool
+    ].freeze
+
+    def initialize(config = Configuration.new)
+      @config = config
+      @logger = config.logger
+      @session_manager = SessionManager.new(config)
+      @resource_manager = ResourceManager.new(config)
+      @tool_instances = {}
+      @mcp_server = create_mcp_server
+
+      setup_tools
+      setup_resources
+      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...'
+      session_manager.shutdown
+      logger.info 'Server shutdown complete'
+    end
+
+    def handle_request(json_request)
+      request = JSON.parse(json_request)
+      logger.debug "Received request: #{request['method']}"
+
+      mcp_server.handle_request(request)
+    rescue JSON::ParserError => e
+      logger.error "Invalid JSON request: #{e.message}"
+      error_response('Invalid JSON request')
+    rescue StandardError => e
+      logger.error "Request handling error: #{e.message}"
+      logger.error e.backtrace.join("\n")
+      error_response(e.message)
+    end
+
+    private
+
+    def create_mcp_server
+      MCP::Server.new(
+        name: 'ferrum-browser',
+        version: FerrumMCP::VERSION,
+        instructions: 'A browser automation server using Ferrum and BotBrowser for web scraping and testing',
+        resources: resource_manager.resources
+      )
+    end
+
+    def setup_tools
+      # Capture references to instance variables for use in the block
+      server_instance = self
+
+      TOOL_CLASSES.each do |tool_class|
+        mcp_server.define_tool(
+          name: tool_class.tool_name,
+          description: tool_class.description,
+          input_schema: tool_class.input_schema
+        ) do |**params|
+          # Call execute_tool on the server instance
+          server_instance.send(:execute_tool, tool_class, params)
+        end
+      end
+
+      logger.info "Registered #{TOOL_CLASSES.length} tools"
+    end
+
+    def setup_resources
+      # Capture references to instance variables for use in the block
+      manager = resource_manager
+
+      # Define the resources_read handler
+      mcp_server.resources_read_handler do |params|
+        uri = params[:uri]
+        logger.debug "Reading resource: #{uri}"
+
+        result = manager.read_resource(uri)
+        if result
+          [result]
+        else
+          logger.error "Resource not found: #{uri}"
+          []
+        end
+      end
+
+      logger.info "Registered #{resource_manager.resources.length} resources"
+    end
+
+    def execute_tool(tool_class, params)
+      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
+
+        logger.debug "Using session_id: #{session_id}"
+
+        # 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
+      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)
+      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)
+    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.instrumentation_callback = lambda { |data|
+          logger.debug "MCP Method: #{data[:method]}, Duration: #{data[:duration]}s"
+        }
+      end
+    end
+
+    def error_response(message)
+      {
+        jsonrpc: '2.0',
+        error: {
+          code: -32_603,
+          message: message
+        },
+        id: nil
+      }
+    end
+
+    # Helper to create error response for tool execution
+    def error_tool_response(message)
+      MCP::Tool::Response.new([{ type: 'text', text: message }], error: true)
+    end
+  end
+end

data/lib/ferrum_mcp/session.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module FerrumMCP
+  # Represents a browser session with its own BrowserManager and configuration
+  class Session
+    attr_reader :id, :browser_manager, :config, :session_config, :created_at, :last_used_at, :metadata, :options
+
+    def initialize(config:, options: {})
+      @id = SecureRandom.uuid
+      @config = config
+      @options = normalize_options(options)
+      @created_at = Time.now
+      @last_used_at = Time.now
+      @metadata = options[:metadata] || {}
+      @mutex = Mutex.new
+      @session_config, @browser_manager = create_browser_manager
+    end
+
+    # Execute a block with thread-safe access to the browser
+    def with_browser
+      @mutex.synchronize do
+        @last_used_at = Time.now
+        yield @browser_manager
+      end
+    end
+
+    # Check if session is active (browser is running)
+    def active?
+      @browser_manager.active?
+    end
+
+    # Start the browser for this session
+    def start
+      @mutex.synchronize do
+        @browser_manager.start unless @browser_manager.active?
+        @last_used_at = Time.now
+      end
+    end
+
+    # Stop the browser for this session
+    def stop
+      @mutex.synchronize do
+        @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
+    end
+
+    # Get session information
+    def info
+      {
+        id: @id,
+        active: active?,
+        created_at: @created_at.iso8601,
+        last_used_at: @last_used_at.iso8601,
+        idle_seconds: (Time.now - @last_used_at).to_i,
+        metadata: @metadata,
+        browser_type: browser_type,
+        options: sanitized_options
+      }
+    end
+
+    # Get browser type (public method for logging and info)
+    def browser_type
+      if @session_config.bot_profile
+        "BotBrowser (#{@session_config.bot_profile.name})"
+      elsif @session_config.browser
+        # Check ID first (for system browser), then type
+        if @session_config.browser.id == 'system'
+          'System Chrome/Chromium'
+        elsif @session_config.browser.type == 'botbrowser'
+          "BotBrowser (#{@session_config.browser.name})"
+        else
+          @session_config.browser.name
+        end
+      else
+        'System Chrome/Chromium'
+      end
+    end
+
+    private
+
+    def normalize_options(options)
+      {
+        browser_id: options[:browser_id] || options['browser_id'],
+        browser_path: options[:browser_path] || options['browser_path'],
+        user_profile_id: options[:user_profile_id] || options['user_profile_id'],
+        bot_profile_id: options[:bot_profile_id] || options['bot_profile_id'],
+        botbrowser_profile: options[:botbrowser_profile] || options['botbrowser_profile'],
+        headless: options.fetch(:headless, options.fetch('headless', @config.headless)),
+        timeout: options.fetch(:timeout, options.fetch('timeout', @config.timeout)),
+        browser_options: options[:browser_options] || options['browser_options'] || {},
+        metadata: options[:metadata] || options['metadata'] || {}
+      }
+    end
+
+    def create_browser_manager
+      # Create a custom configuration for this session
+      session_config = SessionConfiguration.new(
+        base_config: @config,
+        overrides: @options
+      )
+      [session_config, BrowserManager.new(session_config)]
+    end
+
+    # Return sanitized options (without sensitive data)
+    def sanitized_options
+      @options.except(:metadata)
+    end
+  end
+
+  # Session-specific configuration that overrides base configuration
+  class SessionConfiguration
+    attr_reader :browser, :user_profile, :bot_profile, :headless, :timeout,
+                :server_host, :server_port, :log_level, :transport,
+                :browser_options
+
+    def initialize(base_config:, overrides:)
+      @base_config = base_config
+      @headless = overrides[:headless]
+      @timeout = overrides[:timeout]
+      @browser_options = overrides[:browser_options] || {}
+      @server_host = base_config.server_host
+      @server_port = base_config.server_port
+      @log_level = base_config.log_level
+      @transport = base_config.transport
+
+      # Resolve browser configuration
+      @browser = resolve_browser(overrides, base_config)
+      @user_profile = resolve_user_profile(overrides, base_config)
+      @bot_profile = resolve_bot_profile(overrides, base_config)
+    end
+
+    def valid?
+      browser&.path.nil? || File.exist?(browser.path)
+    end
+
+    def using_botbrowser?
+      browser&.type == 'botbrowser' || !bot_profile.nil?
+    end
+
+    # Legacy compatibility methods
+    def browser_path
+      browser&.path
+    end
+
+    def botbrowser_profile
+      bot_profile&.path
+    end
+
+    def logger
+      @base_config.logger
+    end
+
+    private
+
+    def resolve_browser(overrides, base_config)
+      # Priority: browser_id > browser_path (legacy) > default browser
+      if overrides[:browser_id]
+        base_config.find_browser(overrides[:browser_id])
+      elsif overrides[:browser_path]
+        # Legacy: create a temporary browser config
+        Configuration::BrowserConfig.new(
+          id: 'custom',
+          name: 'Custom Browser',
+          path: overrides[:browser_path],
+          type: overrides[:botbrowser_profile] ? 'botbrowser' : 'chrome',
+          description: 'Session-specific browser'
+        )
+      else
+        base_config.default_browser
+      end
+    end
+
+    def resolve_user_profile(overrides, base_config)
+      # Priority: user_profile_id > nil
+      return nil unless overrides[:user_profile_id]
+
+      base_config.find_user_profile(overrides[:user_profile_id])
+    end
+
+    def resolve_bot_profile(overrides, base_config)
+      # Priority: bot_profile_id > botbrowser_profile (legacy) > nil
+      if overrides[:bot_profile_id]
+        base_config.find_bot_profile(overrides[:bot_profile_id])
+      elsif overrides[:botbrowser_profile]
+        # Legacy: create a temporary bot profile config
+        Configuration::BotProfileConfig.new(
+          id: 'custom',
+          name: 'Custom Profile',
+          path: overrides[:botbrowser_profile],
+          encrypted: overrides[:botbrowser_profile].end_with?('.enc'),
+          description: 'Session-specific profile'
+        )
+      end
+    end
+
+    # Merge session-specific browser options with base options
+    def merged_browser_options
+      base_options = default_browser_options
+      base_options.merge(@browser_options)
+    end
+
+    def default_browser_options
+      options = {
+        'no-sandbox' => nil,
+        'disable-dev-shm-usage' => nil,
+        'disable-blink-features' => 'AutomationControlled',
+        'disable-gpu' => nil
+      }
+
+      options['disable-setuid-sandbox'] = nil if ENV['CI']
+
+      # Add BotBrowser profile if configured
+      if using_botbrowser? && botbrowser_profile && File.exist?(botbrowser_profile)
+        options['bot-profile'] = botbrowser_profile
+      end
+
+      options
+    end
+  end
+end