Lv.0
# brosdk-mcp-go 深度教程：让 AI Agent 掌控指纹浏览器
brosdk-mcp-go 是一个将 BroSDK 指纹浏览器 SDK 封装为 MCP (Model Context Protocol) SSE 服务的 Go 项目。通过它，AI Agent（如 Claude、CodeBuddy 等）可以直接操控指纹浏览器环境，实现浏览器自动化、环境管理、录制回放等能力。
---
## 一、项目概览
### 1.1 什么是 brosdk-mcp-go？
简单来说，brosdk-mcp-go 是一个**桥梁**——它把 BroSDK 指纹浏览器的底层能力，通过 MCP 协议暴露为 72 个标准化的 Tool，让 AI Agent 可以像调用函数一样控制浏览器。
### 1.2 核心能力一览
| 能力类别 | 说明 |
|---------|------|
| **72 个 MCP Tool** | 覆盖 SDK 生命周期、浏览器控制、环境 CRUD、录制回放等全部能力 |
| **Cookie 实时回调** | SDK 级别拦截 cookie 变更，通过 SSE `cookies-event` 实时广播 |
| **高层浏览器操作** | 基于 chromedp 实现点击、输入、截图、PDF 等 37+ 种操作，无需手写 CDP 命令 |
| **透明 CDP 代理** | 保留 `browser_command` 工具，支持所有 DevTools 命令的高级/自定义场景 |
| **录制回放** | `record_start` → 操作自动捕获 → `record_stop` 保存场景，`scene_replay` 一键回放 |
| **跨平台** | Windows / macOS 原生支持，首次运行自动下载对应动态库 |
### 1.3 适用场景
- **AI 驱动的浏览器自动化**：让 AI Agent 自主完成网页操作
- **指纹浏览器环境管理**：批量创建、切换、销毁浏览器环境
- **自动化测试与录制回放**：录制用户操作并回放
- **爬虫与数据采集**：结合指纹浏览器规避反爬
---
## 二、架构解析
理解架构有助于更好地使用和调试。以下是项目的核心分层：
```
Agent / MCP Client
│
▼
┌──────────────────────────────────────┐
│ MCP SSE Server (net/http) │ ← SSE 流 + JSON-RPC 2.0
│ internal/mcp/server.go │
└───────────────┬──────────────────────┘
│
┌───────────────▼──────────────────────┐
│ Tool Layer │ ← 72 个 Tool 定义与分发
│ internal/tools/tools.go │
└───────────────┬──────────────────────┘
│
┌───────────────▼──────────────────────┐
│ Browser Actions Layer (chromedp) │ ← 37+ 高层操作
│ internal/brosdk/actions.go │
└───────────────┬──────────────────────┘
│
┌───────────────▼──────────────────────┐
│ Native Layer (syscall / CGo) │ ← brosdk.dll / .dylib
│ internal/brosdk/native_*.go │
└───────────────┬──────────────────────┘
│
┌───────────────▼──────────────────────┐
│ CDP Proxy │ ← DevTools 原始命令转发
│ internal/brosdk/cdp.go │
└──────────────────────────────────────┘
```
### 2.1 关键设计决策
- **传输层**：采用 SSE + Streamable HTTP，符合 MCP 2024-11-05 和 2025-03-26 规范
- **FFI 策略**：Windows 使用 `syscall.LazyDLL`（无 CGo），macOS 使用 CGo + dlopen
- **浏览器操作**：基于 chromedp v0.15.1 提供高层 API
- **配置加载**：`config.local.json` → `config.json` 优先级加载，支持环境变量覆盖
---
## 三、安装与配置
### 3.1 前置要求
- **操作系统**：Windows x64 或 macOS arm64
- **Go 版本**：1.26+
- **原生库**：首次运行自动从 GitHub Releases 下载，无需手动准备
### 3.2 编译
```bash
# Windows / macOS — 生产编译
go build -o brosdk-mcp .
```
构建约束会自动匹配平台：
- Windows: `//go:build windows`
- macOS: `//go:build darwin`
- 其他: `//go:build !windows && !darwin`
### 3.3 配置文件
启动时按顺序读取 `config.local.json` → `config.json`，找到即用。
**配置文件格式**：
```json
{
"apiKey": "your-customer-id"
}
```
> **重要**：启动时**必须提供 apiKey**。`apiKey` 即你的 BroSDK 客户 ID。
### 3.4 环境变量覆盖
可以通过环境变量覆盖配置项，格式为 `BROSDK_` 前缀 + 大写配置键名。
---
## 四、核心功能详解
### 4.1 SDK 信息与认证（3 个工具）
| 工具 | 类型 | 说明 |
|------|------|------|
| `sdk_info` | 同步 | 获取 SDK 运行时信息：版本、状态、配置 |
| `sdk_token_update` | 异步 | 刷新 userSig |
| `sdk_get_user_sig` | 同步 | 通过 API 获取 userSig，参数：apiKey、duration |
**使用示例**（AI Agent 调用）：
```
# 获取 SDK 状态
调用 sdk_info → 返回 {version, status, config}
# 刷新认证令牌
调用 sdk_token_update → 返回 reqId，结果通过 SSE 回传
```
### 4.2 浏览器控制（6 个工具）
| 工具 | 类型 | 说明 |
|------|------|------|
| `browser_install` | 异步 | 安装/更新浏览器内核 |
| `browser_info` | 同步 | 列出所有运行中的环境 |
| `browser_select` | 同步 | 设置当前激活的浏览器环境 |
| `browser_open` | 异步 | 打开浏览器，支持传入 URL 和启动参数 |
| `browser_close` | 异步 | 关闭浏览器 |
| `browser_command` | 同步 | 原始 CDP 命令代理 |
> **注意**：`envId` 在多数浏览器操作中是可选的——系统会通过 `browser_select` 自动解析当前环境。只有 `browser_open`、`browser_close`、`browser_select`、`browser_command` 和 `env_*` 工具要求显式提供 `envId`。
**典型工作流**：
```
1. browser_install → 确保浏览器内核已安装
2. env_create → 创建浏览器环境（获得 envId）
3. browser_open envId → 启动浏览器
4. browser_select envId → 设为当前环境
5. 执行各种 browser_* 操作...
6. browser_close envId → 关闭浏览器
```
### 4.3 浏览器操作（50 个工具）
这是最丰富的工具类别，涵盖页面导航、鼠标、键盘、表单、滚动、截图等。
#### 页面导航
| 工具 | 说明 |
|------|------|
| `browser_navigate` | 导航到 URL |
| `browser_reload` | 刷新当前页面 |
| `browser_back` | 后退 |
| `browser_forward` | 前进 |
| `browser_snapshot` | 捕获无障碍树（AX Tree），`interactiveOnly=true` 可过滤交互节点，输出减少 10-50 倍 |
#### 鼠标操作
| 工具 | 说明 |
|------|------|
| `browser_click` | CSS 选择器点击 |
| `browser_click_ref` | 通过 snapshot ref 点击 |
| `browser_dblclick` | 双击 |
| `browser_hover` | 悬停 |
| `browser_hover_ref` | 通过 snapshot ref 悬停 |
#### 键盘与输入
| 工具 | 说明 |
|------|------|
| `browser_type` | CSS 选择器输入（追加） |
| `browser_type_ref` | 通过 snapshot ref 输入（追加） |
| `browser_fill` | 清空 + 输入 |
| `browser_fill_ref` | 通过 snapshot ref 清空 + 输入 |
| `browser_press_key` | 按下按键（Enter、Escape、Tab 等） |
| `browser_keyboard_type` | 逐字符输入 |
#### 其他操作
还包括截图、PDF 导出、滚动、等待元素、执行 JavaScript 等工具，完整列表参见 [tools-reference.md](https://github.com/browsersdk/brosdk-mcp-go/blob/master/docs/tools-reference.md)。
### 4.4 环境管理（env_* 工具）
环境（Environment）是 BroSDK 的核心概念——每个环境代表一个独立的浏览器配置文件，包含独立的 cookies、存储、指纹设置等。
| 工具 | 说明 |
|------|------|
| `env_create` | 创建新环境，自动填充环境 ID |
| `env_list` | 列出所有环境 |
| `env_delete` | 删除环境 |
| `env_update` | 更新环境配置 |
### 4.5 异步工具与 SSE 事件
**重要**：所有异步工具（标记为 `async`）调用后立即返回 `reqId`，实际结果通过 SSE 的 `sdk-event` 事件回传。
这意味着 AI Agent 需要：
1. 调用异步工具，获取 `reqId`
2. 监听 SSE 流，等待对应 `reqId` 的结果事件
3. 根据结果决定后续操作
此外，Cookie 变更会通过独立的 `cookies-event`（SSE）广播，独立于工具调用。
---
## 五、高级功能：录制回放
这是 brosdk-mcp-go 最强大的特性之一。
### 5.1 录制流程
```
record_start → 用户操作（自动捕获）→ record_stop → 场景保存
```
**相关工具**：
| 工具 | 说明 |
|------|------|
| `record_start` | 开始录制，可指定场景名称 |
| `record_stop` | 停止录制，自动保存场景 |
| `scene_list` | 列出所有已保存场景 |
| `scene_replay` | 回放指定场景 |
| `scene_delete` | 删除场景 |
### 5.2 变量替换
录制回放支持 `{{变量名}}` 语法，回放时可以动态替换。例如：
- 录制时输入 `{{username}}`
- 回放时传入 `{"username": "test_user"}`
这使得同一个场景可以用不同数据重复执行。
### 5.3 智能等待
录制器内置了 `WaitFor` 推断能力，可以自动识别页面加载和元素出现时机。
---
## 六、实战案例
### 案例一：AI 自动登录并截图
```mermaid
sequenceDiagram
participant AI as AI Agent
participant MCP as MCP Server
participant Browser as 指纹浏览器
AI->>MCP: env_create
MCP-->>AI: envId
AI->>MCP: browser_open(envId)
MCP-->>AI: 浏览器已启动
AI->>MCP: browser_navigate(https://example.com/login)
MCP-->>AI: 导航完成
AI->>MCP: browser_fill(#username, "user")
AI->>MCP: browser_fill(#password, "pass")
AI->>MCP: browser_click(#login-btn)
MCP-->>AI: 点击完成
AI->>MCP: browser_screenshot
MCP-->>AI: 截图数据
```
### 案例二：录制回放工作流
```
# 1. 开始录制
record_start(scene_name="login_flow")
# 2. 执行操作（自动捕获）
browser_navigate("https://example.com")
browser_type("#search", "{{keyword}}")
browser_click("#search-btn")
# 3. 停止录制
record_stop → 场景 "login_flow" 已保存
# 4. 回放（带变量替换）
scene_replay(scene_name="login_flow", variables={"keyword": "AI automation"})
```
### 案例三：Cookie 监控
通过注册 `mgr.OnCookies()` 回调，所有 cookie 变更都会通过 SSE `cookies-event` 广播。这对于以下场景非常有用：
- 检测登录状态变化
- 监控会话过期
- 跨环境同步 cookie
---
## 七、最佳实践
### 7.1 环境管理
- **为不同任务使用独立环境**：每个自动化任务使用独立的环境（envId），避免相互干扰
- **及时清理**：任务完成后调用 `browser_close` 和 `env_delete` 释放资源
- **环境复用**：对于频繁使用的配置（如已登录状态），可以保存环境 ID 复用
### 7.2 操作策略
- **优先使用高层工具**：日常操作使用 `browser_click`、`browser_fill` 等高层工具，无需关心 CDP 细节
- **snapshot 优先于 selector**：使用 `browser_snapshot` 获取页面结构后，通过 `ref` 定位元素更可靠
- **善用 interactiveOnly**：`browser_snapshot(interactiveOnly=true)` 可大幅减少输出
### 7.3 异步处理
- 异步工具调用后，必须监听 SSE 流获取结果
- 对于长时间操作（如页面加载），设置合理的超时
- 使用 `reqId` 关联请求与响应
### 7.4 配置管理
- 开发环境使用 `config.local.json`（加入 .gitignore）
- 生产环境使用 `config.json`
- 敏感信息（如 apiKey）优先使用环境变量
### 7.5 调试技巧
- 项目内置了 MCP Inspector Web UI（`internal/mcp/inspector.html`），可通过浏览器直接调试
- 使用 `browser_command` 可以发送任意 CDP 命令，用于调试复杂场景
- 日志使用 `log/slog` 结构化输出，便于问题排查
---
## 八、总结
brosdk-mcp-go 为 AI Agent 提供了完整的指纹浏览器控制能力。通过 72 个标准化的 MCP Tool，开发者可以：
1. **快速集成**：无需了解 BroSDK 底层细节，通过 MCP 协议即可调用
2. **灵活扩展**：高层操作 + 透明 CDP 代理，覆盖从简单到复杂的全部场景
3. **高效开发**：录制回放功能大幅降低自动化脚本编写成本
4. **生产可用**：跨平台支持、自动库下载、结构化日志，开箱即用
---
## 参考资料
- [项目仓库](https://github.com/browsersdk/brosdk-mcp-go)
- [架构设计文档](https://github.com/browsersdk/brosdk-mcp-go/blob/master/docs/ARCHITECTURE.md)
- [完整工具 API 参考](https://github.com/browsersdk/brosdk-mcp-go/blob/master/docs/tools-reference.md)
- [MCP 协议规范](https://modelcontextprotocol.io/)