内容
# chrome-hook MCP
本地 [MCP](https://modelcontextprotocol.io) 服务器，用于驱动真正的Chromium浏览器（Chrome / Brave），用于**多账户测试**和**完整网络捕获**，具有严格的机器人保护的真实浏览器附加路径。
查看 [CHANGELOG.md](./CHANGELOG.md) 以获取最近的行为更改（可选代理，无旧身份验证种子，公共文档卫生）。
构建于 **patchright**（一个即插即用的 Playwright，具有 CDP 层反检测补丁），在没有 patchright 的情况下回退到原始 Playwright。
**跨平台**（macOS / Windows / Linux）。Chrome 和 Brave 二进制文件从标准安装位置和 `PATH` **自动检测**，无需硬编码路径。隐身 UA 源自已安装浏览器的版本和主机操作系统。
> **仅限本地使用。** 所有操作都在您的机器上运行。捕获的流量、cookie、身份验证状态和浏览器配置文件写入本地磁盘，**从不上传**到任何地方。请勿提交运行时目录（参见 `.gitignore`）。
---
## 功能
- **命名浏览器槽位**（`a`，`b`，…）可以并行运行，因此您可以同时测试两个账户**而无需退出登录**（服务器通常会在退出登录时撤销令牌 - 而是使用两个槽位）。
- **项目范围**的身份验证/配置文件（`project=` 在每个站点上隔离 cookie，因此账户不会跨项目混淆）。
- **完整捕获** 默认：每个 HTTP(S) 请求/响应 + WebSocket 帧，流式传输到 `network.jsonl`，保存正文和可导出的 HAR。
- **严格的机器人保护**：patchright 驱动程序 + 真实浏览器 *附加* 模式（计划 A），可以解决冷启动的自动化浏览器永远无法解决的管理挑战。
- **可选代理**：默认关闭；需要时设置 `CHROME_HOOK_PROXY` 或 `proxy=`。
---
## 安装
```bash
pip install -r requirements.txt
# patchright 附带其自己的 patched 驱动程序；使用 channel="chrome"/"brave"（真实二进制文件）意味着您不需要单独的 `patchright install chromium` 下载。
```
需要安装真正的 Google Chrome 和/或 Brave。它们的二进制文件在 macOS、Windows 和 Linux 上自动定位（标准安装目录 + `PATH`）。
### 在您的 MCP 主机上注册（例如 Grok CLI）
```toml
[mcp_servers.chrome-hook]
command = "python3"
# 优先使用已安装的运行时路径（Grok 加载此路径）；与存储库保持同步。
args = ["/ABS/PATH/TO/chrome-hook-mcp/server.py"] # 或 ~/.grok/tools/chrome-hook-mcp/server.py
enabled = true
startup_timeout_sec = 45
tool_timeout_sec = 180
# 代理是可选的（默认关闭）。取消注释需要 Burp/Clash 时：
# env = { CHROME_HOOK_PROXY = "http://127.0.0.1:8080" }
```
编辑 `server.py` 后，如果需要，请复制到安装路径，然后 **重启 MCP 主机**。
代理工作流程位于配套技能 **`chrome-hook-browser`**（本存储库中的 `SKILL.md` 和 `~/.grok/skills/chrome-hook-browser/`）。
---
## 使用方法
### 1. 正常启动（大多数网站）
```text
browser_launch(project="acme", slot="a", headless=false,
start_url="https://example.com/")
browser_launch(project="acme", slot="b", headless=false,
start_url="https://example.com/") # 第二个账户，无需退出登录
# ... 首次在每个窗口登录 ...
browser_persist(slot="a"); browser_persist(slot="b") # 保存身份验证
# 稍后运行自动恢复 — 在令牌有效时无需重新登录
browser_request(..., slot="a")
```
自动应用反机器人强化：patchright 驱动程序；UA 自动匹配到已安装的 Chrome 主版本号；`locale`/`timezone_id` 在 patchright 下保持本地（强制例如在亚洲机器上强制 `en-US` 本身就是一个 Cloudflare 不匹配标志）；仅在 stock-Playwright 回退时注入 JS 隐身初始化脚本。
### 2. 计划 A — 附加到真实、温暖的浏览器（严格的机器人保护）
某些网站会向 **冷/全新启动** 的自动化浏览器提供 **无法解决** 的托管挑战 - 即使在 patchright 下，即使您手动勾选复选框。
可靠的解决方案是附加到一个真实的、已经预热的浏览器，您在其中通过了挑战。
```text
# 步骤 1 — 使用远程调试端口和专用配置文件启动您自己的真实浏览器
browser_open_real(project="demo", slot="a",
url="https://example.com/",
port=9222, browser="brave") # 浏览器： "chrome" | "brave"
# -> 在打开的窗口中手动解决挑战
# 步骤 2 — MCP 通过 CDP 连接并捕获温暖的会话
browser_attach(project="demo", slot="a", port=9222)
```
为什么这样有效，以及需要注意的细节：
- **Brave**（`browser="brave"`）通常可以清除严格的挑战，而冷启动的 Chrome 配置文件无法清除，由于其内置的反指纹功能。专用配置文件位于 `real-chrome/<project>/<slot>[-brave]/`，并且 **跨运行重复使用**，因此一旦您通过挑战，清算 cookie 就会持续存在，您很少需要再次解决它。
- 它使用一个 **独立的配置文件**，与您的日常浏览器（正在运行的浏览器锁定其自己的配置文件，无法在其上公开 CDP）分开。您的正常浏览器不会被触及。
- CDP 附加的 **预先存在的标签页不会发出 Playwright 网络事件**，因此附加会打开 **同一个上下文中的新捕获页面** - 它继承上下文 cookie（包括清算令牌），加载挑战后没有新提示，并落在标签页的 URL 上。在该页面上进行捕获。
- `browser_close` 在附加的槽位上 **仅断开连接** - 它永远不会关闭您的真实浏览器或其原始标签页，并且永远不会用过时的身份验证覆盖其 cookie。
`browser_launch(cdp_url="http://127.0.0.1:9222", …)` 是 `browser_attach` 的低级等价物。
---
## 工具（27）
**会话/槽位**
`browser_set_project` · `browser_sessions` · `browser_focus` · `browser_launch` ·
`browser_status` · `browser_close`
**计划 A（真实浏览器）**
`browser_open_real` — 使用调试端口生成真实 Chrome/Brave ·
`browser_attach` — 通过 CDP 连接并捕获温暖的会话
**身份验证持久性**
`browser_persist` · `browser_restore` · `browser_storage_save` ·
`browser_storage_load` · `browser_cookies_get` · `browser_cookies_set`
**页面操作**
`browser_navigate` · `browser_snapshot` · `browser_click` · `browser_type` ·
`browser_press` · `browser_wait` · `browser_screenshot` · `browser_eval`
**网络捕获/重放**
`browser_network_dump` — `hits` 键下的事件（`count` = 总数） ·
`browser_network_set_filter` · `browser_network_set_mode` (`all` | `api`) ·
`browser_export_har` · `browser_request` — 在上下文中发出请求
---
## 代理（可选）
| 项目 | 值 |
|------|--------|
| 默认值 | **无代理**（直接） |
| 环境变量 | `CHROME_HOOK_PROXY`（可选，例如 `http://127.0.0.1:8080` Burp） |
| 按调用 | `browser_launch(proxy=…)` / `browser_open_real(proxy=…)` |
| 强制关闭 | `proxy="none"` 或 `CHROME_HOOK_PROXY=none` |
| MITM | 设置代理时，自动忽略证书错误 |
| 附加 | **不**更改真实浏览器的代理 - 在 `open_real` 时设置 |
## 磁盘布局
```text
chrome-hook-mcp/
server.py # MCP 服务器（27 个工具）
SKILL.md # 配套代理技能（chrome-hook-browser）
requirements.txt
README.md
# --- 运行状态存储在 ~/.grok/tools/chrome-hook-mcp/（git-ignored） ---
profiles/<project>/<slot>/ # Chromium 用户数据用于正常启动
auth/<project>/<slot>.json # 存储状态自动保存/恢复
real-chrome/<project>/<slot>[-brave]/ # 计划 A 专用预热配置文件
sessions/<project>_<slot>_…/ # 每次运行的 network.jsonl + HAR + 正文
```
默认值：`auto_restore=true`，`auto_save=true`（在关闭时保存），
`capture_mode="all"`， 正文上限 512 KB HTTP / 64 KB WS，**无代理** 除非设置 `CHROME_HOOK_PROXY` 或按调用设置 `proxy=`。
---
## 注释和限制
- **编辑 `server.py` 后重启 MCP 主机** - 运行中的进程保留旧代码，不会公开新工具。
- 仅限浏览器上下文（非其他 OS 进程）。一个 Playwright 驱动程序线程；多个 Chromium/Brave 进程可以正常运行。
- 通过一次性 `python3 -c` 进行临时测试会遇到 Playwright 的线程亲和力（`greenlet: Cannot switch to a different thread`）和 `EPIPE` 在重复 `connect_over_cdp`；长期运行的 MCP 进程可以正常运行。要在脚本中探测内部，请在驱动程序线程上运行您的函数，方法是 `server._PW.submit(fn)`。
- **安全：** 永远不要上传捕获的数据、cookie、身份验证状态或配置文件。保持运行时目录本地且不受版本控制约束。
