Umbra

通过 AI 代理驱动您自己已登录的 Chrome，一次一个会话，而无需将 Cookie 交给代理。

Umbra 由两部分组成，它们通过您生成的共享密钥配对：一个拥有所有 Chrome API 调用的 MV3 Chrome 扩展，以及一个向任何 MCP 客户端暴露浏览器工具界面的本地 MCP 服务器。它们仅通过经过身份验证的回环 WebSocket 通信。没有任何内容离开您的机器。

为什么存在

远程调试浏览器会一次性把一切都交给代理：每个标签页、每个 Cookie 存储、每个配置文件。Umbra 采取了相反的立场。代理只能获得它创建的标签组、其中的标签页，以及这些。如果要求它读取不属于它的标签页，扩展会在 Chrome 被触及之前就拒绝。

有两个工具故意被放在这个边界之外，并且都列在 docs/permissions.md 中：browser_find_tabs 和 browser_find_groups 会报告会话不拥有的标签页的标题和 URL，这就是您移交标签页的方式；browser_cleanup_groups 会按标题在整个配置文件中匹配标签组，以便清理由已消失的会话留下的组。给 browser_cleanup_groups 一个您自己的组不会使用的前缀，或者先使用 dryRun: true 运行它。

正是这个边界使它能够用于您已经登录的浏览器。代理可以读取您已登录的仪表板、填写表单、导出 CSV，并在完成后关闭它自己的标签页，而您的其他窗口保持不受影响且不可读。

这个项目刻意保持简单：

• 真正的 Chrome、真正的配置文件、真正的登录状态，由您选择

• 一个浏览器中支持多个并发代理会话，每个会话隔离到自己的标签组

• 每个操作都强制执行按会话的标签页所有权

• 不导出 Cookie、不提取令牌、不解决验证码、不进行通用后台抓取

• 仅限回环的传输，双向 HMAC 握手

Related MCP server: byob

安装

完整的演练，包括普通安装所需的每个变量，都在 docs/install.md 中。简而言之：

git clone https://github.com/RobertJLora/umbra
cd umbra/mcp-server
npm install
npm test

依赖项位于 mcp-server/ 中，而不是仓库根目录，因此根目录下的 npm install 不会安装任何内容，而根目录下的 npm test 会失败，直到上述命令运行过一次。之后，npm test、npm run doctor 和 npm run release:check 都可以从根目录运行。

在 chrome://extensions 中启用开发者模式并加载 extension/ 解压目录，打开扩展选项页面，点击生成密钥，然后点击复制环境行并将该行粘贴到您的 MCP 客户端配置中。重启客户端，工具就会出现。在第一次读取页面之前，点击同一页面上的授予站点访问权限，因为 Umbra 在安装时不会请求任何站点访问权限。

安装是从公共仓库检出。在上述克隆之后，node mcp-server/cli.js pair 会生成密钥，将其写入 ~/.umbra/shared-key，并打印客户端配置块。公共检出不包含任何可选的本地插件。

工具表面

会话和标签页 browser_create_tab、browser_list_tabs、browser_switch_tab、browser_close_tab、browser_close_session_tabs、browser_freeze_session_tabs、browser_group_tabs、browser_cleanup_groups、browser_mark_debug_group、browser_tabs_context、browser_get_session_status、browser_get_bridge_pressure

采用您已经打开的标签页 browser_find_tabs、browser_adopt_tab、browser_find_groups、browser_adopt_group

导航 browser_navigate、browser_navigate_back、browser_navigate_forward、browser_wait、browser_resize

读取 browser_get_page_content、browser_read_page、browser_read_interactive、browser_find、browser_get_technical_snapshot、browser_screenshot、browser_console_messages

交互 browser_click、browser_click_text、browser_type、browser_fill、browser_form_input、browser_select_option、browser_hover、browser_press_key、browser_shortcut、browser_scroll、browser_file_upload

节省往返的组合操作 browser_batch、browser_wait_click_read、browser_navigate_wait_read、browser_click_wait_selector_read

