ferrum-mcp 1.0.0

data/lib/ferrum_mcp/transport/stdio_server.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module FerrumMCP
+  module Transport
+    # STDIO Server with MCP StdioTransport
+    class StdioServer
+      attr_reader :server, :config, :logger, :mcp_transport
+
+      def initialize(server, config)
+        @server = server
+        @config = config
+        @logger = config.logger
+        @mcp_transport = MCP::Server::Transports::StdioTransport.new(server.mcp_server)
+        server.mcp_server.transport = @mcp_transport
+      end
+
+      def start # rubocop:disable Metrics/AbcSize
+        logger.info 'Starting STDIO server'
+        logger.info 'Reading from STDIN and writing to STDOUT'
+
+        # Open the transport for stdio communication
+        @mcp_transport.open
+
+        # Read from stdin and process messages
+        loop do
+          line = $stdin.gets
+          break if line.nil? # EOF
+
+          begin
+            request = JSON.parse(line.strip)
+            response = @mcp_transport.handle_json_request(request)
+            $stdout.puts(response.to_json)
+            $stdout.flush
+          rescue JSON::ParserError => e
+            logger.error "Invalid JSON: #{e.message}"
+            error_response = {
+              jsonrpc: '2.0',
+              error: { code: -32_700, message: 'Parse error' },
+              id: nil
+            }
+            $stdout.puts(error_response.to_json)
+            $stdout.flush
+          rescue StandardError => e
+            logger.error "Request error: #{e.message}"
+            logger.error e.backtrace.join("\n")
+          end
+        end
+      rescue StandardError => e
+        logger.error "STDIO server error: #{e.message}"
+        logger.error e.backtrace.join("\n")
+        raise
+      end
+
+      def stop
+        logger.info 'Stopping STDIO server...'
+        @mcp_transport&.close
+        logger.info 'STDIO server stopped'
+      end
+    end
+  end
+end

data/lib/ferrum_mcp/version.rb

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

