内容
# 铬桥
任何MCP客户端（Claude Code、Claude Desktop、Codex或任何支持模型上下文协议的客户端）都可以驱动您真正的铬浏览器：您的标签页、已登录的会话、Cookie，通过浏览器扩展和本地消息主机。无需第二个浏览器，无需CDP调试端口，无需`--remote-debugging`标志。
由于它操作的是您已经登录的浏览器，因此代理可以执行全新无头浏览器无法执行的操作：读取您授权后的页面、点击您登录的应用程序、拉取框架存储在`localStorage`中的令牌。这种能力也意味着风险。在安装前请阅读安全部分。
翻译：[简体中文](./README.zh_CN.md)、[繁体中文](./README.zh_TW.md)。
## 安全第一
铬桥驱动一个真实的、经过身份验证的浏览器。它可以读取页面内容、Cookie（包括`httpOnly`）和网络存储，并且可以在您的页面上运行JavaScript。安全措施：
- **批准每个站点。** 新的源触发提示；除非您已批准，否则站点上不会运行任何内容。
- **确认高风险操作。** 提交点击、按键、关闭标签页、文件上传和每个`page_eval`在扩展程序拥有的窗口中确认，对页面不可见或点击。在通过Touch ID注册的Mac上，`page_eval`和`page_upload`批准是安全环境的用户存在检查（Touch ID或登录密码），任何页面或程序都无法伪造（[ADR-0031](./docs/adr/0031-touch-id-confirmations-and-presence-grants.md)）。这些门控默认开启；每个都是有文档记录的设置，放松一个是明确的、知情的选择（[SECURITY.md](./SECURITY.md#page_eval-and-confirmation-defaults-fail-safe)）。
- **只读凭证。** Cookie和存储可以读取（始终掩盖：JWT、长十六进制、长数字运行），但绝不写入。按照设计，没有`cookie_set`或`storage_set`。
- **身份验证、证明桥。** 在macOS和Linux上，主机进程之间的桥是私有Unix域套接字（无监听端口）。每个连接必须通过内核对等UID检查、内核证明可执行身份和HMAC挑战，基于每个运行的秘密。MCP客户端本身被允许加入受信任的客户端允许列表，该列表以证明的代码身份为键，任何一侧都可以随时撤销信任（[ADR-0024](./docs/adr/0024-multi-client-attested-pairing-and-broker.md）、[ADR-0025](./docs/adr/0025-any-side-revocation-epoch.md)）。
- **全局终止开关。** CLI、扩展程序或应用程序的单个操作会停止所有操作，直到您通过存在证明释放它（[ADR-0030](./docs/adr/0030-global-kill-switch-and-audit.md)）。每个安全决策都会记录在磁盘审计轨迹中。
平台诚实度：强大的桥接保证（无端口套接字、对等UID检查、证明）仅在macOS和Linux上存在。在Windows上，桥接是一个仅通过HMAC机密控制的环回TCP套接字，服务器在启动时警告这一点。Windows支持尽力而为。详细信息请参见[SECURITY.md](./SECURITY.md#platform-support)。
完整详细信息：[SECURITY.md](./SECURITY.md)、[威胁模型](./docs/security/threat-model.md)、[信任边界](./docs/security/trust-boundaries.md)、[每个工具的风险矩阵](./docs/security/tool-risk-matrix.md)。
## 快速入门（macOS，应用）
铬桥桌面应用是主要的安装路径。它捆绑了签名的主机二进制文件和扩展程序，唯一的命令是将服务器注册到您的MCP客户端。
> 应用下载尚未发布：发布版本仅包含CLI存档和扩展程序zip，发布管道的桌面作业处于休眠状态，直到其签名机密被配置并且发布保持被解除（参见[docs/release.md](./docs/release.md)）。在此之前，请从源代码检出构建应用：`moon run dmg-app`生成签名的磁盘镜像，`moon run install-app`将构建的应用放入/Applications，`moon run run-app`在本地构建并启动它。 使用免费开发证书签名的构建仅在Mac的配置文件的Mac上运行，公共分发也需要付费的Developer ID进行身份验证；两者都保持开放。或者使用下面的CLI路径。
1. **安装应用。** 获取`Chromium Bridge.app`（参见上面的注释）并打开它。首次启动时，它会在检测到的每个铬浏览器上注册本地消息主机并显示其写入的内容。
2. **加载扩展程序。** 在应用的设置页面上，点击“显示文件夹”以打开捆绑的扩展程序，然后在您的浏览器中打开`chrome://extensions`，启用开发者模式，点击“加载解压”，然后选择该文件夹。重启浏览器使其获取注册。
3. **与Touch ID配对。** 在应用的配对页面上，点击配对（出现Touch ID提示），然后在扩展程序的选项页面上批准密钥指纹。在macOS上，扩展程序默认需要此注册，并且在指纹不匹配时拒绝操作（[ADR-0021](./docs/adr/0021-enrollment-ceremony.md)）。
4. **连接您的MCP客户端。** 在设置页面上，点击安装，将`chromium-bridge`命令放入`~/.local/bin`。然后将其注册到您的客户端。对于Claude Code：
```sh
claude mcp add chromium-bridge -- "$HOME/.local/bin/chromium-bridge"
```
其他客户端采用相同的二进制文件作为`mcpServers`条目；参见[连接您的MCP客户端](#connect-your-mcp-client)。
请您的客户端“列出我的浏览器标签页”。第一次针对新站点时，点击铬桥工具栏图标并批准它。
该应用也是持续的控制面板：配对、受信任的客户端、终止开关和审计轨迹，在注册的Mac上具有Touch ID保护的高风险操作。参见[docs/desktop-app.md](./docs/desktop-app.md)。
## 快速入门（CLI，macOS，Linux，Windows）
CLI是同等重要的：从终端执行与应用相同的操作，除了二进制文件本身之外，没有任何依赖。它是Linux和Windows上的自然路径，在无头机器和CI中也是如此。
1. 从[最新发布](https://github.com/Vivswan/chromium-bridge/releases/latest)下载适用于您平台的存档并解压。或者，在解压前先验证它；在macOS/Linux上（Windows存档为`.zip`，请使用您自己的sha256工具检查）：
```sh
shasum -a 256 -c chromium-bridge-<tag>-<platform>-<arch>.tar.gz.sha256
gh attestation verify chromium-bridge-<tag>-<platform>-<arch>.tar.gz --repo Vivswan/chromium-bridge
```
完整的验证故事在[SECURITY.md](./SECURITY.md#release-artifact-integrity)中。
2. 将提取的二进制文件注册到您的浏览器中。注册是幂等的，因此相同的命令是新的安装、修复和在移动二进制文件后重新注册：
```sh
./chromium-bridge doctor --fix # 每个检测到的浏览器
./chromium-bridge doctor --fix --browser chrome,brave
```
将二进制文件保持在稳定的路径下（它在原地注册）。在Linux上，`~/.local/lib/chromium-bridge/`是一个不错的家。`chromium-bridge uninstall`会反转已经注册的内容。
3. 加载扩展程序：存档的`extension/dist/`目录通过`chrome://extensions`、开发者模式、“加载解压”。重启浏览器。
4. 在macOS上，配对：`chromium-bridge pair`（Touch ID），然后在扩展程序的选项页面上批准指纹；Linux和Windows跳过此步骤。
5. 将您的MCP客户端连接到提取的二进制文件（绝对路径），如下所示。
从源代码构建：`cargo build --release`，然后从`target/release/chromium-bridge`运行相同的`doctor --fix`（参见[docs/development.md](./docs/development.md)）。
完整的CLI（doctor，配对，撤销，终止开关，审计）记录在[docs/cli.md](./docs/cli.md)中。
## 连接您的MCP客户端
将您的客户端指向已安装的二进制文件。运行时不带参数，它通过stdio进行MCP通信。使用绝对路径；大多数客户端不扩展`~`。
Claude Code：
```sh
claude mcp add chromium-bridge -- "$HOME/.local/bin/chromium-bridge"
```
Claude Desktop和其他`mcpServers` JSON客户端：
```json
{
"mcpServers": {
"chromium-bridge": {
"command": "/ABSOLUTE/PATH/TO/chromium-bridge",
"args": []
}
}
}
```
Codex（`~/.codex/config.toml`）：
```toml
[mcp_servers.chromium-bridge]
command = "/absolute/path/to/chromium-bridge"
args = []
```
多个客户端可以同时连接：第一个服务器实例成为代理，后续实例附加到它，每个实例都经过身份验证和单独撤销（[ADR-0024](./docs/adr/0024-multi-client-attested-pairing-and-broker.md)）。
在WSL上：如果您的日常浏览器是Windows Chrome，请在Windows上安装并通过`/mnt/c`将WSL客户端指向`.exe`；不要安装Linux主机。如果Chrome在WSLg下运行，请在Linux中本地安装。参见[WSL指南](./docs/wsl.md)。
## 您能做的事：26种工具
分组来自单一的真实来源，Rust工具目录（[`src/packages/core/src/tools/catalogue.rs`](./src/packages/core/src/tools/catalogue.rs)）。每个工具的完整风险范围详细信息在[工具风险矩阵](./docs/security/tool-risk-matrix.md)中。
### 浏览器
| 工具 | 功能 | 风险 |
|------|------|------|
| `list_browsers` | 列出连接到桥的浏览器（标签 + 打开的标签计数） | 低 |
可以同时连接多个浏览器（在macOS/Linux上，每个浏览器都有自己的主机和标签，例如`chrome`和`brave`）。其他工具都带有可选的`browser`参数来选择一个；如果连接了多个浏览器，未寻址的调用将失败并显示清晰的错误，而不是猜测要在哪个已登录的浏览器中执行。参见[ADR-0022](./docs/adr/0022-multi-browser-label-routing.md)。
### 标签页
| 工具 | 功能 | 风险 |
|------|------|------|
| `tab_list` | 列出打开的标签页（id，title，url，active） | 低 |
| `tab_focus` | 将标签页带到前景 | 低 |
| `tab_open` | 在新标签页中打开URL（主机必须在白名单中） | 中 |
| `tab_close` | 关闭标签页（确认窗口） | 高 |
### 导航
| 工具 | 功能 | 风险 |
|------|------|------|
| `page_navigate` | 在活动标签页中加载http（s）URL | 中 |
| `page_back` / `page_forward` | 遍历历史记录 | 低 |
| `page_reload` | 重新加载活动标签页 | 低 |
### 检查页面
| 工具 | 功能 | 风险 |
|------|------|------|
| `page_snapshot` | 交互元素的无障碍样式树，每个元素都有稳定的`ref` | 低 |
| `page_snapshot_precise` | 通过`chrome.debugger`进行权威的a11y树（shadow DOM /复杂ARIA）；引用使用`p`前缀 | 中 |
| `page_text` | 可见页面文本（密码和类似卡片的数字被屏蔽） | 中 |
| `page_screenshot` | 可见视口作为PNG | 中 |
| `console_get` | 最近的控制台输出，被屏蔽 | 中 |
### 驱动页面
| 工具 | 功能 | 风险 |
|------|------|------|
| `page_click` | 按`ref`或`selector`点击；提交/链接点击需要确认 | 高 |
| `page_fill` | 输入到字段（原生设置器，因此React / Vue检测到它） | 高 |
| `page_press` | 发送按键或组合键（确认） | 高 |
| `page_select` | 在`<select>`中选择选项（确认） | 高 |
| `page_hover` | 移动指针到元素上 | 低 |
| `page_scroll` | 向上/向下/顶部/底部/ N像素 | 低 |
| `page_wait_for` | 等待选择器、文本或导航 | 低 |
| `page_handle_dialog` | 接受或拒绝JS对话框（默认关闭） | 高 |
### 运行代码和上传（最高风险）
| 工具 | 功能 | 风险 |
|------|------|------|
| `page_eval` | 执行任意JS。每次调用都确认，显示完整的代码；在注册的Mac上使用Touch ID。返回值默认被屏蔽。优先使用上面的工具。 | 关键 |
| `page_upload` | 将命名本地文件附加到文件输入（默认关闭；每次调用都确认路径） | 关键 |
### 读取凭证（只读，始终屏蔽）
| 工具 | 功能 | 风险 |
|------|------|------|
| `cookie_get` | 读取活动标签页的Cookie，包括`httpOnly`；仅限白名单主机 | 高 |
| `storage_get` | 读取页面的`localStorage` / `sessionStorage`（同源） | 高 |
按照设计，没有写入工具；Cookie /存储写入范围不受支持（[ADR-0010](./docs/adr/0010-cookie-storage-readonly.md)）。
## 工作原理
一个Rust二进制文件，两种模式，通过身份验证的本地套接字连接。桌面应用和CLI管理相同的状态。
```
MCP客户端A --stdio--> chromium-bridge（代理：第一个MCP服务器实例）
MCP客户端B --stdio--> chromium-bridge ----attach----^ |
（每个客户端在提供服务前都经过受信任的客户端允许列表验证） | 桥接套接字
| （Unix域套接字，
| 对等方身份验证 +
| HMAC; Windows上的TCP）
v
chromium-bridge --native-host <-- 由
| 每个浏览器
| chrome.runtime.connectNative
v
Chromium Bridge扩展（MV3）--> 您的页面
```
- **MCP服务器（默认模式）**：由您的MCP客户端通过stdio启动。讲话JSON-RPC 2.0（MCP协议`2025-06-18`）。第一个实例拥有套接字并成为代理；后续实例作为中继附加，因此多个客户端可以并发共享浏览器。
- **`--native-host`**：由浏览器通过主机清单启动。薄桥将Chrome的本地消息帧转换为套接字的NDJSON。每个安装的浏览器都启动自己的主机，并带有自己的标签，因此一个代理可以通过名称寻址多个浏览器。
- **桌面应用/CLI**：同等的管理表面在核心之上（注册、配对、撤销、终止开关、审计）。两者都不是信任根；能力授予的行为以用户存在门控结束。
为什么有两个进程？浏览器启动原生主机；MCP客户端启动服务器。它们不是父子进程，因此需要IPC。原生主机保持薄，以便MV3服务工作器回收（大约每5分钟一次）和主机重启不会丢失会话状态。
深入探讨：[docs/architecture.md](./docs/architecture.md)。
## 兼容性
| | 支持 |
|---|---|
| macOS | Apple Silicon (arm64) 预构建；桌面应用和Touch ID门控在此处。Intel版本可从源代码构建。 |
| Linux | x64预构建；任何基于铬的浏览器；CLI管理界面。 |
| Windows | x64预构建（本地，无需管理员）。桥接安全为尽力而为；参见[SECURITY.md](./SECURITY.md#platform-support)。 |
| 浏览器 | 任何基于铬的浏览器，清单V3 |
| MCP协议 | `2025-06-18`（[ADR-0007](./docs/adr/0007-mcp-protocol-version-2025-06-18.md)） |
| 内部桥接协议 | `1`（[src/packages/core/src/protocol.rs](./src/packages/core/src/protocol.rs)中的`BRIDGE_PROTOCOL_VERSION`） |
已知浏览器（`--browser`键）：`chrome`，`chromium`，`brave`，`edge`，`vivaldi`，`opera`。每个铬浏览器都读取相同的原生消息清单；只有每个用户的`NativeMessagingHosts`位置不同，核心中的共享解析器知道它们所有。有关非表格中的铬变体的更多信息，请参阅[docs/compatibility.md](./docs/compatibility.md)和[docs/cli.md](./docs/cli.md)。
## 配置
启动时读取环境变量：
| 变量 | 值 | 默认值 | 效果 |
|-----|--------|---------|--------|
| `BB_LOG` | `error` \| `warn` \| `info` \| `debug` | `info` | stderr日志/审计阈值 |
| `BB_LOG_FORMAT` | `text` \| `json` | `text` | 审计行格式；`json`每行发出一个对象 |
持久审计轨迹（`chromium-bridge audit`）独立于这些记录；参见[docs/cli.md](./docs/cli.md#logging-and-audit-bb_log--bb_log_format)。
## 故障排除
首先运行内置的只读自检：
```sh
chromium-bridge doctor # 或：chromium-bridge status
```
它报告服务器是否可达、锁定文件状态、终止开关以及每个浏览器的注册状态，并且`doctor --fix`会就地修复注册。然后检查您的MCP客户端的服务器UI（在Claude Code中通过`/mcp`重新连接），以及扩展程序的服务工作器控制台在`chrome://extensions`（查找 `[bb]` 日志）。完整的运行手册：[docs/cli.md](./docs/cli.md)和[docs/operations.md](./docs/operations.md)。
## 文档地图
| 文档 | 内容 |
|-----|--------------|
| [docs/quickstart.md](./docs/quickstart.md) | 安装和首次使用，应用和CLI（也可在[简体中文](./docs/quickstart.zh_CN.md)和[繁体中文](./docs/quickstart.zh_TW.md)中找到） |
| [docs/architecture.md](./docs/architecture.md) | 组件、数据流、协议、安全模型、关键约束 |
| [docs/security/](./docs/security/) | 威胁模型、信任边界、工具风险矩阵、事件响应 |
| [docs/cli.md](./docs/cli.md) | 完整的CLI：doctor/--fix、卸载、配对、撤销、终止开关、审计 |
| [docs/desktop-app.md](./docs/desktop-app.md) | 桌面应用：它管理的内容以及如何验证它 |
| [docs/operations.md](./docs/operations.md) | 二进制模式、日志记录/审计、运行时目录、重新连接 |
| [docs/compatibility.md](./docs/compatibility.md) | 版本规则和能力/协议握手 |
| [docs/release.md](./docs/release.md) | 标签驱动的发布、预构建存档+校验和、SBOM |
| [docs/wsl.md](./docs/wsl.md) | WSL的两种模式：Windows Chrome互操作和WSLg |
| [docs/adr/](./docs/adr/) | 架构决策记录：每个“为什么选择这个” |
<details>
<summary>测试和项目布局</summary>
独立套件跨两种语言：
- 协议层：`tests/protocol/e2e.py`（plus `adversarial.py`和`chaos.py`）驱动真正的二进制文件进行实际线路协议。
- DOM层：`tests/browser/dom_test.ts`将实际内容脚本注入隔离的Chrome中，并通过CDP针对实际DOM测试每个操作。
- 烟雾测试：`tests/browser/ext_test.ts`使用内置的Chrome启动隔离的Chrome，并带有扩展程序。
- 真实集成（可选）：`tests/browser/integration_e2e.ts`使用`BB_REAL_E2E=1`。
参见[tests/README.md](./tests/README.md)。布局：`src/apps/host`（Rust二进制文件），`src/apps/extension`（MV3，WXT），`src/apps/desktop`（Tauri应用），`src/packages/core`（Rust库和跨进程合同的单一源），`src/packages/shared`（生成的TS合同+验证器）。
</details>
## 项目状态
预-1.0（[Cargo.toml](./Cargo.toml)）。协议层由端到端、逆向和混沌测试覆盖；线缆解析器被模糊化。参见[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)。版权归浏览器桥接贡献者所有。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器