Wechat Devtools

Wechat DevTools MCP Skill (v0.9.18)

前置条件

Step 0：安装与配置

pip install uv
uv tool install wechat-devtools-mcp --force

{
  "mcpServers": {
    "wechat-devtools-mcp": {
      "command": "uvx",
      "args": ["wechat-devtools-mcp"],
      "env": {
        "WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat",
        "WECHAT_PROJECT_PATH": "D:\\Your\\Project\\Path"
      }
    }
  }
}

• 注册名用 wechat-devtools-mcp（开发者工具 2.x 把自家 MCP bridge 注册成 wechat-devtools，同名会被覆盖）。macOS CLI 路径 /Applications/wechatwebdevtools.app/Contents/MacOS/cli。各编辑器配置见 README。
• 必须开启服务端口：设置 → 安全设置 → 服务端口。未开启则所有 CLI 操作报 CLI_TIMEOUT。

Step 1：运行时环境检查

先调 wechat_ide(action='status') 一次确认全部前置条件：

环境分流规则（IDE 2.x 内建 MCP）

开发者工具 2.x（2026-08-18 起为官方 Stable）在 http://127.0.0.1:<ide_port>/mcp 内建 MCP Server（47 个原子工具）。official_mcp.available: true 且官方 MCP 已接入当前 agent 时：

available: false（1.06、IDE 未启动、端口漂移）或官方 MCP 未接入时，本 skill 承接全部能力，不要让用户为基础操作去装官方 MCP。

效率原则

• IDE 只在会话开始 open 一次；改了代码只需 compile → page_data（自动重连 automator），不要重新 open。
• 没改代码换页面用 evaluate(fn_source="function(){ wx.reLaunch({url:'/pages/x/index'}); return 'ok' }") → page_data。
• 连接断开先 start → page_data，不要直接走完整恢复。

API 速查表

完整参数与返回字段见 tool_reference.md。

wechat_ide

wechat_build

compile_condition 对 tabBar 页可能被 app 路由守卫覆盖，跳转用 evaluate 更可靠。

wechat_automator

先调 start 开启自动化端口，整个会话一次。

evaluate 用法：

• fn_source 传完整函数源码（function(){...} 或箭头函数），入参放 args_json（JSON 数组）。多语句、声明、return 都由函数体决定，mode: "function"。
• expression 只传单个表达式。多语句会退回语句模式（全部执行，mode: "statement"），没有 return 时结果为 null 并附 hint。
• 例：fn_source="function(){ const p=getCurrentPages(); return p[p.length-1].route }"。

wechat_inspector

排查「刚才报的错」用 cdp；要与交互严格对齐时间线才用 console。

wechat_screenshot

• full_page（默认 true）长图拼接，false 只截视口，可配 scroll_top；page_path 不匹配时自动跳转；output_path 留空存到项目 screenshots/。
• 只在用户要求或需要视觉确认时截图；fixed/absolute 弹窗蒙层可能拍不到，以 page_data 为准。

先看 message 有无 ⚠。以下情况图看着连续但不完整：

fixed_header / fixed_footer 是识别到的固定区高度（物理像素）。

wechat_navigate

• page_path 必填，可带 query；tabBar 页自动走 switchTab，其余 reLaunch（返回 navigation_method）。
• wait_ms 默认 2000，含网络请求的页面建议 3000。clear_logs=true 过滤跳转前的历史 CDP 日志。
• 返回 current_page、cdp_logs、navigation_mismatch；带 query 且 check_data=true 时数据大面积为空会给 warning（疑似参数名错）。
• 前提：start 已调用且项目以 cdp_enabled=true 打开。reLaunch 进入的页面云函数调用可能丢上下文，非 tabBar 页优先 evaluate + wx.navigateTo。

wechat_file

路径口径统一：先按 miniprogramRoot 解析再回退项目根，list_pages 的输出可直接喂给 read_page。

云函数与云数据库请用 CloudBase MCP。

SOP 标准操作流程

SOP A：初始化

wechat_ide(action='status')                    # 环境诊断
wechat_ide(action='is_login')                  # 未登录 → login(qr_format='terminal')
wechat_ide(action='open', cdp_enabled=True)    # 9222 被占用时加 cdp_port=9223
  ↳ success=false + startup_errors → 先修复再继续
wechat_automator(action='start')               # verified=false → 按 retry_after_ms 重试，期间可先 compile
wechat_build(action='compile')                 # 建立干净基线，自动重连 automator
wechat_automator(action='page_data')           # 验证连接；AppID undefined → project_path 指到子目录了

project_path 必须是含 project.config.json 的根目录，云开发项目的 miniprogram/ 是子目录。

SOP A-2：改代码后

wechat_build(action='compile') → wechat_automator(action='page_data')

不需要重新 open，也不需要 cache_clean。

页面跳转

SOP B：UI 调试

wechat_file(action='list_pages')                            # 拿有效路径
wechat_navigate(page_path='pages/x/index', wait_ms=3000)    # 跳转 + CDP 日志
wechat_automator(action='page_data')                        # path 必须等于目标页
  ↳ 数据异常 → set_data 热更新验证；元素问题 → element_info；需要看图才 screenshot

SOP C：异常排查（报错 / 白屏 / JS 异常）

wechat_automator(action='page_data')                        # ① 关键字段 null → 数据没加载