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 文件。