claude-code/docs/features/claude-in-chrome-mcp.md

Claude in Chrome MCP — 恢复计划

更新时间：2026-04-03 参考项目：E:\源码\claude-code-source-main\claude-code-source-main

1. 功能概述

Claude in Chrome 让 Claude Code CLI 通过 MCP 协议控制用户的 Chrome 浏览器：导航网页、填写表单、截图、录制 GIF、读取 DOM、执行 JS、监控网络请求和控制台日志。

通信方式有两种：

• 本地 Socket：Chrome 扩展通过 Native Messaging Host 与 CLI 建立 Unix socket 连接
• Bridge WebSocket：通过 Anthropic 的 bridge 服务中转，支持远程浏览器

2. 完整加载链路

CLI 启动
  │
  ▼
src/main.tsx:1003
  .option('--chrome', 'Enable Claude in Chrome integration')
  │
  ▼
src/main.tsx:1522-1527
  setChromeFlagOverride(chromeOpts.chrome)
  │
  ▼
src/utils/claudeInChrome/setup.ts
  shouldEnableClaudeInChrome()
  ├── --chrome flag → true
  ├── --no-chrome flag → false
  ├── 非交互模式 → false
  ├── 环境变量 CLAUDE_CODE_DISABLE_CHROME → false
  ├── 配置 claudeInChromeDefaultEnabled → true/false
  └── Chrome 扩展已安装 + GrowthBook tengu_chrome_auto_enable → auto
  │
  ▼
src/utils/claudeInChrome/setup.ts
  setupClaudeInChrome()
  ├── 生成 MCP server 配置
  └── 返回 mcpConfig + allowedTools
  │
  ▼
src/utils/claudeInChrome/mcpServer.ts
  import { createClaudeForChromeMcpServer } from '@ant/claude-for-chrome-mcp'
  │
  ▼
packages/@ant/claude-for-chrome-mcp/src/index.ts  ← 当前是 STUB
  export function createClaudeForChromeMcpServer() { return null }
  export const BROWSER_TOOLS = []

3. 阻塞点清单

#	阻塞点	位置	状态
①	@ant/claude-for-chrome-mcp 是 stub	packages/@ant/claude-for-chrome-mcp/src/index.ts	6 行空壳，返回 null
②	缺少完整实现（7 个文件，3038 行）	packages/@ant/claude-for-chrome-mcp/src/	只有 1 个 stub 文件

不需要任何 feature flag — /chrome 命令无条件注册在 src/commands.ts:264。

不需要改 src/ 下任何文件 — 以下文件全部与参考项目 0 行差异：

• src/utils/claudeInChrome/setup.ts
• src/utils/claudeInChrome/mcpServer.ts
• src/utils/claudeInChrome/common.ts
• src/utils/claudeInChrome/chromeNativeHost.ts
• src/utils/claudeInChrome/prompt.ts
• src/utils/claudeInChrome/setupPortable.ts
• src/utils/claudeInChrome/toolRendering.tsx
• src/commands/chrome/index.ts
• src/commands/chrome/chrome.tsx（仅 sourcemap 差异）
• src/skills/bundled/claudeInChrome.ts

4. 参考项目完整实现清单

参考项目路径：deps/@ant/claude-for-chrome-mcp/src/

文件	行数	职责
index.ts	15	导出入口：createBridgeClient、BROWSER_TOOLS、createChromeSocketClient、createClaudeForChromeMcpServer、localPlatformLabel + 类型导出
types.ts	134	类型定义：Logger、PermissionMode、BridgeConfig、ChromeExtensionInfo、ClaudeForChromeContext、SocketClient、BridgePermissionRequest/Response、PermissionOverrides
browserTools.ts	546	17 个浏览器工具定义（MCP tool schema）
mcpServer.ts	96	MCP Server 创建：注册 ListTools/CallTool handler，选择 socket/bridge 传输
mcpSocketClient.ts	493	Unix Socket 客户端：连接 Chrome Native Messaging Host，JSON-RPC 通信
mcpSocketPool.ts	327	Socket 连接池：多 Chrome profile 支持，按 tabId 路由
bridgeClient.ts	1126	Bridge WebSocket 客户端：连接 Anthropic bridge 服务，扩展发现、设备配对、权限管理
toolCalls.ts	301	工具调用路由：连接状态处理、结果转换、权限模式切换、浏览器切换

17 个浏览器工具

工具名	功能
javascript_tool	在页面上下文执行 JavaScript
read_page	获取页面可访问性树（DOM）
find	自然语言搜索页面元素
form_input	填写表单字段
computer	鼠标键盘操作 + 截图（13 种 action）
navigate	URL 导航 / 前进后退
resize_window	调整浏览器窗口尺寸
gif_creator	GIF 录制和导出
upload_image	图片上传到文件输入框或拖拽区域
get_page_text	提取页面纯文本
tabs_context_mcp	获取当前标签组信息
tabs_create_mcp	创建新标签页
update_plan	向用户提交操作计划供审批
read_console_messages	读取浏览器控制台日志
read_network_requests	读取网络请求
shortcuts_list	列出可用快捷方式
shortcuts_execute	执行快捷方式
switch_browser	切换到其他 Chrome 浏览器（仅 bridge 模式）

外部依赖

