概述

mcp-chrome 是一个基于 Chrome 扩展实现的 MCP (Model Context Protocol) Server，它将 Chrome 浏览器的控制能力以标准化的工具接口暴露给 AI 助手使用。通过这个项目，AI 可以直接操控浏览器完成网页自动化、网页内容提取、用户脚本管理等多种复杂任务。资料来源：README.md

核心特性

资料来源：README.md

项目概述

mcp-chrome 是一个基于 Chrome 扩展和本地原生消息（Native Messaging）通信协议的 MCP（Model Context Protocol）服务器实现。它允许 AI 模型通过标准化的接口直接控制 Chrome 浏览器，完成网页交互、内容提取、网络监控等任务。

系统架构

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

前置要求

资料来源：app/native-server/package.json

安装步骤

步骤 1：安装原生服务器

原生服务器负责处理 AI 模型与 Chrome 浏览器之间的原生消息通信。

# 克隆项目
git clone https://github.com/hangwin/mcp-chrome.git
cd mcp-chrome

# 进入原生服务器目录
cd app/native-server

# 安装依赖
pnpm install
# 或
npm install

步骤 2：构建项目

# 构建原生服务器
pnpm build

# 构建 Chrome 扩展
cd ../chrome-extension
pnpm install
pnpm build

资料来源：app/chrome-extension/package.json

步骤 3：注册原生消息主机

根据你的操作系统和浏览器，需要配置 Native Messaging Host 清单文件。

#### Windows 系统

# 用户级注册（推荐）
.\dist\cli.js register --browser chrome

# 或系统级注册（需要管理员权限）
.\dist\cli.js register --browser chrome --system

#### macOS 系统

# 用户级注册
./dist/cli.js register --browser chrome

# 系统级注册（需要 sudo）
sudo ./dist/cli.js register --browser chrome --system

#### Linux 系统

# 用户级注册
./dist/cli.js register --browser chrome

# 系统级注册
sudo ./dist/cli.js register --browser chrome --system

资料来源：app/native-server/src/scripts/browser-config.ts

步骤 4：安装 Chrome 扩展

1. 打开 Chrome，访问 chrome://extensions/
2. 开启右上角的「开发者模式」
3. 点击「加载已解压的扩展程序」
4. 选择 app/chrome-extension/dist 目录

清单文件路径配置

不同平台和浏览器的 Native Messaging Host 清单文件路径如下：

资料来源：app/native-server/src/scripts/browser-config.ts

验证安装

使用诊断命令检查安装状态：

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

常见诊断结果

MCP 客户端配置

安装完成后，在你的 MCP 客户端配置文件中添加以下配置：

{
  "mcpServers": {
    "chrome": {
      "command": "node",
      "args": ["/path/to/mcp-chrome/app/native-server/dist/index.js"]
    }
  }
}

可用工具一览

安装成功后，以下工具将自动可用：

🌐 标签页管理（5 个工具）

🔧 浏览器控制（7 个工具）

🎯 页面交互（3 个工具）

📚 数据管理（5 个工具）

🌐 网络监控（4 个工具）

资料来源：README.md

安全配置

Chrome 扩展在生产环境中启用了以下安全策略：