data/lib/ferrum_mcp/whisper_service.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+require 'open3'
+require 'fileutils'
+require 'net/http'
+require 'uri'
+require 'shellwords'
+
+module FerrumMCP
+  # Service to handle Whisper speech recognition for CAPTCHA solving
+  # Uses whisper-cli (whisper.cpp) for fast, efficient transcription
+  class WhisperService
+    attr_reader :whisper_path, :model, :language, :logger
+
+    # Model URLs for whisper.cpp
+    MODEL_URLS = {
+      'tiny' => 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.bin',
+      'base' => 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin',
+      'small' => 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin',
+      'medium' => 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin'
+    }.freeze
+
+    def initialize(model: nil, language: nil, logger: nil)
+      @whisper_path = ENV.fetch('WHISPER_PATH', 'whisper-cli')
+      @model = model || ENV.fetch('WHISPER_MODEL', 'base')
+      @language = language || ENV.fetch('WHISPER_LANGUAGE', 'en')
+      @logger = logger || Logger.new($stdout)
+
+      verify_whisper_available!
+      ensure_model_available!
+    end
+
+    # Transcribe audio file to text
+    # @param audio_path [String] Path to audio file
+    # @return [String] Transcribed and cleaned text
+    def transcribe(audio_path)
+      logger.debug "Transcribing audio: #{audio_path}"
+
+      cmd = build_whisper_command(audio_path)
+      logger.debug "Command: #{cmd.join(' ')}"
+
+      stdout, stderr, status = Open3.capture3(*cmd)
+
+      unless status.success?
+        logger.error "Whisper failed: #{stderr}"
+        raise ToolError, "Whisper transcription failed: #{stderr}"
+      end
+
+      logger.debug "Whisper stdout: #{stdout}"
+
+      # Extract transcription from output or file
+      transcription = extract_transcription_from_output(stdout) || read_transcription_file(audio_path)
+      clean_transcription(transcription)
+    ensure
+      # Cleanup .txt file created by whisper-cli
+      txt_file = "#{audio_path}.txt"
+      FileUtils.rm_f(txt_file)
+    end
+
+    # Download audio from URL using browser context
+    # @param browser [Ferrum::Browser] Browser instance
+    # @param url [String] Audio URL
+    # @return [Tempfile] Temporary audio file
+    def download_audio(_browser, url)
+      temp_file = Tempfile.new(['captcha_audio', '.mp3'])
+      temp_file.binmode
+
+      logger.info "Downloading audio from: #{url[0..80]}..."
+
+      # Use curl to download (simpler and more reliable)
+      _, stderr, status = Open3.capture3("curl -s -L -o #{temp_file.path} #{url.shellescape}")
+
+      unless status.success?
+        logger.error "curl failed: #{stderr}"
+        raise ToolError, "Failed to download audio with curl: #{stderr}"
+      end
+
+      # Verify file was downloaded
+      unless File.exist?(temp_file.path) && File.size(temp_file.path).positive?
+        raise ToolError, 'Audio file is empty or not downloaded'
+      end
+
+      logger.info "Downloaded: #{File.size(temp_file.path)} bytes"
+      temp_file
+    rescue StandardError => e
+      temp_file&.close
+      temp_file&.unlink
+      raise ToolError, "Failed to download audio: #{e.message}"
+    end
+
+    # Check if Whisper is available
+    # @return [Boolean]
+    def available?
+      verify_whisper_available!
+      true
+    rescue StandardError
+      false
+    end
+
+    private
+
+    def verify_whisper_available!
+      _, stderr, status = Open3.capture3("#{whisper_path} --help 2>&1")
+
+      unless status.success?
+        raise ToolError,
+              "Whisper not found at '#{whisper_path}'. " \
+              "Install with: brew install whisper-cpp\n" \
+              "Or on Linux: follow instructions at https://github.com/ggerganov/whisper.cpp\n" \
+              "Or set WHISPER_PATH environment variable.\n" \
+              "Error: #{stderr}"
+      end
+
+      logger.info "Whisper CLI available at: #{whisper_path}"
+    end
+
+    def ensure_model_available!
+      model_path = get_model_path
+
+      # Check if model already exists
+      if File.exist?(model_path)
+        logger.debug "Model already available: #{model_path}"
+        return
+      end
+
+      # Download model
+      logger.info "Model '#{model}' not found, downloading..."
+      download_model(model_path)
+    end
+
+    def get_model_path # rubocop:disable Naming/AccessorMethodName
+      models_dir = File.expand_path('~/.whisper.cpp/models')
+      FileUtils.mkdir_p(models_dir)
+      File.join(models_dir, "ggml-#{model}.bin")
+    end
+
+    def download_model(model_path) # rubocop:disable Metrics/AbcSize
+      url = MODEL_URLS[model]
+
+      raise ToolError, "Unknown model: #{model}. Available: #{MODEL_URLS.keys.join(', ')}" unless url
+
+      logger.info "Downloading model from: #{url}"
+      logger.info 'This may take a few minutes...'
+
+      # Download with progress
+      uri = URI(url)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+        request = Net::HTTP::Get.new(uri)
+
+        http.request(request) do |response|
+          raise ToolError, "Failed to download model: HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+          total_size = response['content-length'].to_i
+          downloaded = 0
+
+          File.open(model_path, 'wb') do |file|
+            response.read_body do |chunk|
+              file.write(chunk)
+              downloaded += chunk.size
+
+              # Log progress every 10MB
+              if (downloaded % (10 * 1024 * 1024)).zero? || downloaded == total_size
+                progress = (downloaded * 100.0 / total_size).round(1)
+                mb_downloaded = downloaded / 1024 / 1024
+                mb_total = total_size / 1024 / 1024
+                logger.info "Download progress: #{progress}% (#{mb_downloaded}MB / #{mb_total}MB)"
+              end
+            end
+          end
+        end
+      end
+
+      logger.info "Model downloaded successfully: #{model_path}"
+    rescue StandardError => e
+      FileUtils.rm_f(model_path)
+      raise ToolError, "Failed to download model: #{e.message}"
+    end
+
+    def build_whisper_command(audio_path)
+      model_path = get_model_path
+
+      [
+        whisper_path,
+        '--model', model_path,
+        '--language', language,
+        '--output-txt',
+        '--file', audio_path
+      ]
+    end
+
+    def extract_transcription_from_output(output)
+      # whisper-cli outputs the transcription in the stdout
+      # Format: [00:00:00.000 --> 00:00:05.000]  transcription text here
+      lines = output.lines.grep(/\]\s+\w/)
+      return nil if lines.empty?
+
+      # Extract text after the timestamp
+      transcription = lines.map do |line|
+        line.sub(/\[.*?\]\s*/, '').strip
+      end.join(' ')
+
+      transcription.empty? ? nil : transcription
+    end
+
+    def read_transcription_file(audio_path)
+      # whisper-cli creates audio_path.txt in the same directory
+      txt_file = "#{audio_path}.txt"
+
+      raise ToolError, "Whisper output file not found: #{txt_file}" unless File.exist?(txt_file)
+
+      File.read(txt_file).strip
+    end
+
+    def clean_transcription(text)
+      text.strip
+          .gsub(/\s+/, ' ')           # normalize whitespace
+          .gsub(/[^\w\s]/, '')        # remove punctuation
+          .downcase                   # lowercase for consistency
+    end
+  end
+end

