# 腾讯云浏览器控制 MCP Server

> **让 LLM 替你点腾讯云控制台。**
> 通过 CDP（Chrome DevTools Protocol）接管你本机已登录的 Microsoft Edge，完成 **DNSPod 域名解析** 与 **CVM / 轻量应用服务器（Lighthouse）安全组 / 防火墙规则** 的配置。

![Node](https://img.shields.io/badge/node-%3E%3D18.18-339933?logo=node.js&logoColor=white)
![License](https://img.shields.io/badge/license-MIT-blue)
![MCP](https://img.shields.io/badge/MCP-stdio-6E56CF)
![Transport](https://img.shields.io/badge/transport-stdio-informational)
![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-0078D4)

| 项目 | 值 |
| --- | --- |
| 协议内自报名（`serverInfo.name`） | `browser-control-tencent-cloud` |
| 传输方式 | stdio（`StdioServerTransport`） |
| 运行时 | Node.js ≥ 18.18（实测 Node 24.x / Edge 153 / Playwright 1.63 / MCP SDK 1.30） |
| 浏览器接管方式 | `chromium.connectOverCDP('http://127.0.0.1:<port>')` |
| 工具数量 | 7 |

---

## 0. 它解决什么问题

腾讯云控制台是重登录态的 React 单页应用：微信扫码、短信验证、滑块验证层层叠加，LLM 无法自己登录；而直接用云 API 又需要 `SecretId` / `SecretKey`，意味着把长期凭据交给模型。

本项目走第三条路：**借用你浏览器里已经存在的登录态**。

```
┌──────────────┐   stdio / JSON-RPC   ┌─────────────────────┐   CDP    ┌──────────────────┐
│ MCP Client   │ ◄──────────────────► │ 本 MCP Server       │ ◄──────► │ 你的 Edge 窗口   │
│ (Claude /    │   7 个 Tool          │ (dist/index.js)     │ 9222     │ (已登录腾讯云)   │
│  Cursor/DSH) │                      │ 无凭据、无 Cookie   │          │ 登录态天然存在   │
└──────────────┘                      └─────────────────────┘          └──────────────────┘
```

### 设计原则（先看这一节，能避免 90% 的误解）

1. **不碰账号密码。** 本 Server 从不读取、不保存、也不代填任何腾讯云账号密码、短信验证码或扫码凭据。它只是"借用"你浏览器里已经存在的登录态。遇到登录 / 验证码时会**主动停下来**，提示你人工处理。
2. **不启动、也不关闭浏览器。** 它只通过 CDP *附加* 到你手动启动的 Edge 上。即使本 Server 退出，你的 Edge 窗口和标签页也不会被关闭（代码里刻意不调用 `browser.close()`）。
3. **只连本机回环地址。** 所有 CDP 连接都是 `http://127.0.0.1:<port>`，不对外网暴露。
4. **每一步都可追溯。** 每个工具的返回值里都带 `steps`（做了什么、成功还是跳过、耗时多久）；失败时自动附带**失败现场截图**，让 LLM 能接着用 `interact_element` 手工收尾。

---

## 1. 快速开始

### 1.0 三步走

```bash
# ① 克隆并构建
git clone https://github.com/<你的用户名>/tencent-browser-mcp.git
cd tencent-browser-mcp
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install
npm run build

# ② 启动一个「可被 CDP 接管」的 Edge（Windows 双击即可）
scripts\start-edge-cdp.bat

# ③ 在这个窗口里登录腾讯云，然后把 dist/index.js 配到你的 MCP 客户端
```

### 1.1 启动带 CDP 调试端口的 Edge

#### 最快的方式：双击自带的一键启动脚本（推荐）

```
scripts\start-edge-cdp.bat      ← 双击运行即可
```

它会自动完成：找到 Edge → 用**独立配置目录**启动 → 打开腾讯云控制台 → 等待并自检调试端口 → 打印"可以接管了"。

脚本启动的这个 Edge 和你日常用的 Edge **可以同时开着，互不干扰**（因为配置目录不同）。在这个窗口里登录一次腾讯云之后，登录态会持久保存在该目录里，以后直接双击 → 确认已登录 → 让 Agent 接管即可。

脚本还支持参数（命令行调用时）：

```powershell
scripts\start-edge-cdp.bat -Port 9333                    # 换调试端口（之后调用工具时传 cdpPort=9333）
scripts\start-edge-cdp.bat -UserDataDir "D:\EdgeCDP"     # 换配置目录
scripts\start-edge-cdp.bat -NoOpenTencent                # 启动时不自动打开腾讯云
```

> 端口已经就绪时，重复运行不会多开浏览器，只会提示"已就绪，直接连"。
>
> **启动器还会等登录页真正渲染出来**：全新配置目录**第一次**访问腾讯云时，登录页可能长时间停在"白底 + 一句品牌 slogan"的占位壳上（看起来就是白屏）。启动器会自动刷新重试，最多等 120 秒，并在控制台打印进度，不会让你对着白屏干等。详见 FAQ 的 **Q4**。

下面的手工命令适合你想自己掌控参数、或排查问题时使用。

#### 1.1.1 为什么必须加 `--user-data-dir`（最容易踩的坑）

从 Chrome 136 / 对应版本的 Edge 开始，官方出于安全考虑**不再允许对"默认用户数据目录"开启远程调试端口**：如果你只写 `--remote-debugging-port=9222` 而不指定 `--user-data-dir`，端口很可能**根本不会监听**（命令行看起来完全正常，但 `connect_edge` 会一直报 `ECONNREFUSED`）。

所以：**请务必显式指定一个独立的 `--user-data-dir`。**

> 参考：[Changes to remote debugging switches to improve security（Chrome for Developers）](https://developer.chrome.com/blog/remote-debugging-port?hl=zh-cn)
>
> 副作用与对策：独立目录 = 一个全新的浏览器配置文件，**第一次需要在这个配置文件里登录一次腾讯云**（之后会持久保存在该目录中，不会每次都要求登录）。

#### 1.1.2 各平台启动命令

```powershell
# Windows（推荐：使用独立配置文件目录，不影响你日常使用的 Edge）
& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" `
  --remote-debugging-port=9222 `
  --user-data-dir="$env:LOCALAPPDATA\EdgeCDP" `
  --no-first-run --no-default-browser-check
```

Edge 装在 64 位目录时，把路径换成 `C:\Program Files\Microsoft\Edge\Application\msedge.exe` 即可。

```bash
# macOS
"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" \
  --remote-debugging-port=9222 --user-data-dir="$HOME/EdgeCDP"

# Linux
microsoft-edge --remote-debugging-port=9222 --user-data-dir="$HOME/EdgeCDP"
```

启动后访问 <http://127.0.0.1:9222/json/version> 能看到 JSON，就说明端口已就绪。

---

## 2. 编译构建

### 2.1 前置要求

```bash
node -v    # 需要 >= 18.18，建议 20/22/24 LTS
npm -v     # 或用 pnpm / yarn，命令等价
```

其它机器上部署时，装官方 Node.js LTS 即可：<https://nodejs.org/>

### 2.2 安装依赖

```bash
npm install
```

**建议顺手跳过 Playwright 自带浏览器下载**（约 500MB）：本项目只做 CDP *接管*，从不需要 Playwright 自己下载的 Chromium。

```powershell
# Windows PowerShell
$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1; npm install
```
```bash
# macOS / Linux
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install
```

### 2.3 构建

```bash
npm run build          # tsc 编译 src/index.ts -> dist/index.js
# 其它可用脚本：
npm run watch          # 增量编译
npm run typecheck      # 只做类型检查
npm run clean          # 删除 dist
npm run rebuild        # clean + build
```

### 2.4 自检（两条命令，强烈建议先跑通再配客户端）

```bash
npm run smoke     # 协议层自检：不需要开浏览器，拉起进程跑 initialize / tools/list / tools/call
npm run e2e       # 端到端自检：需要先启动可接管的 Edge（默认连 9222）
npm run e2e -- --cdp-port 9333   # 指定端口
```

- `smoke`：校验 7 个工具的 JSON Schema、错误处理、以及 **stdout 没有被日志污染**（stdio 型 MCP Server 最常见的翻车点）。退出码 0 = 全部通过。
- `e2e`：真实连接 Edge 跑完 9 步：
  `connect_edge → take_screenshot → get_text → 故意失败的选择器（校验失败信封）→ type 真实键盘输入 → navigate_tencent_console → wait_for_user_auth → connect_edge 登录态预检 → 白屏占位自愈`。
  其中第 5 步会在本机临时起一个测试页，验证 `type` 真的把字符敲进了页面（这正是 Web 终端的形态）；第 9 步验证白屏能被识别并自动刷新重试。

> ⚠️ `e2e` 会驱动**当前激活标签页**跳转（含一个本地测试页和腾讯云页面）。请用一个专门的测试窗口跑它，不要对着正在干正事的标签页运行。

### 2.5 手动启动（排错用）

```bash
# Windows PowerShell
$env:MCP_LOG_LEVEL='debug'; node dist/index.js
# macOS / Linux
MCP_LOG_LEVEL=debug node dist/index.js
```

正常情况下它会"挂住"等待 stdin 上的 JSON-RPC 报文；`Ctrl+C` 退出。所有日志都在 **stderr**，stdout 只用于协议通信。

---

## 3. 配置到 MCP 客户端

下面配置里的**键名就是客户端里显示的 Server 名称**，同时决定工具在模型侧的前缀（例如键名 `tencent-browser` → 工具 `mcp__tencent-browser__connect_edge`）。

请把 `/ABSOLUTE/PATH/TO/tencent-browser-mcp/dist/index.js` 换成你自己的**绝对路径**；Windows 路径在 JSON 里必须写成双反斜杠（`D:\\code\\tencent-browser-mcp\\dist\\index.js`）。

### 3.1 Claude Desktop

配置文件位置：

- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "tencent-browser": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/tencent-browser-mcp/dist/index.js"],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}
```

改完**必须完全退出并重启 Claude Desktop**（不是关窗口，是退出进程）。

### 3.2 Cursor

项目级：`<项目根>/.cursor/mcp.json`；全局：Windows `%USERPROFILE%\.cursor\mcp.json`，macOS/Linux `~/.cursor/mcp.json`。

```json
{
  "mcpServers": {
    "tencent-browser": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/tencent-browser-mcp/dist/index.js"],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}
```

配置后在 Cursor 的 **Settings → MCP** 里确认该 Server 状态为绿色（已连接），并在对话中把工具授权给 Agent 使用。

### 3.3 其它客户端 / 命令行 Agent

MCP 是客户端无关协议：**任何支持 stdio 型 MCP Server 的客户端，用的都是上面同一份 `mcpServers` 结构**。把它粘进对应客户端的配置文件（或 `--mcp-config` 指定的文件）即可。

```json
{
  "mcpServers": {
    "tencent-browser": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/tencent-browser-mcp/dist/index.js"],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}
```

**如何确认挂载成功**：让客户端列出工具，应当看到且仅看到这 7 个：`connect_edge`、`take_screenshot`、`navigate_tencent_console`、`interact_element`、`add_dns_record`、`configure_security_group`、`wait_for_user_auth`。

> 少数客户端换了外层键名（例如 VS Code 的 `.vscode/mcp.json` 用 `"servers"` 且需要 `"type": "stdio"`），**内层字段（`command` / `args` / `env`）完全一致**。

### 3.4 配置检查清单

- [ ] `node -v` 能输出版本号（客户端启动 Server 时用的是同一个 `node`）
- [ ] `dist/index.js` 存在（先跑过 `npm run build`）
- [ ] 路径是**绝对路径**，Windows 下反斜杠已转义成 `\\`
- [ ] 已运行 `scripts\start-edge-cdp.bat`，且窗口提示"可接管状态就绪"
- [ ] 改完配置后**重启了客户端**
- [ ] `npm run smoke` 退出码为 0

---

## 4. 工具清单

| 工具 | 关键参数 | 说明 |
| --- | --- | --- |
| `connect_edge` | `cdpPort`(默认 9222)、`force` | 连接/复用一个 CDP 连接，返回浏览器版本、**所有标签页的 URL/标题**，以及 **`preflight` + `tencentTabs`：逐个腾讯云标签页告诉你哪个已登录、哪个还需要人工验证**。 |
| `take_screenshot` | `fullPage`、`savePath`、`cdpPort` | 截取当前激活标签页，返回 **Base64 PNG**（MCP image content）。整页截图超过约 3.5MB 会自动降级为可视区域截图。 |
| `navigate_tencent_console` | `target`(`dnspod`\|`cvm`\|`lighthouse`\|`custom`)、`customUrl`、`screenshot` | 快捷导航。导航后自动检测登录/验证码：命中时**直接附带截图**并给出人工介入提示。 |
| `interact_element` | `action`(`click`\|`fill`\|`wait_for`\|`hover`\|`select`\|`press`\|`type`\|`get_text`\|`reload`)、`selector`、`text`、`timeoutMs`、`state`、`nth`、`frameUrlContains`、`force`、`submit`、`delay` | 通用兜底操作。选择器支持 CSS / `text=文字` / `xpath=//...` / `:has-text()`。`fill` 对受控组件失败时会降级为模拟键入并回读校验。**`type` 用真实键盘事件逐字输入，专治 xterm/Canvas 这类"看不见输入框"的 Web 终端，配 `submit: true` 自动回车。** `reload` 刷新当前页（selector 可传 `body`）。 |
| `add_dns_record` | `domain`、`subDomain`、`recordType`、`value`、`ttl`、`mode`(`auto`\|`create`\|`update`)、`line` | **高层封装**：打开解析记录页 → 查重 → 新增或修改 → 保存 → **回读表格校验**。 |
| `configure_security_group` | `region`、`instanceId`、`port`、`protocol`、`policy`、`product`、`direction`、`sourceCidr`、`description`、`mode`(`add`\|`list`) | **高层封装**：定位实例 → 打开安全组/防火墙 → 添加规则 → 提交。`mode=list` 只读不改。放行高危端口会给风险提醒。 |
| `wait_for_user_auth` | `mode`(`detect`\|`wait`\|`confirm`)、`timeoutMs`、`note` | 人机协同：`detect` 立即检测并截图；`wait` 轮询等待（默认 180s，上限 900s）；`confirm` 清除挂起状态。 |

### 4.1 一个典型的完整流程

> 对 LLM 说："把 `www.example.com` 的 A 记录指向 `1.2.3.4`，TTL 600，然后给广州的 `ins-abcdefgh` 放行 80 和 443 端口。"

期望的调用顺序：

```
connect_edge                     → 确认接管的窗口与标签页
navigate_tencent_console(dnspod) → 打开控制台
  ↳ 若返回 needsUserAuth=true → 让用户在弹出的 Edge 里登录/扫码 → wait_for_user_auth(mode=detect) 轮询
add_dns_record(domain=example.com, subDomain=www, recordType=A, value=1.2.3.4, ttl=600)
  ↳ 失败时看返回里的 steps + 截图，用 interact_element 手工收尾
configure_security_group(region=ap-guangzhou, instanceId=ins-abcdefgh, port=80,443, protocol=TCP, policy=ACCEPT)
  ↳ 返回里带 warnings 提醒高危端口风险
```

### 4.2 推荐工作流：先登录，再让 Agent 接管

```powershell
# ① 双击（或在终端运行）启动器 —— 打开一个「可被接管」的 Edge 窗口
scripts\start-edge-cdp.bat
```

```
[*] Edge: C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
[*] 启动 Edge（调试端口 9222）...
[OK] 可接管状态就绪：Edg/153.0.4234.32  端点 http://127.0.0.1:9222
```

```
② 在这个窗口里正常登录腾讯云（微信扫码 / 账号密码都行，本工具完全不接触你的凭据）
③ 回到 Agent 这边说一句：「已登录，继续」
④ Agent 做的第一件事就是 connect_edge 做登录态预检，并把结果摊开给你看，例如：

   preflight: 发现 1 个腾讯云标签页：1 个可直接操作，0 个需要人工登录/验证
   tencentTabs: [ { authRequired: false, authKind: "none", url: "https://console.cloud.tencent.com/lighthouse/instance/index" } ]
```

**登录态判断是"实测"而不是"猜"**：不仅看 URL，还会实际探测页面上有没有登录框、扫码二维码容器、滑块验证 iframe 等特征。如果预检显示"需要人工登录"，Agent 会停下来告诉你，而不是对着登录页瞎点。

### 4.3 操作失败时你会拿到什么

任何一步失败（包括**"操作做了但回读校验没通过"**这种业务性失败），返回体里都必然同时包含这三样：

| 字段 | 内容 |
| --- | --- |
| `details.steps` | 步骤轨迹：第几步、做了什么、`ok`/`skip`/`fail`、耗时多少毫秒、失败原因 |
| `details.page.textExcerpt` | **页面文字摘要**（最多 1200 字，已压缩空白），告诉你当时页面上到底写了什么 |
| 图片内容块 + `details.screenshot` | **失败现场截图**（Base64 PNG）+ 截图元信息（URL、标题、字节数、时间） |

再加上 `hint`（排错建议）与 `details.page.url/title`，足够判断是"选择器失效"还是"需要登录"还是"权限/配额限制"。

### 4.4 用本 Server 在 Lighthouse 上部署 1Panel（实操示例）

前提：`scripts\start-edge-cdp.bat` 已启动、你已在该窗口登录腾讯云。之后 Agent 会这样走：

1. `connect_edge` → 确认登录态就绪（`tencentTabs` 里 `authRequired: false`）。
2. `navigate_tencent_console(target: "lighthouse")` → 打开轻量应用服务器实例列表。
3. 定位目标实例 → 打开它的**在线终端 / OrcaTerm**（或 `configure_security_group(mode: "list")` 先确认 22/80/443 等端口的现状）。
4. **敲 1Panel 安装命令**（关键一步用 `type`）：

   ```json
   {
     "action": "type",
     "selector": "终端区域的选择器（例如 .xterm 或 iframe 内的容器）",
     "text": "curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o quick_start.sh && sudo bash quick_start.sh",
     "submit": true,
     "delay": 30
   }
   ```

   - `type` 走的是**真实键盘事件**，所以 xterm/Canvas 终端能收到（`fill` 只改 DOM 值，终端收不到）；
   - `submit: true` 会在输入完自动回车；
   - `delay: 30` 是每个字符间隔毫秒数，别低于 20，否则终端可能丢字符；
   - 如果终端在 iframe 里，用 `frameUrlContains` 定位那个 frame。
5. 安装脚本是**交互式**的（会问端口、安全入口、用户名密码）。每一步的终端回显要读回来给你看（`type` 的返回里有 `screenText`，`get_text` 也能读终端文本），**需要你决定的地方停下来问，绝不替你编密码**。
6. 装完后用 `configure_security_group` 放行 1Panel 面板端口（默认面板端口在安装时指定，常见 8090 / 安全入口随机路径），再把面板地址给你。
7. 全程可随时 `take_screenshot` 看画面。

> ⚠️ 安全组是"真实变更云上配置"：变更前先展示要加什么、加完回读规则列表；对 `0.0.0.0/0` 放行 22/3389/3306/6379 这类高危端口时返回里会带 `warnings` 提醒。
>
> 1Panel 官方安装脚本地址（`resource.fit2cloud.com`）请在执行前自行确认；涉及从外网拉脚本执行的操作，先看命令原文再执行。

---

## 5. 环境变量

| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `MCP_LOG_LEVEL` | `info` | `error` / `warn` / `info` / `debug`。日志全部写 **stderr**。排错时设为 `debug`。 |

---

## 6. 安全说明

- **凭据**：本 Server 不接收、不存储任何账号密码或验证码；登录必须由你本人在浏览器里完成。
- **浏览器**：绝不调用 `browser.close()`（那会关掉你正在用的 Edge 窗口）。退出时只释放 CDP 连接。
- **网络**：只连 `127.0.0.1`（CDP 端口）。除腾讯云控制台页面本身外，不向外发送任何数据。
- **变更类操作**：`add_dns_record` / `configure_security_group` 会**真实修改云端配置**。工具描述里已标注 `destructiveHint: true`，请在客户端的工具授权里留意；`configure_security_group` 支持 `mode="list"` 先只读确认。
- **风险提醒**：对 `0.0.0.0/0` 放行 `22/3389/3306/6379/27017` 等高危端口时，返回结果里会带 `warnings` 字段提示，建议改用具体来源 IP。

---

## 7. Web 终端（OrcaTerm / xterm）怎么读输出

这是本项目**最关键的一个工程约束**，务必了解：

**OrcaTerm / xterm 把终端渲染进 `<canvas>`，终端文字完全不在 DOM 里。**
实测：没有 `.xterm-rows`，没有无障碍层（`.xterm-accessibility`），React fiber 里也拿不到 Terminal 实例。
所以"读命令输出"不能靠抓 DOM，只能靠 **截图 + OCR**：

```bash
# 敲命令（真实键盘事件，终端才能收到）
node scripts/mcp-call.mjs --calls-file calls.json      # calls.json 里用 interact_element + action=type + submit=true
# 读输出（截图 + Windows 内置 OCR，OCR 由 ocr-image.ps1 完成）
node scripts/read-screen.mjs --url-contains orcaterm --selector .xterm --scale 3
```

要点：

- `--scale 3` 会在截图前把 `deviceScaleFactor` 临时调到 3 倍（小字号等宽字体 OCR 更准），截完立即恢复，不影响你继续用。
- OCR 引擎是 Windows 自带的 `Windows.Media.Ocr`（通常为 `zh-Hans-CN`），**不依赖任何第三方服务**，图片不出本机。
- OCR 会把 `_` 读成空格（`MY_VAR` → `MY VAR`）、把 `0` 读成 `e`、`1` 读成 `l`。因此：
  - 判断关键词时要容忍这些差异；
  - **密码、密钥这类关键值，请以屏幕上的显示为准**，不要让 OCR 结果当唯一依据。
- 命令输出尽量用"单列"（`awk '{print $4}'`、`sed -n 3p`）形式打印，多列表格会被 OCR 按位置打乱。

`dom-query.mjs` 则是另一个方向的工具：**页面是普通 DOM（例如 1Panel 面板、腾讯云控制台）时，直接跑 JS 把真实结构 dump 出来**，比猜选择器可靠得多：

```bash
node scripts/dom-query.mjs --url-contains 8090 --js-file q.js
```

---

## 8. 常见问题（FAQ）

**Q1：`connect_edge` 报 `connect ECONNREFUSED 127.0.0.1:9222`**
端口没监听。按顺序排查：① 是否**没加 `--user-data-dir`**（见 1.1.1 的 Chrome/Edge 136+ 限制）；② Edge 是否本来就在运行（旧进程会吞掉新的启动参数，需先完全退出）；③ 端口是否被占用（换 `9333` 并传 `cdpPort`）；④ 用 `http://127.0.0.1:9222/json/version` 直接验证。

**Q2：连上了，但操作的是"错误的"标签页**
调用 `connect_edge`，看返回的 `pages` 数组与 `activePage`；必要时手动点一下目标标签页（工具通过 `document.hasFocus()` 判断激活页），或用 `interact_element` 明确指定选择器操作。多标签场景下，`interact_element` / `take_screenshot` 支持 `pageUrlContains` 显式指定标签页。

**Q3：返回 `needsUserAuth: true` / `authKind: "qr"`**
这是**正常的人机交接**，不是报错：登录态过期或需要扫码。请在 Edge 窗口里完成登录，然后用 `wait_for_user_auth`（`mode=detect` 轮询或 `mode=wait`）确认后再重试原操作。

**Q4：打开腾讯云登录页只看到白屏 / 只有一句品牌 slogan 页脚怎么办？**

这是**登录 SPA 的加载占位壳**，不是工具坏了。现象：页面白底，只有页脚一句 slogan，登录框和二维码都不出来。

原因：腾讯云登录页由 SSR 外壳 + 十几个外部脚本组成（`cloudcache.tencent-cloud.com` 的 react / passport 包、Aegis 探针、以及 Google Tag Manager / DoubleClick 等第三方脚本）。**全新 Edge 配置目录第一次访问**时缓存全空、脚本要逐个冷启动，容易长时间停在占位壳上。

三个解决办法（从省事到彻底）：

1. **在那个窗口按 `Ctrl+R` 刷新一次** —— 绝大多数情况立刻就出来了。
2. **让工具自己修**：调用 `wait_for_user_auth`（任意模式）或 `interact_element(action="reload")`，工具会检测到白屏并自动刷新重试。
3. **重跑启动器**：`scripts\start-edge-cdp.bat` 会主动等登录页渲染完成（自动刷新，最多 120 秒），并打印进度。

> 实测记录：同一个配置目录、同一个启动器，**第一次**冷启动时出现过该白屏；缓存预热后再启动，登录页（含微信二维码 iframe）秒开、无任何请求失败。所以这基本是一次性现象。

**Q4.1：为什么启动器只开一个标签页了？**
全新配置目录下，两个登录页同时冷启动会互相抢带宽，反而更容易停在白屏。需要 DNSPod 页面时，让 Agent 用 `navigate_tencent_console(target="dnspod")` 打开即可（那时缓存已经热了）。

**Q5：腾讯云控制台改版了，`add_dns_record` / `configure_security_group` 失败**
这两个工具用的是"多候选选择器 + 分步容错"的启发式策略，改版后可能需要调整。失败时返回里会带：

- `details.steps`：卡在哪一步、为什么；
- `details.page.textExcerpt`：当时页面上的文字；
- 一张**失败现场截图**。

推荐的应对顺序：① 用 `take_screenshot` 看清页面；② 用 `interact_element` 手工完成剩余步骤；③ 若要长期修好，改 `src/index.ts` 顶部集中定义的 **`CONSOLE_ENTRY_URLS` / `URL_CANDIDATES`**（地址变了改这里）与各 `fillFieldByLabels` / `chooseDropdownOption` 调用里的**候选标签文案**（字段名变了改这里），然后 `npm run build`。

**Q6：客户端提示工具调用超时**
`wait_for_user_auth(mode=wait)` 会长时间占住一次调用。改用 `mode=detect`，让 LLM 每隔几秒轮询一次（返回体会给出这个建议）。

**Q7：截图太大 / 图片被客户端丢弃**
整页截图超过约 3.5MB 会自动降级为可视区域截图（返回里 `downgradedFromFullPage: true`）。也可以传 `savePath` 落盘，或干脆用默认的 `fullPage: false`。

**Q8：日志在哪里看？**
全部在 **stderr**。Claude Desktop 的日志目录是 Windows `%APPDATA%\Claude\logs\`、macOS `~/Library/Logs/Claude/`，其中 `mcp-server-*.log` 对应各个 MCP Server。把 `MCP_LOG_LEVEL` 设为 `debug` 会打印每个选择器的命中情况。手动排错时直接 `MCP_LOG_LEVEL=debug node dist/index.js` 最直观。

**Q9：为什么工具返回值是 JSON 文本 + 图片两个 content 块？**
文本块是结构化状态（含 `steps`、`ok`、`hint`），图片块是失败现场或页面状态截图。MCP 客户端会把两样都交给模型，所以模型既能读到严格字段、也能"看见"页面。

---

## 9. 项目结构

```
tencent-browser-mcp
├── package.json            # 依赖与脚本（build / smoke / e2e / clean）
├── tsconfig.json           # TypeScript 配置（NodeNext ESM，strict + noUncheckedIndexedAccess）
├── src/
│   └── index.ts            # MCP Server 全部实现（7 个 Tool、CDP 单例、异常处理）
├── scripts/
│   ├── start-edge-cdp.bat  # 一键启动「可被 CDP 接管」的 Edge（双击即可，纯 ASCII 以兼容 cmd 代码页）
│   ├── start-edge-cdp.ps1  # 启动器的实际逻辑（端口自检 + 登录页渲染自检，带 UTF-8 BOM 以兼容 PS 5.1）
│   ├── wait-login-ready.mjs# 盯着登录页直到真正渲染出来：白屏就自动刷新重试
│   ├── diagnose-page.mjs   # 页面排错：DOM 探针 + 失败请求 + 控制台报错 + 截图（白屏/卡死时用）
│   ├── dom-query.mjs       # 在页面里跑一段 JS 并打印结果（drive 陌生控制台时的"眼睛"，只读）
│   ├── read-screen.mjs     # 截图 + OCR：读取 canvas 渲染的 Web 终端输出（见第 7 节）
│   ├── ocr-image.ps1       # Windows 内置 OCR（Windows.Media.Ocr），被 read-screen.mjs 调用
│   ├── mcp-call.mjs        # 批量调用 MCP 工具（入参写在 JSON 文件里，避免命令行拼 JSON）
│   ├── mcp-client.mjs      # 极简 MCP stdio 客户端（供上述脚本复用）
│   ├── smoke-test.mjs      # 协议层自检：npm run smoke
│   └── e2e-check.mjs       # 端到端自检（9 步，含 type 输入、登录态预检、白屏自愈）：npm run e2e
├── dist/                   # 构建产物（dist/index.js 就是 MCP 客户端要启动的入口）
└── .gitignore
```

---

## 10. 已知限制（如实说明）

1. **腾讯云控制台 UI 自动化是启发式的。** 控制台是 React SPA 且会改版；本 Server 用"多候选选择器 + 标签文案匹配 + 分步容错 + 回读校验"来提高鲁棒性，但**不保证改版后无需调整**（调整点见 Q5）。真正稳定的做法是改用腾讯云官方 API（需要 SecretId/SecretKey），那属于另一套方案。
2. **高危变更没有二次确认弹窗。** 工具会在调用前由 MCP 客户端展示参数并请求授权（`destructiveHint: true`），Server 自身不做 dry-run。建议先用 `configure_security_group(mode="list")` 查看现状。
3. **首次使用独立 profile 需要登录一次**，这是 Chrome/Edge 136+ 安全限制带来的必然代价。
4. **一个进程只维护一条 CDP 连接。** 同时操作多个浏览器实例需要起多个 Server 进程（各自不同的端口）。
5. **`wait_for_user_auth(mode=wait)` 这类长轮询依赖客户端不超时**；工具已给出 `mode=detect` 的替代路径。

---

## 11. License

[MIT](LICENSE)