{
  "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

故障排除

1. 清单文件未找到

# 自动检测并注册
pnpm run register --detect

2. 浏览器无法连接

确保 Chrome 扩展已正确加载，并且原生服务器正在运行：

# 检查服务器状态
pnpm doctor

3. 权限问题（Linux/macOS）

# 确保可执行文件有运行权限
chmod +x dist/cli.js
chmod +x dist/index.js

下一步

• 查看 使用示例 了解常见场景
• 阅读 API 文档 深入了解各工具的参数
• 参考 架构设计 理解内部实现

概述

mcp-chrome 是一个将 Chrome 浏览器与 AI 大模型深度集成的开源项目，通过 Model Context Protocol (MCP) 协议实现浏览器自动化控制与智能交互。该项目由 Chrome 扩展端 和 本地服务（Native Server）端 两大部分组成，采用主从架构设计，通过 Chrome Native Messaging 原生消息通信机制实现双向通信。

核心目标：

• 为 AI Agent 提供完整的浏览器控制能力
• 支持网页内容提取、交互、截图、网络监控等操作
• 实现跨平台的 Chrome 浏览器自动化

资料来源：docs/ARCHITECTURE_zh.md

整体架构

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<br/>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 的执行会话，包括会话状态、上下文信息、配置参数等。

interface SessionConfig {
  mcpServers?: Record<string, unknown>;
  outputFormat?: Record<string, unknown>;
  enableFileCheckpointing?: boolean;
  sandbox?: Record<string, unknown>;
  env?: Record<string, string>;
  codexConfig?: Partial<CodexEngineConfig>;
}

关键特性：

• 支持多种引擎配置（Claude、Codex）
• 会话元数据缓存（Management Info）
• 插件和技能管理
• 输出格式自定义

资料来源：app/native-server/src/agent/session-service.ts:1-80

#### 1.3 Engine Adapter

引擎适配器层封装了不同 AI 引擎的调用接口，目前支持 Claude 和 Codex 两种引擎。

Claude Engine 实现：

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: 返回响应

工具消息分类：

资料来源：app/native-server/src/agent/engines/claude.ts:1-80

#### 1.4 Native Messaging Host

Native Messaging Host 是 Chrome 扩展与本地服务通信的桥梁，支持跨平台的消息传递。

平台特定路径配置：

功能：

• 消息序列化与反序列化
• 进程间通信管理
• 心跳检测与断线重连

资料来源：app/native-server/src/scripts/browser-config.ts:1-100 资料来源：app/native-server/src/scripts/utils.ts:1-80

概述

mcp-chrome 是一个基于 Chrome 扩展的 MCP（Model Context Protocol）服务器实现，旨在为 AI 提供完整的浏览器控制能力。该扩展通过 WXT 框架构建，采用多入口点架构，涵盖后台脚本、内容脚本、侧边栏、弹出窗口等多种扩展页面类型。

整体架构

graph TB
    subgraph "扩展页面层"
        Popup["弹出窗口<br/>popup/"]
        Sidepanel["侧边栏<br/>sidepanel/"]
        Builder["工作流编辑器<br/>builder/"]
        Welcome["欢迎页<br/>welcome/"]
        Options["选项页<br/>options/"]
    end
    
    subgraph "核心服务层"
        Background["后台脚本<br/>background/"]
        Content["内容脚本<br/>content.ts"]
    end
    
    subgraph "功能模块层"
        RecordReplay["录制回放引擎<br/>record-replay/"]
        ContentIndexer["内容索引器<br/>content-indexer.ts"]
        ToolRegistry["工具注册表"]
        TriggerEngine["触发器引擎"]
    end
    
    subgraph "注入脚本层"
        WebFetcher["网页内容提取<br/>web-fetcher-helper.js"]
        DOMObserver["DOM 观察器<br/>dom-observer.js"]
        InjectBridge["注入桥接<br/>inject-bridge.js"]
        AccessibilityTree["无障碍树辅助<br/>accessibility-tree-helper"]
    end
    
    subgraph "外部通信"
        NativeServer["原生服务器<br/>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

入口点架构

入口点清单

资料来源：wxt.config.ts

manifest.json 配置

扩展采用 WXT 框架自动生成 manifest.json，关键配置包括：

manifest: {
  permissions: [
    'tabs',
    'storage',
    'webNavigation',
    'webRequest',
    'scripting',
    'nativeMessaging'
  ],
  host_permissions: ['<all_urls>'],
  web_accessible_resources: [
    '/models/*',
    '/workers/*',
    '/inject-scripts/*'
  ]
}

后台脚本架构

后台脚本职责

后台脚本（Service Worker）是扩展的核心中枢，负责：

1. MCP 协议通信 - 与原生服务器建立 Native Messaging 连接
2. 工具注册与分发 - 管理所有可用工具的定义和调用
3. 标签页管理 - 协调多标签页间的通信
4. 状态维护 - 管理扩展的全局状态

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

工具分类体系

内容脚本架构

内容脚本职责

内容脚本运行在网页上下文中，主要负责：

• 直接访问和操作页面 DOM
• 注入用户脚本
• 收集页面信息
• 响应后台脚本的消息

注入脚本层次

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 负责从网页中提取结构化数据：

// 元数据提取流程
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

内容索引系统

ContentIndexer 模块

content-indexer.ts 实现了自动化的标签页内容索引功能：

class ContentIndexer {
  private options: {
    autoIndex: boolean;      // 是否自动索引
    maxContentLength: number; // 最大内容长度
  }
  
  // 核心方法
  indexTabContent(tabId: number): Promise<void>
  removeTabIndex(tabId: number): Promise<void>
  shouldIndexUrl(url: string): boolean
  extractTabContent(tabId): Promise<{ textContent, title }>
}

URL 过滤规则

以下 URL 模式被排除在索引之外：

索引触发时机

graph LR
    A["页面加载完成<br/>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

录制回放引擎

引擎架构

record-replay/index.ts 实现了 DOM 触发器驱动的自动化录制回放系统：

interface TriggerConfig {
  type: 'dom' | 'network' | 'custom';
  selector?: string;      // DOM 选择器
  appear?: boolean;       // 出现时触发
  once?: boolean;         // 仅触发一次
  debounceMs?: number;    // 防抖延迟
  enabled?: boolean;
}

触发器类型

触发器工作流程

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

安全策略

Content Security Policy

生产环境启用严格 CSP 策略：

content_security_policy: {
  extension_pages: 
    "script-src 'self' 'wasm-unsafe-eval'; " +
    "object-src 'self'; " +
    "style-src 'self' 'unsafe-inline'; " +
    "img-src 'self' data: blob:;"
}

跨域隔离策略

cross_origin_embedder_policy: { value: 'require-corp' },
cross_origin_opener_policy: { value: 'same-origin' }

Web Accessible Resources

技术栈

资料来源：wxt.config.ts

扩展生命周期

stateDiagram-v2
    [*] --> 安装: 首次安装
    安装 --> 就绪: 初始化完成
    就绪 --> 活跃: 用户操作
    活跃 --> 等待: 空闲超时
    等待 --> 活跃: 新操作
    活跃 --> 更新: manifest 更新
    更新 --> 就绪: 重新初始化
    就绪 --> [*]: 卸载

常量定义

扩展使用集中式常量管理：

// 存储键名
const STORAGE_KEYS = {
  RR_TRIGGERS: 'rr_triggers',
  // ... 其他键
}

// 消息类型
const CONTENT_MESSAGE_TYPES = {
  ACCESSIBILITY_TREE_HELPER_PING: '...',
  // ... 其他类型
}

资料来源：common/constants.ts

总结

mcp-chrome 扩展采用现代化的多入口点架构，通过 WXT 框架简化了 manifest 管理。核心设计特点包括：

1. 分层架构 - 清晰的后台脚本、内容脚本、注入脚本分层
2. 工具化设计 - 丰富的浏览器控制工具集
3. 自动化索引 - 智能的内容索引系统
4. 录制回放 - 基于触发器的自动化引擎
5. 安全优先 - 严格的 CSP 和跨域策略

概述

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 采用分层架构设计，各层之间通过定义良好的接口进行通信：

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 客户端的请求
• 调度工具执行并返回结果
• 管理会话生命周期

资料来源：app/native-server/src/mcp/mcp-server.ts:1-100

Agent 引擎

Agent 引擎负责协调 AI 模型与工具系统之间的交互。当前实现支持 Claude 模型，未来可扩展支持其他模型。

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 扩展的枢纽，负责：

• 工具发现和元数据管理
• 参数验证和转换
• 执行结果格式化
• 错误处理和重试

资料来源：app/native-server/src/agent/tool-bridge.ts:1-80

通信机制

Native Messaging 协议

mcp-chrome 使用 Chrome 的 Native Messaging 协议实现与扩展的安全通信。该协议基于标准输入/输出流进行 JSON 消息交换。

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 响应

消息格式遵循以下结构：

{
  "id": "unique-message-id",
  "method": "tool_name",
  "params": {
    "tabId": 123,
    "selector": "#element"
  }
}

跨平台支持

本地服务器支持多个操作系统和浏览器组合的 Native Messaging 配置：

资料来源：app/native-server/src/scripts/browser-config.ts:30-90

内容索引系统

语义搜索引擎

content-indexer 模块提供了对浏览器标签页内容进行语义搜索的能力，这对于 AI 代理理解用户当前浏览内容至关重要。

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

关键配置参数：

资料来源：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 提供了完整的系统诊断功能，确保本地服务器正确安装和配置：

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

诊断检查项

诊断报告会生成 Markdown 格式的输出，包含：

• 各检查项的详细状态
• 预期路径与实际路径对比
• 修复建议和命令

资料来源：app/native-server/src/scripts/doctor.ts:100-200

工作流程示例

完整工具调用流程

当 AI 代理需要执行浏览器操作时，整个调用流程如下：

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

状态管理

工具执行过程中的状态流转：

资料来源：app/native-server/src/agent/engines/claude.ts:80-120

安全考虑

Content Security Policy

生产环境中启用严格的安全策略：

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 三大平台
• 流式处理：支持实时交互的低延迟响应
• 可扩展性：工具系统和引擎系统均支持灵活扩展

该架构为构建智能化的浏览器自动化应用提供了坚实的技术基础。

概述

浏览器工具集是 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 协议暴露标准化的工具接口。

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[脚本注入执行]

工具分类

资料来源：docs/TOOLS.md:1-30

标签页管理

功能列表

资料来源：app/chrome-extension/entrypoints/background/tools/browser/index.ts:50-100

创建标签页

chrome_create_tab 工具支持以下参数：

标签页切换与关闭

• chrome_switch_tab 支持通过标签页 ID 或 URL 模式切换
• chrome_close_tabs 支持关闭单个标签页、多个标签页或整个窗口
• 所有操作均返回更新后的标签页状态

导航控制

前进/后退

chrome_go_back_or_forward 工具提供浏览器历史导航功能：

视图控制

截图功能

chrome_screenshot

高级截图工具，支持多种截图模式：

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. 拼接图像片段

网络监控

工具列表

资料来源：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 请求：

interface NetworkRequestOptions {
  url: string;           // 请求 URL
  method?: string;       // HTTP 方法
  headers?: object;      // 请求头
  body?: string;         // 请求体
  timeout?: number;      // 超时时间
}

内容分析

工具列表

资料来源：app/chrome-extension/entrypoints/background/tools/browser/content-analysis.ts:1-80

search_tabs_content

基于语义的内容搜索工具，支持：

• 跨多个浏览器标签页进行全文搜索
• 使用向量嵌入进行语义匹配
• 返回匹配结果及其上下文片段

chrome_get_web_content

网页内容提取工具：

交互元素获取

chrome_get_interactive_elements 返回页面的可点击元素：

interface InteractiveElement {
  tagName: string;        // 元素标签名
  id?: string;           // 元素 ID
  className?: string;    // 样式类名
  textContent?: string;  // 文本内容
  attributes: object;    // 所有属性
  boundingRect: object;  // 位置坐标
  selector: string;      // 唯一选择器
}

交互操作

工具列表

资料来源：app/chrome-extension/entrypoints/background/tools/browser/interaction.ts:1-50

元素点击

chrome_click_element 通过 DOM 选择器定位并点击元素：

表单操作

chrome_fill_or_select 支持多种表单输入：

• 文本输入：直接设置 input 值并触发 change 事件
• 下拉选择：通过 value 或文本选择选项
• 复选框/单选框：设置 checked 状态
• 文件上传：设置文件路径

键盘模拟

chrome_keyboard 支持：

• 普通文本输入
• 快捷键组合（如 Command+Shift+P）
• 特殊键序列

脚本注入

chrome_inject_script

在网页上下文中执行自定义 JavaScript：

chrome_send_command_to_inject_script

向已注入的内容脚本发送命令，实现双向通信：

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: 返回结果

数据模型

工具返回格式

所有工具遵循统一的响应格式：

interface ToolResponse<T = unknown> {
  success: boolean;      // 操作是否成功
  data?: T;             // 返回数据
  error?: string;       // 错误信息
  metadata?: {          // 元数据
    tabId?: number;
    timestamp: number;
    duration?: number;
  };
}

标签页模型

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

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：脚本注入
• <all_urls>：全网站访问

最佳实践

性能优化

1. 批量操作：多个标签页操作时使用 Promise.all 并行执行
2. 按需截图：仅在需要时进行全页面截图，避免频繁滚动
3. 网络过滤：使用精确的 URL 模式过滤减少事件监听开销

错误处理

1. 标签页操作前检查标签页是否存在
2. 网络请求设置合理的超时时间
3. 脚本注入前验证目标页面是否加载完成

安全考虑

1. 避免在不可信页面执行未验证的脚本
2. 网络请求监控注意敏感信息保护
3. 脚本注入仅在必要时使用

相关资源

• 工具文档（英文）
• 工具文档（中文）
• Chrome Extension API 文档

概述

录制回放系统是 Chrome MCP 扩展中用于记录用户浏览器操作并在需要时进行自动化回放的模块。该系统通过监听浏览器事件、捕获 DOM 变化、记录网络请求等方式，实现对用户操作流程的完整复现。

系统设计目标包括：

• 操作录制：自动捕获用户的导航、点击、表单填写等交互行为
• 智能触发：支持基于 URL、DOM 变化、时间等多种触发条件
• 流程回放：精确还原录制时的操作序列
• 状态同步：在回放过程中处理页面状态变化和异步操作

系统架构

核心组件

架构图

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 监听页面导航事件，这是录制回放系统的核心数据来源。

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);
  // ... 触发器处理逻辑
});

