Agent Browser Ga

本项目的浏览器通信 / web bridge 代码提取自 GenericAgent，主要包含 genericagent_web/TMWebDriver.py 和 extension/tmwd_cdp_bridge/。本仓库只保留运行 agent-browser-ga MCP 所需的真实 Chrome 通信部分，不包含完整 GenericAgent Agent 框架。

agent-browser-ga 是一个本地 stdio MCP Server，用来把支持 MCP 的 Agent 客户端连接到用户正在使用的真实 Chrome。它通过本仓库内置的 TMWebDriver 和 Chrome 扩展 tmwd_cdp_bridge 工作，因此可以在已经登录、已经完成 SSO/MFA、保留 Cookie 和浏览器指纹的页面里执行 JavaScript、读取 Cookie、调用页面内 fetch()、发 CDP 命令和截图。

这个 MCP 适合处理需要真实登录态的内网页面、后台系统、企业 SSO 页面和用户已经打开的标签页。它不适合无授权的公网爬取，也不适合在没有明确确认的情况下执行会修改数据的点击、表单提交或写接口调用。

和 agent-browser MCP 的区别

维度	agent-browser-ga MCP	agent-browser / agent-browser MCP
浏览器对象	用户真实 Chrome 中已经打开的可脚本化标签页	通用浏览器自动化运行时，通常由工具启动或管理 Chrome/Chromium 会话
登录态	直接复用用户当前 Chrome 的 Cookie、SSO、MFA 和扩展状态	可做持久化会话或认证管理，但不是天然接入用户当前正在操作的 Chrome 标签页
核心通道	MCP stdio -> Python FastMCP -> 内置 genericagent_web/TMWebDriver.py -> 本地 WebSocket -> Chrome 扩展	CLI/自动化运行时通过 CDP 和可访问性树等能力控制浏览器
主要能力	exec_js、fetch_in_page、cookies、cdp、screenshot、真实标签页枚举	页面导航、点击、表单、截图、可访问性树元素引用、QA/测试/通用自动化
最佳场景	已登录后台、内网系统、需要真实 Cookie 调接口、复用当前 Chrome 标签页	公网页面自动化、端到端测试、探索式 QA、可重复浏览器任务
风险边界	操作的是用户真实账号，写操作有真实后果，必须显式确认	通常更容易隔离在自动化浏览器或独立会话中
依赖	Python、MCP SDK、本仓库提取的 GenericAgent web bridge、Chrome 扩展	agent-browser CLI 及其浏览器运行环境

简短判断：如果任务依赖“我现在 Chrome 里已经登录的这个站点”，选 agent-browser-ga；如果任务是通用网页自动化、测试、截图、爬取公开页面或需要稳定元素定位工作流，优先选 agent-browser。

架构

MCP Client
  Codex / Claude Code / Claude Desktop / other MCP host
        |
        | stdio
        v
agent-browser-ga/server.py
  FastMCP tools: diagnostic, tabs, set_session, exec_js, fetch_in_page, ...
        |
        | Python import
        v
genericagent_web/TMWebDriver.py
  Extracted from GenericAgent web bridge
  WebSocket master: ws://127.0.0.1:18765
  HTTP relay/fallback: http://127.0.0.1:18766
        |
        | WebSocket
        v
Chrome extension: tmwd_cdp_bridge
        |
        | chrome.scripting / chrome.cookies / chrome.debugger / chrome.tabs
        v
User's real Chrome tabs

关键点：

• server.py 不直接启动 Chrome，也不保存登录凭证；它只通过 TMWebDriver 把 MCP 工具调用转给已连接的 Chrome 扩展。
• TMWebDriver 默认监听 127.0.0.1:18765，扩展连接成功后会上报可脚本化标签页。
• Chrome 的 chrome://、about:blank、chrome-extension:// 等内部页面无法注入扩展脚本，通常不会出现在可操作标签页列表里。
• fetch_in_page() 在页面上下文中执行 fetch()，因此会带上浏览器同源 Cookie、指纹和页面可访问的 CSRF 信息。
• cdp() 和 cdp_batch() 通过扩展的 chrome.debugger 权限转发 Chrome DevTools Protocol 命令。

文件结构

agent-browser-ga/
  server.py          # MCP Server 主入口，使用 FastMCP 暴露工具
  register.py        # 生成 Claude/Codex MCP 配置片段，可选写入 ~/.claude.json
  requirements.txt   # MCP 侧 Python 依赖
  genericagent_web/
    TMWebDriver.py   # 从 GenericAgent 提取的 web bridge 代码
  extension/
    tmwd_cdp_bridge/ # TMWD CDP Bridge Chrome 扩展，可直接加载
  skills/
    agent-browser-ga/
      SKILL.md       # 配套 Agent skill，约束何时使用和安全边界
  licenses/
    GenericAgent-LICENSE
  README.md          # 本文档
  .gitignore

