Skip to main content
Glama
Invictum Browser Bridge

Invictum Browser Bridge

Official
by invictumhr

Invictum Browser Bridge

面向 AI 代理的开源浏览器控制,专为开发者打造。

Invictum Browser Bridge(IBB,也称为 Invictum Browser Gate 或 IBG)允许经授权的 AI 代理在用户现有的 Google Chrome 配置文件中工作。该代理可以使用已登录的 Web 应用程序,而无需导出 cookie、密码、浏览器配置文件或原始身份验证状态。

该项目基于 MIT License 授权。它专为本地开发和高级浏览器工作流而设计,可通过 MCP、CLI、TypeScript SDK 或回环控制 API 使用。

视频演示

观看 Invictum Browser Bridge 演示

在 YouTube 上观看完整的 Invictum Browser Bridge 演示 ,观看 AI 代理在真实的 Chrome 配置文件中工作,语义化地理解公共网站,浏览其内容,测试移动视口,并创建整页和带注释的截图,同时保持受控标签页可见并明确保留。

Related MCP server: Antigravity Browser Controller

为什么使用它?

大多数浏览器自动化会启动一个干净的浏览器配置文件,或依赖不可靠的屏幕坐标。IBB 则在用户真实的 Chrome 配置文件中提供类型化、经策略检查的操作:

  • 语义化页面读取和确定性元素引用;

  • 后台优先的标签页控制,避免打扰用户;

  • 为 WordPress、WHM/cPanel 终端和 Figma 专门构建的适配器;

  • 可靠的表单、富文本/代码编辑器、上传、对话框、截图和调试工具;

  • 显式授权、按标签页保留、用户停止、脱敏审计数据和有保证的清理。

已安装的扩展会报告其确切的运行时能力。代理应始终调用 system.capabilities,而不是假设文档与加载的 Chrome 构建版本完全相同。

主要功能

浏览器和页面控制

  • 列出、打开、关闭、导航、激活标签页,并在标签页历史中移动。

  • 默认在专用代理窗口和后台标签页中工作。

  • 等待 URL、标题、文本、选择器、DOM 稳定或应用程序就绪;仅当有界后台等待证明需要聚焦时,才聚焦一次延迟渲染的标签页。

  • 读取紧凑、大纲、完整、交互式或限定范围的语义快照。

  • 提取干净的文本或轻量级 Markdown,并通过确定性的自然语言排序查找元素。

  • 单击、双击、右键单击、悬停、聚焦、输入、按键、选择、勾选、滚动到元素或文档位置,以及拖放。

  • 仅将坐标点击作为受修订版本约束的回退方案。

表单、编辑器、文件和身份验证

  • 设置原生输入框、文本域、选择框、复选框、单选按钮、contenteditable 区域和 WYSIWYG 编辑器。

  • 同步 CodeMirror、Ace、Monaco、Quill、TinyMCE、Gutenberg 及类似的权威编辑器模型,确保值在提交后仍然有效。

  • 通过 Chrome 的原生文件输入 API 附加一个或多个本地文件,而不会在结果或审计日志中暴露路径。

  • 仅在获得所需授权的情况下提交表单,包括为已获批准的代理指令提供显式授权的无提示路径。

  • 通过专用操作使用预填的登录表单、临时 HTTP Basic Auth 以及原生 JavaScript 的 alert、confirm、prompt 和 beforeunload 对话框。

WordPress 支持

IBB 包含类型化的 WordPress 工作流,而不是要求代理通过外观性的 DOM 更改或坐标拖拽来临时发挥:

  • 识别 wp-admin 屏幕、通知、列表表格、行和可用操作;

  • 使用精确的 WordPress 操作键执行行操作和批量操作;

  • 读取和更新 Gutenberg 或经典编辑器中的内容、标题、摘要、slug、状态、分类、标签、特色图片元数据以及其他受支持的字段;

  • 将更改的审阅与保存分开,并在保存后验证权威编辑器模型;

  • 检查和编辑经典的 外观 > 菜单 树,包括自定义链接、更新、移除、完整子树移动、嵌套、排序和保存;

  • 当 WordPress 的未保存更改提示阻止导航时安全恢复;

  • 回退到通用表单、上传、编辑器、DOM、控制台和同源 API 工具,用于插件设置、媒体、类似 ACF 的控件和自定义管理页面。