关键事件类型：

标签页事件监听

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();
});

导航类型过滤

系统会过滤特定的导航类型，只录制有意义的用户操作：

const shouldRecord =
  t === 'reload' ||
  t === 'typed' ||
  t === 'generated' ||
  t === 'auto_bookmark' ||
  t === 'keyword' ||
  t === 'form_submit';  // 捕获回车搜索行为

不录制的类型：link（纯链接点击由其他机制处理）

流程数据模型

Flow 结构

Flow 是录制回放系统的核心数据结构，用于存储录制过程中捕获的所有操作信息。

interface Flow {
  id: string;           // 唯一标识
  steps: FlowStep[];    // 操作步骤列表
  metadata: FlowMeta;   // 元数据
  triggers?: Trigger[]; // 关联的触发器
}

interface FlowStep {
  type: 'navigation' | 'click' | 'input' | 'wait' | 'screenshot';
  timestamp: number;
  data: Record<string, unknown>;
}

导航步骤

导航步骤记录页面 URL 变化和相关上下文：

if (flow && url) {
  addNavigationStep(flow, url);
}

触发器系统

触发器类型

DOM 触发器配置

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,  // 防抖延迟
  }));

等待策略

系统在回放过程中使用多种等待策略来确保页面状态就绪。

网络空闲检测