本仓库已经包含运行 MCP 所需的 GenericAgent web bridge 代码；使用者下载本项目后，不需要再安装完整 GenericAgent。GENERICAGENT_HOME 只是高级覆盖项：如果你想改用外部 GenericAgent 或其他 TMWebDriver.py 目录，可以在 MCP 配置里设置它。

MCP 工具

工具	说明	是否只读
diagnostic()	检查 TMWebDriver 路径、导入状态、18765 端口和当前标签页	是
tabs()	列出当前可脚本化浏览器标签页	是
set_session(url_pattern)	按 URL 子串绑定后续默认标签页	否，仅改变 MCP 会话状态
exec_js(code, timeout, session_id)	在页面主世界执行 JavaScript，返回最后表达式或 return 值	取决于代码
jump(url, timeout)	导航当前绑定标签页到新 URL	否
cookies(url)	获取指定 URL 的 Cookie，包括 Partitioned Cookie	是，但会暴露凭证
cdp(method, params, tab_id)	发送单条 Chrome DevTools Protocol 命令	取决于命令
cdp_batch(commands, tab_id)	一次发送多条 CDP 命令，支持 $N.path 引用前序结果	取决于命令
screenshot(tab_id, full_page)	捕获当前标签页 PNG，返回 data URL	是
fetch_in_page(url, options, session_id)	在页面上下文中执行 fetch()，复用登录态	取决于 HTTP 方法
list_extensions()	列出 Chrome 扩展，用于确认 tmwd_cdp_bridge 是否安装	是

安装步骤

以下步骤以 Windows 为主，因为本地实例使用的是 Windows 路径。macOS/Linux 也可以使用同样思路，但需要把路径替换成对应系统路径。

1. 准备 Python

需要 Python 3.10 或更高版本。确认命令：

python --version

建议在仓库目录创建虚拟环境：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -r requirements.txt

如果你希望复用系统 Python，也可以只执行：

python -m pip install -r requirements.txt

2. 确认内置 web bridge 代码

Test-Path ".\genericagent_web\TMWebDriver.py"
Test-Path ".\extension\tmwd_cdp_bridge\manifest.json"

这两个文件都应返回 True。如果仓库是完整下载的，这一步不需要额外安装 GenericAgent。

3. 安装 TMWD CDP Bridge Chrome 扩展

1. 打开 Chrome。
2. 访问 chrome://extensions。
3. 打开右上角“开发者模式”。
4. 点击“加载已解压的扩展程序”。
5. 优先选择本仓库自带的扩展目录：

~\extension\tmwd_cdp_bridge

如果你显式改用完整 GenericAgent，也可以选择 GenericAgent 安装目录里的同一份扩展：

%USERPROFILE%\GenericAgent\assets\tmwd_cdp_bridge

6. 打开任意真实网页，例如 https://example.com。不要停留在 chrome://、about:blank 或扩展页。

扩展需要 cookies、tabs、debugger、scripting、management、contentSettings 等权限，这是实现 Cookie 读取、CDP 透传、标签页枚举和页面脚本执行所必需的。

4. 安装配套 Skill

本仓库包含配套 skill：

~\skills\agent-browser-ga\SKILL.md

它的作用是让 Agent 知道什么时候应该使用 agent-browser-ga，什么时候应该改用 agent-browser，以及真实账号操作的安全边界。

Codex 常见安装位置：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\skills" | Out-Null
Copy-Item -Recurse -Force `
  "~\skills\agent-browser-ga" `
  "$env:USERPROFILE\.codex\skills\"

如果你的 Codex/Agent 环境读取 ~\.agents\skills，使用：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills" | Out-Null
Copy-Item -Recurse -Force `
  "~\skills\agent-browser-ga" `
  "$env:USERPROFILE\.agents\skills\"

Claude Code 常见安装位置：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item -Recurse -Force `
  "~\skills\agent-browser-ga" `
  "$env:USERPROFILE\.claude\skills\"

安装 skill 后重启对应客户端，或按客户端自己的 skill 重新加载方式刷新。

5. 配置 MCP Client

先生成当前机器的配置片段：

python .\register.py

它会打印 Claude JSON 和 Codex TOML 两种配置。根据你使用的客户端选择一种。

Codex

编辑：