逃生舱 browser_javascript、browser_run_page_action、browser_wait_for_download

browser_reload_extension 仅适用于解压的开发者安装。当 UMBRA_ALLOW_EXTENSION_RELOAD=1 时会通告它，商店安装会拒绝它。选项页面的重新加载按钮涵盖了相同的工作流程，而不会暴露跨会话工具。

上面的列表是每个已发布构建的全部表面。检出可以携带可选的本地页面配方插件，这些插件不属于任何已发布构建的一部分：mcp-server/plugins/ 中的模块与 extension/recipes/ 中的页面配方配对。两个文件夹都是未跟踪且未发布的，插件只会将其自己的工具和 browser_run_page_action 值添加到持有它的安装中。

在调用这些工具之前，需要了解一些注意事项：

• browser_get_page_content 默认为纯文本，并支持选择器作用域以及 maxChars 上限。仅当您需要可见图像清单时，才传递 includeImages: true。

• browser_batch 在一次 MCP 调用中运行有界的创建、导航、等待、读取、点击、填充、按键、滚动、关闭工作流。子参数可以通过 {"$ref":"prev.tabId"} 引用先前的结果（用于最后一个成功步骤）、通过 {"$ref":"0.tabId"} 按索引引用步骤，或者当较早的调用设置了 label: "create" 时通过 {"$ref":"create.tabId"} 引用。

• browser_read_interactive 返回可见控件的紧凑列表，其中包含绑定到当前 DOM 版本的短期引用。browser_click、browser_fill、browser_scroll 和 browser_screenshot 接受这些引用；过期的引用会返回错误，提示调用者重新读取。

• browser_get_bridge_pressure 报告一个会话的压力：其拥有的标签页数量以及这些标签页的样本、连接的监听器计数和内容代理队列深度。它还会回收不再存在的标签页的所有权记录，因此它并非纯粹的只读操作。

• browser_freeze_session_tabs 使用 chrome.tabs.discard 丢弃拥有的非活动标签页以释放渲染器内存。它默认为 dryRun: true，并且永远不会针对另一个会话拥有的标签页。

• browser_run_page_action 运行预定义的命名页面操作并返回 JSON 安全输出。它不是一个任意的脚本工具；browser_javascript 才是，并且它通过调试器路由到拥有的标签页。

如何组合在一起

1. 您的 MCP 客户端通过 stdio 与本地服务器通信。

2. 服务器注册一个会话，可以直接在回环桥接监听器上，也可以通过 Rust 代理。

3. Chrome 扩展的离屏文档持有 WebSocket，并在服务工作线程波动时保持其存活。

4. 扩展通过共享密钥加上每个会话的随机数对每个连接进行 HMAC 质询身份验证。

5. 后台服务工作线程为每个会话分配自己的标签组，并在每次 Chrome 调用之前检查所有权。

存在两种传输方式。Rust 代理是启动器的默认设置：一个扩展 WebSocket，许多轻量级 MCP 垫片通过本地 Unix 套接字在其后注册会话，代理拥有路由、身份验证、压力计数器和请求清理。传统模式为每个会话提供自己的回环监听器，只需设置 UMBRA_BROKER_MODE=legacy 即可。无论哪种方式，扩展都是唯一接触 Chrome API 的组件。

并发和所有权

• 一个 Chrome 配置文件同时托管多个会话。

• 每个会话获得一个会话 ID、一个命名的青色 Chrome 标签组，以及自己的浏览器视图。

• 打开、导航和 DOM 交互默认为非活动标签页，因此常规工作永远不会将 Chrome 带到前台。当您确实需要焦点时，传递 activate: true。

• Umbra 会记住一个专用的 Chrome 窗口用于其标签页，并将新的会话标签页路由到那里。它拒绝在窗口聚焦时重用该窗口，因此它永远不会将标签页添加到您正在工作的窗口中。

• 导航在扩展边界处受方案限制：允许 http:、https:、file: 和 about:blank，并且在 Chrome 看到之前拒绝 javascript: 和 data: 等危险方案。