export async function waitForNetworkIdle(
  tabId: number,
  sniffMs: number = 500,
  finish: () => void
): Promise<void> {
  let mark: () => void;
  let timer: ReturnType<typeof setTimeout>;

  const getLogger = (): ((...args: unknown[]) => void) => {
    return (...args: unknown[]) => console.log('[NetworkIdle]', ...args);
  };

  const isIdle = (): boolean => {
    // 检测逻辑
  };

  const wait = (): Promise<void> =>
    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);
    });
}

参数说明：

内容脚本注入

系统通过 chrome.scripting.executeScript API 向目标页面注入脚本，以获取页面内容或执行特定操作。

await chrome.scripting.executeScript({
  target: { tabId: details.tabId, allFrames: true },
  files: ['inject-scripts/dom-observer.js'],
  world: 'ISOLATED',
});

注入脚本类型

消息通信

await chrome.tabs.sendMessage(details.tabId, {
  action: 'setTriggers',
  triggers: domTriggers,
});

录制状态管理

会话状态

interface Session {
  getStatus(): 'idle' | 'recording' | 'replaying';
  getFlow(): Flow | null;
  getActiveTabs(): number[];
}

状态转换

stateDiagram-v2
    [*] --> Idle: 初始化
    Idle --> Recording: 开始录制
    Recording --> Replaying: 执行回放
    Replaying --> Idle: 回放完成
    Recording --> Idle: 停止录制
    Idle --> [*]: 清理

