# chrome-devtools-mcp

让 AI 通过 MCP 协议直接调用 Chrome DevTools Protocol（CDP），获取浏览器运行时 DOM 结构、计算样式、控制台日志、网络请求等信息，彻底解决 AI 只能读源码、无法获取真实运行时上下文的问题。

## 前置条件

- Node.js 18+
- Chrome 浏览器

## 安装

```bash
npm install
npm run build
```

## 启动 Chrome（调试模式）

```bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug-profile
```

推荐添加 alias 到 `~/.zshrc`，之后直接用 `chrome-debug` 启动：

```bash
alias chrome-debug='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug-profile'
```

## OpenCode 集成

在 `~/.config/opencode/opencode.json` 中添加：

```json
{
  "mcp": {
    "chrome-devtools": {
      "type": "local",
      "command": ["node", "/path/to/chrome-devtools-mcp/dist/index.js"],
      "env": {
        "CHROME_DEBUGGING_PORT": "9222"
      },
      "enabled": true
    }
  }
}
```

> **注意**：`command` 必须是数组格式，不能是字符串。

## 查看实时日志

MCP server 的所有 CDP 调用日志写入 `~/chrome-devtools-mcp.log`，在任意终端运行以下命令实时查看：

```bash
tail -f ~/chrome-devtools-mcp.log
```

## 工具清单（11 个）

### DOM 工具

| 工具 | 说明 |
|------|------|
| `list_tabs` | 列出所有可调试的 Tab（type=page） |
| `query_selector` | 按 CSS 选择器查找元素，返回 tagName/id/classList |
| `get_dom_tree` | 获取 DOM 子树，`selector` 可选，`depth` 最大 10 |
| `get_ancestors` | **获取元素完整祖先链（含指定样式 + 自动诊断），sticky/overflow/z-index 问题根因定位专用** |

### CSS 工具

| 工具 | 说明 |
|------|------|
| `get_computed_styles` | 获取元素计算样式，返回 `summary`（布局关键属性）+ `all`（完整属性） |
| `get_matched_styles` | 获取元素匹配的 CSS 规则列表（含来源文件、行号） |
| `get_box_model` | 获取元素盒模型尺寸（width/height/margin/padding/border/content） |

### Runtime 工具

| 工具 | 说明 |
|------|------|
| `get_layout_metrics` | 获取页面视口/内容尺寸（viewportWidth/viewportHeight/contentWidth/contentHeight） |
| `evaluate_js` | 在页面上下文执行 JS 表达式，自动拦截 cookie/localStorage/fetch 等敏感 API |
| `get_console_logs` | 获取控制台日志，支持按 level 过滤（log/info/warn/error/debug） |

### Network 工具

| 工具 | 说明 |
|------|------|
| `get_network_requests` | 获取网络请求记录，支持 `url_filter` 关键词过滤，返回 method/status/duration/headers |

> **注意**：`get_console_logs` 和 `get_network_requests` 只收集 MCP 连接后的事件，连接前的记录无法追溯。

## 智能诊断（Phase 3）

`get_ancestors` 会自动在返回结果里附带 `diagnosis` 字段，无需 AI 额外推理即可定位根因：

```json
{
  "ancestors": [...],
  "diagnosis": {
    "hints": [
      {
        "depth": 2,
        "tagName": "section",
        "classList": ["arco-layout"],
        "issue": "position:sticky 失效 — 祖先节点 overflow 非 visible/unset 会阻断 sticky",
        "property": "overflow",
        "value": "hidden",
        "impact": "blocking"
      }
    ],
    "summary": "发现 1 个阻断性问题。第2层 <section> overflow:hidden"
  }
}
```

`impact` 三级：`blocking`（直接阻断）/ `likely`（大概率影响）/ `possible`（可能有影响）

检测覆盖：
- `overflow: hidden/scroll/auto/clip` → sticky 失效
- `transform` 非 none → fixed/sticky 失效
- `will-change: transform/opacity/filter` → 层叠上下文异常
- `contain: layout/paint/strict/content` → fixed 失效
- `filter` / `backdrop-filter` → 层叠上下文异常

## 典型用法

### 诊断 sticky 失效

```
1. 调用 get_computed_styles(".sticky-header")
   → summary.position: sticky（确认已设置）

2. 调用 get_ancestors(".sticky-header")
   → diagnosis.summary: "发现 1 个阻断性问题。第3层 <div.el-scrollbar__wrap> overflow:hidden"
   → 根因定位完成，无需进一步推理
```

### 排查 JS 错误

```
1. 调用 get_console_logs(level="error")
   → 获取页面 error 级别日志

2. 调用 evaluate_js("document.querySelector('.btn').disabled")
   → 获取按钮当前的 disabled 状态
```

### 排查接口问题

```
1. 调用 get_network_requests(url_filter="/api/cooperation")
   → 查看合作相关接口的请求状态和响应时间
```

## 安全说明

- 调试端口绑定 `127.0.0.1`，禁止公网暴露
- `evaluate_js` 自动拦截 `document.cookie`、`localStorage`、`sessionStorage`、`fetch`、`XMLHttpRequest`
- MCP Server 仅本地运行，数据不出 localhost
- 仅供开发环境使用，勿集成到生产流程