参见 WordPress wp-admin 和 经典菜单编辑。

WHM、cPanel 和浏览器终端

类型化的 xterm 适配器支持浏览器托管的终端,例如 WHM/cPanel 终端:

  • 检测真实终端,而不是 WHM 的 搜索工具 字段;

  • 读取有界、脱敏的 xterm 缓冲区或一个操作局部的终端 WebSocket;

  • 仅聚焦终端辅助输入,并在后台标签页中发送受信任的文本或特殊按键;

  • 在发送一次 Enter 之前,暂存并验证确切的命令;

  • 故障关闭,扣留 Enter,并尝试清除未经验证的草稿;

  • 等待提示符、文本、输出变化或静默状态;

  • 返回明确的草稿和投递验证,而不记录原始命令或输出。

终端输出为 R2,每个文本/按键操作均为 R3。只读请求绝不会授权命令。参见 终端自动化。

Chrome 中的 Figma

类型化的 Figma 操作可以检查设计文件周围的浏览器 UI:

  • 对预期的 Figma UI 锚点进行健康检查;

  • 读取文件名、页面、当前模式和当前选择;

  • 读取渲染后的图层树行和检查器属性;

  • 在有过期行保护的情况下选择页面、模式或可见图层;

  • 使用截图获取 WebGL 画布图形。

Figma 会虚拟化其图层树,并使用 WebGL 绘制设计画布,因此该适配器有意不声称支持完整的文档变更。参见 Figma 支持。

开发者诊断和视觉输出

  • 有界、脱敏的控制台捕获和仅元数据的网络诊断。

  • 同源页面 API 请求,支持可选的 WordPress nonce 处理。

  • 可逆的移动视口、方向、DPR 和触摸模拟。

  • 视口、元素、区域和整页截图。

  • 教程截图,支持矩形、椭圆、箭头、标签和自动编号的标记集叠加。

  • 元素/监听器/源码检查、有界事件观察、类型化 DOM 和内联样式变更、可逆 CSS 注入以及有界 PDF 导出。

  • 经显式授权的原始页面 JavaScript 作为 R3 的最后手段;敏感、导航、提交和无限制网络表面仍然被拒绝。

  • 保留策略的顺序批处理、试运行、幂等键、后快照、语义 DOM 差异、验证和过期引用重定位。

代理集成

IBB 提供四个本地开发者界面:

界面

用例

MCP 服务器

Codex、Cursor、Claude Code 和其他 stdio MCP 客户端的主要接口

JSON CLI

适合 PowerShell 的回退方案、诊断和自动化脚本

TypeScript Agent SDK

应用程序集成和 withReservedTab() 生命周期辅助工具

回环控制 API

在 127.0.0.1:47820 上进行本地适配器开发

127.0.0.1:47821 上的 Native Host 传输专属于 Desktop Authority。代理不得直接连接到扩展或该端口。

服务器目前公开 54 个运行时浏览器操作和 61 个 MCP 工具。该数字是发布快照,而非代理契约:请在运行时调用 invictum_capabilities。

安全模型

  • Desktop Authority 是唯一的策略和审计边界。

  • 每个操作都分为 R0-R3 等级;敏感操作需要匹配的、显式的授权断言。

  • 标签页在工作前被保留,以代理身份可见标记,并在 finally 中释放。用户可以立即停止控制。

  • 元素引用绑定到文档和 DOM 修订版本。

  • 快照会脱敏敏感值;上传、终端命令、凭据、提示文本和响应体不会写入审计日志。

  • 浏览器内部页面、扩展、DevTools、Chrome 网上应用店、本地文件和其他受限界面仍然不可用。

  • 后台工作是默认方式。代理不应请求前台激活,除非应用程序确实需要。

  • 调试器访问是标签页范围且有界的。持久适配器会在停止、重置、解锁、导航或崩溃清理时释放其租约。