活动标签页管理

// 录制开始时记录活动标签页
session.addActiveTab(tabId);

// 标签页关闭时移除
chrome.tabs.onRemoved.addListener((tabId) => {
  if (session.getStatus() !== 'recording') return;
  session.removeActiveTab(tabId);
});

与其他模块的交互

与工具系统的集成

录制回放系统通过 MCP 工具协议暴露功能：

// 注册命令处理器
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 模块共享部分事件监听器：

if (chrome.webNavigation) {
  chrome.webNavigation.onCommitted.addListener(async (details) => {
    if (details.frameId === 0) {
      await this.removeTabIndex(details.tabId);
    }
  });
}

安全考虑

跨域隔离策略

在生产环境中，系统启用以下安全策略：

cross_origin_embedder_policy: { value: 'require-corp' as const },
cross_origin_opener_policy: { value: 'same-origin' as const },

内容安全策略

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，避免无效广播

相关文档

• 工具系统概览
• 内容索引系统
• MCP 协议文档

概述

可视化编辑器（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 两个版本并行运行的架构设计：

两个版本使用不同的 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 注册快捷入口：

await chrome.contextMenus.create({
  id: CONTEXT_MENU_ID,
  title: '切换网页编辑模式',
  contexts: ['all'],
});

该菜单项支持在任意页面通过右键调用"切换网页编辑模式"功能。资料来源：app/chrome-extension/entrypoints/background/web-editor/index.ts:150-170

