Crucible

🚀 Crucible

Ferrum とヘッドレスChromeを使用した、ブラウザ自動化用のRuby MCP (Model Context Protocol) サーバーです。AIエージェントがブラウザを制御するために使用できる29のツールを提供し、ボット検出を回避するためのステルスモードが組み込まれています。

🚀 クイックスタート

📦 インストール

gem install crucible

またはソースからインストールする場合は、以下のコマンドを実行します。

git clone https://github.com/joshfng/crucible.git
cd crucible
bundle install

💻 使用例

基本的な使用法

サーバーの起動

# デフォルト設定で起動（ヘッドレスモード、1280x720のビューポート、30秒のタイムアウト）
crucible

# ブラウザを表示して起動
crucible --no-headless

# 全オプションを指定して起動
crucible \
  --no-headless \
  --width 1920 \
  --height 1080 \
  --timeout 60 \
  --chrome /usr/bin/chromium \
  --error-level debug

CLIオプション

Claude Codeとの統合

gem install crucible

Claude CodeのMCP設定ファイル (~/.claude/settings.json) に以下の内容を追加します。

{
  "mcpServers": {
    "crucible": {
      "command": "crucible",
      "args": ["--config", "~/.config/crucible/config.yml"]
    }
  }
}

高度な使用法

ツールの使用

ナビゲーション

インタラクション

抽出

クッキー

セッション

ダウンロード

ステルス

セッション管理

すべてのツールは、複数の独立したブラウザインスタンスを管理するためのオプションの session パラメータを受け取ります。

# 別々のブラウザで実行
navigate(session: "login-flow", url: "https://example.com/login")
navigate(session: "signup-flow", url: "https://example.com/signup")

# アクティブなセッションを一覧表示
list_sessions()
# => { "count": 2, "sessions": ["login-flow", "signup-flow"] }

# 特定のセッションを閉じる
close_session(session: "login-flow")

# すべてのセッションを閉じる
close_session(all: true)

セッションは初回使用時に自動的に作成され、明示的に閉じられるまで保持されます。

サンプルワークフロー

基本的なナビゲーション

navigate(url: "https://example.com")
wait_for(selector: ".content")
get_content(format: "text")

フォーム送信

navigate(url: "https://example.com/login")
type(selector: "#email", text: "user@example.com")
type(selector: "#password", text: "secret123")
click(selector: "button[type=submit]")
wait_for(selector: ".dashboard")

スクリーンショットとPDF

# ビューポートのスクリーンショット（base64で返す）
screenshot()

# 全ページのスクリーンショット
screenshot(full_page: true)

# 要素のスクリーンショット
screenshot(selector: ".hero-image")

# ファイルに保存
screenshot(path: "/tmp/page.png")
screenshot(format: "jpeg", quality: 90, path: "/tmp/page.jpg")

# PDF生成
pdf()                                    # base64で返す
pdf(path: "/tmp/page.pdf")               # ファイルに保存
pdf(format: "Letter", landscape: true)   # カスタム形式

JavaScript実行

# ページの寸法を取得
evaluate(expression: "[window.innerWidth, window.innerHeight]")

# ページの先頭にスクロール
evaluate(expression: "window.scrollTo(0, 0)")

# 要素の数を取得
evaluate(expression: "document.querySelectorAll('a').length")

ファイルダウンロード

# ダウンロードディレクトリを設定
set_download_path(path: "/tmp/downloads")

# ダウンロードリンクをクリックして待機
click(selector: "a.download-btn")
wait_for_download(timeout: 30)

# 追跡されているダウンロードを一覧表示（ナビゲーションをまたいで保持される）
list_downloads()

# 追跡をクリアしてファイルを削除
clear_downloads(delete_files: true)

ステルスモード

ステルスモードは、ボット検出システムに対してヘッドレスChromeを通常のブラウザとして見せるためのさまざまな回避技術を適用します。デフォルトでは "moderate" プロファイルで有効になっています。

ステルスプロファイル

適用される回避技術

ステルスモジュールには、puppeteer-extra から移植された回避技術が含まれています。

• navigator.webdriver - webdriverフラグを削除する
• chrome.app - chrome.appオブジェクトをモックする
• chrome.csi - chrome.csi関数をモックする
• chrome.loadTimes - chrome.loadTimesをモックする
• chrome.runtime - 拡張機能用のchrome.runtimeをモックする
• navigator.vendor - navigator.vendorを上書きする
• navigator.languages - Accept-Languageヘッダーに一致させる
• navigator.plugins - プラグインとmimeTypesをモックする
• navigator.permissions - Notification.permissionを修正する
• navigator.hardwareConcurrency - 現実的なコア数を設定する
• webgl.vendor - WebGLのベンダー/レンダラーを修正する
• media.codecs - 独自のコーデックのサポートを報告する
• iframe.contentWindow - iframeの検出を修正する
• window.outerdimensions - outerWidth/outerHeightを修正する
• ユーザーエージェントの上書き - "Headless" を削除し、プラットフォームを修正する

ランタイム制御

# ステルス状態を確認
get_stealth_status(session: "default")

# 最大保護でステルスモードを有効にする
enable_stealth(session: "default", profile: "maximum")

# ステルスモードを無効にする（既に適用された回避技術は残る）
disable_stealth(session: "default")

# プロファイルを変更する
set_stealth_profile(session: "default", profile: "minimal")

設定ファイル

~/.config/crucible/config.yml を作成します。

browser:
  headless: true
  window_size: [1280, 720]

stealth:
  enabled: true
  profile: moderate
  locale: "en-US,en"

server:
  log_level: info

📚 詳細ドキュメント

プロジェクト構造

crucible/
├── exe/crucible                # CLI実行ファイル
├── crucible.gemspec            # Gemの仕様
├── Gemfile                     # 依存関係
├── Rakefile                    # ビルドタスク
├── lib/
│   ├── crucible.rb             # メインモジュール
│   └── crucible/
│       ├── version.rb          # バージョン定数
│       ├── configuration.rb    # YAMLサポート付きの設定
│       ├── session_manager.rb  # マルチセッション管理
│       ├── server.rb           # MCPサーバーのセットアップ
│       ├── stealth.rb          # ステルスモードモジュール
│       ├── stealth/
│       │   ├── utils.js        # ステルスユーティリティ
│       │   └── evasions/       # 個別の回避スクリプト
│       └── tools/
│           ├── helpers.rb      # 共有ユーティリティ
│           ├── navigation.rb   # ナビゲーションツール
│           ├── interaction.rb  # インタラクションツール
│           ├── extraction.rb   # 抽出ツール
│           ├── cookies.rb      # クッキーツール
│           ├── sessions.rb     # セッションツール
│           ├── downloads.rb    # ダウンロードツール
│           └── stealth.rb      # ステルス制御ツール
└── spec/                       # RSpecテスト

開発

# テストを実行
bundle exec rspec

# リンターを実行
bundle exec rubocop

# 対話型コンソールを起動
bundle exec rake console

# 開発用にサーバーを起動
bundle exec rake server

リリース

bin/release 0.2.0

このスクリプトは、バージョンを更新し、コミット、タグ付け、プッシュ、GitHubリリースを作成し、GemをビルドしてRubyGemsにプッシュします（ブラウザを介してMFAを処理します）。

要件

• Ruby >= 3.2.0
• ChromeまたはChromiumブラウザ
• 依存関係:
  • ferrum ~> 0.17.1
  • mcp ~> 0.4.0

📄 ライセンス

MITライセンスです。詳細は LICENSE を参照してください。