IBB 不会暴露 cookie、已保存的密码、自动填充数据、任意浏览器存储、无限制下载、被动请求/响应体、流量拦截、操作系统级受信任输入或远程控制。

在扩展操作界面之前,请阅读 SECURITY.md 和 POLICY_CONFIGURATION.md。

架构

AI agent
  |  MCP / CLI / TypeScript SDK / local control API
  v
Desktop Authority :47820
  |  policy -> validation -> reservation -> audit -> cleanup
  v
Native Host -> private loopback WebSocket :47821
  v
Chrome MV3 extension -> typed page/CDP adapters -> authorized tab

参见 ARCHITECTURE.md 了解信任边界和传输契约。

要求

  • Windows 11 x64

  • Google Chrome 120+

  • Node.js 22+

  • pnpm 11

  • Git

该仓库目前提供基于源码的开发者安装方式,而不是签名的 Chrome 网上应用店包或生产安装程序。

快速开始

git clone https://github.com/invictumhr/ai-invictum-browser-bridge.git
Set-Location .\ai-invictum-browser-bridge
$env:CI = 'true'
pnpm install --frozen-lockfile
pnpm build
pnpm typecheck
pnpm test
pnpm lint

通过 chrome://extensions 将 apps/extension/dist 作为未打包扩展加载,复制其生成的扩展 ID,然后注册 Native Host:

.\scripts\register-native-host-dev.ps1 -ExtensionId "PASTE_EXTENSION_ID"
pnpm browser ping
pnpm browser capabilities

将扩展的 Chrome 站点访问权限 设置为 在所有站点上。这样可以避免为每个新的 HTTP(S) 来源手动进行工具栏批准;Chrome 策略和 Bridge 自身的授权模型仍然适用。

完整说明请参阅 INSTALL_WINDOWS.md 和 EXTENSION_INSTALL.md。

在 Windows 上使用 AI 代理安装

将下面的提示词复制到有权访问 Windows 计算机 PowerShell 的可信 AI 编码代理中。该代理可以安装和构建本地运行时,但 Chrome 需要用户执行一些可见操作来安装未打包扩展。因此,该提示词会准确告诉代理何时暂停并引导用户。

Desktop Authority 是在 127.0.0.1:47820 上接受代理命令的本地进程;Native Host 在其与 127.0.0.1:47821 上的 Chrome 扩展之间进行中继。受支持的安装方式不会创建永久的 Windows 服务。MCP 和 CLI 会在需要时将 Desktop Authority 作为隐藏的本地守护进程启动,而 Chrome 会启动已注册的 Native Host。不要暴露任一端口,也不要创建防火墙规则。

Install Invictum Browser Bridge from the public repository on this Windows PC:

https://github.com/invictumhr/ai-invictum-browser-bridge.git

Your goal is to install the complete supported local chain:

AI client -> MCP/CLI -> Desktop Authority -> Native Host -> Chrome extension

Work autonomously wherever PowerShell can do the work. Guide me step by step
only for actions Chrome requires me to perform manually. Explain each manual
step in one short message, wait for my confirmation or the extension ID, and
then continue. Do not ask me to execute commands that you can safely execute.

Safety rules:

1. Use only the public repository above and the scripts checked into it.
2. Do not request, copy, print, or store Chrome passwords, cookies, tokens,
   browser-profile files, or browsing data.
3. Do not disable Chrome security, install an unrelated extension, expose a
   loopback port, create a firewall rule, or bind any service publicly.
4. Do not invent a Windows Service or Scheduled Task. This project intentionally
   auto-starts Desktop Authority through MCP/CLI and lets Chrome start the Native
   Host.
5. Do not overwrite an existing checkout. If the target directory exists,
   inspect its Git remote and working tree first. Continue only if it is this
   repository and existing changes are safe; otherwise choose a new directory.
6. Avoid administrator elevation unless a missing prerequisite genuinely
   requires it. Native Host registration itself is per-user under HKCU.