脚本注入机制

编辑器支持将脚本动态注入到目标页面，注入过程如下：

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 接收命令，切换页面编辑状态

动作响应函数

根据版本不同，编辑器支持以下核心动作：

资料来源：app/chrome-extension/entrypoints/background/web-editor/index.ts:200-250

状态管理

等待策略

编辑器内置网络空闲等待策略，用于确保页面完全加载后再进行操作：

function waitForNetworkIdle(tabId: number, sniffMs = 2000): Promise<void> {
  // 监听网络请求完成
  // 监听标签页更新
  // 监听 URL 变化
  // 超时自动结束
}

资料来源：app/chrome-extension/entrypoints/background/record-replay/engine/policies/wait.ts:1-50

设计令牌

编辑器使用设计令牌系统统一管理样式变量，确保界面一致性：

// 设计令牌示例
export const tokens = {
  colors: {
    primary: '#xxx',
    secondary: '#xxx',
  },
  spacing: {
    small: '8px',
    medium: '16px',
  },
};

扩展集成

入口点配置

mcp-chrome 扩展定义了多个入口点，编辑器作为 Sidepanel 页面的一部分运行：

资料来源：app/chrome-extension/entrypoints/sidepanel/index.html:1-15

Web Accessible Resources

编辑器通过 web_accessible_resources 配置允许注入脚本访问资源：

web_accessible_resources: [
  {
    resources: [
      '/models/*',
      '/workers/*',
      '/inject-scripts/*',
    ],
    matches: ['<all_urls>'],
  },
]

资料来源：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. 在需要时触发执行

安全策略

编辑器在生产环境启用以下安全策略：

开发环境使用 WXT 默认策略，避免阻断开发服务器资源加载。资料来源：app/chrome-extension/wxt.config.ts:35-50

总结

可视化编辑器是 mcp-chrome 项目的核心交互模块，通过结合 Chrome 扩展 API、MCP 协议和 AI Agent 技术，实现了自然语言驱动的网页编辑能力。其双版本架构确保了向后兼容性和持续演进，丰富的上下文菜单集成和脚本注入机制提供了灵活的使用方式。

概述

mcp-chrome 扩展中的语义搜索与向量数据库模块为浏览器标签页内容提供了基于语义理解的智能搜索能力。该模块将网页文本内容转换为高维向量嵌入（Embedding），存储在本地向量数据库中，并支持通过语义相似度进行跨标签页内容检索。

此功能的核心价值在于突破传统关键词搜索的局限性——用户可以使用自然语言描述来查找曾经访问过的内容，而无需记忆具体词汇或页面标题。

核心架构

模块组成

架构图

