微信小程序页面迁移校验之前 P5任务处理之前

docs/mcp/WEIXIN-DEVTOOLS-MCP.md

@@ -0,0 +1,73 @@
+# 微信开发者工具 MCP 连接指南
+
+## 概述
+
+`weixin-devtools-mcp` 用于通过 MCP 协议控制微信开发者工具，支持页面导航、截图、元素操作、JS 执行等自动化功能。
+
+## 环境信息
+
+| 项目 | 值 |
+|------|-----|
+| 开发者工具路径 | `C:\dev\WechatDevtools\微信开发者工具.exe` |
+| CLI 路径 | `C:\dev\WechatDevtools\cli.bat` |
+| 小程序项目路径 | `C:\NeoZQYY\apps\miniprogram` |
+| 自动化端口 | `9420`（固定） |
+| AppID | `wx7c07793d82732921` |
+
+## 连接步骤（必须按顺序执行）
+
+### 第 1 步：确保开发者工具已登录
+
+打开微信开发者工具，确认已扫码登录。未登录会报 `Error: 需要重新登录 (code 10)`。
+
+### 第 2 步：在终端启动自动化端口
+
+```powershell
+& "C:\dev\WechatDevtools\cli.bat" auto --project "C:\NeoZQYY\apps\miniprogram" --auto-port 9420
+```
+
+成功输出：
+```
+√ IDE server has started, listening on http://127.0.0.1:XXXXX
+√ Using AppID: wx7c07793d82732921
+√ auto
+```
+
+### 第 3 步：MCP 连接
+
+使用 `connect_devtools` 工具，策略必须为 `wsEndpoint`：
+
+```
+strategy: wsEndpoint
+wsEndpoint: ws://127.0.0.1:9420
+projectPath: C:\NeoZQYY\apps\miniprogram
+healthCheck: true
+```
+
+## 踩坑记录
+
+### 禁止使用 `connect` / `discover` / `auto` 策略
+
+这些策略会内部 spawn CLI 进程，导致微信开发者工具被重启。只能用 `wsEndpoint` 策略连接已有的自动化端口。
+
+### `spawn EINVAL` 错误
+
+原因：MCP 内部 spawn 子进程时路径无效（中文路径 + 非标准安装位置）。解决方案就是不让 MCP spawn，改用手动启动 + wsEndpoint 连接。
+
+### MCP 配置中的环境变量
+
+`mcp.json` 中已配置 `WECHAT_DEVTOOLS_CLI` 和 `WECHAT_DEVTOOLS_PROJECT` 环境变量，但这些仅供 MCP server 内部参考，不能替代手动启动自动化端口。
+
+## MCP 配置参考
+
+```jsonc
+// .kiro/settings/mcp.json
+"weixin-devtools-mcp": {
+  "command": "npx",
+  "args": ["-y", "weixin-devtools-mcp", "--tools-profile=full", "--ws-endpoint=ws://127.0.0.1:9420"],
+  "env": {
+    "WECHAT_DEVTOOLS_CLI": "C:\\dev\\WechatDevtools\\cli.bat",
+    "WECHAT_DEVTOOLS_PROJECT": "C:\\NeoZQYY\\apps\\miniprogram"
+  }
+}
+```