7. Never work around a failed test, Chrome permission, or Native Messaging
   error. Diagnose it and preserve the security model.

Perform these phases:

PHASE 1 — Preflight

- Use PowerShell.
- Check Windows version and availability/versions of Git, Google Chrome,
  Node.js, npm/Corepack, and pnpm.
- Require Node.js 22 or newer and pnpm 11. Use the pnpm version declared in the
  repository package.json.
- If a prerequisite is missing, explain what is missing. Install it through an
  official source or winget only when installation is within my request; report
  any UAC/manual step before continuing.
- Resolve a normal per-user installation directory. Default to
  %USERPROFILE%\invictum-browser-bridge unless I already selected another path.

PHASE 2 — Clone, inspect, install, and build

- Clone the repository with:
  git clone https://github.com/invictumhr/ai-invictum-browser-bridge.git
- Enter the repository and verify that origin points to that repository.
- Read README.md, INSTALL_WINDOWS.md, EXTENSION_INSTALL.md, SECURITY.md, and
  AGENT_USAGE.md before installation.
- Run the repository secret scan before installation.
- Set CI=true for the install and run:
  pnpm install --frozen-lockfile
  pnpm build
  pnpm typecheck
  pnpm test
  pnpm lint
- Stop and diagnose any failed gate. Do not continue with a partial build.
- Resolve and show me the exact absolute folder I will need in Chrome:
  <repository>\apps\extension\dist
- Copy that folder path to the Windows clipboard if possible.

PHASE 3 — Guide me through loading the Chrome extension

Pause and ask me to do exactly this:

1. Open Google Chrome and go to chrome://extensions.
2. Turn on Developer mode in the top-right corner.
3. Click Load unpacked.
4. Select the exact apps\extension\dist folder you resolved above.
5. Confirm that Invictum Browser Controller appears and is enabled.
6. Copy its 32-character extension ID and send only that ID back to you.

Do not guess or hardcode the extension ID. Validate that the value I provide
matches Chrome's unpacked-extension ID format before using it.

PHASE 4 — Register the local Native Host

- From the repository root, run:
  .\scripts\register-native-host-dev.ps1 -ExtensionId "THE_ID_I_PROVIDED"
- Confirm that the script created the per-user Native Messaging registration
  for com.invictum.browser_bridge and did not expose a network port.
- If the Windows C# compiler needed by the checked-in launcher is unavailable,
  report that exact blocker; do not download or execute an unverified launcher.

PHASE 5 — Finish Chrome configuration

Pause and guide me through these steps:

1. Return to chrome://extensions.
2. Click Reload on Invictum Browser Controller once.
3. Open Details for the extension.
4. Set Site access to On all sites.
5. Confirm the extension remains enabled and has no current error.
6. Optionally pin its toolbar icon so the ON/AI status and settings are easy to
   see.

Explain that On all sites prevents a new manual approval for every HTTP(S)
domain, but does not bypass Chrome policy, restricted pages, User Stop, or IBB's
own authorization rules. Wait for my confirmation before testing.

PHASE 6 — Start and verify the bridge

- Run pnpm browser health.
- Run pnpm browser ping. The CLI should automatically start Desktop Authority
  as a hidden local daemon if it is offline.
- Run pnpm browser capabilities.
- Verify that Desktop Authority is reachable only through 127.0.0.1:47820, the
  private Native Host transport uses 127.0.0.1:47821, nativeConnected is true,
  and the loaded extension returns its runtime capabilities.
- Treat runtime capabilities as authoritative. The current source expects 54
  browser actions and the built MCP server expects 61 tools, but do not hide a
  mismatch or force those numbers if the checked-out release differs.
- If the badge briefly shows ON and disconnects, diagnose Desktop Authority,
  the HKCU Native Messaging manifest, its allowed extension ID, the built Native
  Host paths, and extension errors. Rebuild/reregister/reload only the component
  that is stale.
- Do not ask for a second extension reload unless extension files or its Native
  Host registration actually changed.

