Crucible

🚀 Crucible

Crucible 是一個基於 Ruby 的 MCP（模型上下文協議）服務器，它藉助 Ferrum 和無頭 Chrome 瀏覽器實現自動化操作。該項目提供了 29 種工具，可供 AI 代理控制瀏覽器，並且內置了隱身模式，能夠有效躲避機器人檢測。

🚀 快速開始

運行服務器

# 使用默認配置運行（無頭模式，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"]
    }
  }
}

✨ 主要特性

• 提供 29 種工具，方便 AI 代理控制瀏覽器。
• 內置隱身模式，可有效躲避機器人檢測。
• 支持多會話管理，可同時處理多個獨立的瀏覽器實例。

📦 安裝指南

使用 gem 安裝

gem install crucible

從源碼安裝

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

💻 使用示例

基礎導航

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)

📚 詳細文檔

工具列表

導航工具

交互工具

提取工具

Cookie 工具

會話工具

下載工具

隱身工具

會話管理

所有工具都接受一個可選的 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)

會話在首次使用時自動創建，並在顯式關閉之前一直存在。

隱身模式

隱身模式應用了各種規避技術，使無頭 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      # Cookie 工具
│           ├── 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 文件。