158 lines
5.4 KiB
Markdown
158 lines
5.4 KiB
Markdown
# 微信开发者工具 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 重新打开项目。
|
||
```
|