data/lib/ferrum_mcp.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require 'ferrum'
+require 'logger'
+require 'json'
+require 'zeitwerk'
+
+# Setup Zeitwerk loader
+loader = Zeitwerk::Loader.for_gem
+
+# Custom inflector for acronyms
+loader.inflector.inflect(
+  'ferrum_mcp' => 'FerrumMCP',
+  'mcp' => 'MCP',
+  'cli' => 'CLI',
+  'get_html_tool' => 'GetHTMLTool',
+  'get_url_tool' => 'GetURLTool',
+  'evaluate_js_tool' => 'EvaluateJSTool',
+  'http_server' => 'HTTPServer',
+  'query_shadow_dom_tool' => 'QueryShadowDOMTool'
+)
+
+loader.setup
+
+# Main module for Ferrum MCP Server
+module FerrumMCP
+  class Error < StandardError; end
+  class BrowserError < Error; end
+  class ToolError < Error; end
+end
+
+# Eager load in production, lazy load in development
+# Note: bin/ferrum-mcp loads this file first to avoid circular dependencies
+loader.eager_load unless ENV['RACK_ENV'] == 'development'

metadata

@@ -0,0 +1,248 @@
+--- !ruby/object:Gem::Specification
+name: ferrum-mcp
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Eth3rnit3
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-12-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: ferrum
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.17.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.17.1
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.16'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: ruby-vips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: |
+  FerrumMCP is a browser automation server that implements the Model Context Protocol (MCP),
+  enabling AI assistants to interact with web pages through a standardized interface.
+  Features include navigation, form interaction, content extraction, screenshot capture,
+  JavaScript execution, cookie management, and advanced capabilities like smart cookie banner
+  detection and AI-powered CAPTCHA solving.
+email:
+- eth3rnit3@gmail.com
+executables:
+- ferrum-mcp
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env.example"
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- SECURITY.md
+- bin/ferrum-mcp
+- bin/lint
+- bin/serve
+- bin/test
+- docs/API_REFERENCE.md
+- docs/CONFIGURATION.md
+- docs/DEPLOYMENT.md
+- docs/DOCKER.md
+- docs/DOCKER_BOTBROWSER.md
+- docs/GETTING_STARTED.md
+- docs/TROUBLESHOOTING.md
+- lib/ferrum_mcp.rb
+- lib/ferrum_mcp/browser_manager.rb
+- lib/ferrum_mcp/cli/command_handler.rb
+- lib/ferrum_mcp/cli/server_runner.rb
+- lib/ferrum_mcp/configuration.rb
+- lib/ferrum_mcp/resource_manager.rb
+- lib/ferrum_mcp/server.rb
+- lib/ferrum_mcp/session.rb
+- lib/ferrum_mcp/session_manager.rb
+- lib/ferrum_mcp/tools/accept_cookies_tool.rb
+- lib/ferrum_mcp/tools/base_tool.rb
+- lib/ferrum_mcp/tools/clear_cookies_tool.rb
+- lib/ferrum_mcp/tools/click_tool.rb
+- lib/ferrum_mcp/tools/close_session_tool.rb
+- lib/ferrum_mcp/tools/create_session_tool.rb
+- lib/ferrum_mcp/tools/drag_and_drop_tool.rb
+- lib/ferrum_mcp/tools/evaluate_js_tool.rb
+- lib/ferrum_mcp/tools/execute_script_tool.rb
+- lib/ferrum_mcp/tools/fill_form_tool.rb
+- lib/ferrum_mcp/tools/find_by_text_tool.rb
+- lib/ferrum_mcp/tools/get_attribute_tool.rb
+- lib/ferrum_mcp/tools/get_cookies_tool.rb
+- lib/ferrum_mcp/tools/get_html_tool.rb
+- lib/ferrum_mcp/tools/get_session_info_tool.rb
+- lib/ferrum_mcp/tools/get_text_tool.rb
+- lib/ferrum_mcp/tools/get_title_tool.rb
+- lib/ferrum_mcp/tools/get_url_tool.rb
+- lib/ferrum_mcp/tools/go_back_tool.rb
+- lib/ferrum_mcp/tools/go_forward_tool.rb
+- lib/ferrum_mcp/tools/hover_tool.rb
+- lib/ferrum_mcp/tools/list_sessions_tool.rb
+- lib/ferrum_mcp/tools/navigate_tool.rb
+- lib/ferrum_mcp/tools/press_key_tool.rb
+- lib/ferrum_mcp/tools/query_shadow_dom_tool.rb
+- lib/ferrum_mcp/tools/refresh_tool.rb
+- lib/ferrum_mcp/tools/screenshot_tool.rb
+- lib/ferrum_mcp/tools/session_tool.rb
+- lib/ferrum_mcp/tools/set_cookie_tool.rb
+- lib/ferrum_mcp/tools/solve_captcha_tool.rb
+- lib/ferrum_mcp/transport/http_server.rb
+- lib/ferrum_mcp/transport/rate_limiter.rb
+- lib/ferrum_mcp/transport/stdio_server.rb
+- lib/ferrum_mcp/version.rb
+- lib/ferrum_mcp/whisper_service.rb
+homepage: https://github.com/Eth3rnit3/FerrumMCP
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Eth3rnit3/FerrumMCP
+  source_code_uri: https://github.com/Eth3rnit3/FerrumMCP
+  changelog_uri: https://github.com/Eth3rnit3/FerrumMCP/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Eth3rnit3/FerrumMCP/issues
+  documentation_uri: https://github.com/Eth3rnit3/FerrumMCP/tree/main/docs
+  rubygems_mfa_required: 'true'
+post_install_message: "\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nThank
+  you for installing FerrumMCP 1.0.0!\n\n\U0001F4DA Documentation: https://github.com/Eth3rnit3/FerrumMCP/tree/main/docs\n\U0001F680
+  Quick Start:   https://github.com/Eth3rnit3/FerrumMCP/blob/main/docs/GETTING_STARTED.md\n\U0001F41B
+  Issues:        https://github.com/Eth3rnit3/FerrumMCP/issues\n\nTo start the server:\n\n
+  \ ferrum-mcp start [OPTIONS]\n\nFor help:\n\n  ferrum-mcp --help\n\n⚠️  Requirements:\n
+  \ - Chrome/Chromium browser must be installed\n  - Optional: whisper-cli for CAPTCHA
+  solving\n  - Optional: BotBrowser for anti-detection\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n"
+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: 3.5.22
+signing_key:
+specification_version: 4
+summary: Browser automation server implementing the Model Context Protocol
+test_files: []