内容
# browser-bridge
让任何 **MCP 客户端** — Claude Code、Claude Desktop、Codex 或任何支持模型上下文协议的客户端 — 控制您的真实 Chrome 浏览器：您的标签页、已登录的会话、Cookie，通过 Chrome 扩展程序和本地消息传递主机。无需第二个浏览器，无需 CDP 调试端口，无需 `--remote-de` 标志。
由于它操作的是您已经浏览器，因此代理可以执行全新无头浏览器无法执行的操作：读取您授权后的页面，点击您已登录的应用程序，提取您的框架存储在 `localStorage` 中的令牌。这种能力也带来了风险 — 在安装前请参阅下面的 **安全** 部分。
## 🔒 安全第一 - 请阅读
browser-bridge 控制的是 **真实、已认证的 Chrome 浏览器**。它可以读取页面内容、Cookie（包括 `httpOnly`）和 Web 存储，并且可以在您的页面上运行 JavaScript。确保安全的防护措施：
- **批准每个网站。** 新的源触发弹出窗口提示；除非您已批准某个网站（这也授予主机权限，内容脚本需要），否则不会在该网站上运行任何内容。
- **确认高风险操作。** 提交按钮点击、链接导航、标签页关闭和 **每个 `page_eval`** 都会弹出页面确认提示，您必须批准（具有短暂的同源宽限期）。
- **只读凭证。** Cookie 和存储可以 **读取**（始终掩盖 — JWT、长十六进制、长数字序列），但绝不会写入。按照设计，没有 `cookie_set` / `storage_set`。
- **认证桥。** localhost TCP 套接字通过 `0600` 锁定文件中的每次运行密钥对每个连接进行身份验证；原生主机清单固定了扩展程序 ID。
详细资料： **[SECURITY.md](./SECURITY.md)** · [威胁模型](./docs/security/threat-model.md) · [信任边界](./docs/security/trust-boundaries.md) · [每个工具的风险矩阵](./docs/security/tool-risk-matrix.md)。
## 快速入门（约 60 秒）
**前提条件：** Google Chrome（或 Linux 上的 Chromium）。下面的 **预编译** 路径不需要 Rust 和 Node.js。
### 1. 获取二进制文件 + 扩展程序
从 **[最新版本](https://github.com/whg517/browser-bridge/releases/latest)** 下载适用于您平台的存档，然后运行捆绑的安装程序。`install.sh` 自动检测预编译的 tarball 并直接安装已附带的二进制文件 + 扩展程序。
<details open>
<summary><b>macOS (Apple Silicon) / Linux x64</b></summary>
```sh
tar xzf browser-bridge-*-macos-arm64.tar.gz # 或 -linux-x64
cd browser-bridge-*-macos-arm64
./install.sh
```
将二进制文件安装到 `~/.browser-bridge/`（mac或 `~/./browser-bridge/`（并写入具有固定扩展 的原生消息传递，该 ID 已被信任 **macOS Gatekeeper 预编译的二进制文件 notarization，因此浏览器下载的存档可能会被隔离无法验证”）。在清除一次 — 在提取的文件夹中运行 `xdr com.apple.quarant` — 然后重新运行.sh`。
</details>
<summary><b x64</b></summary>
```powershell
Expand browser-bridge-*-windows-x64.zip -DestinationPath .
cd browser-bridge-*-windows-x64
powershell - Bypass -File .\install.ps1
```
将 `bridge.exe` 安装到 `%LOCALAPPDATA%\bridge\` 并在您的用户 Chrome 原生消息传递键下注册主机。权限。
> **：** 预编译的 exe 未签名，因此 SmartScreen 可能会在第一次运行时发出警告 — 选择 **更多信息 → 仍然运行**。
</details>
<details>
<summary><b>从源代码构建（需要 Rust + Node.js/npm）</b></summary>
```sh
git clone https://github.com/whg517/browser-bridge && cd browser-bridge
./install/install.sh # Linux: --browser chrome|chromium|both
```
`install/install.sh` 构建 Rust 二进制文件和扩展程序包，然后安装两者。有关完整的构建/测试循环，请参阅 [docs/development.md](./docs/development.md)。
</details>
> 只需要扩展程序（已安装二进制文件）？从同一个版本中获取 `browser-bridge-extension-<tag>.zip` 并解压它 — 它包含可以直接加载的顶级 `dist/`。
### 2. 加载扩展程序
`chrome://extensions` → 启用 **开发者模式** → **加载解压的** → 选择 **`extension/dist/`** 目录（构建输出，*不是* `extension/`）。
扩展程序 ID 被 **固定** 为 `mkjjlmjbcljpcfkfadfmhblmmddkdihf`（通过清单 `key`），安装程序已经信任它 — **无需复制，无需修补。**
### 3. 注册 MCP 服务器
将您的客户端指向已安装的二进制文件（运行不带参数 — 它通过 stdio 使用 MCP）。使用 **绝对路径**；大多数客户端不扩展 `~`。
- **Claude Code (CLI):**
```sh
claude mcp add browser-bridge -- "$HOME/.browser-bridge/browser-bridge"
```
- **Claude Desktop / generic (`mcpServers` JSON):** 从 [`mcp-config.example.json`](./install/mcp-config.example.json) 复制 `browser-bridge` 条目。
- **Codex (`~/.codex/config.toml`):**
```toml
[mcp_servers.browser-bridge]
command = "/absolute/path/to/browser-bridge"
args = []
```
### 4. 重新启动 Chrome 并尝试
重新启动 Chrome 以加载原生主机清单，然后重新连接您的 MCP 客户端并询问：**“列出我的浏览器标签页。”** 首次针对新网站时，点击 Browser Bridge 工具栏图标并批准它 在 **WSL**您的日常浏览器是，请在 Windows 上安装并通过 `/mnt/c`SL 客户端指向 `.exe` — 不要安装 Linux 主机。如果 Chrome 在 WSLg 下运行，请在 Linux 中原生安装。有关详细信息，请参阅 [WSL 指南](./docs/wsl.md)。
## 您能做的 — 15 种工具
分组来自单一真实来源，[`contracts/tools.json`](./contracts/tools.json)：
### 标签页
| 工具 | 功能 | 风险 |
|------|------|------|
| `tab_list` | 列出打开的标签页（id、标题、网址、活动） | 低 |
| `tab_focus` | 将标签页带到前景 | 低 |
| `tab_open`新标签页中打开网址（主机必须在允许列表中） | 中 |
| `tab_close` | 关闭标签页（页面确认） | 高 |
### 检查页面
| 工具 | 功能 | 风险 |
|------|------|------|
| `page_snapshot` | 交互元素的无障碍样式树，每个元素都有稳定的 `ref` | 低 `page_snapshot_precise` | 通过 `chrome` 的权威无障碍树（shadow DOM / 复杂 ARIA）；引用使用 `p` 前缀 | 中 |
| `page_text` | 可见页面文本（密码和类似卡片的数字被掩盖） | 中 |
| `page_screenshot` | 可见视口的 PNG 图片 | 中 |
### 操作页面
| 工具 | 风险 |
|------|------|------|
| `page_click` | 按` 或 `selector` 点击；提交/链接点击需要确认 | 高 |
| `page_fill` | 输入到字段（原生设置，因此 React/Vue 检测到它） | 高 |
| `page_scroll` | 向上/向下/顶部/底部/ N 像素 | 低 |
| `page_wait_for` | 等待选择器、文本或导航 | 低 |
### 运行代码（风险最高）
| 工具 | 功能 | 风险 |
|------|------|------|
| `page_eval` | ⚠ 执行任意 JS。**每次调用** 都在确认提示中显示完整代码情况下返回值被掩盖。优先使用上面的工具。 | 关键 |
### 读取凭证（只读，始终掩盖）
| 工具 | 功能 | 风险 |
|------|------|------|
| `cookie_get` | 读取活动标签页的 Cookie，包括 `httpOnly`；仅限允许列表主机 | 高 |
| `storage_get` | 读取页面的 `localStorage` / `sessionStorage`（同源） | 高 |
*按照设计，无写入工具 — Cookie/存储写入超出范围 ([ADR-0010](./docs/adr/0010-cookie-storage-readonly.md))。
## 工作原理
一个 Rust 二进制文件，两种模式，通过 localhost 套接字连接：
```
MCP 客户端 ──stdio MCP──▶ browser-bridgeCP 服务器，Rust）
（Claude Code │
Codex，…） │ localhost TCP（NDJSON，每次运行密钥认证）
▼
-bridge --native-host ◀── 由 Chrome 启动
│
│ chrome.runtime.connectNative
扩展（MV3─▶ 您的```
- **M（默认模式） 由您的 MCP stdio 启动。支持 JSON-RPC 2.0（MCP 协议 `2025-06-18`）。拥有会话状态和 TCP 套接字，通过锁定文件发布。
- **`--native-host`** — 由 Chrome 通过主机清单启动。 一个薄桥，将 Chrome 的原生消息帧（4 字节小端长度 + JSON）转换为套接字上的 NDJSON。
为什么使用两个进程？原生主机；MCP 客户端启动服务器 — 它们不是父/子进程，因此需要进程间通信。原生主机保持简单，以便 MV3 服务工作线程回收（约每 5 分钟）和主机重启不会丢失会话状态。
深入了解：[docs/architecture.md](./docs/architecture.md) · [ADR-0002](./docs/adr/0002-three-process-architecture-localhost-tcp.md).
## 兼容性
| | 支持 |
|---|---|
| **macOS** | Apple Silicon (arm 预编译。Intel 通过 Rosetta 2 或从编译。 |
|** | x64 预编译；Google Chrome 或 Chromium。 |
| **Windows** | x64 预编译（原生，无需管理员权限）。 |
| **浏览器** | Chrome / Chromium，Manifest V3 |
| **MCP 协议** | `2025-06-18` ([ADR-0007](./docs/adr/0007-mcp-protocol-version-2025-06-18.md)) |
| **内部桥协议** | `1`（参见 [contracts/protocol-version.json/protocol-version.json)) |
预编译目标来自标签 [发布工作流github/workflows/release.yml参见 [docs/](./docs/compatibility.md).
## 配置
启动时读取环境变量（源自/log.rs`, [docs/cli.md](./docs/cli.md)）：
| 变量 | 值 | 默认值 | 效果 |
|-----|--------|---------|--------|
| `BB_LOG` | `error` \| `warn` \|` \| `debug `info` | 标准 / 审计。`warn`/`error` 沉默审计 |
| `BB` | `text `json` |` | 审计行格式；`json` 为机器收集发出一个对象。 |
## 故障排除
首先运行内置的只读自检：
```sh
browser-bridge doctor # 或：browser-bridge status
```
它报告服务器是否可达、锁定文件端口/pid 和常见的错误配置。然后检查您的 MCP 客户端的服务器 UI（通过 Claude Code 中的 `/mcp` 重新连接）和扩展的 Service Worker 控制台，网址为 `chrome://extensions`（查找 `[bb]` 日志）。完整的运行手册：[docs/cli.md](./docs/cli.md) · [docs/operations.md](./docs/operations.md).
## 文档地图
| 文档 | 内容 |
|-----|--------------|
| [docs/requirements.md](./docs/requirements.md) | 目标、用户故事、功能/非功能需求、范围边界 |
| [docs/architecture.md](./docs/architecture.md) | 组件、数据流、协议、安全模型、关键约束 |
| [docs/security/](./docs/security/) | 威胁模型、信任边界、工具风险矩阵、事件响应 |
| [docs/cli.md](./docs/cli.md) | `doctor`/`status` 自检、故障排除 |
| [docs/operations.md](./docs/operations.md) | 两种二进制模式、日志/审计、锁定文件、重新连接 |
| [docs/compatibility.md](./docs/compatibility.md) | 版本纪律和能力/协议握手 |
| [docs/release.md](./docs/release.md) | 标签驱动发布、预编译 tarball + 校验和、SBOM |
| [docs/wsl.md](./docs/wsl.md) | Windows Chrome 互操作性和 WSLg 两种模式 |
| [docs/adr/](./docs/adr/) | 架构决策记录 (ADR) — 每个“为什么这么选择” |
| [contracts/](./contracts/README.md) | 工具目录、错误代码、能力、协议版本（跨进程合约源） |
<details>
<summary>测试和项目布局</summary>
两个语言的独立套件一起运行，`./tests/run_all.sh`：
- **协议层** — `tests/e2e.py` 驱动真正的二进制文件（MCP 通过 stdio、`--native-host` 分帧，TCP 桥上的模拟扩展）。
- **DOM 层** — `tests/dom_test.ts` 通过 CDP 将真正的 内容脚本注入无头 Chrome，并针对真实 DOM 练习每个操作。
- **冒烟测试** — `tests/ext_test.ts` 使用 `extension/dist/` 启动真实 Chrome。
- **真实集成**（按需）— `tests/integration_e2e.ts`；使用 `BB_REAL_E2E=1` 运行。需要 Chrome for Testing / Chromium。
参见 [tests/README.md](./tests/README.md)。大致源布局：`src/`（Rust：`main.rs` 模式调度，`protocol.rs`, `ipc.rs`, `native_host.rsmcp_server.rs`, `tools/`, `session.rs`），`extension/src/`（TypeScript → `dist/` 通过 esbuild），`contracts/`（跨进程合约），`docs/`。
</details>
## 项目状态
**v0.1.0** ([Cargo.toml](./Cargo.toml)) 加上第二/三个阶段的工具。协议层（NM 分帧、M-RPC、TCP 桥）由端到端测试覆盖。默认快照是内容脚本的无障碍树近似；`page_snapshot_precise` 是用于复杂 ARIA/shadow DOM 的基于调试器的备用。Cookie/存储访问是只读和掩盖参见 [CHANGELOG.md](./CHANGELOG.md).
## 贡献与治理
[CONTRIBUTING.md](./CONTRIBUTING.md)（工作流程）· [GOVERNANCE.md](./GOVERNANCE.md)（变更如何做出）· [SECURITY.md](./SECURITY.md)（报告 + 审查栏）· [docs/development.md](./docs/development.md)（构建/测试/发布循环）。
## 许可证
[Apache-2.0](./LICENSE). 版权归 browser-bridge 贡献者所有。