%USERPROFILE%\.codex\config.toml

加入类似配置，注意按你的实际 Python 和仓库路径修改：

[mcp_servers.agent-browser-ga]
type = "stdio"
command = '~\.venv\Scripts\python.exe'
args = ['~\server.py']

[mcp_servers.agent-browser-ga.env]
GENERICAGENT_HOME = '~\genericagent_web'
PYTHONIOENCODING = "utf-8"

如果没有使用虚拟环境，command 可以改成系统 Python，例如：

command = '~\AppData\Local\Programs\Python\Python310\python.exe'

Claude / Claude Code

可以手工编辑 ~/.claude.json，加入：

{
  "mcpServers": {
    "agent-browser-ga": {
      "type": "stdio",
      "command": "~\\agent-browser-ga\\.venv\\Scripts\\python.exe",
      "args": ["~\\agent-browser-ga\\server.py"],
      "env": {
        "GENERICAGENT_HOME": "~\\agent-browser-ga\\genericagent_web",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

也可以让脚本写入 ~/.claude.json：

python .\register.py --write-claude

如果你想覆盖为外部 TMWebDriver.py 目录：

python .\register.py --ga-home "D:\tools\GenericAgent" --write-claude

6. 重启 MCP Client

修改配置后重启 Codex、Claude Code 或 Claude Desktop，让 MCP Server 被重新加载。

7. 验证连接

在 MCP 客户端里调用：

diagnostic()

期望看到：

• ga_home_exists: true
• tmwebdriver_importable: true
• ws_port_18765_listening: true
• tabs 中有你打开的真实网页标签页

然后调用：

tabs()
set_session("example.com")
exec_js("return document.title")

也可以用 MCP Inspector 做本地检查：

cd ~
$env:GENERICAGENT_HOME="$PWD\genericagent_web"
npx @modelcontextprotocol/inspector .\.venv\Scripts\python.exe .\server.py

使用示例

读取当前页面标题：

tabs()
set_session("your-site.example")
exec_js("return { title: document.title, url: location.href }")

用用户登录态调用同源 API：

fetch_in_page("/api/current-user", { "method": "GET" })

截图：

screenshot(full_page=true)

读取 Cookie：

cookies("https://your-site.example")

发送 CDP 命令：

cdp("Runtime.evaluate", { "expression": "document.body.innerText.slice(0, 200)" })

安全规则

这个 MCP 操作的是用户真实 Chrome 和真实账号，所有写操作都可能产生真实后果。

• 读取页面、列出标签页、截图、读取标题等只读操作可以直接执行。
• POST、PUT、PATCH、DELETE、表单提交、点击保存/删除/发布按钮、执行会改页面或远端状态的 JavaScript 前，必须得到用户明确确认。
• 不要盲目重试点击或提交。如果一次操作没有预期效果，应先检查标签页、选择器、页面状态和错误信息。
• cookies() 会暴露会话凭证。不要把返回结果写入日志、提交到仓库或发给不可信服务。
• 内网页面和企业后台通常有审计日志。使用前确认你有权限代表当前账号执行对应操作。

常见问题

Cannot import TMWebDriver

原因通常是 genericagent_web\TMWebDriver.py 缺失、GENERICAGENT_HOME 覆盖到了错误目录，或 MCP 使用的 Python 没有安装依赖。

检查：

Test-Path ".\genericagent_web\TMWebDriver.py"
python -m pip install -r requirements.txt

如果你要使用外部 GenericAgent，确认 MCP 配置里的 GENERICAGENT_HOME 指向包含 TMWebDriver.py 的目录。

mcp SDK missing

安装 MCP Python SDK：

python -m pip install "mcp[cli]>=1.0"

ws_port_18765_listening 是 false

MCP Server 尚未创建 TMWebDriver 实例，或客户端没有真正调用工具。先调用 diagnostic() 或 tabs()。如果仍失败，重启 MCP 客户端。

tabs 为空

按顺序检查：

1. Chrome 是否打开了真实网页。
2. tmwd_cdp_bridge 是否已在 chrome://extensions 中启用。
3. 是否停留在 chrome://、about:blank、chrome-extension:// 这类扩展无法注入的页面。
4. 是否需要点击扩展页的刷新按钮，或重新加载扩展。
5. 是否有安全软件拦截 127.0.0.1:18765 的本地 WebSocket。

页面 CSP 导致脚本执行失败

扩展会尝试通过 CDP fallback 执行脚本。若仍失败，可改用 cdp("Runtime.evaluate", ...) 直接调试，或先确认当前标签页是否绑定正确。