wechat-devtools-mcp

WeChat DevTools MCP

Local MCP server that lets an AI agent drive WeChat DevTools on Windows: the official CLI for project operations, and the official mini program automation SDK for simulator control.

把微信开发者工具接到 AI 的本地 MCP 服务。控制面分两层：

• 官方 CLI：打开项目、关闭项目、退出 IDE、登录、预览、构建 npm、上传（默认禁用）。
• 官方自动化 SDK：连接模拟器，做页面跳转、元素查询/点击/输入、截图、evaluate、调用 wx API、原生弹窗操作。

不使用改包、注入或私有协议。实现只依赖官方 CLI、miniprogram-automator 和本地进程管理。

环境要求

• Windows，已安装微信开发者工具。默认路径： C:\Program Files (x86)\Tencent\微信web开发者工具
• Node.js >= 20。
• 开发者工具里开启 设置 → 安全设置 → 服务端口（CLI/HTTP 调用）。自动化必需。
• 预览、上传需要开发者工具已登录。
• touristappid 只能用于本地模拟器自动化；CLI 的 open/build-npm/preview 需要真实 AppID。

安装

git clone https://github.com/sdjvhbuw/wechat-devtools-mcp.git
cd wechat-devtools-mcp
npm install
npm start

MCP 走 stdio，日志只写 stderr，不会污染协议输出。

项目结构

src/runtime.js       路径、CLI 调用、IDE 端口检测、残留状态清理
src/session.js       自动化连接生命周期、复用/重启、页面轮询
src/server.js        MCP 工具注册与参数校验
scripts/e2e.js       模拟器自动化回归
scripts/cli-e2e.js   open/close/preview/quit/恢复回归
scripts/smoke.js     最小联调脚本
test-fixtures/       测试用小程序（touristappid）

环境变量

变量	作用	默认
WECHAT_DEVTOOLS_DIR	开发者工具安装目录	C:\Program Files (x86)\Tencent\微信web开发者工具
WECHAT_DEVTOOLS_PROJECT	默认小程序项目目录	空
WECHAT_DEVTOOLS_AUTOMATION_PORT	自动化端口	9420
WECHAT_DEVTOOLS_MCP_OUTPUT_DIR	截图输出目录	<repo>/output
WECHAT_DEVTOOLS_MCP_ALLOW_UPLOAD	设为 1 才允许上传工具	未设置
WECHAT_DEVTOOLS_SKIP_SERVICE_PORT_CHECK	设为 1 跳过预检查	未设置
WECHAT_DEVTOOLS_NO_STALE_CLEANUP	设为 1 禁止清理退出后残留的 .ide 端口文件	未设置

CLI 需要 token 时用 WECHAT_DEVTOOLS_CLI_TOKEN（不通过工具参数传递）。

接入 MCP 客户端

Qoder、Claude Desktop、Cursor、Codex 等客户端都使用同样的 stdio 配置。把路径换成仓库的实际绝对路径：

{
  "mcpServers": {
    "wechat-devtools": {
      "command": "node",
      "args": ["C:/path/to/wechat-devtools-mcp/src/server.js"],
      "env": {
        "WECHAT_DEVTOOLS_PROJECT": "C:/path/to/your-miniprogram",
        "WECHAT_DEVTOOLS_AUTOMATION_PORT": "9420"
      }
    }
  }
}

Qoder 写在 ~/.qoder/settings.json，其他客户端按各自文档放到对应位置。修改后重启客户端或重载 MCP。

启动与退出恢复

• 调用 open / login / preview / build-npm / auto_start 前，先确保 IDE 以正常 GUI 方式启动，再交给 CLI，避免 CLI 冷启动时抢在服务端口就绪之前检查。
• 开发者工具退出后可能残留 Default/.ide 和 .ide-status=On，导致 CLI 一直等待旧端口。检测到端口已关闭且文件超过 15 秒未更新时，会备份为 .ide.stale-<时间> 并清理，同时把状态写为 Off。
• wdt_quit 会等待实际 .ide 端口关闭（最多 40 秒），然后清理残留。
• 不想让 MCP 动这些状态文件时设 WECHAT_DEVTOOLS_NO_STALE_CLEANUP=1。
• 手动改过安全设置后，可先用 wdt_status 看 ide.portOpen、servicePort.configured 和 servicePort.ok（ok 表示配置已开启且 IDE 端口当前真的在线）。

