内容
# 浏览器优化器 MCP
[](https://pypi.org/project/browser-optimizer-mcp/)
[](https://www.python.org/downloads/)
[](LICENSE)
一款建立在 **FastMCP** 和 **Playwright** 之上的优化中间件层。它位于 AI 代理（LLM）和浏览器自动化框架之间，旨在大幅减少 token 使用量、执行延迟和 API 推理成本，同时保持浏览器工作流的高准确性。
## 功能特点
- **大幅减少 token 使用量**：通过过滤掉非必需的 HTML 元素，减少 LLM token 使用量高达 98%。
- **智能元素提取**：识别和提取仅交互式 UI 组件（按钮、链接、输入框）。
- **语义缓存**：使用 xxhash 实现快速内存缓存，实现即时页面状态检索。
- **差异计算**：计算并返回连续页面状态之间的变化。
- **自动分类**：根据结构启发式动态分类页面。
## 快速安装
```bash
pip install browser-optimizer-mcp
browser-optimizer install
```
`install` 命令会自动执行以下设置：
- 检查本地 Python 版本（需要 >= 3.11）。
- 安装 Playwright 浏览器二进制文件（`chromium`）。
- 检测 **Claude Desktop** 并自动配置其 MCP 集成。
- 检测 **Antigravity IDE** 并自动配置其 MCP 集成。
- 为 **Cursor** 提供手动配置说明。
- 验证安装过程的端到端。
安装完成后，使用以下命令启动服务器：
```bash
browser-optimizer start
```
> **注意：** 在任何时候执行 `browser-optimizer doctor` 以对您的环境运行诊断检查。
---
## 工作原理与流程
### 1. 执行管道
当 AI 代理请求网页的上下文时，优化器执行以下顺序：
1. **请求接收**：AI 代理调用 `extract_context` 并提供目标 URL。
2. **浏览器导航**：浏览器管理器获取 Playwright 页面实例并导航到指定 URL。
3. **标记和可访问性捕获**：提取模块检索原始 HTML 标记并生成文档主体的语义 ARIA 快照。
4. **状态指纹识别**：语义缓存对原始 HTML 应用 xxhash 算法，以唯一标识页面状态。
* **缓存命中**：如果哈希与现有签名匹配，服务器在 1ms 内返回缓存的上下文，绕过 DOM 解析。
* **缓存未命中**：对于新或修改的页面，执行提取过程。
5. **上下文压缩**：压缩模块过滤掉样式、脚本、SVG 和样板结构元素（头部、脚部）。它隔离可交互组件，如按钮、输入框、下拉菜单和链接。
6. **任务分类**：基于规则的分类器评估交互元素以确定页面类别（例如，登录、产品搜索、结账）。
7. **差异计算**：差异引擎比较当前 UI 元素与上次观察的状态，仅返回添加或删除的组件。
8. **指标记录**：指标子系统记录数据量、压缩大小和效率比率。
9. **有效载荷交付**：包含优化的 UI 元素、ARIA 快照和页面元数据的精简 JSON 有效载荷返回给请求的代理。
### 2. 流程图
```mermaid
sequenceDiagram
autonumber
actor Agent as AI 代理（LLM）
participant Server as MCP 服务器（main.py）
participant Cache as 语义缓存（cache.py）
participant Browser as 浏览器管理器（manager.py）
participant Ext as 页面提取器（extractor.py）
participant Comp as 上下文压缩器（compressor.py）
participant Diff as 差异引擎（diff.py）
Agent->>Server: extract_context(url)
Server->>Browser: navigate(url)
Browser-->>Server: 页面加载
Server->>Cache: lookup(url, current_html)
alt 缓存命中（HTML 未更改）
Cache-->>Server: 返回缓存的上下文
else 缓存未命中（HTML 已更改 / 新 URL）
Server->>Ext: extract(page)
Ext-->>Server: 原始 html、标题、URL、ARIA 树
Server->>Comp: compress(extracted_data)
Comp-->>Server: 清理的 UI 元素列表、文本摘要
Server->>Cache: store(url, html, compressed_context)
end
Server->>Diff: compute_diff(url, current_ui)
Diff-->>Server: 添加和删除的 UI 元素
Server-->>Agent: 返回优化的 JSON 上下文
```
---
## 主要用例
浏览器优化器 MCP 设计用于促进各种 AI 驱动的自动化工作流：
1. **AI 代理的成本优化**：在复杂的网页上（例如电子商务平台或社交媒体动态）降低 token 消耗量高达 98%，显著减少 LLM API 费用。
2. **结构化数据提取**：使基于 LLM 的爬虫能够高效识别和提取内容，而无需解析脚本、样式或过多的 HTML 嵌套。
3. **自动化 UI 和端到端测试**：通过利用差异计算来识别结构回归，从而促进快速断言检查 UI 变化。
4. **智能表单自动化**：提供干净的交互元素树，使代理能够无缝地填充表单、身份验证或与自定义组件交互。
5. **实时页面监控**：使用差异计算观察活动页面是否有更新，仅在相关交互组件更改时提醒代理。
6. **网页搜索和 RAG 管道**：作为一个高效的爬虫，去除样板内容并为检索增强的生成工作流提供精炼的上下文。
7. **可访问性审计**：公开语义 ARIA 可访问性树，使自动化代理能够执行合规性检查。
8. **电子商务监控**：导航产品目录，分类页面类型，并提取价格或库存更新，数据传输量最小。
9. **动态单页应用（SPA）支持**：通过本地执行 Playwright、缓存状态和交付处理后的组件，管理现代 JavaScript 密集型框架。
10. **多代理会话共享**：作为多代理系统的一个标准化的 MCP 集成层，允许不同代理共享和交互一个统一的浏览器会话。
---
## MCP 工具参考
服务器向模型上下文协议环境公开以下工具：
| 工具 | 参数 | 返回类型 | 描述 |
| :--- | :--- | :--- | :--- |
| `extract_context` | `url`（字符串） | `CompressedContext` | 导航到 URL，执行清理和压缩，运行页面分类，并返回优化的 UI 和 ARIA 树。 |
| `page_diff` | `url`（字符串） | `PageDiff` | 返回与上次观察状态相比的增量（添加/删除的元素）。 |
| `execute_action` | `action`（字符串），`selector`（可选），`value`（可选） | `ActionResult` | 在活动页面上执行标准交互（`click`、`type`、`select`、`scroll`、`wait`、`navigate`）。 |
| `summarize_page` | `url`（字符串） | `Dict` | 生成一个简洁的文本摘要，详细介绍交互元素计数和相关的文本片段。 |
| `classify_page` | `url`（字符串） | `ClassificationResult` | 评估 UI 元素以分类页面（例如，登录、搜索、调查）。 |
| `wait_until_ready` | `url`（字符串），`timeout`（可选） | `ActionResult` | 导航到页面并暂停执行，直到浏览器稳定。 |
| `cache_lookup` | `url`（字符串） | `Dict` | 直接查询语义缓存以获取存储的上下文条目。 |
| `get_metrics` | 无 | `Dict` | 检索遥测数据，包括节省的字节数、缓存命中率和执行的总操作数。 |
---
## 架构和模块
应用程序在 `app/` 目录内以模块化结构，确保可维护性和关注点分离：
* **`app/browser/manager.py`**：管理异步 Playwright 浏览器生命周期。重用页面上下文以最小化启动延迟并处理导航约束。
* **`app/extractor/extractor.py`**：检索原始 HTML 并利用 Playwright `.aria_snapshot()` API 捕获可访问性结构。
* **`app/compressor/compressor.py`**：包含 DOM 过滤逻辑。删除多余的标签（脚本、样式、SVG）并生成结构化的 UI 控件列表。
* **`app/classifier/classifier.py`**：实现基于启发式的评分算法，以将页面分类为定义的 state（`LOGIN`、`SEARCH`、`SURVEY`、`CHECKOUT`、`PRODUCT`、`DASHBOARD`）。
* **`app/diff/diff.py`**：比较 URL 的连续观察结果并使用复合元素指纹构造增量报告。
* **`app/cache/cache.py`**：通过 URL 索引并通过 64 位 `xxhash` HTML 签名验证，维护一个内存中的 `cachetools.TTLCache`。
* **`app/executor/executor.py`**：确定性地处理标准浏览器交互。
* **`app/schemas/schemas.py`**：定义 Pydantic 数据模型，以确保所有模块和工具之间的严格合同合规性。
* **`app/metrics/metrics.py`**：记录数据大小减少、缓存性能指标和聚合字节节省。
---
## 设置和安装
### 1. 先决条件
* Python 3.11 或更高版本。
* Node.js（可选，取决于外部依赖）。
* Playwright 系统依赖。
### 2. 标准安装
```bash
# 克隆仓库
git clone https://github.com/yourusername/browser-optimizer-mcp.git
cd browser-optimizer-mcp
# 创建并激活虚拟环境
python -m venv venv
venv\Scripts\activate # Windows
source venv/bin/activate # macOS/Linux
# 安装依赖
pip install -r requirements.txt
# 安装 Playwright 浏览器二进制文件
playwright install chromium
```
### 3. 环境配置
在根目录中创建 `.env` 文件：
```env
LOG_LEVEL=INFO
HEADLESS=True
CACHE_ENABLED=True
CACHE_TTL=300
CACHE_MAX_SIZE=100
BROWSER_TIMEOUT=30000
```
---
## 客户端集成
### 1. Claude Desktop
在 `claude_desktop_config.json` 文件中添加以下配置。
* **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
* **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
#### Windows 配置（使用 `cmd` 包装器）：
```json
{
"mcpServers": {
"browser-optimizer": {
"command": "cmd",
"args": [
"/c",
"C:\\path\\to\\browser-optimizer-mcp\\venv\\Scripts\\python.exe",
"-m",
"app.server.main"
],
"env": {
"PYTHONPATH": "C:\\path\\to\\browser-optimizer-mcp"
}
}
}
}
```
#### macOS / Linux 配置：
```json
{
"mcpServers": {
"browser-optimizer": {
"command": "/path/to/browser-optimizer-mcp/venv/bin/python",
"args": ["-m", "app.server.main"],
"env": {
"PYTHONPATH": "/path/to/browser-optimizer-mcp"
}
}
}
}
```
### 2. Antigravity IDE
将以下内容附加到您的 `mcp_config.json` 文件中。
* **Windows**：`%USERPROFILE%\.gemini\config\mcp_config.json`
* **macOS/Linux**：`~/.gemini/config/mcp_config.json`
```json
{
"mcpServers": {
"browser-optimizer": {
"command": "C:\\path\\to\\browser-optimizer-mcp\\venv\\Scripts\\python.exe",
"args": ["-m", "app.server.main"],
"env": {
"PYTHONPATH": "C:\\path\\to\\browser-optimizer-mcp"
}
}
}
}
```
### 3. Cursor
1. 导航到 **设置** -> **功能** -> **MCP**。
2. 选择 **+ 添加新 MCP 服务器**。
3. 应用以下设置：
* **名称**：`browser-optimizer`
* **类型**：`command`
* **命令**：`C:\path\to\browser-optimizer-mcp\venv\Scripts\python.exe -m app.server.main`
4. 设置环境变量 `PYTHONPATH` = `C:\path\to\browser-optimizer-mcp`。
5. 点击 **保存**。
---
## 基准测试和工具比较
**浏览器优化器 MCP** 与标准浏览器自动化代理的直接比较表明效率有显著提高：
### 1. 性能比较
| 指标 / 功能 | 标准浏览器工具 | 浏览器优化器 MCP |
| :--- | :--- | :--- |
| **平均 token 数量（Google）** | ~50,000+ token | **~120 token**（97.7% 减少） |
| **平均 token 数量（HN）** | ~9,000+ token | **~1,500 token**（87.8% 减少） |
| **观察有效载荷类型** | 原始 DOM 或 Base64 截图 | **干净的 JSON UI 控件 + ARIA 快照** |
| **增量观察** | 重新发送整个 DOM 或新的截图 | **仅返回元素增量（添加/删除）** |
| **重新观察延迟** | 完整的 DOM 下载和解析（~1.5s） | **内存缓存查找**（~0.12ms） |
| **页面分类** | 需要 LLM API 调用和推理 token | **即时、基于本地规则的启发式**（0 token） |
| **操作执行** | LLM 必须逐步推理 | **确定性的基于规则的执行** |
| **推理成本** | 高（$0.15 - $1.00+ 每步） | **极低**（80-95% 成本减少） |
### 2. 运行基准测试套件
在实时公共页面上运行基准测试套件以验证效率指标：
```powershell
$env:PYTHONPATH="."
venv/Scripts/python scripts/benchmark.py
```
---
## 测试和部署
### 运行单元测试
使用 `pytest` 运行测试套件：
```bash
pytest tests/ -v
```
### Docker 部署
使用 Docker Compose 部署服务：
```bash
docker compose -f docker/docker-compose.yml up --build
```
---
## 贡献
欢迎贡献。请确保您的拉取请求符合已建立的编码标准，并包含适当的单元测试。首先打开一个问题以讨论重大架构更改。
---
## 支持和故障排除
如果您在安装或运行时遇到问题：
1. 运行 `browser-optimizer doctor` 以诊断环境不一致性。
2. 验证您的 Python 版本是否为 `>= 3.11`。
3. 检查 `logs/` 目录中的详细异常跟踪。
4. 如果问题仍然存在，请在仓库中打开一个问题。
---
## 许可证
在 MIT 许可证下分发。有关更多信息，请参见 [LICENSE](LICENSE)。
版权所有 (c) 2026 Manthan。