graph TD
    A[网页内容] --> B[内容索引器<br/>content-indexer.ts]
    B --> C[文本分块器<br/>text-chunker.ts]
    C --> D[语义相似度引擎<br/>semantic-similarity-engine.ts]
    D --> E[SIMD数学引擎<br/>simd-math-engine.ts]
    E --> F[WASM SIMD模块<br/>Rust lib.rs]
    F --> G[向量数据库<br/>vector-database.ts]
    G --> H[语义搜索查询]
    
    B -.->|网络请求| I[Inject Script<br/>web-fetcher-helper.js]
    I --> B

工作流程

内容索引流程

当用户访问网页并完成加载后，系统自动触发以下索引流程：

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过滤规则，排除以下类型的地址不进行索引：

const excludePatterns = [
  /^chrome:\/\//,        // Chrome内部页面
  /^chrome-extension:\/\//, // 扩展页面
  /^edge:\/\//,          // Edge内部页面
  /^about:/,             // about页面
  /^moz-extension:\/\//, // Firefox扩展
  /^file:\/\//,          // 本地文件
];

资料来源：content-indexer.ts:55-61

语义搜索流程

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提供以下能力：

• 向量点积计算
• 向量归一化
• 余弦相似度计算
• 批量矩阵运算

性能优化

graph LR
    A[JavaScript向量运算] -->|慢| B[串行计算]
    A -->|快| C[SIMD向量化]
    C --> D[并行处理多条数据]
    D --> E[显著提升吞吐量]

使用SIMD指令集，单条CPU指令可以同时处理多个数据元素，这对于大规模向量运算（如搜索10万条记录）尤为重要。

搜索标签页内容功能

语义搜索系统的主要应用场景是跨标签页的语义检索。

使用方式

用户可以通过自然语言描述来搜索之前访问过的标签页内容。例如：

• "查找我昨天看的关于机器学习的文章"
• "搜索包含Python代码示例的页面"
• "找出讨论过向量数据库的标签"

技术实现

1. 用户输入查询文本
2. 系统将查询转换为向量
3. 在向量数据库中执行相似度搜索
4. 返回最相关的标签页和内容片段
5. 提供快速跳转链接

配置与状态管理

引擎状态

语义引擎维护以下状态：

自动索引控制

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

安全与隔离

扩展页面隔离

生产环境中启用以下安全策略：

cross_origin_embedder_policy: { value: 'require-corp' },
cross_origin_opener_policy: { value: 'same-origin' },

资料来源：wxt.config.ts:44-47

这些策略确保向量数据库和语义引擎的数据不会被恶意网页访问。

Web资源访问控制

只有明确指定的资源可以被网页内容脚本访问：

web_accessible_resources: [
  '/models/*',        // AI模型文件
  '/workers/*',       // Web Workers
  '/inject-scripts/*' // 注入脚本
]

资料来源：wxt.config.ts:25-33

性能优化策略

延迟索引

系统在页面加载完成2秒后才开始索引，避免阻塞页面渲染：

setTimeout(() => {
  this.indexTabContent(tabId);
}, 2000);

资料来源：content-indexer.ts:33

条件索引

只有当语义引擎完全就绪时才执行索引操作，避免因引擎未准备好而产生错误。

导航事件监听

系统监听多种导航事件以保持索引同步：

• tabs.onUpdated：检测页面加载状态变化
• tabs.onRemoved：删除关闭标签页的索引
• webNavigation.onCommitted：检测主帧导航
• webNavigation.onHistoryStateUpdated：检测SPA路由变化

总结

mcp-chrome的语义搜索与向量数据库模块为浏览器标签页提供了强大的语义理解能力。通过将网页内容转换为向量嵌入并存储在本地向量数据库中，用户可以使用自然语言进行跨标签页搜索。SIMD优化的数学引擎确保了计算性能，而完善的索引管理机制保证了搜索结果的实时性和准确性。

概述

AI Agent 集成是 mcp-chrome 项目中连接浏览器扩展与本地 AI 引擎的核心模块。该系统支持多种 AI 引擎（包括 Claude 和 Codex），通过统一的接口抽象，为浏览器扩展提供智能代理能力。用户可以在浏览器侧边栏中与 AI Agent 对话，执行自动化工作流、网页内容分析和浏览器控制等任务。

架构设计

整体架构

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

核心组件关系

引擎类型定义

引擎基类与类型

项目定义了统一的引擎抽象接口，支持多引擎并行：

