# 微信开发者工具 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"
  }
}
```