# 微信开发者工具 MCP：配置与验证交接

## 当前结论

`wechat-devtools-mcp` 已安装并注册到 Codex，全局配置和基础环境均已验证成功；但当前微信开发者工具的**自动化 WebSocket 会话尚未可用**，因此暂时不能可靠地进行页面栈读取、点击、输入或截图。

已验证的小程序项目为：

- 项目根目录：`/Users/lapuda/code/shz-employment-service`
- AppID：`wx99193c507b93d6db`
- 小程序基础库：`3.14.3`
- 微信开发者工具服务端口：`60423`（正在监听）
- 自动化端口：`9420`（正在监听，但 WebSocket 健康检查失败）

> 该文档不包含令牌、登录态或其他敏感信息。

## 已完成的本机配置

MCP Server 已通过 `uv` 安装：

```text
wechat-devtools-mcp v0.9.10
可执行文件：/Users/lapuda/.local/bin/wechat-devtools-mcp
```

Codex 全局配置文件为 `~/.codex/config.toml`，其中已加入：

```toml
[mcp_servers.wechat-devtools]
command = "/Users/lapuda/.local/bin/wechat-devtools-mcp"
startup_timeout_sec = 30.0

[mcp_servers.wechat-devtools.env]
WECHAT_DEVTOOLS_CLI = "/Applications/wechatwebdevtools.app/Contents/MacOS/cli"
WECHAT_PROJECT_PATH = "/Users/lapuda/code/shz-employment-service"
PATH = "/Users/lapuda/.local/bin:/Users/lapuda/.nvm/versions/node/v22.22.2/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
NODE_PATH = "/Users/lapuda/.nvm/versions/node/v22.22.2/bin/node"
```

`codex mcp get wechat-devtools` 已确认该 Server 为 `enabled`，传输方式为 `stdio`。

## 已完成的 MCP 验证

### 1. Server 和运行环境

通过 MCP 标准握手完成初始化，Server 成功暴露 7 个工具：

- `wechat_ide`
- `wechat_build`
- `wechat_automator`
- `wechat_inspector`
- `wechat_screenshot`
- `wechat_navigate`
- `wechat_file`

随后调用只读的 `wechat_ide(action="status")`，返回成功：

```json
{
  "success": true,
  "data": {
    "mcp_version": "0.9.10",
    "cli_exists": true,
    "project_exists": true,
    "node_available": true,
    "appid": "wx99193c507b93d6db",
    "lib_version": "3.14.3"
  },
  "message": "状态正常"
}
```

### 2. 微信开发者工具端口

本机端口监听已确认：

```text
127.0.0.1:60423  → 微信开发者工具 Renderer 进程监听
*:9420           → 微信开发者工具 Renderer 进程监听
```

注意：

- `60423` 是微信开发者工具的 IDE 服务端口，开启它只是 MCP 能下发 IDE/CLI 指令的前提。
- `9420` 是小程序自动化连接端口。MCP 要通过其 WebSocket 会话进行页面读取和交互。

### 3. 自动化控制验证及阻塞原因

已调用：

```text
wechat_automator(action="start", auto_port=9420)
```

返回结果：

```json
{
  "success": true,
  "data": {
    "port": 9420,
    "verified": false,
    "tcp_ready": true,
    "ws_ready": false,
    "verify_attempts": 2,
    "retry_after_ms": 3000
  },
  "message": "自动化端口 9420 的 WS 层未就绪（已尝试 2 次）。"
}
```

随后尝试只读的：

```text
wechat_automator(action="page_stack", auto_port=9420)
```

最终失败信息：

```text
连接失败: Connection not ready: health check failed after connect
```

因此，当前状态应判断为：**MCP 配置正常；微信开发者工具的自动化 WebSocket 尚不可用；暂不能宣称小程序已可被控制。**

## 新对话应如何继续

先新开一个 Codex 对话/会话，让 Codex 从 `~/.codex/config.toml` 加载新注册的 MCP 工具。新会话应能直接看到 `wechat_ide`、`wechat_automator` 等工具。

建议按以下顺序继续，且先保持只读：

1. 调用 `wechat_ide(action="status")`，再次确认环境。
2. 调用 `wechat_automator(action="start", auto_port=9420)`。
3. 若返回 `ws_ready: true`，调用 `wechat_automator(action="page_stack", auto_port=9420)`。
4. 读取成功后，调用 `wechat_screenshot(full_page=false)` 获取当前视口截图。
5. 仅在用户明确指定目标控件且确认不会触发提交、支付、删除、登录切换等副作用后，才使用 `wechat_automator(action="tap", selector="…")` 验证真实点击控制。

## 若 WebSocket 仍不可用

官方工具的已知建议是：手动启动的微信开发者工具有时不会生成 MCP 需要的自动化/CDP 会话。可采取以下恢复方式：

1. **先取得用户确认**：关闭/重开当前微信开发者工具可能打断正在运行的小程序，且可能影响未保存的编辑状态。
2. 得到确认后，关闭当前 IDE 项目或退出 IDE。
3. 通过 MCP 用配置中的项目目录重新打开：`wechat_ide(action="open", cdp_enabled=true)`。
4. 等待项目完全载入后，再执行 `wechat_automator(action="start")` 与 `page_stack`。

在此前的操作中，没有擅自关闭、重开或重编译微信开发者工具，也没有修改小程序业务代码。

## 可直接发送给新对话的请求

```text
请阅读 shz-backend/WECHAT_DEVTOOLS_MCP_HANDOFF.md，继续测试微信小程序 MCP 控制能力。

当前 MCP 已配置为 wechat-devtools-mcp v0.9.10，项目路径是 /Users/lapuda/code/shz-employment-service，IDE 服务端口为 60423。上次测试发现自动化端口 9420 的 TCP 已监听但 WebSocket 未就绪，page_stack 健康检查失败。

先执行只读验证：status → automator start → page_stack → 当前视口截图。若仍无法连接，不要擅自关闭微信开发者工具；先向我确认是否允许关闭并通过 MCP 重新打开项目。
```