# https://github.com/hangwin/mcp-chrome 项目说明书
生成时间：2026-05-13 11:45:57 UTC
## 目录
- [项目介绍](#introduction)
- [快速开始](#quick-start)
- [系统架构设计](#architecture)
- [Chrome 扩展架构](#chrome-extension-structure)
- [本地服务器架构](#native-server-architecture)
- [浏览器工具集](#browser-tools)
- [录制回放系统 (V3)](#record-replay-v3)
- [可视化编辑器](#visual-editor)
- [语义搜索与向量数据库](#semantic-search)
- [AI Agent 集成](#agent-integration)
## 项目介绍
### 相关页面
相关主题：[快速开始](#quick-start), [系统架构设计](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/hangwin/mcp-chrome/blob/main/README.md)
- [app/chrome-extension/entrypoints/welcome/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/welcome/index.html)
- [app/chrome-extension/entrypoints/builder/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/builder/index.html)
- [app/chrome-extension/entrypoints/sidepanel/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/sidepanel/index.html)
- [app/chrome-extension/entrypoints/popup/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/popup/index.html)
- [app/chrome-extension/entrypoints/options/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/options/index.html)
- [app/chrome-extension/utils/indexeddb-client.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/indexeddb-client.ts)
- [app/chrome-extension/utils/lru-cache.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/lru-cache.ts)
# 项目介绍
## 概述
mcp-chrome 是一个基于 Chrome 扩展实现的 **MCP (Model Context Protocol) Server**，它将 Chrome 浏览器的控制能力以标准化的工具接口暴露给 AI 助手使用。通过这个项目，AI 可以直接操控浏览器完成网页自动化、网页内容提取、用户脚本管理等多种复杂任务。资料来源：[README.md]()
### 核心特性
| 特性 | 描述 |
|------|------|
| MCP 协议支持 | 遵循 Model Context Protocol 标准，与各类 AI 助手无缝集成 |
| 浏览器完全控制 | 提供标签页管理、导航控制、截图等完整功能 |
| 工作流自动化 | 支持录制、回放自定义浏览器操作工作流 |
| 网页内容分析 | AI 语义搜索、HTML 内容提取、交互元素识别 |
| 网络监控 | 支持 webRequest 和 Debugger API 进行网络请求分析 |
资料来源：[README.md]()
---
## 系统架构
### 整体架构图
```mermaid
graph TB
subgraph "AI 助手层"
AI[AI Assistant]
end
subgraph "MCP 协议层"
MCP[MCP Server]
end
subgraph "Chrome 扩展层"
subgraph "后台脚本"
BG[Background Script]
RR[Record-Replay Engine]
end
subgraph "入口点"
POP[Popup]
SP[Side Panel]
BLD[Builder]
WEL[Welcome]
OPT[Options]
end
subgraph "注入脚本"
EM[Element Marker]
WF[Web Fetcher]
end
end
subgraph "浏览器 API 层"
TABS[Chrome Tabs API]
NR[Network APIs]
DB[IndexedDB]
end
AI --> MCP
MCP --> BG
BG --> RR
BG --> TABS
BG --> NR
BG --> DB
POP --> BG
SP --> BG
BLD --> BG
EM --> WF
WF --> TABS
```
### 扩展入口点架构
项目定义了多个独立的扩展入口点，每个入口点对应不同的用户界面和功能场景。资料来源：[app/chrome-extension/entrypoints/welcome/index.html]()、[app/chrome-extension/entrypoints/sidepanel/index.html]()、[app/chrome-extension/entrypoints/builder/index.html]()
| 入口点 | 类型 | 功能描述 |
|--------|------|----------|
| welcome | unlisted_page | 欢迎页面，Chrome MCP Server 启动引导 |
| sidepanel | side_panel | 工作流管理侧边栏 |
| builder | unlisted_page | 工作流编辑器，支持拖拽式工作流设计 |
| popup | browser_action | 浏览器动作弹出窗口 |
| options | options_page | Userscripts 脚本管理器 |
| offscreen | offscreen | 后台离屏文档，用于音频播放等后台任务 |
资料来源：[app/chrome-extension/entrypoints/popup/index.html]()、[app/chrome-extension/entrypoints/options/index.html]()、[app/chrome-extension/entrypoints/offscreen/index.html]()
---
## 工具功能体系
### 浏览器控制工具
项目提供 6 个浏览器控制类工具，覆盖标签页管理、导航控制、脚本注入等场景。资料来源：[README.md]()
| 工具名称 | 功能 | 输入参数 |
|----------|------|----------|
| chrome_manage_tabs | 打开、创建、重新加载标签页 | action, url, tabId |
| chrome_viewport_control | 控制视口缩放和滚动 | zoom, scrollX, scrollY |
| chrome_switch_tab | 切换当前活动标签页 | tabId |
| chrome_close_tabs | 关闭指定标签页或窗口 | tabIds, windowId |
| chrome_go_back_or_forward | 浏览器导航前进/后退 | direction |
| chrome_inject_script | 向网页注入内容脚本 | script |
| chrome_send_command_to_inject_script | 向注入脚本发送命令 | command |
### 交互操作工具
提供 3 个用户交互模拟工具，支持模拟真实用户行为。资料来源：[README.md]()
| 工具名称 | 功能描述 |
|----------|----------|
| chrome_click_element | 使用 CSS 选择器点击页面元素 |
| chrome_fill_or_select | 填写表单字段或选择下拉选项 |
| chrome_keyboard | 模拟键盘输入和快捷键组合 |
### 截图与视觉工具
| 工具名称 | 功能描述 |
|----------|----------|
| chrome_screenshot | 高级截图捕获，支持元素定位、全页面截图和自定义尺寸 |
### 数据管理工具
提供 5 个书签和历史记录管理工具。资料来源：[README.md]()
| 工具名称 | 功能描述 |
|----------|----------|
| chrome_history | 按时间范围搜索浏览器历史记录 |
| chrome_bookmark_search | 按关键词搜索书签 |
| chrome_bookmark_add | 添加新书签，支持文件夹分类 |
| chrome_bookmark_delete | 删除指定书签 |
### 网络监控工具
支持 4 种网络监控方式，基于 Chrome 扩展的网络 API 实现。资料来源：[README.md]()
| 工具名称 | API 来源 | 功能 |
|----------|----------|------|
| chrome_network_capture_start/stop | webRequest API | 拦截网络请求 |
| chrome_network_debugger_start/stop | Debugger API | 带响应体的深度调试 |
| chrome_network_request | - | 发送自定义 HTTP 请求 |
### 内容分析工具
提供 4 个 AI 辅助内容分析工具。资料来源：[README.md]()
| 工具名称 | 功能描述 |
|----------|----------|
| search_tabs_content | AI 语义搜索跨标签页内容 |
| chrome_get_web_content | 提取网页 HTML 或文本内容 |
| chrome_get_interactive_elements | 识别页面可点击交互元素 |
| chrome_console | 捕获并获取浏览器控制台输出 |
---
## 工作流引擎
### Record-Replay 架构
项目包含完整的工作流录制与回放引擎，支持复杂浏览器自动化场景。引擎采用节点图结构定义工作流，通过调度器执行。资料来源：[app/chrome-extension/entrypoints/background/record-replay/engine/runners/subflow-runner.ts]()
```mermaid
graph LR
subgraph "工作流定义"
S1[Step 节点]
S2[Step 节点]
E1[边 - Default]
E2[边 - On Error]
end
subgraph "执行引擎"
SCH[Scheduler]
RUN[Subflow Runner]
end
S1 --> E1 --> S2
S1 --> E2 --> SCH
SCH --> RUN
```
### 节点类型与边
引擎使用 `indeg` (入度) 和 `outEdges` (出边) 管理节点图结构，通过以下规则确定执行顺序：
1. **根节点识别**：查找入度为 0 且非 TRIGGER 类型的节点作为首个可执行节点
2. **边标签选择**：DEFAULT 标签表示默认执行路径，ON_ERROR 标签表示错误处理路径
3. **迭代保护**：通过 MAX_ITERATIONS 限制最大执行次数，防止循环工作流导致的死循环
资料来源：[app/chrome-extension/entrypoints/background/record-replay/engine/scheduler.ts]()
### 消息分类处理
引擎通过 `useAgentThreads` composable 对 AI 消息进行分类，识别不同类型的操作意图。资料来源：[app/chrome-extension/entrypoints/sidepanel/composables/useAgentThreads.ts]()
| 工具类型 | 识别规则 | 显示标签 |
|----------|----------|----------|
| Edit | 包含 'edit'、'apply_patch'、'patch_file' | Edit |
| Write | 包含 'write'、'create_file' | Write |
| Run | 'bash'、'shell'、以 'Running:'/'Ran:' 开头 | Run |
| Grep | 'grep'、'search'、有 pattern 参数 | Grep |
---
## 数据存储
### IndexedDB 客户端
项目实现了统一的 IndexedDB 客户端封装，提供 Promise 化的数据库操作接口。资料来源：[app/chrome-extension/utils/indexeddb-client.ts]()
| 方法 | 模式 | 功能 |
|------|------|------|
| getAll | readonly | 获取指定仓库所有数据 |
| get | readonly | 根据 key 获取单条数据 |
| put | readwrite | 插入或更新数据 |
| delete | readwrite | 删除指定 key 的数据 |
| clear | readwrite | 清空指定仓库 |
| putMany | readwrite | 批量插入数据 |
### LRU 缓存
项目实现了线程安全的 LRU (Least Recently Used) 缓存模块。资料来源：[app/chrome-extension/utils/lru-cache.ts]()
```typescript
class LRUNode {
key: K;
value: V;
prev: LRUNode | null;
next: LRUNode | null;
frequency: number; // 访问频率
lastAccessed: number; // 最近访问时间戳
}
```
缓存策略结合访问频率和最近访问时间进行淘汰判定，容量默认值为 100。
---
## 元素标注系统
### Element Marker 组件
Element Marker 是一个嵌入到网页中的交互式元素选择器组件，支持两种选择模式。资料来源：[app/chrome-extension/inject-scripts/element-marker.js]()
| 选择模式 | 功能 | 支持格式 |
|----------|------|----------|
| 单选模式 | 选择单个元素 | CSS Selector / XPath |
| 列表模式 | 批量标注相似元素 | 仅 CSS Selector |
### 选择器类型
| 类型 | 示例 | 说明 |
|------|------|------|
| CSS Selector | `#__em_selector_type` | 通过 CSS 选择器定位 |
| XPath | `//button[@id='submit']` | 通过 XML 路径定位 |
---
## Web 内容获取
### Web Fetcher Helper
内容提取算法基于 Readability 算法改进，通过多维度评分机制识别页面主体内容。资料来源：[app/chrome-extension/inject-scripts/web-fetcher-helper.js]()
#### 内容评分规则
| 评分因素 | 权重说明 |
|----------|----------|
| 标签类型 | article、section、div 等不同标签基础分不同 |
| 段落文本长度 | 每 100 字符加 1 分，最多 3 分 |
| 逗号分隔 | 每增加一个逗号加 1 分 |
| 链接密度 | 高链接密度的内容会降低最终得分 |
| 祖先节点层级 | 父节点不除、祖节点除 2、曾祖节点及以上乘 3 |
#### 候选节点处理流程
```mermaid
graph TD
A[遍历所有节点] --> B{是否为候选内容节点?}
B -->|是| C[初始化 Readability 分数]
B -->|否| D[跳过]
C --> E[计算内容分数]
E --> F[向祖先节点累加加权分数]
F --> G{还有祖先节点?}
G -->|是| F
G -->|否| H[收集所有候选节点]
H --> I[计算最终分数]
I --> J[按链接密度调整]
J --> K[返回最高分节点]
```
---
## 应用示例
### 场景一：AI 辅助网页摘要与图表绘制
AI 可以先分析当前页面内容，提取关键信息后自动控制 Excalidraw 等绘图工具生成图表。资料来源：[README.md]()
**提示词示例：**
> Help me summarize the current page content, then draw a diagram to aid my understanding.
### 场景二：图像分析与复现
AI 可以分析网页中的图像内容，然后结合分析结果和图像本身复制图像。资料来源：[README.md]()
**流程：**
1. 接收图像 URL
2. 使用 content-analize 工具分析图像内容
3. 通过 Excalidraw 工具复现图像
### 场景三：浏览器自动化工作流
通过录制用户操作生成工作流，实现复杂浏览器自动化任务。
---
## 技术栈
| 层级 | 技术选型 |
|------|----------|
| 前端框架 | Vue 3 (Composition API) |
| 扩展框架 | WXT (Modern Chrome Extension Framework) |
| 协议 | Model Context Protocol (MCP) |
| 存储 | IndexedDB |
| 构建工具 | Vite |
| 语言 | TypeScript |
---
## 快速开始
### 安装步骤
1. 克隆项目仓库
2. 安装依赖：`pnpm install`
3. 构建扩展：`pnpm build`
4. 在 Chrome 中加载 `dist/chrome-extension` 目录
### 配置 MCP Server
在 AI 助手的 MCP 配置中添加以下配置：
```json
{
"mcpServers": {
"chrome": {
"command": "path/to/mcp-chrome-server",
"args": []
}
}
}
---
## 快速开始
### 相关页面
相关主题：[项目介绍](#introduction)
相关源码文件
以下源码文件用于生成本页说明：
- [app/chrome-extension/package.json](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/package.json)
- [app/native-server/package.json](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/package.json)
- [app/native-server/install.md](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/install.md)
- [app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)
- [app/native-server/src/scripts/doctor.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/doctor.ts)
- [app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)
- [README.md](https://github.com/hangwin/mcp-chrome/blob/main/README.md)
# 快速开始
本文档为 **mcp-chrome** 项目提供完整的快速上手指南，帮助你在最短时间内完成环境搭建并开始使用 Chrome MCP Server。
## 项目概述
mcp-chrome 是一个基于 Chrome 扩展和本地原生消息（Native Messaging）通信协议的 MCP（Model Context Protocol）服务器实现。它允许 AI 模型通过标准化的接口直接控制 Chrome 浏览器，完成网页交互、内容提取、网络监控等任务。
## 系统架构
```mermaid
graph TD
subgraph "客户端层"
A[AI Model / Claude]
B[MCP Client SDK]
end
subgraph "Chrome Extension"
C[Side Panel UI]
D[Background Service Worker]
E[Content Scripts]
end
subgraph "Native Server"
F[MCP Server Core]
G[Browser Controller]
H[Native Messaging Host]
end
subgraph "Browser"
I[Chrome Browser]
J[Extension API]
end
A --> B
B --> C
C --> D
D --> E
E --> J
D --> H
H --> F
F --> G
G --> J
J --> I
style A fill:#e1f5fe
style I fill:#fff3e0
style H fill:#f3e5f5
```
## 前置要求
| 组件 | 版本要求 | 说明 |
|------|----------|------|
| Node.js | ≥ 18.0.0 | 本地服务器运行环境 |
| npm / pnpm | 最新稳定版 | 包管理工具 |
| Chrome / Chromium | ≥ 120 | 目标浏览器 |
| 支持的操作系统 | Windows / macOS / Linux | 完整支持三大平台 |
资料来源：[app/native-server/package.json](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/package.json)
## 安装步骤
### 步骤 1：安装原生服务器
原生服务器负责处理 AI 模型与 Chrome 浏览器之间的原生消息通信。
```bash
# 克隆项目
git clone https://github.com/hangwin/mcp-chrome.git
cd mcp-chrome
# 进入原生服务器目录
cd app/native-server
# 安装依赖
pnpm install
# 或
npm install
```
### 步骤 2：构建项目
```bash
# 构建原生服务器
pnpm build
# 构建 Chrome 扩展
cd ../chrome-extension
pnpm install
pnpm build
```
资料来源：[app/chrome-extension/package.json](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/package.json)
### 步骤 3：注册原生消息主机
根据你的操作系统和浏览器，需要配置 Native Messaging Host 清单文件。
#### Windows 系统
```powershell
# 用户级注册（推荐）
.\dist\cli.js register --browser chrome
# 或系统级注册（需要管理员权限）
.\dist\cli.js register --browser chrome --system
```
#### macOS 系统
```bash
# 用户级注册
./dist/cli.js register --browser chrome
# 系统级注册（需要 sudo）
sudo ./dist/cli.js register --browser chrome --system
```
#### Linux 系统
```bash
# 用户级注册
./dist/cli.js register --browser chrome
# 系统级注册
sudo ./dist/cli.js register --browser chrome --system
```
资料来源：[app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)
### 步骤 4：安装 Chrome 扩展
1. 打开 Chrome，访问 `chrome://extensions/`
2. 开启右上角的「开发者模式」
3. 点击「加载已解压的扩展程序」
4. 选择 `app/chrome-extension/dist` 目录
## 清单文件路径配置
不同平台和浏览器的 Native Messaging Host 清单文件路径如下：
| 平台 | 浏览器 | 用户级路径 | 系统级路径 |
|------|--------|------------|------------|
| Windows | Chrome | `%APPDATA%\Google\Chrome\User Data\Default\Extensions\...` | `%ProgramFiles%\Google\Chrome\NativeMessagingHosts\` |
| Windows | Chromium | `%APPDATA%\Chromium\User Data\Default\Extensions\...` | `%ProgramFiles%\Chromium\NativeMessagingHosts\` |
| macOS | Chrome | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/` | `/Library/Google/Chrome/NativeMessagingHosts/` |
| macOS | Chromium | `~/Library/Application Support/Chromium/NativeMessagingHosts/` | `/Library/Application Support/Chromium/NativeMessagingHosts/` |
| Linux | Chrome | `~/.config/google-chrome/NativeMessagingHosts/` | `/etc/opt/chrome/native-messaging-hosts/` |
| Linux | Chromium | `~/.config/chromium/NativeMessagingHosts/` | `/etc/chromium/native-messaging-hosts/` |
资料来源：[app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)
## 验证安装
使用诊断命令检查安装状态：
```bash
cd app/native-server
pnpm doctor
```
诊断脚本会检查以下项目：
1. **Node.js 版本** - 确认 Node 环境正确
2. **原生服务器可执行文件** - 验证 `mcp-chrome` 可执行文件存在
3. **清单文件** - 检查各平台 Native Messaging Host 配置
4. **Windows 注册表**（仅 Windows）- 验证注册表项正确设置
5. **浏览器连接** - 确认扩展与服务器可以正常通信
资料来源：[app/native-server/src/scripts/doctor.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/doctor.ts)
### 常见诊断结果
| 检查项 | 状态 | 说明 |
|--------|------|------|
| manifest.chrome | ok | Chrome 清单文件正确 |
| manifest.chrome | error | 清单文件不存在或配置错误 |
| windowsRegistry | ok | 注册表项正确（仅 Windows） |
## MCP 客户端配置
安装完成后，在你的 MCP 客户端配置文件中添加以下配置：
```json
{
"mcpServers": {
"chrome": {
"command": "node",
"args": ["/path/to/mcp-chrome/app/native-server/dist/index.js"]
}
}
}
```
## 可用工具一览
安装成功后，以下工具将自动可用：
### 🌐 标签页管理（5 个工具）
| 工具名称 | 功能描述 |
|----------|----------|
| `chrome_search_tabs` | 跨标签页内容语义搜索 |
| `chrome_get_web_content` | 提取网页 HTML/文本内容 |
| `chrome_get_interactive_elements` | 获取页面可交互元素 |
| `chrome_console` | 获取浏览器控制台输出 |
| `chrome_screenshot` | 页面截图（支持元素定位） |
### 🔧 浏览器控制（7 个工具）
| 工具名称 | 功能描述 |
|----------|----------|
| `chrome_navigate` | 导航到指定 URL |
| `chrome_scroll` | 控制页面滚动 |
| `chrome_viewport` | 调整视口大小 |
| `chrome_switch_tab` | 切换浏览器标签页 |
| `chrome_close_tabs` | 关闭指定标签页 |
| `chrome_go_back_or_forward` | 浏览器前进/后退 |
| `chrome_inject_script` | 注入内容脚本 |
### 🎯 页面交互（3 个工具）
| 工具名称 | 功能描述 |
|----------|----------|
| `chrome_click_element` | 点击页面元素（CSS 选择器） |
| `chrome_fill_or_select` | 表单填充和选项选择 |
| `chrome_keyboard` | 模拟键盘输入和快捷键 |
### 📚 数据管理（5 个工具）
| 工具名称 | 功能描述 |
|----------|----------|
| `chrome_history` | 搜索浏览器历史记录 |
| `chrome_bookmark_search` | 搜索书签 |
| `chrome_bookmark_add` | 添加书签 |
| `chrome_bookmark_delete` | 删除书签 |
### 🌐 网络监控（4 个工具）
| 工具名称 | 功能描述 |
|----------|----------|
| `chrome_network_capture_start/stop` | 网络请求捕获（webRequest API） |
| `chrome_network_debugger_start/stop` | 网络调试（响应体捕获） |
| `chrome_network_request` | 发送自定义 HTTP 请求 |
资料来源：[README.md](https://github.com/hangwin/mcp-chrome/blob/main/README.md)
## 安全配置
Chrome 扩展在生产环境中启用了以下安全策略：
```json
{
"cross_origin_embedder_policy": "require-corp",
"cross_origin_opener_policy": "same-origin",
"content_security_policy": {
"extension_pages": "script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;"
}
}
```
开发环境下这些策略会被禁用，以允许 Vite 开发服务器的正常资源加载。
资料来源：[app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)
## 故障排除
### 1. 清单文件未找到
```bash
# 自动检测并注册
pnpm run register --detect
```
### 2. 浏览器无法连接
确保 Chrome 扩展已正确加载，并且原生服务器正在运行：
```bash
# 检查服务器状态
pnpm doctor
```
### 3. 权限问题（Linux/macOS）
```bash
# 确保可执行文件有运行权限
chmod +x dist/cli.js
chmod +x dist/index.js
```
## 下一步
- 查看 [使用示例](../examples/) 了解常见场景
- 阅读 [API 文档](../api/) 深入了解各工具的参数
- 参考 [架构设计](../architecture/) 理解内部实现
---
## 系统架构设计
### 相关页面
相关主题：[Chrome 扩展架构](#chrome-extension-structure), [本地服务器架构](#native-server-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/ARCHITECTURE.md](https://github.com/hangwin/mcp-chrome/blob/main/docs/ARCHITECTURE.md)
- [docs/ARCHITECTURE_zh.md](https://github.com/hangwin/mcp-chrome/blob/main/docs/ARCHITECTURE_zh.md)
- [app/chrome-extension/entrypoints/background/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/index.ts)
- [app/native-server/src/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/index.ts)
- [app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)
- [app/native-server/src/agent/engines/claude.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/claude.ts)
- [app/native-server/src/agent/session-service.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/session-service.ts)
- [app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)
- [app/chrome-extension/utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)
- [app/chrome-extension/inject-scripts/web-fetcher-helper.js](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/inject-scripts/web-fetcher-helper.js)
# 系统架构设计
## 概述
mcp-chrome 是一个将 Chrome 浏览器与 AI 大模型深度集成的开源项目，通过 Model Context Protocol (MCP) 协议实现浏览器自动化控制与智能交互。该项目由 **Chrome 扩展端** 和 **本地服务（Native Server）端** 两大部分组成，采用主从架构设计，通过 Chrome Native Messaging 原生消息通信机制实现双向通信。
**核心目标**：
- 为 AI Agent 提供完整的浏览器控制能力
- 支持网页内容提取、交互、截图、网络监控等操作
- 实现跨平台的 Chrome 浏览器自动化
资料来源：[docs/ARCHITECTURE_zh.md]()
## 整体架构
```mermaid
graph TB
subgraph "客户端层 (Client)"
AI_Agent[AI Agent / Claude Code]
MCP_Client[MCP Client SDK]
end
subgraph "本地服务层 (Native Server)"
MCP_Server[MCP Server]
Session_Manager[Session Manager]
Engine_Adapter[Engine Adapter
Claude / Codex]
Native_Messaging[Native Messaging Host]
end
subgraph "Chrome 扩展层 (Chrome Extension)"
Background_Script[Background Script]
Sidepanel[Sidepanel UI]
Popup[Popup UI]
Content_Script[Content Scripts]
Inject_Scripts[Inject Scripts]
end
subgraph "浏览器层 (Browser)"
Chrome_Runtime[Chrome Runtime API]
Tabs_Management[标签页管理]
Network_Monitor[网络监控]
Console[控制台捕获]
end
AI_Agent --> MCP_Client
MCP_Client --> MCP_Server
MCP_Server --> Session_Manager
MCP_Server --> Engine_Adapter
Engine_Adapter --> Native_Messaging
Native_Messaging --> Background_Script
Background_Script --> Content_Script
Background_Script --> Tabs_Management
Background_Script --> Network_Monitor
Background_Script --> Chrome_Runtime
Content_Script --> Inject_Scripts
```
## 核心组件
### 1. 本地服务层 (Native Server)
本地服务层是整个系统的核心引擎，负责处理 AI 请求、管理会话、调用浏览器扩展功能。
#### 1.1 MCP Server
MCP Server 是基于 Model Context Protocol 协议实现的服务端，负责接收来自 AI Agent 的请求并路由到对应的处理模块。
**主要职责**：
- 协议解析与消息编解码
- 工具（Tools）注册与调用分发
- 会话生命周期管理
- 错误处理与重试机制
资料来源：[app/native-server/src/index.ts]()
#### 1.2 Session Manager
会话管理器负责管理 AI Agent 的执行会话，包括会话状态、上下文信息、配置参数等。
```typescript
interface SessionConfig {
mcpServers?: Record;
outputFormat?: Record;
enableFileCheckpointing?: boolean;
sandbox?: Record;
env?: Record;
codexConfig?: Partial;
}
```
**关键特性**：
- 支持多种引擎配置（Claude、Codex）
- 会话元数据缓存（Management Info）
- 插件和技能管理
- 输出格式自定义
资料来源：[app/native-server/src/agent/session-service.ts:1-80]()
#### 1.3 Engine Adapter
引擎适配器层封装了不同 AI 引擎的调用接口，目前支持 Claude 和 Codex 两种引擎。
**Claude Engine 实现**：
```mermaid
sequenceDiagram
participant Client as MCP Client
participant Engine as Claude Engine
participant Chrome as Chrome Extension
Client->>Engine: 发送消息
Engine->>Engine: 构建消息结构
Engine->>Chrome: dispatchToolMessage
Chrome-->>Engine: 工具执行结果
Engine->>Engine: 处理 content_block_stop
Engine->>Client: 返回响应
```
**工具消息分类**：
| 消息类型 | 说明 | 严重级别 |
|---------|------|---------|
| `edit` | 文件编辑操作 | error/success |
| `run` | 命令执行操作 | error/success/info |
| `grep` | 搜索操作 | error/info |
| `agent` | Agent 相关操作 | error/info |
资料来源：[app/native-server/src/agent/engines/claude.ts:1-80]()
#### 1.4 Native Messaging Host
Native Messaging Host 是 Chrome 扩展与本地服务通信的桥梁，支持跨平台的消息传递。
**平台特定路径配置**：
| 操作系统 | 用户级路径 | 系统级路径 |
|---------|-----------|-----------|
| Windows | `%APPDATA%\Google\Chrome\NativeMessagingHosts\` | `%ProgramFiles%\Google\Chrome\NativeMessagingHosts\` |
| macOS | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/` | `/Library/Google/Chrome/NativeMessagingHosts/` |
| Linux | `~/.config/google-chrome/NativeMessagingHosts/` | `/etc/opt/chrome/native-messaging-hosts/` |
**功能**：
- 消息序列化与反序列化
- 进程间通信管理
- 心跳检测与断线重连
资料来源：[app/native-server/src/scripts/browser-config.ts:1-100]()
资料来源：[app/native-server/src/scripts/utils.ts:1-80]()
---
### 2. Chrome 扩展层
Chrome 扩展是系统的执行端，负责实际的浏览器操作和页面交互。
#### 2.1 扩展入口点
| 入口点 | 文件路径 | 功能说明 |
|-------|---------|---------|
| Background Script | `entrypoints/background/index.ts` | 后台服务脚本，处理 Native Messaging 通信 |
| Sidepanel | `entrypoints/sidepanel/` | 侧边栏 UI，用于工作流管理 |
| Popup | `entrypoints/popup/` | 浏览器工具栏弹窗 |
| Options | `entrypoints/options/` | 扩展设置页面 |
| Builder | `entrypoints/builder/` | 工作流编辑器 |
| Welcome | `entrypoints/welcome/` | 欢迎页面 |
资料来源：[app/chrome-extension/entrypoints/background/index.ts]()
资料来源：[app/chrome-extension/entrypoints/sidepanel/index.html]()
资料来源：[app/chrome-extension/entrypoints/popup/index.html]()
#### 2.2 扩展配置
扩展使用 WXT 框架构建，配置包括资源访问策略和内容安全策略。
**Web 可访问资源**：
```typescript
web_accessible_resources: [
{
resources: [
'/models/*', // AI 模型文件
'/workers/*', // Web Worker 文件
'/inject-scripts/*' // 注入脚本
],
matches: ['']
}
]
```
**内容安全策略（CSP）**：
```typescript
content_security_policy: {
extension_pages: "script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;"
}
```
资料来源：[app/chrome-extension/wxt.config.ts:1-50]()
#### 2.3 核心功能模块
**Content Indexer（内容索引器）**
内容索引器负责自动提取和索引浏览器标签页的内容，支持语义搜索功能。
```mermaid
graph LR
A[页面加载完成] --> B{自动索引启用?}
B -->|是| C{语义引擎就绪?}
C -->|是| D[延迟 2 秒]
D --> E[提取页面内容]
E --> F[存储索引]
C -->|否| G[跳过]
B -->|否| G
```
**URL 过滤规则**：
```typescript
const excludePatterns = [
/^chrome:\/\//,
/^chrome-extension:\/\//,
/^edge:\/\//,
/^about:/,
/^moz-extension:\/\//,
/^file:\/\//
];
```
资料来源：[app/chrome-extension/utils/content-indexer.ts:1-80]()
**Web Fetcher Helper（网页内容提取）**
通过内容脚本注入到网页中，提取页面元数据和正文内容。
**提取的元数据字段**：
| 字段 | 来源优先级 |
|-----|----------|
| `title` | JSON-LD → og:title → twitter:title |
| `byline` | JSON-LD → author → article:author |
| `excerpt` | JSON-LD → dc:description → og:description |
| `siteName` | JSON-LD → og:site_name |
| `publishedTime` | JSON-LD → article:published_time |
资料来源：[app/chrome-extension/inject-scripts/web-fetcher-helper.js:1-100]()
---
## 工具能力体系
### 工具分类总览
| 类别 | 工具数量 | 主要功能 |
|-----|---------|---------|
| 标签页管理 | 6 | 开关标签页、切换、导航控制 |
| 交互操作 | 3 | 元素点击、表单填充、键盘输入 |
| 数据管理 | 5 | 历史记录、书签增删改查 |
| 截图视觉 | 1 | 高级截图（元素/全页/自定义尺寸） |
| 网络监控 | 4 | Request API、Debugger API、自定义请求 |
| 内容分析 | 4 | 语义搜索、内容提取、交互元素、控制台 |
### 核心工具详解
#### 网络监控工具
```mermaid
graph TD
A[网络监控工具] --> B[chrome_network_capture]
A --> C[chrome_network_debugger]
A --> D[chrome_network_request]
B --> B1[webRequest API]
B1 --> B2[无响应体]
C --> C1[Debugger API]
C1 --> C2[完整响应体]
D --> D1[自定义 HTTP 请求]
D1 --> D2[拦截响应]
```
**对比表**：
| 特性 | capture | debugger | request |
|-----|---------|----------|---------|
| API 来源 | webRequest | Debugger | fetch |
| 响应体 | ✗ | ✓ | ✓ |
| 性能开销 | 低 | 高 | 中 |
| 使用场景 | 快速记录 | 详细调试 | 自定义请求 |
资料来源：[README.md]()
资料来源：[docs/ARCHITECTURE_zh.md]()
---
## 通信机制
### Native Messaging 通信流程
```mermaid
sequenceDiagram
participant Agent as AI Agent
participant MCPServer as MCP Server
participant NativeHost as Native Messaging Host
participant Background as Background Script
participant Content as Content Script
participant Page as Web Page
Agent->>MCPServer: MCP JSON-RPC 请求
MCPServer->>MCPServer: 解析工具调用
MCPServer->>NativeHost: 序列化消息
NativeHost->>Background: Chrome.runtime.sendNativeMessage
Background->>Background: 处理请求
Background->>Content: chrome.tabs.sendMessage
Content->>Page: 执行脚本
Page-->>Content: 返回结果
Content-->>Background: 发送结果
Background-->>NativeHost: 返回响应
NativeHost-->>MCPServer: 解析响应
MCPServer-->>Agent: MCP JSON-RPC 响应
```
### 消息类型定义
**工具调用消息**：
```typescript
{
method: 'tools/call',
params: {
name: 'chrome_screenshot',
arguments: {
tabId: 123,
fullPage: true
}
}
}
```
**结果返回消息**：
```typescript
{
method: 'tools/call/result',
result: {
success: true,
data: { screenshot: 'base64...' }
}
}
```
资料来源：[app/native-server/src/index.ts]()
资料来源：[app/chrome-extension/entrypoints/background/index.ts]()
---
## 安全策略
### 权限控制
Chrome 扩展声明的权限范围决定了其能访问的 API 和资源：
```json
{
"permissions": [
"tabs",
"storage",
"activeTab",
"scripting",
"nativeMessaging",
"webNavigation",
"webRequest"
],
"host_permissions": [""]
}
```
### 内容安全策略
生产环境启用以下安全策略：
| 策略 | 值 | 说明 |
|-----|-----|-----|
| `cross_origin_embedder_policy` | require-corp | 要求跨域资源支持 CORP |
| `cross_origin_opener_policy` | same-origin | 防止跨域窗口访问 |
| `script-src` | 'self' 'wasm-unsafe-eval' | 允许自身脚本和 WebAssembly |
| `object-src` | 'self' | 仅允许自身对象资源 |
| `style-src` | 'self' 'unsafe-inline' | 允许内联样式（Vite 构建） |
开发环境使用 WXT 默认策略，避免阻断 dev server 资源加载。
资料来源：[app/chrome-extension/wxt.config.ts:20-35]()
---
## 安装与配置
### 本地服务安装
1. **自动安装**：
```bash
npx mcp-chrome-bridge install
```
2. **注册表/Manifest 配置**：
- Windows：写入 `HKCU\Software\Google\Chrome\NativeMessagingHosts\`
- macOS：创建 `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/`
- Linux：创建 `~/.config/google-chrome/NativeMessagingHosts/`
3. **验证安装**：
```bash
mcp-chrome-bridge doctor
```
### MCP Server 配置
在 MCP 客户端配置文件中添加：
```json
{
"mcpServers": {
"chrome": {
"command": "npx",
"args": ["mcp-chrome-bridge"]
}
}
}
```
资料来源：[app/native-server/install.md]()
---
## 扩展组件清单
| 组件类型 | 文件夹路径 | 功能说明 |
|---------|-----------|---------|
| 入口点 | `entrypoints/*/` | 各类型扩展页面的入口 |
| 组件 | `components/` | Vue 组件库 |
| 工具函数 | `utils/` | 通用工具函数 |
| 注入脚本 | `inject-scripts/` | 注入到网页的 JavaScript |
| 内容脚本 | `content/` | 页面内容脚本 |
| 类型定义 | `types/` | TypeScript 类型定义 |
资料来源：[app/chrome-extension/wxt.config.ts]()
---
## 总结
mcp-chrome 采用分层架构设计，将复杂的浏览器自动化能力抽象为标准化的 MCP 工具接口：
1. **Native Server 层** 处理 AI 逻辑和会话管理，通过 Native Messaging 与浏览器通信
2. **Chrome Extension 层** 实际执行浏览器操作，包括标签页管理、网络监控、内容提取等
3. **通信层** 基于 Chrome Native Messaging 协议实现跨进程、跨语言的可靠消息传递
该架构具有良好的可扩展性，支持后续添加更多 AI 引擎适配器和浏览器工具，同时通过权限管理和 CSP 策略保障安全性。
---
## Chrome 扩展架构
### 相关页面
相关主题：[系统架构设计](#architecture), [浏览器工具集](#browser-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [app/chrome-extension/entrypoints/background/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/index.ts)
- [app/chrome-extension/entrypoints/content.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/content.ts)
- [app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)
- [app/chrome-extension/common/constants.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/common/constants.ts)
- [app/chrome-extension/entrypoints/background/record-replay/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/index.ts)
- [app/chrome-extension/utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)
- [app/chrome-extension/inject-scripts/web-fetcher-helper.js](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/inject-scripts/web-fetcher-helper.js)
# Chrome 扩展架构
## 概述
mcp-chrome 是一个基于 Chrome 扩展的 MCP（Model Context Protocol）服务器实现，旨在为 AI 提供完整的浏览器控制能力。该扩展通过 WXT 框架构建，采用多入口点架构，涵盖后台脚本、内容脚本、侧边栏、弹出窗口等多种扩展页面类型。
## 整体架构
```mermaid
graph TB
subgraph "扩展页面层"
Popup["弹出窗口
popup/"]
Sidepanel["侧边栏
sidepanel/"]
Builder["工作流编辑器
builder/"]
Welcome["欢迎页
welcome/"]
Options["选项页
options/"]
end
subgraph "核心服务层"
Background["后台脚本
background/"]
Content["内容脚本
content.ts"]
end
subgraph "功能模块层"
RecordReplay["录制回放引擎
record-replay/"]
ContentIndexer["内容索引器
content-indexer.ts"]
ToolRegistry["工具注册表"]
TriggerEngine["触发器引擎"]
end
subgraph "注入脚本层"
WebFetcher["网页内容提取
web-fetcher-helper.js"]
DOMObserver["DOM 观察器
dom-observer.js"]
InjectBridge["注入桥接
inject-bridge.js"]
AccessibilityTree["无障碍树辅助
accessibility-tree-helper"]
end
subgraph "外部通信"
NativeServer["原生服务器
native-server/"]
MCPServer["MCP 服务器"]
end
Popup --> Background
Sidepanel --> Background
Builder --> Background
Options --> Background
Background --> Content
Background --> RecordReplay
Background --> ContentIndexer
Background --> ToolRegistry
Background --> TriggerEngine
Content --> WebFetcher
Content --> DOMObserver
Content --> InjectBridge
Content --> AccessibilityTree
Background --> NativeServer
Background --> MCPServer
```
## 入口点架构
### 入口点清单
| 入口点 | 路径 | 用途 | manifest.type |
|--------|------|------|---------------|
| 后台脚本 | `background/index.ts` | 核心业务逻辑、MCP 协议处理 | service_worker |
| 内容脚本 | `content.ts` | 页面交互、DOM 操作 | content_script |
| 弹出窗口 | `popup/index.html` | 快速操作入口 | browser_action |
| 侧边栏 | `sidepanel/index.html` | 工作流管理 | side_panel |
| 工作流编辑器 | `builder/index.html` | 可视化工作流设计 | unlisted_page |
| 欢迎页 | `welcome/index.html` | 用户引导 | unlisted_page |
| 选项页 | `options/index.html` | 用户脚本管理 | - |
资料来源：[wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)
### manifest.json 配置
扩展采用 WXT 框架自动生成 manifest.json，关键配置包括：
```typescript
manifest: {
permissions: [
'tabs',
'storage',
'webNavigation',
'webRequest',
'scripting',
'nativeMessaging'
],
host_permissions: [''],
web_accessible_resources: [
'/models/*',
'/workers/*',
'/inject-scripts/*'
]
}
```
## 后台脚本架构
### 后台脚本职责
后台脚本（Service Worker）是扩展的核心中枢，负责：
1. **MCP 协议通信** - 与原生服务器建立 Native Messaging 连接
2. **工具注册与分发** - 管理所有可用工具的定义和调用
3. **标签页管理** - 协调多标签页间的通信
4. **状态维护** - 管理扩展的全局状态
```mermaid
sequenceDiagram
participant MCP as MCP 客户端
participant BG as 后台脚本
participant Content as 内容脚本
participant Tab as 目标页面
MCP->>BG: 工具调用请求
BG->>BG: 解析工具名称与参数
BG->>Content: chrome.tabs.sendMessage
Content->>Tab: 执行脚本注入
Tab-->>Content: 执行结果
Content-->>BG: 响应消息
BG-->>MCP: JSON-RPC 响应
```
资料来源：[entrypoints/background/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/index.ts)
### 工具分类体系
| 类别 | 工具数量 | 功能描述 |
|------|----------|----------|
| 网络监控 | 4 | 请求捕获、调试、发送自定义请求 |
| 内容分析 | 4 | 语义搜索、内容提取、元素定位、控制台捕获 |
| 浏览器控制 | 6 | 标签管理、导航控制、视图切换 |
| 交互操作 | 3 | 元素点击、表单填充、键盘模拟 |
| 数据管理 | 5 | 书签管理、历史记录搜索 |
| 截图 | 1 | 高级截图功能 |
## 内容脚本架构
### 内容脚本职责
内容脚本运行在网页上下文中，主要负责：
- 直接访问和操作页面 DOM
- 注入用户脚本
- 收集页面信息
- 响应后台脚本的消息
### 注入脚本层次
```mermaid
graph TD
Page["网页页面"]
IS["注入脚本层 (ISOLATED)"]
CS["内容脚本层 (ISOLATED)"]
subgraph "内容脚本"
InjectBridge["inject-bridge.js"]
AccessibilityTree["accessibility-tree-helper"]
end
subgraph "注入脚本"
WebFetcher["web-fetcher-helper.js"]
DOMObserver["dom-observer.js"]
end
Page --> IS
IS --> WebFetcher
IS --> DOMObserver
Page --> CS
CS --> InjectBridge
CS --> AccessibilityTree
```
### Web Fetcher 辅助脚本
`web-fetcher-helper.js` 负责从网页中提取结构化数据：
```javascript
// 元数据提取流程
metadata.title // 从 JSON-LD、Open Graph、Twitter Card 获取
metadata.byline // 作者信息
metadata.excerpt // 文章摘要
metadata.siteName // 网站名称
metadata.publishedTime // 发布时间
```
支持的元数据源优先级：
1. JSON-LD 结构化数据
2. Open Graph 标签 (`og:*`)
3. Twitter Card 标签 (`twitter:*`)
4. Dublin Core 标签 (`dc:*`, `dcterm:*`)
5. 通用 meta 标签
资料来源：[inject-scripts/web-fetcher-helper.js](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/inject-scripts/web-fetcher-helper.js)
## 内容索引系统
### ContentIndexer 模块
`content-indexer.ts` 实现了自动化的标签页内容索引功能：
```typescript
class ContentIndexer {
private options: {
autoIndex: boolean; // 是否自动索引
maxContentLength: number; // 最大内容长度
}
// 核心方法
indexTabContent(tabId: number): Promise
removeTabIndex(tabId: number): Promise
shouldIndexUrl(url: string): boolean
extractTabContent(tabId): Promise<{ textContent, title }>
}
```
### URL 过滤规则
以下 URL 模式被排除在索引之外：
| 模式 | 说明 |
|------|------|
| `chrome://*` | Chrome 内部页面 |
| `chrome-extension://*` | 扩展页面 |
| `edge://*` | Edge 内部页面 |
| `about:*` | about 协议页面 |
| `moz-extension://*` | Firefox 扩展页面 |
| `file:///*` | 本地文件 |
### 索引触发时机
```mermaid
graph LR
A["页面加载完成
status=complete"] --> B{自动索引开启?}
B -->|是| C{语义引擎就绪?}
B -->|否| D["跳过"]
C -->|是| E["延迟 2 秒"]
C -->|否| D
E --> F["执行索引"]
F --> G["存储索引数据"]
H["标签页关闭"] --> I["移除索引"]
J["页面导航"] --> K{"frameId === 0?"}
K -->|是| L["移除旧索引"]
```
资料来源：[utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)
## 录制回放引擎
### 引擎架构
`record-replay/index.ts` 实现了 DOM 触发器驱动的自动化录制回放系统：
```typescript
interface TriggerConfig {
type: 'dom' | 'network' | 'custom';
selector?: string; // DOM 选择器
appear?: boolean; // 出现时触发
once?: boolean; // 仅触发一次
debounceMs?: number; // 防抖延迟
enabled?: boolean;
}
```
### 触发器类型
| 类型 | 说明 | 配置项 |
|------|------|--------|
| DOM | DOM 元素变化触发 | selector, appear, once, debounceMs |
| Network | 网络请求触发 | urlPattern, method |
| Custom | 自定义触发器 | - |
### 触发器工作流程
```mermaid
sequenceDiagram
participant Ext as 扩展
participant Tab as 标签页
participant Observer as DOM Observer
participant Trigger as 触发器
Ext->>Tab: 注入 dom-observer.js
Tab->>Observer: 创建 MutationObserver
Observer->>Trigger: 检测到变化
Trigger->>Trigger: 防抖处理
Trigger->>Tab: 发送 set_dom_triggers
Tab-->>Ext: 触发事件响应
```
### 初始化流程
1. 从 storage 加载触发器配置
2. 过滤启用的 DOM 类型触发器
3. 遍历所有标签页注入脚本
4. 发送触发器配置到各标签页
资料来源：[entrypoints/background/record-replay/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/index.ts)
## 安全策略
### Content Security Policy
生产环境启用严格 CSP 策略：
```typescript
content_security_policy: {
extension_pages:
"script-src 'self' 'wasm-unsafe-eval'; " +
"object-src 'self'; " +
"style-src 'self' 'unsafe-inline'; " +
"img-src 'self' data: blob:;"
}
```
### 跨域隔离策略
```typescript
cross_origin_embedder_policy: { value: 'require-corp' },
cross_origin_opener_policy: { value: 'same-origin' }
```
### Web Accessible Resources
| 资源路径 | 用途 | 匹配范围 |
|----------|------|----------|
| `/models/*` | AI 模型文件 | `` |
| `/workers/*` | Web Worker 文件 | `` |
| `/inject-scripts/*` | 注入脚本辅助文件 | `` |
## 技术栈
| 组件 | 技术选型 |
|------|----------|
| 扩展框架 | WXT |
| UI 框架 | Vue 3 |
| 样式 | TailwindCSS v4 |
| 图标 | SVG 组件自动注册 |
| 构建工具 | Vite |
| 脚本类型 | TypeScript |
资料来源：[wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)
## 扩展生命周期
```mermaid
stateDiagram-v2
[*] --> 安装: 首次安装
安装 --> 就绪: 初始化完成
就绪 --> 活跃: 用户操作
活跃 --> 等待: 空闲超时
等待 --> 活跃: 新操作
活跃 --> 更新: manifest 更新
更新 --> 就绪: 重新初始化
就绪 --> [*]: 卸载
```
## 常量定义
扩展使用集中式常量管理：
```typescript
// 存储键名
const STORAGE_KEYS = {
RR_TRIGGERS: 'rr_triggers',
// ... 其他键
}
// 消息类型
const CONTENT_MESSAGE_TYPES = {
ACCESSIBILITY_TREE_HELPER_PING: '...',
// ... 其他类型
}
```
资料来源：[common/constants.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/common/constants.ts)
## 总结
mcp-chrome 扩展采用现代化的多入口点架构，通过 WXT 框架简化了 manifest 管理。核心设计特点包括：
1. **分层架构** - 清晰的后台脚本、内容脚本、注入脚本分层
2. **工具化设计** - 丰富的浏览器控制工具集
3. **自动化索引** - 智能的内容索引系统
4. **录制回放** - 基于触发器的自动化引擎
5. **安全优先** - 严格的 CSP 和跨域策略
---
## 本地服务器架构
### 相关页面
相关主题：[系统架构设计](#architecture), [AI Agent 集成](#agent-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [app/native-server/src/server/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/server/index.ts)
- [app/native-server/src/mcp/mcp-server.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/mcp/mcp-server.ts)
- [app/native-server/src/agent/engines/claude.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/claude.ts)
- [app/native-server/src/agent/tool-bridge.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/tool-bridge.ts)
- [app/native-server/src/scripts/browser-config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/browser-config.ts)
- [app/native-server/src/scripts/doctor.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/scripts/doctor.ts)
- [app/chrome-extension/utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)
- [app/chrome-extension/inject-scripts/web-fetcher-helper.js](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/inject-scripts/web-fetcher-helper.js)
# 本地服务器架构
## 概述
mcp-chrome 的本地服务器（Native Server）是整个系统的核心后端组件，负责在 AI 代理（如 Claude）和 Chrome 浏览器之间建立双向通信桥梁。该模块采用 Node.js/TypeScript 实现，通过 Native Messaging 协议与 Chrome 扩展进行交互，同时集成了 AI 引擎来完成复杂的浏览器自动化任务。
本地服务器的核心职责包括：
- **协议转换**：将 MCP（Model Context Protocol）协议转换为 Chrome 扩展可理解的命令
- **工具编排**：管理 AI 引擎调用的各类工具（tool），包括浏览器操作、内容获取、网络请求等
- **状态维护**：维护跨会话的浏览器状态和索引信息
- **安全通信**：通过原生消息机制确保安全的进程间通信
资料来源：[app/native-server/src/server/index.ts:1-50]()
## 整体架构
mcp-chrome 采用分层架构设计，各层之间通过定义良好的接口进行通信：
```mermaid
graph TD
subgraph 客户端层
A[Claude AI / MCP Client]
end
subgraph 本地服务器层
B[MCP Server]
C[Agent Engine]
D[Tool Bridge]
end
subgraph 通信层
E[Native Messaging]
F[Chrome Extension Runtime]
end
subgraph 浏览器层
G[Chrome Extension]
H[Content Scripts]
I[Inject Scripts]
end
A -->|MCP Protocol| B
B --> C
C --> D
D -->|Native Message| E
E --> F
F --> G
G --> H
G --> I
J[Web Content] --> I
```
## 核心组件
### MCP 服务器
MCP 服务器是整个架构的入口点，负责：
- 初始化并管理 MCP 协议会话
- 处理来自 AI 客户端的请求
- 调度工具执行并返回结果
- 管理会话生命周期
| 组件 | 职责 | 关键文件 |
|------|------|----------|
| Session Manager | 管理多个并发会话 | mcp-server.ts |
| Request Handler | 处理 MCP 请求/响应 | server/index.ts |
| Tool Registry | 注册和管理可用工具 | tool-bridge.ts |
资料来源：[app/native-server/src/mcp/mcp-server.ts:1-100]()
### Agent 引擎
Agent 引擎负责协调 AI 模型与工具系统之间的交互。当前实现支持 Claude 模型，未来可扩展支持其他模型。
```mermaid
graph LR
A[User Request] --> B[Parse Intent]
B --> C{Requires Tools?}
C -->|Yes| D[Tool Bridge]
C -->|No| E[Direct Response]
D --> F[Execute Tool]
F --> G[Format Result]
G --> H[Return to AI]
E --> H
```
关键特性包括：
- **流式处理**：支持流式输出和工具调用的交错处理
- **错误恢复**：工具执行失败时的自动重试和错误报告
- **上下文管理**：维护对话上下文和工具调用历史
资料来源：[app/native-server/src/agent/engines/claude.ts:1-150]()
### 工具桥接器
工具桥接器（Tool Bridge）是连接 AI 引擎与 Chrome 扩展的枢纽，负责：
- 工具发现和元数据管理
- 参数验证和转换
- 执行结果格式化
- 错误处理和重试
| 工具类别 | 数量 | 示例 |
|----------|------|------|
| 标签页管理 | 5 | chrome_tabs_query, chrome_tabs_create, chrome_tabs_update, chrome_tabs_close, chrome_tabs_move |
| 导航控制 | 3 | chrome_navigate, chrome_go_back_or_forward, chrome_reload |
| 内容获取 | 4 | chrome_get_web_content, chrome_screenshot, chrome_get_interactive_elements, search_tabs_content |
| 网络操作 | 6 | chrome_network_capture_start, chrome_network_debugger_start, chrome_network_request 等 |
| 书签管理 | 4 | chrome_bookmark_search, chrome_bookmark_add, chrome_bookmark_delete 等 |
| 脚本注入 | 2 | chrome_inject_script, chrome_send_command_to_inject_script |
资料来源：[app/native-server/src/agent/tool-bridge.ts:1-80]()
## 通信机制
### Native Messaging 协议
mcp-chrome 使用 Chrome 的 Native Messaging 协议实现与扩展的安全通信。该协议基于标准输入/输出流进行 JSON 消息交换。
```mermaid
sequenceDiagram
participant MCP as MCP Server
participant Chrome as Chrome Extension
participant Native as Native Host
MCP->>Native: 启动进程
Native->>Chrome: 发送连接消息
Chrome->>Native: 初始化握手
Native->>MCP: 握手完成
MCP->>Native: JSON-RPC 请求
Native->>Chrome: 转发请求
Chrome->>Native: 执行结果
Native->>MCP: JSON-RPC 响应
```
消息格式遵循以下结构：
```json
{
"id": "unique-message-id",
"method": "tool_name",
"params": {
"tabId": 123,
"selector": "#element"
}
}
```
### 跨平台支持
本地服务器支持多个操作系统和浏览器组合的 Native Messaging 配置：
| 平台 | 浏览器 | 配置路径 |
|------|--------|----------|
| Windows | Chrome | `%APPDATA%\Google\Chrome\NativeMessagingHosts\` |
| Windows | Chromium | `%APPDATA%\Chromium\NativeMessagingHosts\` |
| macOS | Chrome | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/` |
| macOS | Chromium | `~/Library/Application Support/Chromium/NativeMessagingHosts/` |
| Linux | Chrome | `~/.config/google-chrome/NativeMessagingHosts/` |
| Linux | Chromium | `~/.config/chromium/NativeMessagingHosts/` |
资料来源：[app/native-server/src/scripts/browser-config.ts:30-90]()
## 内容索引系统
### 语义搜索引擎
content-indexer 模块提供了对浏览器标签页内容进行语义搜索的能力，这对于 AI 代理理解用户当前浏览内容至关重要。
```mermaid
graph TD
A[Tab Load Complete] --> B{Is Excluded URL?}
B -->|chrome://| C[Skip]
B -->|chrome-extension://| C
B -->|about:| C
B -->|file://| C
B -->|Yes| D[Process Content]
D --> E[Wait 2 seconds]
E --> F[Inject Web Fetcher]
F --> G[Extract Text + Metadata]
G --> H[Index with Semantic Engine]
H --> I[Store in Vector DB]
C --> J[End]
I --> J
```
关键配置参数：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| autoIndex | true | 页面加载完成后自动索引 |
| indexDelay | 2000ms | 等待页面完全加载的延迟 |
| excludePatterns | 5种 | 排除的 URL 模式（chrome://、file:// 等） |
资料来源：[app/chrome-extension/utils/content-indexer.ts:40-80]()
### 元数据提取
web-fetcher-helper.js 负责从网页中提取结构化元数据，支持多种数据源优先级：
1. **JSON-LD** 结构化数据
2. **Open Graph** 元标签
3. **Twitter Card** 元标签
4. **Dublin Core** 元标签
5. **标准 HTML** 元标签
提取的元数据字段：
- `title` - 文章标题
- `byline` - 作者信息
- `excerpt` - 描述/摘要
- `siteName` - 网站名称
- `publishedTime` - 发布时间
- `image` - 主图 URL
资料来源：[app/chrome-extension/inject-scripts/web-fetcher-helper.js:1-100]()
## 诊断系统
### 健康检查流程
doctor.ts 提供了完整的系统诊断功能，确保本地服务器正确安装和配置：
```mermaid
graph TD
A[Run Diagnostics] --> B[Check Native Host]
B --> C{Host Found?}
C -->|No| D[Show Install Instructions]
C -->|Yes| E[Check Manifest]
E --> F{Manifest Valid?}
F -->|No| G[Run Register Command]
F -->|Yes| H[Check Permissions]
H --> I{Permissions OK?}
I -->|No| J[Show Permission Guide]
I -->|Yes| K[All Checks Passed]
D --> L[End]
G --> L
J --> L
K --> L
```
### 诊断检查项
| 检查项 | 状态标识 | 失败处理 |
|--------|----------|----------|
| 原生主机可执行文件 | `host.binary` | 提示安装步骤 |
| 用户级 Manifest | `manifest.user` | `register --browser` |
| 系统级 Manifest | `manifest.system` | 需要管理员权限 |
| Windows 注册表 | `registry` | 自动修复注册 |
| 允许来源 | `allowed_origins` | 重新注册扩展 ID |
诊断报告会生成 Markdown 格式的输出，包含：
- 各检查项的详细状态
- 预期路径与实际路径对比
- 修复建议和命令
资料来源：[app/native-server/src/scripts/doctor.ts:100-200]()
## 工作流程示例
### 完整工具调用流程
当 AI 代理需要执行浏览器操作时，整个调用流程如下：
```mermaid
sequenceDiagram
participant AI as Claude AI
participant MCP as MCP Server
participant Engine as Agent Engine
participant Bridge as Tool Bridge
participant Ext as Chrome Extension
AI->>MCP: tool_use request
MCP->>Engine: dispatch tool call
Engine->>Bridge: validate & prepare
Bridge->>Ext: native message
Ext->>Ext: execute in browser
Ext-->>Bridge: result message
Bridge->>Engine: format result
Engine->>MCP: tool result
MCP-->>AI: tool result response
```
### 状态管理
工具执行过程中的状态流转：
| 阶段 | 状态 | 说明 |
|------|------|------|
| 接收请求 | `pending` | 等待工具调度 |
| 验证参数 | `validating` | 检查参数合法性 |
| 发送消息 | `sending` | 写入 Native Message |
| 等待响应 | `waiting` | 阻塞等待浏览器响应 |
| 处理结果 | `processing` | 解析返回数据 |
| 完成 | `completed` / `error` | 最终状态 |
资料来源：[app/native-server/src/agent/engines/claude.ts:80-120]()
## 安全考虑
### Content Security Policy
生产环境中启用严格的安全策略：
```typescript
content_security_policy: {
extension_pages: "script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;"
}
```
### Web Accessible Resources
受限的资源访问模式：
- `/models/*` - AI 模型文件（需明确声明）
- `/workers/*` - Web Worker 脚本
- `/inject-scripts/*` - 内容脚本辅助文件
资料来源：[app/chrome-extension/wxt.config.ts:20-40]()
## 扩展性设计
### 添加新工具
在 tool-bridge.ts 中注册新工具的流程：
1. 定义工具的 schema（名称、参数、返回值）
2. 实现工具执行逻辑
3. 注册到工具注册表
4. 扩展 Chrome 扩展端的处理逻辑
### 添加新 AI 引擎
Agent 引擎采用策略模式设计，添加新引擎只需：
1. 实现 `BaseEngine` 接口
2. 在引擎工厂中注册
3. 配置相应的 API 端点和认证
## 总结
mcp-chrome 的本地服务器架构通过清晰的层次划分和标准化的通信协议，实现了 AI 代理与浏览器之间的高效协作。核心优势包括：
- **模块化设计**：各组件职责明确，易于测试和维护
- **跨平台兼容**：支持 Windows、macOS、Linux 三大平台
- **流式处理**：支持实时交互的低延迟响应
- **可扩展性**：工具系统和引擎系统均支持灵活扩展
该架构为构建智能化的浏览器自动化应用提供了坚实的技术基础。
---
## 浏览器工具集
### 相关页面
相关主题：[Chrome 扩展架构](#chrome-extension-structure), [可视化编辑器](#visual-editor)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/TOOLS.md](https://github.com/hangwin/mcp-chrome/blob/main/docs/TOOLS.md)
- [docs/TOOLS_zh.md](https://github.com/hangwin/mcp-chrome/blob/main/docs/TOOLS_zh.md)
- [app/chrome-extension/entrypoints/background/tools/browser/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/index.ts)
- [app/chrome-extension/entrypoints/background/tools/browser/screenshot.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/screenshot.ts)
- [app/chrome-extension/entrypoints/background/tools/browser/network-capture.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/network-capture.ts)
- [app/chrome-extension/entrypoints/background/tools/browser/interaction.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/interaction.ts)
- [app/chrome-extension/entrypoints/background/tools/browser/content-analysis.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/content-analysis.ts)
# 浏览器工具集
## 概述
浏览器工具集是 mcp-chrome 项目中负责与 Chrome 浏览器进行交互的核心功能模块。通过 MCP（Model Context Protocol）协议，该工具集允许 AI Agent 能够感知、操控和分析浏览器状态，从而实现自动化浏览器操作、网页内容提取、网络请求监控等高级功能。
工具集位于 `app/chrome-extension/entrypoints/background/tools/browser/` 目录下，采用模块化架构设计，每个工具类别对应独立的功能文件。资料来源：[app/chrome-extension/entrypoints/background/tools/browser/index.ts:1-50]()
## 架构设计
### 整体架构
浏览器工具集采用分层架构，底层通过 Chrome Extension API 与浏览器内核交互，上层通过 MCP 协议暴露标准化的工具接口。
```mermaid
graph TD
A[MCP Client / AI Agent] --> B[Chrome Extension Background]
B --> C[Browser Tools 模块]
C --> D[chrome.tabs API]
C --> E[chrome.webNavigation API]
C --> F[chrome.webRequest API]
C --> G[chrome.debugger API]
C --> H[chrome.scripting API]
D --> I[浏览器 Tab 管理]
E --> J[页面导航监控]
F --> K[网络请求拦截]
G --> L[响应体调试]
H --> M[脚本注入执行]
```
### 工具分类
| 类别 | 工具数量 | 主要功能 |
|------|----------|----------|
| 标签页管理 | 4 | 创建、切换、关闭标签页 |
| 导航控制 | 2 | 前进/后退、URL 跳转 |
| 视图控制 | 2 | 缩放、视口调整 |
| 截图 | 1 | 页面和元素截图 |
| 网络监控 | 4 | 请求捕获、调试、自定义请求 |
| 内容分析 | 4 | 内容提取、元素查找、控制台捕获 |
| 交互操作 | 3 | 元素点击、表单填充、键盘输入 |
资料来源：[docs/TOOLS.md:1-30]()
## 标签页管理
### 功能列表
| 工具名称 | 功能描述 |
|----------|----------|
| `chrome_create_tab` | 创建新的浏览器标签页 |
| `chrome_switch_tab` | 切换当前活动标签页 |
| `chrome_close_tabs` | 关闭指定标签页或窗口 |
| `chrome_get_tabs` | 获取当前所有标签页列表 |
资料来源：[app/chrome-extension/entrypoints/background/tools/browser/index.ts:50-100]()
### 创建标签页
`chrome_create_tab` 工具支持以下参数：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `url` | string | 是 | 目标 URL |
| `active` | boolean | 否 | 是否激活新标签页（默认 true） |
| `index` | number | 否 | 标签页位置索引 |
| `windowId` | number | 否 | 指定窗口 ID |
### 标签页切换与关闭
- `chrome_switch_tab` 支持通过标签页 ID 或 URL 模式切换
- `chrome_close_tabs` 支持关闭单个标签页、多个标签页或整个窗口
- 所有操作均返回更新后的标签页状态
## 导航控制
### 前进/后退
`chrome_go_back_or_forward` 工具提供浏览器历史导航功能：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `direction` | "back" \| "forward" | 是 | 导航方向 |
| `tabId` | number | 否 | 指定标签页（默认当前活动标签页） |
| `steps` | number | 否 | 步进数量（默认 1） |
### 视图控制
| 工具名称 | 功能描述 |
|----------|----------|
| `chrome_set_viewport` | 设置页面缩放比例和视口尺寸 |
| `chrome_zoom` | 调整页面缩放级别 |
## 截图功能
### chrome_screenshot
高级截图工具，支持多种截图模式：
```typescript
interface ScreenshotOptions {
tabId?: number; // 指定标签页
fullPage?: boolean; // 全页面截图
elementSelector?: string; // 特定元素截图
width?: number; // 自定义宽度
height?: number; // 自定义高度
format?: 'png' | 'jpeg'; // 输出格式
quality?: number; // 图片质量（1-100）
}
```
资料来源：[app/chrome-extension/entrypoints/background/tools/browser/screenshot.ts:1-50]()
### 截图模式
1. **标签页截图**：捕获指定标签页的可见区域
2. **全页面截图**：通过滚动拼接获取整个页面
3. **元素截图**：通过 CSS 选择器定位并截取特定元素
### 技术实现
截图功能通过 `chrome.tabs.captureVisibleTab` API 实现，对于全页面截图需要：
1. 获取页面原始尺寸
2. 设置视口为页面总高度
3. 滚动页面并多次截图
4. 拼接图像片段
## 网络监控
### 工具列表
| 工具名称 | 功能描述 |
|----------|----------|
| `chrome_network_capture_start` | 启动 webRequest API 网络捕获 |
| `chrome_network_capture_stop` | 停止网络捕获 |
| `chrome_network_debugger_start` | 启动 Debugger API 调试 |
| `chrome_network_debugger_stop` | 停止调试模式 |
| `chrome_network_request` | 发送自定义 HTTP 请求 |
资料来源：[app/chrome-extension/entrypoints/background/tools/browser/network-capture.ts:1-60]()
### webRequest API 模式
使用 `chrome.webRequest` API 监听网络请求：
- 支持请求过滤（URL 模式、类型、状态码）
- 可记录请求头、响应头、请求时间
- 适合高并发场景的性能监控
### Debugger API 模式
使用 `chrome.debugger` API 获取完整响应体：
- 支持拦截并修改请求/响应
- 可以获取二进制响应内容
- 适合需要深度分析 HTTP 流量的场景
### 自定义请求
`chrome_network_request` 支持构造完整的 HTTP 请求：
```typescript
interface NetworkRequestOptions {
url: string; // 请求 URL
method?: string; // HTTP 方法
headers?: object; // 请求头
body?: string; // 请求体
timeout?: number; // 超时时间
}
```
## 内容分析
### 工具列表
| 工具名称 | 功能描述 |
|----------|----------|
| `search_tabs_content` | 跨标签页语义搜索 |
| `chrome_get_web_content` | 提取网页 HTML/文本内容 |
| `chrome_get_interactive_elements` | 获取可交互元素列表 |
| `chrome_console` | 捕获页面控制台输出 |
资料来源：[app/chrome-extension/entrypoints/background/tools/browser/content-analysis.ts:1-80]()
### search_tabs_content
基于语义的内容搜索工具，支持：
- 跨多个浏览器标签页进行全文搜索
- 使用向量嵌入进行语义匹配
- 返回匹配结果及其上下文片段
### chrome_get_web_content
网页内容提取工具：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `tabId` | number | 是 | 目标标签页 ID |
| `format` | "html" \| "text" | 否 | 输出格式（默认 text） |
| `selectors` | string[] | 否 | CSS 选择器过滤 |
### 交互元素获取
`chrome_get_interactive_elements` 返回页面的可点击元素：
```typescript
interface InteractiveElement {
tagName: string; // 元素标签名
id?: string; // 元素 ID
className?: string; // 样式类名
textContent?: string; // 文本内容
attributes: object; // 所有属性
boundingRect: object; // 位置坐标
selector: string; // 唯一选择器
}
```
## 交互操作
### 工具列表
| 工具名称 | 功能描述 |
|----------|----------|
| `chrome_click_element` | 通过 CSS 选择器点击元素 |
| `chrome_fill_or_select` | 填写表单或选择选项 |
| `chrome_keyboard` | 模拟键盘输入和快捷键 |
资料来源：[app/chrome-extension/entrypoints/background/tools/browser/interaction.ts:1-50]()
### 元素点击
`chrome_click_element` 通过 DOM 选择器定位并点击元素：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `selector` | string | 是 | CSS 选择器 |
| `tabId` | number | 否 | 目标标签页 |
| `button` | "left" \| "right" \| "middle" | 否 | 鼠标按钮 |
| `clickCount` | number | 否 | 点击次数 |
### 表单操作
`chrome_fill_or_select` 支持多种表单输入：
- **文本输入**：直接设置 input 值并触发 change 事件
- **下拉选择**：通过 value 或文本选择选项
- **复选框/单选框**：设置 checked 状态
- **文件上传**：设置文件路径
### 键盘模拟
`chrome_keyboard` 支持：
- 普通文本输入
- 快捷键组合（如 `Command+Shift+P`）
- 特殊键序列
## 脚本注入
### chrome_inject_script
在网页上下文中执行自定义 JavaScript：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `tabId` | number | 是 | 目标标签页 |
| `script` | string | 是 | JavaScript 代码 |
| `args` | any[] | 否 | 传递给脚本的参数 |
### chrome_send_command_to_inject_script
向已注入的内容脚本发送命令，实现双向通信：
```mermaid
sequenceDiagram
participant A as MCP Client
participant B as Background Script
participant C as Content Script
A->>B: send_command_to_inject_script
B->>C: chrome.tabs.sendMessage
C-->>B: 消息响应
B-->>A: 返回结果
```
## 数据模型
### 工具返回格式
所有工具遵循统一的响应格式：
```typescript
interface ToolResponse {
success: boolean; // 操作是否成功
data?: T; // 返回数据
error?: string; // 错误信息
metadata?: { // 元数据
tabId?: number;
timestamp: number;
duration?: number;
};
}
```
### 标签页模型
```typescript
interface ChromeTab {
id: number;
windowId: number;
index: number;
url: string;
title: string;
active: boolean;
pinned: boolean;
status: 'loading' | 'complete';
incognito: boolean;
}
```
## 配置与扩展
### 安全策略
浏览器工具集在 Chrome Extension 中运行，需要配置适当的安全策略：
资料来源：[app/chrome-extension/wxt.config.ts:1-30]()
```typescript
content_security_policy: {
extension_pages:
"script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;",
}
```
### 权限声明
工具集需要在 `manifest.json` 中声明所需权限：
- `tabs`：标签页管理
- `webNavigation`：导航监控
- `webRequest`：网络请求拦截
- `debugger`：调试功能
- `scripting`：脚本注入
- ``：全网站访问
## 最佳实践
### 性能优化
1. **批量操作**：多个标签页操作时使用 Promise.all 并行执行
2. **按需截图**：仅在需要时进行全页面截图，避免频繁滚动
3. **网络过滤**：使用精确的 URL 模式过滤减少事件监听开销
### 错误处理
1. 标签页操作前检查标签页是否存在
2. 网络请求设置合理的超时时间
3. 脚本注入前验证目标页面是否加载完成
### 安全考虑
1. 避免在不可信页面执行未验证的脚本
2. 网络请求监控注意敏感信息保护
3. 脚本注入仅在必要时使用
## 相关资源
- [工具文档（英文）](https://github.com/hangwin/mcp-chrome/blob/main/docs/TOOLS.md)
- [工具文档（中文）](https://github.com/hangwin/mcp-chrome/blob/main/docs/TOOLS_zh.md)
- [Chrome Extension API 文档](https://developer.chrome.com/docs/extensions/reference/)
---
## 录制回放系统 (V3)
### 相关页面
相关主题：[Chrome 扩展架构](#chrome-extension-structure), [浏览器工具集](#browser-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [app/chrome-extension/entrypoints/background/record-replay/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/index.ts)
- [app/chrome-extension/entrypoints/background/record-replay/engine/policies/wait.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/engine/policies/wait.ts)
- [app/chrome-extension/entrypoints/background/record-replay/recording/browser-event-listener.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/record-replay/recording/browser-event-listener.ts)
- [app/chrome-extension/entrypoints/background/tools/browser/common.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/tools/browser/common.ts)
- [app/chrome-extension/utils/content-indexer.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/content-indexer.ts)
# 录制回放系统 (V3)
> **注意**：查询中请求的 `record-replay-v3` 目录下的源码文件未在当前上下文环境中检索到。以下文档基于现有的 `record-replay` 目录中的代码进行说明，涵盖了录制回放系统的核心架构与实现细节。
## 概述
录制回放系统是 Chrome MCP 扩展中用于记录用户浏览器操作并在需要时进行自动化回放的模块。该系统通过监听浏览器事件、捕获 DOM 变化、记录网络请求等方式，实现对用户操作流程的完整复现。
系统设计目标包括：
- **操作录制**：自动捕获用户的导航、点击、表单填写等交互行为
- **智能触发**：支持基于 URL、DOM 变化、时间等多种触发条件
- **流程回放**：精确还原录制时的操作序列
- **状态同步**：在回放过程中处理页面状态变化和异步操作
## 系统架构
### 核心组件
| 组件 | 职责 | 源码位置 |
|------|------|----------|
| BrowserEventListener | 监听并捕获浏览器事件 | `browser-event-listener.ts` |
| Flow | 流程数据模型定义 | `domain/flow.ts` |
| Kernel | 回放引擎核心 | `engine/kernel/kernel.ts` |
| Triggers | 触发器管理 | `engine/triggers/index.ts` |
| WaitPolicies | 等待策略（网络空闲检测等） | `engine/policies/wait.ts` |
### 架构图
```mermaid
graph TD
subgraph 录制阶段
BEL[BrowserEventListener]
BEL -->|捕获事件| NE[导航事件]
BEL -->|捕获事件| CE[点击事件]
BEL -->|捕获事件| FE[表单事件]
NE -->|记录| FL[Flow]
CE -->|记录| FL
FE -->|记录| FL
end
subgraph 回放阶段
K[Kernel]
K -->|读取| FL
K -->|执行| IE[交互引擎]
K -->|检测| WP[WaitPolicies]
WP -->|等待条件| K
K -->|触发| TR[Triggers]
end
subgraph 事件监听
BEL -->|onCommitted| WN[webNavigation]
BEL -->|onUpdated| TU[tabs.onUpdated]
BEL -->|onRemoved| TRU[tabs.onRemoved]
end
```
## 事件监听机制
### 导航事件捕获
系统通过 `chrome.webNavigation` API 监听页面导航事件，这是录制回放系统的核心数据来源。
```typescript
chrome.webNavigation.onCommitted.addListener(async (details) => {
if (details.frameId !== 0) return;
// 确保核心内容脚本已注入
await ensureCoreInjected(details.tabId);
// 获取存储的 DOM 触发器
const { [STORAGE_KEYS.RR_TRIGGERS]: stored } =
await chrome.storage.local.get(STORAGE_KEYS.RR_TRIGGERS);
// ... 触发器处理逻辑
});
```
**关键事件类型**：
| 事件 | 触发条件 | 录制价值 |
|------|----------|----------|
| `onCommitted` | 导航提交时 | 记录初始 URL 变化 |
| `onCompleted` | 页面加载完成 | 标记加载结束 |
| `onHistoryStateUpdated` | 历史状态更新 | SPA 路由变化 |
### 标签页事件监听
```typescript
chrome.tabs.onUpdated.addListener((updatedId, change, tab) => {
if (updatedId !== tabId) return;
// 检测 loading 状态
if (change.status === 'loading') mark();
// 检测 URL 变化
if (typeof change.url === 'string' && (!prevUrl || change.url !== prevUrl)) mark();
});
```
### 导航类型过滤
系统会过滤特定的导航类型，只录制有意义的用户操作：
```typescript
const shouldRecord =
t === 'reload' ||
t === 'typed' ||
t === 'generated' ||
t === 'auto_bookmark' ||
t === 'keyword' ||
t === 'form_submit'; // 捕获回车搜索行为
```
**不录制的类型**：`link`（纯链接点击由其他机制处理）
## 流程数据模型
### Flow 结构
Flow 是录制回放系统的核心数据结构，用于存储录制过程中捕获的所有操作信息。
```typescript
interface Flow {
id: string; // 唯一标识
steps: FlowStep[]; // 操作步骤列表
metadata: FlowMeta; // 元数据
triggers?: Trigger[]; // 关联的触发器
}
interface FlowStep {
type: 'navigation' | 'click' | 'input' | 'wait' | 'screenshot';
timestamp: number;
data: Record;
}
```
### 导航步骤
导航步骤记录页面 URL 变化和相关上下文：
```typescript
if (flow && url) {
addNavigationStep(flow, url);
}
```
## 触发器系统
### 触发器类型
| 类型 | 描述 | 适用场景 |
|------|------|----------|
| `url` | URL 模式匹配 | 特定页面触发 |
| `dom` | DOM 元素检测 | 元素出现时触发 |
| `timer` | 定时触发 | 周期性任务 |
| `manual` | 手动触发 | 调试/测试 |
### DOM 触发器配置
```typescript
const domTriggers = triggers
.filter((x) => x.type === 'dom' && x.enabled !== false)
.map((x: any) => ({
id: x.id,
selector: x.selector, // CSS 选择器
appear: x.appear !== false, // 出现/消失
once: x.once !== false, // 单次/重复
debounceMs: x.debounceMs ?? 800, // 防抖延迟
}));
```
## 等待策略
系统在回放过程中使用多种等待策略来确保页面状态就绪。
### 网络空闲检测
```typescript
export async function waitForNetworkIdle(
tabId: number,
sniffMs: number = 500,
finish: () => void
): Promise {
let mark: () => void;
let timer: ReturnType;
const getLogger = (): ((...args: unknown[]) => void) => {
return (...args: unknown[]) => console.log('[NetworkIdle]', ...args);
};
const isIdle = (): boolean => {
// 检测逻辑
};
const wait = (): Promise =>
new Promise((resolve) => {
mark = resolve;
const startedAt = Date.now();
let prevUrl: string | undefined;
const onCommitted = (d: any) => {
if (d.tabId === tabId && d.frameId === 0 && d.timeStamp >= startedAt) mark();
};
const onCompleted = (d: any) => {
if (d.tabId === tabId && d.frameId === 0 && d.timeStamp >= startedAt) mark();
};
const onHistoryStateUpdated = (d: any) => {
if (d.tabId === tabId && d.frameId === 0 && d.timeStamp >= startedAt) mark();
};
const onUpdated = (updatedId: number, change: chrome.tabs.TabChangeInfo) => {
if (updatedId !== tabId) return;
if (change.status === 'loading') mark();
if (typeof change.url === 'string' && (!prevUrl || change.url !== prevUrl)) mark();
};
chrome.webNavigation.onCommitted.addListener(onCommitted);
chrome.webNavigation.onCompleted.addListener(onCompleted);
chrome.tabs.onUpdated.addListener(onUpdated);
timer = setTimeout(finish, sniffMs);
});
}
```
**参数说明**：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `tabId` | number | - | 目标标签页 ID |
| `sniffMs` | number | 500 | 空闲检测时间窗口（毫秒） |
| `finish` | function | - | 超时完成回调 |
## 内容脚本注入
系统通过 `chrome.scripting.executeScript` API 向目标页面注入脚本，以获取页面内容或执行特定操作。
```typescript
await chrome.scripting.executeScript({
target: { tabId: details.tabId, allFrames: true },
files: ['inject-scripts/dom-observer.js'],
world: 'ISOLATED',
});
```
### 注入脚本类型
| 脚本 | 用途 | 作用域 |
|------|------|--------|
| `web-fetcher-helper.js` | 页面内容提取 | ISOLATED |
| `dom-observer.js` | DOM 变化监听 | ISOLATED |
### 消息通信
```typescript
await chrome.tabs.sendMessage(details.tabId, {
action: 'setTriggers',
triggers: domTriggers,
});
```
## 录制状态管理
### 会话状态
```typescript
interface Session {
getStatus(): 'idle' | 'recording' | 'replaying';
getFlow(): Flow | null;
getActiveTabs(): number[];
}
```
### 状态转换
```mermaid
stateDiagram-v2
[*] --> Idle: 初始化
Idle --> Recording: 开始录制
Recording --> Replaying: 执行回放
Replaying --> Idle: 回放完成
Recording --> Idle: 停止录制
Idle --> [*]: 清理
```
### 活动标签页管理
```typescript
// 录制开始时记录活动标签页
session.addActiveTab(tabId);
// 标签页关闭时移除
chrome.tabs.onRemoved.addListener((tabId) => {
if (session.getStatus() !== 'recording') return;
session.removeActiveTab(tabId);
});
```
## 与其他模块的交互
### 与工具系统的集成
录制回放系统通过 MCP 工具协议暴露功能：
```typescript
// 注册命令处理器
chrome.commands.onCommand.addListener(async (command) => {
const t = commands.find((k) => k.command === command);
if (!t || t.enabled === false) return;
const flow = await getFlow(t.flowId);
if (!flow) return;
await runFlow(flow, { args: t.args || {}, returnLogs: false });
});
```
### 与内容索引器的协同
系统与 `ContentIndexer` 模块共享部分事件监听器：
```typescript
if (chrome.webNavigation) {
chrome.webNavigation.onCommitted.addListener(async (details) => {
if (details.frameId === 0) {
await this.removeTabIndex(details.tabId);
}
});
}
```
## 安全考虑
### 跨域隔离策略
在生产环境中，系统启用以下安全策略：
```typescript
cross_origin_embedder_policy: { value: 'require-corp' as const },
cross_origin_opener_policy: { value: 'same-origin' as const },
```
### 内容安全策略
```typescript
content_security_policy: {
extension_pages:
"script-src 'self' 'wasm-unsafe-eval'; object-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;",
}
```
## 最佳实践
1. **触发器防抖**：DOM 触发器建议设置 `debounceMs >= 800ms` 避免误触发
2. **资源访问控制**：通过 `web_accessible_resources` 限制可访问资源范围
3. **错误处理**：关键操作使用 try-catch 包装，防止单点故障影响整体录制
4. **标签页清理**：及时移除关闭的标签页 ID，避免无效广播
## 相关文档
- [工具系统概览](../tools/overview.md)
- [内容索引系统](./content-indexer.md)
- [MCP 协议文档](../protocol/index.md)
---
## 可视化编辑器
### 相关页面
相关主题：[浏览器工具集](#browser-tools), [录制回放系统 (V3)](#record-replay-v3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/hangwin/mcp-chrome/blob/main/README.md)
- [app/chrome-extension/entrypoints/background/web-editor/index.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/background/web-editor/index.ts)
- [app/chrome-extension/wxt.config.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/wxt.config.ts)
- [app/chrome-extension/entrypoints/builder/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/builder/index.html)
- [app/chrome-extension/entrypoints/sidepanel/index.html](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/sidepanel/index.html)
# 可视化编辑器
## 概述
可视化编辑器（Visual Editor）是 mcp-chrome 项目中用于网页元素编辑的核心功能模块。该编辑器允许 AI Agent 通过自然语言指令直接操作网页上的元素，实现自动化网页交互与编辑功能。
mcp-chrome 的可视化编辑器采用双版本架构，支持 **WebEditor V1**（旧版）与 **WebEditor V2**（新版）两种实现方式，通过 `USE_WEB_EDITOR_V2` 配置开关进行切换。资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:1-100]()
## 架构设计
### 双版本架构
可视化编辑器采用 V1 和 V2 两个版本并行运行的架构设计：
| 版本 | 标识常量 | 脚本路径 | 说明 |
|------|----------|----------|------|
| V1 | `USE_WEB_EDITOR_V2 = false` | `V1_SCRIPT_PATH` | 传统版本，稳定兼容 |
| V2 | `USE_WEB_EDITOR_V2 = true` | `V2_SCRIPT_PATH` | 新版增强版本 |
两个版本使用不同的 action 名称来避免冲突：
- **V1 动作**：`web_editor_ping`、`web_editor_toggle` 等
- **V2 动作**：`web_editor_ping_v2`、`web_editor_toggle_v2` 等
资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:200-230]()
### 组件层次结构
```
mcp-chrome 扩展
├── Background Script (web-editor/index.ts)
│ ├── 上下文菜单注册
│ ├── 脚本注入管理
│ └── 消息通信处理
├── Content Script (注入脚本)
│ ├── 元素标记器 (element-marker.js)
│ └── 交互处理器
└── Sidepanel UI
├── Agent Chat (时间线视图)
└── 工作流编辑器
```
资料来源：[app/chrome-extension/wxt.config.ts:1-50]()
## 核心功能
### 元素标记与选择
编辑器提供可视化的元素标记功能，用户可以通过点击或按空格键选择页面元素：
- 高亮显示可交互元素
- 显示元素信息面板
- 支持 Shift 键多选模式
- 元素检查器集成
资料来源：[app/chrome-extension/inject-scripts/element-marker.js:1-100]()
### 上下文菜单集成
编辑器通过 Chrome 扩展的上下文菜单 API 注册快捷入口：
```typescript
await chrome.contextMenus.create({
id: CONTEXT_MENU_ID,
title: '切换网页编辑模式',
contexts: ['all'],
});
```
该菜单项支持在任意页面通过右键调用"切换网页编辑模式"功能。资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:150-170]()
### 脚本注入机制
编辑器支持将脚本动态注入到目标页面，注入过程如下：
```mermaid
sequenceDiagram
participant BG as Background Script
participant Tab as Target Tab
participant Script as Injected Script
BG->>BG: ensureEditorInjected(tabId)
BG->>BG: 获取版本对应脚本路径
BG->>Tab: chrome.scripting.executeScript
Tab->>Script: 加载编辑器脚本
Script->>BG: 返回注入确认
BG->>Tab: 发送初始化命令
```
资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:230-260]()
## 交互流程
### 编辑模式切换
1. 用户通过上下文菜单或快捷键触发切换
2. Background Script 检查目标 Tab 是否已注入编辑器脚本
3. 如未注入，调用 `ensureEditorInjected()` 注入脚本
4. 发送 `web_editor_toggle` 或 `web_editor_toggle_v2` 命令
5. Content Script 接收命令，切换页面编辑状态
### 动作响应函数
根据版本不同，编辑器支持以下核心动作：
| 动作名称 | V1 | V2 | 功能描述 |
|----------|----|----|----------|
| `web_editor_ping` | ✓ | ✓ | 检测编辑器连接状态 |
| `web_editor_toggle` | ✓ | ✗ | 切换编辑模式 |
| `web_editor_toggle_v2` | ✗ | ✓ | 切换编辑模式（V2） |
| `web_editor_apply` | ✓ | ✓ | 应用变更 |
资料来源：[app/chrome-extension/entrypoints/background/web-editor/index.ts:200-250]()
## 状态管理
### 等待策略
编辑器内置网络空闲等待策略，用于确保页面完全加载后再进行操作：
```typescript
function waitForNetworkIdle(tabId: number, sniffMs = 2000): Promise {
// 监听网络请求完成
// 监听标签页更新
// 监听 URL 变化
// 超时自动结束
}
```
资料来源：[app/chrome-extension/entrypoints/background/record-replay/engine/policies/wait.ts:1-50]()
### 设计令牌
编辑器使用设计令牌系统统一管理样式变量，确保界面一致性：
```typescript
// 设计令牌示例
export const tokens = {
colors: {
primary: '#xxx',
secondary: '#xxx',
},
spacing: {
small: '8px',
medium: '16px',
},
};
```
## 扩展集成
### 入口点配置
mcp-chrome 扩展定义了多个入口点，编辑器作为 Sidepanel 页面的一部分运行：
| 入口点 | 文件路径 | 用途 |
|--------|----------|------|
| sidepanel | `entrypoints/sidepanel/index.html` | 工作流管理主界面 |
| builder | `entrypoints/builder/index.html` | 工作流编辑器 |
| options | `entrypoints/options/index.html` | 用户脚本管理器 |
| background | `entrypoints/background/` | 后台服务脚本 |
资料来源：[app/chrome-extension/entrypoints/sidepanel/index.html:1-15]()
### Web Accessible Resources
编辑器通过 `web_accessible_resources` 配置允许注入脚本访问资源：
```typescript
web_accessible_resources: [
{
resources: [
'/models/*',
'/workers/*',
'/inject-scripts/*',
],
matches: [''],
},
]
```
资料来源：[app/chrome-extension/wxt.config.ts:20-30]()
## 使用示例
### AI 辅助网页编辑
用户可以让 AI Agent 帮助编辑当前网页：
1. 打开目标网页
2. 在 Sidepanel 中启动 AI 对话
3. 使用 AgentChat 时间线追踪操作
4. AI 通过 MCP 协议调用编辑器工具
5. 编辑器将变更应用到页面
### 工作流构建
编辑器支持工作流模式，允许用户预先定义操作序列：
1. 在 Builder 入口点创建工作流
2. 定义触发条件和操作步骤
3. 保存工作流配置
4. 在需要时触发执行
## 安全策略
编辑器在生产环境启用以下安全策略：
| 策略 | 配置值 | 用途 |
|------|--------|------|
| `cross_origin_embedder_policy` | `require-corp` | 跨源隔离 |
| `cross_origin_opener_policy` | `same-origin` | 同源策略 |
| `content_security_policy` | 定制规则 | 内容安全限制 |
开发环境使用 WXT 默认策略，避免阻断开发服务器资源加载。资料来源：[app/chrome-extension/wxt.config.ts:35-50]()
## 总结
可视化编辑器是 mcp-chrome 项目的核心交互模块，通过结合 Chrome 扩展 API、MCP 协议和 AI Agent 技术，实现了自然语言驱动的网页编辑能力。其双版本架构确保了向后兼容性和持续演进，丰富的上下文菜单集成和脚本注入机制提供了灵活的使用方式。
---
## 语义搜索与向量数据库
### 相关页面
相关主题：[浏览器工具集](#browser-tools), [AI Agent 集成](#agent-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [app/chrome-extension/utils/vector-database.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/vector-database.ts)
- [app/chrome-extension/utils/semantic-similarity-engine.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/semantic-similarity-engine.ts)
- [app/chrome-extension/utils/text-chunker.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/text-chunker.ts)
- [app/chrome-extension/utils/simd-math-engine.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/utils/simd-math-engine.ts)
- [packages/wasm-simd/src/lib.rs](https://github.com/hangwin/mcp-chrome/blob/main/packages/wasm-simd/src/lib.rs)
# 语义搜索与向量数据库
## 概述
mcp-chrome 扩展中的语义搜索与向量数据库模块为浏览器标签页内容提供了基于语义理解的智能搜索能力。该模块将网页文本内容转换为高维向量嵌入（Embedding），存储在本地向量数据库中，并支持通过语义相似度进行跨标签页内容检索。
此功能的核心价值在于突破传统关键词搜索的局限性——用户可以使用自然语言描述来查找曾经访问过的内容，而无需记忆具体词汇或页面标题。
## 核心架构
### 模块组成
| 模块 | 文件路径 | 主要职责 |
|------|----------|----------|
| 向量数据库 | `utils/vector-database.ts` | 存储和管理文本块向量嵌入 |
| 语义相似度引擎 | `utils/semantic-similarity-engine.ts` | 生成文本嵌入并执行相似度计算 |
| 文本分块器 | `utils/text-chunker.ts` | 将长文本分割为可管理的块 |
| SIMD数学引擎 | `utils/simd-math-engine.ts` | 提供SIMD优化的向量运算 |
| WASM SIMD模块 | `packages/wasm-simd/src/lib.rs` | Rust实现的SIMD计算后端 |
### 架构图
```mermaid
graph TD
A[网页内容] --> B[内容索引器
content-indexer.ts]
B --> C[文本分块器
text-chunker.ts]
C --> D[语义相似度引擎
semantic-similarity-engine.ts]
D --> E[SIMD数学引擎
simd-math-engine.ts]
E --> F[WASM SIMD模块
Rust lib.rs]
F --> G[向量数据库
vector-database.ts]
G --> H[语义搜索查询]
B -.->|网络请求| I[Inject Script
web-fetcher-helper.js]
I --> B
```
## 工作流程
### 内容索引流程
当用户访问网页并完成加载后，系统自动触发以下索引流程：
```mermaid
graph LR
A[Tab加载完成] --> B{语义引擎就绪?}
B -->|否| C[跳过索引]
B -->|是| D[等待2秒缓冲]
D --> E[提取页面内容]
E --> F[执行web-fetcher-helper.js]
F --> G[获取文本和标题]
G --> H[文本分块]
H --> I[生成向量嵌入]
I --> J[存储至向量数据库]
K[Tab关闭/导航] --> L[删除相关索引]
```
### URL过滤机制
系统内置URL过滤规则，排除以下类型的地址不进行索引：
```typescript
const excludePatterns = [
/^chrome:\/\//, // Chrome内部页面
/^chrome-extension:\/\//, // 扩展页面
/^edge:\/\//, // Edge内部页面
/^about:/, // about页面
/^moz-extension:\/\//, // Firefox扩展
/^file:\/\//, // 本地文件
];
```
资料来源：[content-indexer.ts:55-61]()
### 语义搜索流程
```mermaid
graph TD
A[用户查询] --> B[转换为向量]
B --> C[向量数据库检索]
C --> D[计算余弦相似度]
D --> E[排序结果]
E --> F[返回相关内容片段]
```
## 向量数据库
向量数据库模块负责管理所有已索引内容的向量表示。每个向量条目包含以下信息：
- **文本块内容**：原始文本片段
- **向量嵌入**：由语义相似度引擎生成的高维向量
- **元数据**：来源标签页ID、URL、时间戳等
### 核心操作
| 操作 | 说明 |
|------|------|
| 插入 | 添加新的向量条目 |
| 删除 | 移除指定标签页的所有条目 |
| 搜索 | 基于向量相似度返回相关内容 |
| 更新 | 修改现有条目（通常不常用） |
## 语义相似度引擎
语义相似度引擎是将文本转换为向量嵌入的核心组件。它使用预训练的Transformer模型将任意文本映射到一个稠密的向量空间，使得语义相似的文本在该空间中距离较近。
### 主要功能
1. **嵌入生成**：将文本块转换为固定维度的浮点数向量
2. **相似度计算**：使用余弦相似度或点积计算向量间的语义相似程度
3. **批处理支持**：支持一次性处理多个文本块以提高效率
## 文本分块器
由于网页内容可能非常长，直接对整页内容生成单一向量会导致精度下降。文本分块器将长文本分割为适当大小的块，每个块独立生成向量。
### 分块策略考量
- **块大小**：需要在语义完整性和向量容量之间取得平衡
- **重叠**：相邻块之间可能存在一定重叠，以避免边界语义丢失
- **上下文保留**：分块时考虑句子和段落的自然边界
## SIMD数学引擎
为了在浏览器环境中实现高性能的向量运算，系统使用SIMD（单指令多数据）技术加速计算。
### WASM SIMD模块
Rust实现的SIMD计算后端通过WebAssembly提供以下能力：
- 向量点积计算
- 向量归一化
- 余弦相似度计算
- 批量矩阵运算
### 性能优化
```mermaid
graph LR
A[JavaScript向量运算] -->|慢| B[串行计算]
A -->|快| C[SIMD向量化]
C --> D[并行处理多条数据]
D --> E[显著提升吞吐量]
```
使用SIMD指令集，单条CPU指令可以同时处理多个数据元素，这对于大规模向量运算（如搜索10万条记录）尤为重要。
## 搜索标签页内容功能
语义搜索系统的主要应用场景是跨标签页的语义检索。
### 使用方式
用户可以通过自然语言描述来搜索之前访问过的标签页内容。例如：
- "查找我昨天看的关于机器学习的文章"
- "搜索包含Python代码示例的页面"
- "找出讨论过向量数据库的标签"
### 技术实现
1. 用户输入查询文本
2. 系统将查询转换为向量
3. 在向量数据库中执行相似度搜索
4. 返回最相关的标签页和内容片段
5. 提供快速跳转链接
## 配置与状态管理
### 引擎状态
语义引擎维护以下状态：
| 状态 | 说明 |
|------|------|
| 未初始化 | 引擎尚未加载 |
| 初始化中 | 正在加载模型 |
| 就绪 | 可接受索引和搜索请求 |
| 错误 | 引擎发生错误 |
### 自动索引控制
```typescript
if (this.options.autoIndex && changeInfo.status === 'complete' && tab.url) {
setTimeout(() => {
if (!this.isSemanticEngineReady() && !this.isSemanticEngineInitializing()) {
return; // 跳过
}
this.indexTabContent(tabId);
}, 2000);
}
```
资料来源：[content-indexer.ts:27-40]()
## 安全与隔离
### 扩展页面隔离
生产环境中启用以下安全策略：
```typescript
cross_origin_embedder_policy: { value: 'require-corp' },
cross_origin_opener_policy: { value: 'same-origin' },
```
资料来源：[wxt.config.ts:44-47]()
这些策略确保向量数据库和语义引擎的数据不会被恶意网页访问。
### Web资源访问控制
只有明确指定的资源可以被网页内容脚本访问：
```typescript
web_accessible_resources: [
'/models/*', // AI模型文件
'/workers/*', // Web Workers
'/inject-scripts/*' // 注入脚本
]
```
资料来源：[wxt.config.ts:25-33]()
## 性能优化策略
### 延迟索引
系统在页面加载完成2秒后才开始索引，避免阻塞页面渲染：
```typescript
setTimeout(() => {
this.indexTabContent(tabId);
}, 2000);
```
资料来源：[content-indexer.ts:33]()
### 条件索引
只有当语义引擎完全就绪时才执行索引操作，避免因引擎未准备好而产生错误。
### 导航事件监听
系统监听多种导航事件以保持索引同步：
- `tabs.onUpdated`：检测页面加载状态变化
- `tabs.onRemoved`：删除关闭标签页的索引
- `webNavigation.onCommitted`：检测主帧导航
- `webNavigation.onHistoryStateUpdated`：检测SPA路由变化
## 总结
mcp-chrome的语义搜索与向量数据库模块为浏览器标签页提供了强大的语义理解能力。通过将网页内容转换为向量嵌入并存储在本地向量数据库中，用户可以使用自然语言进行跨标签页搜索。SIMD优化的数学引擎确保了计算性能，而完善的索引管理机制保证了搜索结果的实时性和准确性。
---
## AI Agent 集成
### 相关页面
相关主题：[本地服务器架构](#native-server-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [app/native-server/src/agent/engines/types.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/types.ts)
- [app/native-server/src/agent/engines/claude.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/claude.ts)
- [app/native-server/src/agent/engines/codex.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/engines/codex.ts)
- [app/native-server/src/agent/chat-service.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/chat-service.ts)
- [app/native-server/src/agent/session-service.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/native-server/src/agent/session-service.ts)
- [app/chrome-extension/entrypoints/sidepanel/composables/useAgentChat.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/sidepanel/composables/useAgentChat.ts)
- [app/chrome-extension/entrypoints/sidepanel/composables/useAgentThreads.ts](https://github.com/hangwin/mcp-chrome/blob/main/app/chrome-extension/entrypoints/sidepanel/composables/useAgentThreads.ts)
# AI Agent 集成
## 概述
AI Agent 集成是 mcp-chrome 项目中连接浏览器扩展与本地 AI 引擎的核心模块。该系统支持多种 AI 引擎（包括 Claude 和 Codex），通过统一的接口抽象，为浏览器扩展提供智能代理能力。用户可以在浏览器侧边栏中与 AI Agent 对话，执行自动化工作流、网页内容分析和浏览器控制等任务。
## 架构设计
### 整体架构
```mermaid
graph TD
subgraph 浏览器扩展
A[Sidepanel UI] --> B[useAgentChat]
A --> C[useAgentThreads]
B --> D[MCP Tools]
C --> D
end
subgraph 本地服务
D --> E[ChromeMcpServer]
E --> F[ChatService]
E --> G[SessionService]
F --> H[Engine Adapter]
G --> H
end
subgraph AI 引擎
H --> I[Claude Engine]
H --> J[Codex Engine]
end
```
### 核心组件关系
| 组件 | 层级 | 职责 | 源码位置 |
|------|------|------|----------|
| `useAgentChat` | 前端 | 管理聊天状态、消息流、引擎选择 | `useAgentChat.ts` |
| `useAgentThreads` | 前端 | 管理 Agent 线程和工具调用可视化 | `useAgentThreads.ts` |
| `ChatService` | 服务层 | 协调 AI 引擎与 MCP 工具的交互 | `chat-service.ts` |
| `SessionService` | 服务层 | 管理会话生命周期和元数据 | `session-service.ts` |
| `ClaudeEngine` | 引擎层 | Claude API 集成实现 | `engines/claude.ts` |
| `CodexEngine` | 引擎层 | Codex CLI 集成实现 | `engines/codex.ts` |
## 引擎类型定义
### 引擎基类与类型
项目定义了统一的引擎抽象接口，支持多引擎并行：
```typescript
export interface AgentEngine {
name: string;
provider: string;
readonly: boolean;
chat(options: ChatOptions): Promise>;
destroy(): Promise;
}
```
资料来源：[engines/types.ts:1-10]()
### 支持的引擎类型
| 引擎 | Provider | 说明 |
|------|----------|------|
| Claude | Anthropic | 使用 Claude SDK 进行对话 |
| Codex | OpenAI | 使用 Codex CLI 进行代码任务 |
## 会话管理
### SessionService 功能
`SessionService` 负责管理 AI Agent 会话的生命周期，提供了丰富的会话元数据管理能力。
#### 管理信息接口
```typescript
export interface ManagementInfo {
models?: Array<{ value: string; displayName: string; description: string }>;
commands?: Array<{ name: string; description: string; argumentHint: string }>;
account?: { email?: string; organization?: string; subscriptionType?: string };
mcpServers?: Array<{ name: string; status: string }>;
tools?: string[];
agents?: string[];
plugins?: Array<{ name: string; path?: string }>;
skills?: string[];
slashCommands?: string[];
model?: string;
permissionMode?: string;
cwd?: string;
outputStyle?: string;
betas?: string[];
claudeCodeVersion?: string;
apiKeySource?: string;
lastUpdated?: string;
}
```
资料来源：[session-service.ts:46-69]()
#### 会话预览元数据
```typescript
export interface AgentSessionPreviewMeta {
displayText?: string;
clientMeta?: {
kind?: string;
// 扩展元数据
};
}
```
资料来源：[session-service.ts:82-88]()
### 会话配置选项
| 配置项 | 类型 | 说明 |
|--------|------|------|
| `model` | string | 指定使用的模型 |
| `mcpServers` | Record | MCP 服务器配置 |
| `outputFormat` | Record | 输出格式配置 |
| `enableFileCheckpointing` | boolean | 启用文件检查点 |
| `sandbox` | Record | 沙箱环境配置 |
| `env` | Record | 环境变量 |
| `codexConfig` | Partial | Codex 特定配置覆盖 |
## ChatService 协调层
### 核心职责
`ChatService` 作为中间协调层，负责：
1. 接收来自扩展的聊天请求
2. 路由到对应的 AI 引擎
3. 处理工具调用和结果回传
4. 管理会话状态
### 消息流处理
```mermaid
sequenceDiagram
participant EXT as 浏览器扩展
participant CHAT as ChatService
participant ENGINE as AI 引擎
participant MCP as MCP Tools
EXT->>CHAT: 发送用户消息
CHAT->>ENGINE: 转发消息流
ENGINE->>ENGINE: AI 处理
ENGINE-->>CHAT: 返回 ChatProgress 流
CHAT-->>EXT: 流式响应
Note over ENGINE,MCP: 工具调用时
ENGINE->>MCP: 请求工具执行
MCP-->>ENGINE: 返回执行结果
```
## Claude 引擎集成
### ClaudeEngine 实现
Claude 引擎通过官方 Claude SDK 实现对话功能：
```typescript
export class ClaudeEngine implements AgentEngine {
name = 'claude';
provider = 'anthropic';
readonly = false;
async *chat(options: ChatOptions): AsyncIterable {
// SDK 集成实现
}
}
```
### 关键能力
| 功能 | 支持 | 说明 |
|------|------|------|
| 流式输出 | ✅ | 支持实时流式响应 |
| 工具调用 | ✅ | 支持 MCP 工具集成 |
| 多模态 | ✅ | 支持图像输入 |
| 会话保持 | ✅ | 维护对话上下文 |
## Codex 引擎集成
### CodexEngine 特性
Codex 引擎通过 Codex CLI 实现，特别适用于代码任务：
```typescript
export class CodexEngine implements AgentEngine {
name = 'codex';
provider = 'openai';
readonly = false;
async *chat(options: ChatOptions): AsyncIterable {
// CLI 集成实现
}
}
```
### 配置参数
Codex 引擎支持丰富的配置选项：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `include_apply_patch_tool` | boolean | true | 包含 apply_patch 工具 |
| `include_plan_tool` | boolean | true | 包含计划工具 |
| `enableWebSearch` | boolean | false | 启用网页搜索 |
| `use_experimental_streamable_shell_tool` | boolean | - | 实验性流式 Shell 工具 |
资料来源：[engines/codex.ts:buildCodexConfigArgs()]()
### 项目上下文处理
Codex 引擎自动检测项目目录结构：
```typescript
// 读取目录内容，排除 .git 和 AGENTS.md
const visible = entries
.filter((entry) => !entry.name.startsWith('.git') && entry.name !== 'AGENTS.md')
.map((entry) => entry.name);
// 注入到系统提示
return `${baseInstruction}
Current files in project directory: ${visible.sort().join(', ')}
Work directly in the current directory.
`;
```
资料来源：[engines/codex.ts:appendProjectContext()]()
## 前端集成
### useAgentChat Composable
`useAgentChat` 是前端与 AI Agent 通信的核心 Hook：
```typescript
export function useAgentChat() {
// 聊天状态管理
// 消息发送与接收
// 引擎切换
// 流式响应处理
}
```
#### 核心功能
| 功能 | 方法 | 说明 |
|------|------|------|
| 发送消息 | `sendMessage()` | 发送用户消息 |
| 流式接收 | 响应迭代器 | 处理 AI 流式输出 |
| 引擎管理 | `switchEngine()` | 动态切换 AI 引擎 |
| 中断控制 | `abort()` | 中断正在进行的请求 |
### useAgentThreads Composable
`useAgentThreads` 提供 Agent 线程管理，包括工具调用的可视化展示：
```typescript
export function useAgentThreads() {
// 线程列表管理
// 工具调用记录
// 状态追踪
}
```
#### 工具调用分类
系统根据工具名称和内容自动分类工具调用：
| 类型 | 标签 | 判定规则 |
|------|------|----------|
| 计划 | Plan | toolName 包含 'plan' 或 'todo' |
| 编辑 | Edit | toolName 包含 'edit' 或 'patch' |
| 写入 | Write | toolName 包含 'write' 或 'create_file' |
| 命令 | Run | toolName 包含 'bash' 或 'shell' |
| 搜索 | Grep | toolName 包含 'grep' 或 'search' |
资料来源：[useAgentThreads.ts:工具分类规则]()
#### DiffStats 结构
```typescript
interface DiffStats {
added?: number;
removed?: number;
unchanged?: number;
filesChanged?: number;
}
```
资料来源：[useAgentThreads.ts:buildDiffStats()]()
## 工具调用可视化
### 消息元数据结构
每个工具调用消息包含丰富的元数据：
```typescript
interface ToolCallMeta {
toolName?: string;
filePath?: string;
command?: string;
commandDescription?: string;
pattern?: string;
searchPath?: string;
isError?: boolean;
files?: string[];
planPhase?: string;
todoCount?: number;
output?: string;
}
```
### 严重性级别
| 级别 | 触发条件 | 显示样式 |
|------|----------|----------|
| success | 工具成功执行且 phase === 'result' | 绿色 |
| error | is_error === true 或内容以 'Error:' 开头 | 红色 |
| info | 工具执行中或普通信息 | 蓝色 |
| warning | 子流超过最大迭代次数 | 黄色 |
资料来源：[useAgentThreads.ts:severity 判断逻辑]()
## 配置与扩展
### 引擎配置优先级
```
命令行参数 > 环境变量 > 配置文件 > 默认值
```
### 可扩展性设计
项目采用适配器模式支持新引擎：
```typescript
// 注册新引擎
export function registerEngine(engine: AgentEngine): void;
// 创建引擎工厂
export function createEngine(type: EngineType, config: EngineConfig): AgentEngine;
```
## 最佳实践
### 1. 引擎选择建议
| 场景 | 推荐引擎 | 原因 |
|------|----------|------|
| 通用对话 | Claude | 对话能力强 |
| 代码任务 | Codex | CLI 集成更紧密 |
| 快速原型 | Claude | 配置简单 |
### 2. 会话管理建议
- 定期清理不活跃会话以节省存储
- 使用 `displayText` 提供有意义的会话预览
- 通过 `clientMeta` 标记特殊会话类型
### 3. 错误处理
```typescript
const isError =
meta.is_error === true ||
meta.isError === true ||
(typeof msg.content === 'string' && msg.content.trimStart().startsWith('Error:'));
```
确保前端能正确处理和展示错误状态。
## 总结
AI Agent 集成模块通过统一的接口抽象和多引擎支持，为 mcp-chrome 提供了灵活且强大的 AI 能力。该架构设计遵循了开闭原则，便于后续添加新的 AI 引擎。前端组件 `useAgentChat` 和 `useAgentThreads` 提供了良好的用户交互体验，而服务层的 `ChatService` 和 `SessionService` 则确保了业务逻辑的清晰分离。
---
---
## Doramagic 踩坑日志
项目：hangwin/mcp-chrome
摘要：发现 15 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint。
## 1. 安装坑 · 来源证据：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Singleton McpServer causes 'Already connected to a transport' on HTTP endpoint
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ba76885913a744f0832665f5c62d0f1d | https://github.com/hangwin/mcp-chrome/issues/321 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Opencode cannot use chrome-mcp via mcp-server-stdio on Windows (Failed to connect to MCP server)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4ac5f778b292489482bfdb7953190f96 | https://github.com/hangwin/mcp-chrome/issues/319 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI setup guide still points to ~/.codex/config.json and a port-only flow Codex does not pick up
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_559f34b86ade48e598dac510e9341b9e | https://github.com/hangwin/mcp-chrome/issues/339 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 安装坑 · 来源证据：mcp-chrome-bridge 无法使用
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：mcp-chrome-bridge 无法使用
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5f19fb6526174af2abe5c1eab67e25ff | https://github.com/hangwin/mcp-chrome/issues/333 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：🐛 Status indicator stuck on yellow - Service shows as "not started" after connection
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：🐛 Status indicator stuck on yellow - Service shows as "not started" after connection
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2b32536c95a7456788ba78e1fc705116 | https://github.com/hangwin/mcp-chrome/issues/342 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 6. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | host_targets=mcp_host, claude
## 7. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | README/documentation is current enough for a first validation pass.
## 8. 运行坑 · 来源证据：v0.0.6
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.0.6
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_035dffafcbe64f4ea112f20258430e71 | https://github.com/hangwin/mcp-chrome/releases/tag/v0.0.6 | 来源类型 github_release 暴露的待验证使用条件。
## 9. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | last_activity_observed missing
## 10. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | no_demo; severity=medium
## 11. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | No sandbox install has been executed yet; downstream must verify before user use.
## 12. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | no_demo; severity=medium
## 13. 安全/权限坑 · 来源证据：issue
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：issue
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_82ad93635a5e4ff5aeb2b35e36cbd02e | https://github.com/hangwin/mcp-chrome/issues/330 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 14. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | issue_or_pr_quality=unknown
## 15. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:998796026 | https://github.com/hangwin/mcp-chrome | release_recency=unknown