miniprogram-devtools-mcp

操控微信开发者工具的 MCP server，32 个工具：

• automator 直连（20）：ws 连调试端口（9420）——执行 JS、读写 data、导航、元素操作、静态自检 preflight、坏状态自愈 rebuild、运行时用例
• 官方 wechatide CLI 封装（11）：模拟器截图、console/network 日志、预览、上传体验版、项目列表、云开发透传，以及 wechatide_help 官方工具动态发现
• 系统层窗口控制（1）：ide_window 把 IDE 项目窗口最大化/还原——截图分辨率取决于模拟器面板渲染尺寸，官方 49 个工具没有调窗口或缩放的能力

与官方 MCP 的差异

官方 2.x 开发者工具自带 wechatide mcp（49 工具，需独立 MCP Token）。两者可共存，但不要同时驱动同一项目的自动化（9420 单连接）。选这个的理由：

• 同步快车道：ws 直连，evaluate 100-500ms；官方 automation_* 每次调用走异步 task + 授权摩擦
• 零配置：路径 / 端口 / 项目全自动探测，一次授权弹窗后免确认；官方 MCP 要手动复制配置 + 填 MCP Token
• 编排是代码，不是提示词：授权等待、轮询、错误分类已代码化，失败返回结构化 blocker，不占 AI 上下文
• 自愈与用例体系：preflight 静态自检、rebuild 坏状态自愈、checks/ 运行时用例框架——官方没有对应物
• 细节增强：tabBar 页自动降级 switchTab、delta 越界自动收敛、GBK/UTF-8 混排解码

长尾能力不镜像、不硬编码：wechatide_call 透传 + wechatide_help 动态发现，官方增改废工具实时反映。官方 skill 升级后 wechatide_status 返回 versionRelation: agent_behind 提示跟进。

第三方开源工具，非腾讯官方出品；仅调用开发者工具自带的 cli / wechatide 接口，不分发不逆向。 ⚠️ 提供任意 JS 执行能力，仅用于本机受信任环境；发布类工具只在明确要求时触发。

安装

npx（推荐）——加入 MCP 客户端的 mcpServers，重启客户端：

"wechat-devtools": {
  "command": "npx",
  "args": ["-y", "miniprogram-devtools-mcp"],
  "env": {}
}

其他方式：克隆源码 npm install && npm run smoke；团队共用放进项目 mcp/ 子目录；离线拷贝整个目录（含 node_modules）后把 args 指向 index.js。配置位置：Cursor ~/.cursor/mcp.json、Claude Desktop %APPDATA%\Claude\、Trae %APPDATA%\Trae CN\User\mcp.json、WorkBuddy ~/.workbuddy/mcp.json。

环境

Node ≥ 18；微信开发者工具稳定版 1.06+（推荐 2.x，需带 cli.bat / wechatide.cmd；官方 skill 兼容门槛 2.02.2607152+）。Windows / macOS。

零配置：项目路径、cli 路径、wechatide 路径、端口（9420-9430 扫描）全部自动探测；需要时可用 WECHAT_DEVTOOLS_CLI / WECHAT_DEVTOOLS_PROJECT / WECHATIDE_CLIENT 等环境变量覆盖。首次调用 wechatide 系工具会弹一次授权框（客户端名 miniprogram-mcp），点同意后免确认。

使用

AI 对话里说人话即可（“连上开发者工具” → ensure_ready；“读一下 globalData” → evaluate；“截个图” → simulator_screenshot；“看看 console” → get_simulator_console），或一键 auto_test：定位项目 → 连接 → preflight → 跑用例，返回 pass / blocker / hint。

连接自愈：不必记得先连接

所有依赖连接的工具（automator 直连 14 个 + wechatide 需项目窗口的 7 个）在 dispatch() 统一过一道 ensureAlive 闸门：活着直接放行，死了自动重连，仍连不上才返回 connection_lost 结构化 blocker。

IDE 重启 / 9420 被别的客户端占用 / 久置不用都会让 ws 静默断开，而 mp 引用还在——旧逻辑只查 mp 是否为 null，于是放行，下游抛一堆底层 ws 错误，表现为「截图/console 偶发失败、重试又好了」。现在这一层在入口处拦掉，调用方不需要记得先 ensure_ready，每个 handler 也不必各写一遍重试。

• 探活有 2s 缓存窗口（WECHAT_DEVTOOLS_ALIVE_CACHE_MS 可调），连续调用几乎零额外开销
• WECHAT_DEVTOOLS_AUTO_HEAL=0 退回旧行为（只查 mp 是否为 null），用于对比测试
• ensure_ready 仍然值得显式调用：它会等运行时就绪，避免冷启动后首条调用超时

automator 直连（20）

官方 wechatide CLI 封装（11）

走 wechatide.cmd（随官方工具升级），不依赖官方 MCP 配置；授权等待、异步轮询、错误分类已在 lib/wechatide.js 代码化。需要动手的操作（授权 / 上传确认）短等后返回 {pending, taskId, userAction}，转告用户后用 wechatide_poll_task 续查。

系统层窗口控制（1）

simulator_screenshot 截的是模拟器面板当前渲染出来的屏幕像素，不是设备原生 750px。IDE 窗口被压小时模拟器跟着缩，实测同一页面：

官方 49 个 wechatide 工具里没有任何调窗口或调缩放的能力（automation_viewport_action 只有 pageScrollTo / screenshot / stopAudits / remote / close），所以这一层直接从操作系统动窗口。ensure_ready 与 simulator_screenshot 默认自动最大化，一般不用手动调用。

窗口标题取 project.config.json 的 projectname（实测就是项目名，如 aura），同名窗口按面积取最大，匹配不到时按窗口面积挑最大，此时 matchedBy=largest 并带 warning；项目列表 窗口会被排除。窗口最小化时 GetWindowRect 返回的是图标矩形（约 160×28），此时只看 before.minimized，不要拿宽高当真实尺寸——maximize 会顺带取消最小化。注意 IDE 重启后窗口会回到上次的小尺寸，所以每次测试入口都重新拉一次而不是只做一次。

evaluate 的 fn 必须是函数表达式；call_wx_api 仅支持同步 API（异步用 evaluate 包 Promise）。

故障排查

中文 Windows 的 GBK/UTF-8 混排解码与六类 blocker 分类已在 lib/ 代码化。

限制

BLE 不可用（模拟器 brand: devtools）；call_wx_api 仅同步 API；真机行为可能与模拟器不同；launch 模式在 Windows + Node 18+ 上不可用（仅 connect）。

开发

node --check index.js → npm run smoke（免 IDE）→ node e2e-all-tools.js（需 IDE，产物 gitignore 勿提交）。自定义用例放 checks/*.js（通用）或 checks/examples/（项目专属），模板 _template.js。发布：npm version minor && npm publish（files 白名单须含 smoke.js）。

License

MIT