依赖	用途	我们项目是否已有
ws	WebSocket 客户端（bridge 模式）	✅ 有
@modelcontextprotocol/sdk	MCP Server + 类型	✅ 有
fs/net/os/path	Node.js 内置	✅

5. 修复步骤

步骤 1：复制完整实现到 stub 包目录

# 从参考项目复制 7 个文件（覆盖现有的 1 个 stub）
cp "E:/源码/claude-code-source-main/claude-code-source-main/deps/@ant/claude-for-chrome-mcp/src/"*.ts \
   "E:/源码/Claude-code-bast/packages/@ant/claude-for-chrome-mcp/src/"

复制后 packages/@ant/claude-for-chrome-mcp/src/ 应包含 8 个文件：

packages/@ant/claude-for-chrome-mcp/src/
├── index.ts           ← 覆盖 stub（15 行，导出入口）
├── types.ts           ← 新增（134 行）
├── browserTools.ts    ← 新增（546 行）
├── mcpServer.ts       ← 新增（96 行）
├── mcpSocketClient.ts ← 新增（493 行）
├── mcpSocketPool.ts   ← 新增（327 行）
├── bridgeClient.ts    ← 新增（1126 行）
└── toolCalls.ts       ← 新增（301 行）

步骤 2：验证构建

bun run build

不需要改 scripts/dev.ts 或 build.ts（无 feature flag）。

步骤 3：功能验证

# 启动（手动启用 chrome）
bun run dev -- --chrome

# 在 REPL 中：
# 1. /chrome 命令应显示 Chrome 设置菜单
# 2. 如果 Chrome 扩展已安装 → 状态显示 "Enabled"
# 3. 如果未安装 → 提示安装扩展链接

6. 验证测试项

6.1 构建验证

测试项	预期结果	验证命令
build 成功	无报错	bun run build
BROWSER_TOOLS 非空	产物中包含 17 个工具定义	grep "javascript_tool" dist/*.js
createClaudeForChromeMcpServer 非 null	产物中包含 MCP Server 创建逻辑	grep "ListToolsRequestSchema" dist/*.js
Bridge WebSocket 逻辑在产物中	包含 bridge 连接代码	grep "bridge.claudeusercontent.com" dist/*.js

6.2 命令注册验证

测试项	预期结果
/chrome 命令可见	REPL 中输入 /chrome 显示设置菜单
--chrome 参数可用	bun run dev -- --chrome 不报错
--no-chrome 参数可用	bun run dev -- --no-chrome 不报错

6.3 MCP Server 验证（需要 Chrome 扩展）

测试项	预期结果
Chrome 扩展检测	已安装扩展时 /chrome 显示 "Extension: Installed"
Socket 连接	扩展连接后 MCP tools 可用
BROWSER_TOOLS 注册	tabs_context_mcp 等 17 个工具在 MCP 工具列表中可见

6.4 工具功能验证（需要 Chrome 扩展 + 连接）

测试项	预期结果
tabs_context_mcp	返回当前标签组信息
navigate	能导航到指定 URL
computer + screenshot	返回页面截图
read_page	返回 DOM 可访问性树
javascript_tool	执行 JS 并返回结果

6.5 不影响现有功能

测试项	预期结果
不带 --chrome 启动	正常运行，无 chrome 相关报错
/voice 命令	不受影响
/schedule 命令	不受影响
bun test	现有测试全部通过

7. 改动总结

操作	文件	说明
覆盖 stub	packages/@ant/claude-for-chrome-mcp/src/index.ts	6 行 stub → 15 行完整导出
新增	packages/@ant/claude-for-chrome-mcp/src/types.ts	134 行类型定义
新增	packages/@ant/claude-for-chrome-mcp/src/browserTools.ts	546 行，17 个工具定义
新增	packages/@ant/claude-for-chrome-mcp/src/mcpServer.ts	96 行 MCP Server
新增	packages/@ant/claude-for-chrome-mcp/src/mcpSocketClient.ts	493 行 Socket 客户端
新增	packages/@ant/claude-for-chrome-mcp/src/mcpSocketPool.ts	327 行连接池
新增	packages/@ant/claude-for-chrome-mcp/src/bridgeClient.ts	1126 行 Bridge 客户端
新增	packages/@ant/claude-for-chrome-mcp/src/toolCalls.ts	301 行工具调用路由

不改动：src/ 下所有文件（已与参考项目一致）、scripts/dev.ts、build.ts。

8. 运行时依赖

依赖	必需？	说明
Chrome 浏览器	是	需安装 Chrome
Claude in Chrome 扩展	是	从 https://claude.ai/chrome 安装
claude.ai OAuth 登录	Bridge 模式需要	本地 Socket 模式不需要
Native Messaging Host	本地 Socket 需要	扩展安装时自动注册

9. 与 /voice、/schedule 恢复方式对比

项	/schedule	/voice	Claude in Chrome
编译开关	AGENT_TRIGGERS_REMOTE	VOICE_MODE	无需
改 dev.ts/build.ts	✅	✅	不需要
缺失的 vendor 二进制	无	.node 文件	无
需要替换的 stub	无	audio-capture-napi	@ant/claude-for-chrome-mcp（7 个文件）
改动 src/ 源码	无	无	无
平台限制	无	需原生 .node	需 Chrome 浏览器