# cloakbrowser-mcp

把 [CloakBrowser](https://github.com/CloakHQ/CloakBrowser)（在原始碼層改過、繞過 bot 偵測的隱形 Chromium）包成 [MCP](https://modelcontextprotocol.io) server，讓 Claude Code（或任何 MCP client）直接拿來做網頁檢索。

底層是真正修改過二進位的 Chromium，連 headless 模式都能通過 [sannysoft](https://bot.sannysoft.com) 的 WebDriver 進階偵測，比 JS 注入式的 stealth 方案穩。

## 工具

| 工具 | 用途 |
|------|------|
| `cloak_get_text` | 開網址回傳渲染後的可見純文字（餵 LLM 分析）；可給 `selector` 只取某元素 |
| `cloak_get_html` | 回傳渲染後 HTML 原始碼（結構化解析 / 抽連結） |
| `cloak_screenshot` | 整頁或單一元素截圖存 PNG |
| `cloak_interact` | 單一 session 內依序執行 click/fill/scroll/wait… 再擷取 |

每個工具都吃共用反偵測參數：

| 參數 | 預設 | 說明 |
|------|------|------|
| `humanize` | `false` | 模擬人類滑鼠曲線 / 鍵盤時序 |
| `proxy` | `null` | 代理 URL，例如 `http://user:pass@host:port`（硬站用住宅代理） |
| `geoip` | `false` | 依代理 IP 自動對齊時區 / 語系 |
| `headless` | `true` | 有些站會偵測 headless，硬站設 `false` |
| `timezone` / `locale` | `null` | 手動指定 IANA 時區 / BCP 47 語系 |

要繞 Cloudflare / reCAPTCHA / FingerprintJS 時建議組合：住宅 `proxy` + `geoip=true` + `humanize=true`，再不行加 `headless=false`。

每次呼叫都是「開瀏覽器 → 做事 → 關閉」的無狀態模式；需要跨步驟（登入、填表、翻頁）請用一次 `cloak_interact` 把動作串起來。

## 需求

- Python ≥ 3.10（建議 3.12）
- macOS arm64/x64、Linux x86_64/arm64、Windows x86_64
- 首次執行會自動下載隱形 Chromium 二進位（~200MB，快取在 `~/.cloakbrowser/`）

## 安裝

```bash
git clone https://github.com/Oliver0804/cloakbrowser-mcp.git
cd cloakbrowser-mcp

python3.12 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -c "import cloakbrowser as cb; cb.ensure_binary()"  # 預先下載 Chromium
```

## 註冊到 Claude Code

```bash
claude mcp add --scope user cloakbrowser "$(pwd)/.venv/bin/cloakbrowser-mcp"
```

確認連線：

```bash
claude mcp list | grep cloakbrowser   # 應顯示 ✔ Connected
```

註冊後重開一次 Claude Code session，`mcp__cloakbrowser__*` 四個工具就會出現。

## 在 Claude Code 內使用

直接用自然語言叫工具即可，例如：

```
用 cloak_get_text 幫我抓 https://news.ycombinator.com 的標題
把 https://example.com 用 cloak_screenshot 截整頁存到 /tmp/shot.png
這個站有 Cloudflare，請帶 proxy 跟 humanize 再抓
```

## cloak_interact action 格式

`actions` 是動作清單，第一個通常是 `goto`：

```jsonc
[
  {"type": "goto", "url": "https://example.com", "wait_until": "domcontentloaded"},
  {"type": "fill", "selector": "#email", "value": "a@b.com"},
  {"type": "type", "selector": "#q", "value": "hello", "delay": 40},
  {"type": "press", "selector": "#q", "keys": "Enter"},
  {"type": "click", "selector": "button#go"},
  {"type": "select", "selector": "#country", "value": "TW"},
  {"type": "scroll", "dy": 1500},
  {"type": "wait_selector", "selector": ".results", "timeout_ms": 15000},
  {"type": "wait_ms", "ms": 1500}
]
```

- `extract`：`text` | `html` | `none`（最終回傳形式）
- `selector`：`extract=text` 時只取此元素文字
- `screenshot_path`：給定則動作跑完後再截一張整頁圖

## 其他 MCP client

任何支援 stdio 的 MCP client 都能用，把指令指到 entrypoint：

```json
{
  "mcpServers": {
    "cloakbrowser": {
      "command": "/abs/path/cloakbrowser-mcp/.venv/bin/cloakbrowser-mcp"
    }
  }
}
```

## 授權

- 本倉庫包裝程式碼：MIT
- CloakBrowser 二進位：免費使用但**禁止重新發佈**（見上游 [BINARY-LICENSE.md](https://github.com/CloakHQ/CloakBrowser)）。本倉庫不含二進位，安裝時由 `cloakbrowser` 套件自動下載。