PHASE 7 — Configure AI clients

- Ask whether I want global IBB/IBG discovery for installed AI clients. If yes,
  run:
  powershell -ExecutionPolicy Bypass -File
  .\scripts\install-agent-discovery.ps1
- This should preserve unrelated Codex, Cursor, and Claude configuration.
- Tell me to start a new AI-agent session after MCP registration changes.
- Verify with a harmless request that performs only IBB ping and capabilities;
  do not open a browser tab for this verification.

PHASE 8 — Final report

Report:

- repository installation path and checked-out revision;
- Node.js and pnpm versions;
- build/typecheck/test/lint results;
- Chrome extension ID and loaded dist path (the ID is not a secret);
- Native Host registration status;
- Desktop Authority health and nativeConnected state;
- runtime action count and MCP tool count;
- which AI clients were configured;
- whether any manual action or known limitation remains.

Do not claim success until ping and capabilities work through the normal local
authority. Do not use a temporary test harness that takes over port 47821.

配置 AI 代理

在 pnpm build 之后,为受支持的本地代理安装 MCP 注册和触发规则:

powershell -ExecutionPolicy Bypass -File .\scripts\install-agent-discovery.ps1

短语 use IBB、use IBG、use Invictum Browser Bridge 和 use Invictum Browser Gate(以及它们的克罗地亚语对应短语)都会选择此 Bridge。更改 MCP 注册后,请启动新的代理会话。

参见 MCP 配置、代理发现 和简洁的 代理触发契约。

推荐的代理工作流

ping -> capabilities -> open/navigate in background -> identify agent -> wait
     -> outline/snapshot -> find -> typed action -> verify -> unlock in finally

优先使用类型化操作和语义引用。使用截图进行视觉理解,坐标仅作为回退方案,原始 JavaScript 仅在用户明确授权且没有更安全的类型化操作可以解决任务时使用。

完整的操作指南是 AGENT_USAGE.md。

文档

从 文档索引 开始。重要指南包括:

仓库布局

apps/
  cli/           JSON CLI and authority auto-start
  desktop/       policy/audit authority and loopback control API
  extension/     Manifest V3 Chrome controller
  mcp/           stdio MCP adapter
  native-host/   Native Messaging stdio <-> private local WebSocket
packages/
  agent-sdk/     control client and reserved-tab lifecycle helpers
  audit-log/     redacted audit contract and development sink
  policy-engine/ fail-closed action classification
  protocol/      strict IBP schemas and factories
  shared-types/  transport-neutral contracts
tests/
  fixtures/      deterministic local browser pages
  integration/   emulated transport and real-Chrome smoke tests

贡献

欢迎提交 Issue 和拉取请求。请将策略、验证、审计、预留和清理保留在 Desktop Authority 路径中;不要为扩展添加第二条控制路径。在发起拉取请求之前,请运行完整的本地门禁,并遵循 CONTRIBUTING.md。

请使用结构化的 GitHub 表单提交 Bug 报告 和 功能请求。参与之前,请阅读 SUPPORT.md 了解诊断指南,并阅读 CODE_OF_CONDUCT.md。安全问题必须使用 私有漏洞报告,而不是公开的 Issue。

在发布更改之前,请使用 GIT_PUBLISHING.md 中的私有数据检查清单。

许可证

Invictum Browser Bridge 是根据 MIT License 许可的开源软件。在遵守许可条款的前提下,您可以复制、修改、合并、发布、分发、再许可和出售副本。


由 invictum.hr 制作

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      B
      maintenance
      Enables AI agents to control existing Chrome and Firefox browser sessions locally, including tab management, navigation, form filling, screenshots, and persistent scripts, without remote relays or debugging ports.
      36
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to drive a real Chrome browser for autonomous web tasks, using fast typed decisions with calibrated confidence, human-in-the-loop questions, safety gates, and full debug traces.
      209 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to securely control a real, logged-in browser with per-site permissions, per-action approvals, secret redaction, and a tamper-evident audit log, all locally without a cloud relay.
      1
      MIT