工具

环境与 CLI

• wdt_status：工具路径、服务端口开关、自动化连接、端口占用。
• wdt_open / wdt_close_project / wdt_quit：打开、关闭项目、退出 IDE。wdt_quit 会等待 IDE 端口关闭（最多 40 秒）。
• wdt_login / wdt_is_login：触发扫码登录 / 检查登录状态。
• wdt_preview：生成预览二维码（terminal/image/base64）。image/base64 未给路径时自动写入 output。
• wdt_build_npm：构建 npm；失败时返回 ok=false 和可读 hint。
• wdt_upload：上传版本。默认禁用，需环境变量 + confirm=true。

自动化

• wdt_auto_start：启动并连接自动化端口。默认复用已有连接；restart=true 强制重启。总预算默认 45 秒。
• wdt_auto_connect / wdt_disconnect：连接已有端口 / 断开。
• wdt_current_page：当前页面与页面栈。
• wdt_navigate：navigateTo / redirectTo / reLaunch / switchTab / navigateBack；默认按 app.json 校验页面，动态页面可传 validate=false。
• wdt_query：按 CSS 选择器查询元素摘要。
• wdt_element：tap、input、text、attribute、wxml、trigger、scrollTo、scrollWidth/Height、swipeTo、slideTo、callMethod 等动作。slideTo 会补发 change 事件。
• wdt_wait：等待选择器或毫秒数（最长 60 秒）。
• wdt_page_data：读取/修改页面 data，或调用页面方法（SDK 调用失败时自动用 evaluate 回退）。
• wdt_screenshot：模拟器截图，返回 PNG 路径。
• wdt_evaluate：执行表达式/语句/函数；表达式自动包成函数，可用 $args 访问参数。
• wdt_wx_method：调用 wx API。
• wdt_native：goHome、确认/取消弹窗、授权、分享等原生动作。
• wdt_system_info：systemInfo()。

联调

node scripts/smoke.js "C:/path/to/your-miniprogram"

脚本会依次执行：状态检查 → 启动自动化 → 当前页面 → 查询 view → 截图 → 断开。任何一步失败都会返回 CLI 输出，便于定位服务端口或登录问题。

回归测试：

npm run test:e2e   # 55 项：输入/点击/滑动/滚动/跳转/求值/错误路径
npm run test:cli   # open/close/preview/build/quit/恢复

test:cli 会退出并重新拉起 IDE，运行前保存好未提交的工作。open/preview 需要真实 AppID，用环境变量提供你自己的小程序项目；未提供时相关用例标记为 SKIP：

# PowerShell
$env:WECHAT_DEVTOOLS_TEST_USER_PROJECT="C:/path/to/your-miniprogram"
npm run test:cli

测试用小程序在 test-fixtures/miniprogram，只用于模拟器自动化。

安全边界

• wdt_upload 默认不可用，避免 AI 误发布；需要显式设置环境变量并传 confirm=true。
• wdt_quit、wdt_close_project、wdt_upload 标记为 destructive；调用前应确认。
• wdt_evaluate 和 wdt_wx_method 属于本地任意执行能力，只在可信项目中使用。
• MCP 只监听 stdio，不开放网络端口；请不要把 wdt_evaluate 暴露给不可信输入。
• 本项目只操作微信开发者工具及其模拟器，不控制微信客户端本身。
• miniprogram-automator 的 jimp/phin 链仍有 5 个 moderate 上游告警；critical/high 已通过 npm overrides 处理。详见 SECURITY.md。

已知限制

• 仅支持 Windows。
• 只覆盖“项目 + 模拟器”两层；IDE 自身的菜单、设置面板等界面级操作未实现。
• wdt_preview / wdt_upload 需要开发者工具已登录；touristappid 不能用于 CLI 的 open/build/preview。
• 微信开发者工具升级后，CLI 参数或自动化协议可能变化；请先跑 npm run test:e2e。

版本管理

版本号遵循 SemVer，变更记录见 CHANGELOG.md。发布前建议：

npm run check
npm run format:check
npm run test:e2e

License

MIT