• 任务完成时，代理应调用 browser_close_session_tabs，它会关闭整个拥有的组。仅当窗口中的每个标签页都属于该会话时，它才会关闭整个窗口，因此未拥有的空白标签页会保留。

• 服务器正常关闭时默认运行相同的清理。当运行应保留标签页以供检查时，设置 UMBRA_KEEP_TABS_OPEN=1 或 UMBRA_CLOSE_ON_SHUTDOWN=0。

• 默认端口范围是 47821-47852，这足够宽，普通的多人代理工作不会耗尽空间。扩展将配置的端口限制在 1024-65535 之间；请在两侧设置相同的范围。

Umbra 不会做什么

• 转储或同步 Cookie

• 提取令牌

• 将存储读写暴露为工具

• 代表页面在后台获取

• 解决验证码

• 触及书签、历史记录或剪贴板

• 使用本机消息传递

• 自动更新、自动拉取或自动安装任何内容

已知限制

• 默认截图会在捕获前激活会话拥有的标签页。silent: true 通过将 chrome.debugger 附加到拥有的标签页来避免这种情况，以执行一次 Page.captureScreenshot，这会使 Chrome 显示其自动化横幅。

• 站点访问权限是可选的权限，通过选项页面上的授予站点访问权限按钮请求，而不是在安装时请求。在授予之前，页面读取和截图会因 Chrome 自己的权限错误而失败，因为 Chrome 要求对程序化可见标签页捕获具有字面上的广泛主机权限。docs/permissions.md 为扩展声明的每个权限提供了理由。

• 下载完成通过监视文件系统来检测，因为扩展不请求 Chrome 的 downloads 权限。如果您移动了下载文件夹，请将 UMBRA_DOWNLOAD_DIR 指向浏览器的下载文件夹。

• browser_read_interactive 有意保持紧凑。Umbra 不暴露完整的辅助功能树转储。

• 在密集的应用程序 UI（如搜索分页）上，通用文本点击可能会命中错误的控件。使用带引用的 browser_read_interactive，或使用 browser_run_page_action 配合 inspect_controls 然后 click_control，而不是猜测。

• 更改端口范围需要两侧重新加载：重启 MCP 客户端，以便新的服务器进程继承环境，并重新加载解压的扩展，以便持久化的扩展存储被规范化。

布局

• extension/ - MV3 扩展：后台工作线程、离屏桥接、内容代理、选项页面、弹出窗口

• extension/recipes/ - 可选的站点特定页面配方，按需注入，不包含在已发布包中

• mcp-server/ - stdio MCP 服务器、回环桥接、Rust 代理垫片客户端和本地开发工具

• rust-broker/ - Tokio 代理运行时，通过一个扩展 WebSocket 多路复用会话

• tests/ - 身份验证、所有权、会话隔离、扩展生命周期和打包覆盖

• scripts/ - 隔离的 Chrome 测试配置文件启动器和冒烟测试包装器

• launchd/ - 可选的 macOS 作业模板，用于保持代理运行

• docs/ - 安装、架构、权限和冒烟测试说明

文档

• docs/install.md - 从克隆到连接会话的设置，以及每个环境变量

• docs/architecture.md - 组件、流程以及离屏和后台拆分背后的原因

• docs/permissions.md - 每个 Chrome 权限及其风险和缓解措施

• docs/smoke-test.md - 自动化和手动验证路径

• docs/performance/performance-work.md - 性能优化更改了什么以及测量了什么

• MCP_PROTOCOL.md - 扩展和服务器之间的线路协议

• THREAT_MODEL.md - 资产、信任边界、攻击者和缓解措施

• SECURITY_REVIEW.md - 审查立场、保留和删除矩阵以及上游审计发现

• rust-broker/README.md - 代理范围以及如何运行它

• rust-broker/LEGACY_FALLBACK.md - 回滚触发器和切换形状

在将此工具指向一个保存着你所珍视内容的浏览器之前，请先阅读 THREAT_MODEL.md 和 SECURITY_REVIEW.md。