export interface AgentEngine {
  name: string;
  provider: string;
  readonly: boolean;
  
  chat(options: ChatOptions): Promise<AsyncIterable<ChatProgress>>;
  destroy(): Promise<void>;
}

资料来源：engines/types.ts:1-10

支持的引擎类型

会话管理

SessionService 功能

SessionService 负责管理 AI Agent 会话的生命周期，提供了丰富的会话元数据管理能力。

#### 管理信息接口

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

#### 会话预览元数据

export interface AgentSessionPreviewMeta {
  displayText?: string;
  clientMeta?: {
    kind?: string;
    // 扩展元数据
  };
}

资料来源：session-service.ts:82-88

会话配置选项

ChatService 协调层

核心职责

ChatService 作为中间协调层，负责：

1. 接收来自扩展的聊天请求
2. 路由到对应的 AI 引擎
3. 处理工具调用和结果回传
4. 管理会话状态

消息流处理

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 实现对话功能：

export class ClaudeEngine implements AgentEngine {
  name = 'claude';
  provider = 'anthropic';
  readonly = false;
  
  async *chat(options: ChatOptions): AsyncIterable<ChatProgress> {
    // SDK 集成实现
  }
}

关键能力

Codex 引擎集成

CodexEngine 特性

Codex 引擎通过 Codex CLI 实现，特别适用于代码任务：

export class CodexEngine implements AgentEngine {
  name = 'codex';
  provider = 'openai';
  readonly = false;
  
  async *chat(options: ChatOptions): AsyncIterable<ChatProgress> {
    // CLI 集成实现
  }
}

配置参数

Codex 引擎支持丰富的配置选项：

资料来源：engines/codex.ts:buildCodexConfigArgs()

项目上下文处理

Codex 引擎自动检测项目目录结构：

// 读取目录内容，排除 .git 和 AGENTS.md
const visible = entries
  .filter((entry) => !entry.name.startsWith('.git') && entry.name !== 'AGENTS.md')
  .map((entry) => entry.name);

// 注入到系统提示
return `${baseInstruction}
<current_project_context>
Current files in project directory: ${visible.sort().join(', ')}
Work directly in the current directory.
</current_project_context>`;

资料来源：engines/codex.ts:appendProjectContext()

前端集成

useAgentChat Composable

useAgentChat 是前端与 AI Agent 通信的核心 Hook：

export function useAgentChat() {
  // 聊天状态管理
  // 消息发送与接收
  // 引擎切换
  // 流式响应处理
}

#### 核心功能

useAgentThreads Composable

useAgentThreads 提供 Agent 线程管理，包括工具调用的可视化展示：

export function useAgentThreads() {
  // 线程列表管理
  // 工具调用记录
  // 状态追踪
}

#### 工具调用分类

系统根据工具名称和内容自动分类工具调用：

资料来源：useAgentThreads.ts:工具分类规则

#### DiffStats 结构

interface DiffStats {
  added?: number;
  removed?: number;
  unchanged?: number;
  filesChanged?: number;
}

资料来源：useAgentThreads.ts:buildDiffStats()

工具调用可视化

消息元数据结构

每个工具调用消息包含丰富的元数据：

interface ToolCallMeta {
  toolName?: string;
  filePath?: string;
  command?: string;
  commandDescription?: string;
  pattern?: string;
  searchPath?: string;
  isError?: boolean;
  files?: string[];
  planPhase?: string;
  todoCount?: number;
  output?: string;
}

严重性级别

资料来源：useAgentThreads.ts:severity 判断逻辑

配置与扩展

引擎配置优先级

命令行参数 > 环境变量 > 配置文件 > 默认值

可扩展性设计

项目采用适配器模式支持新引擎：

// 注册新引擎
export function registerEngine(engine: AgentEngine): void;

// 创建引擎工厂
export function createEngine(type: EngineType, config: EngineConfig): AgentEngine;

最佳实践

1. 引擎选择建议

2. 会话管理建议

• 定期清理不活跃会话以节省存储
• 使用 displayText 提供有意义的会话预览
• 通过 clientMeta 标记特殊会话类型

3. 错误处理

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 则确保了业务逻辑的清晰分离。

Pitfall Log / 踩坑日志

项目：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