# agent-browser-ga MCP

> 本项目的浏览器通信 / web bridge 代码提取自 [GenericAgent](https://github.com/lsdefine/GenericAgent/tree/main)，主要包含 `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`。

## 架构

```text
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 命令。

## 文件结构

```text
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 或更高版本。确认命令：

```powershell
python --version
```

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

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

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

```powershell
python -m pip install -r requirements.txt
```

### 2. 确认内置 web bridge 代码

```powershell
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. 优先选择本仓库自带的扩展目录：

```text
~\extension\tmwd_cdp_bridge
```

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

```text
%USERPROFILE%\GenericAgent\assets\tmwd_cdp_bridge
```

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

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

### 4. 安装配套 Skill

本仓库包含配套 skill：

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

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

Codex 常见安装位置：

```powershell
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`，使用：

```powershell
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 常见安装位置：

```powershell
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

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

```powershell
python .\register.py
```

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

#### Codex

编辑：

```text
%USERPROFILE%\.codex\config.toml
```

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

```toml
[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，例如：

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

#### Claude / Claude Code

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

```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`：

```powershell
python .\register.py --write-claude
```

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

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

### 6. 重启 MCP Client

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

### 7. 验证连接

在 MCP 客户端里调用：

```text
diagnostic()
```

期望看到：

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

然后调用：

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

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

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

## 使用示例

读取当前页面标题：

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

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

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

截图：

```text
screenshot(full_page=true)
```

读取 Cookie：

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

发送 CDP 命令：

```text
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 没有安装依赖。

检查：

```powershell
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：

```powershell
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", ...)` 直接调试，或先确认当前标签页是否绑定正确。