wechat-devtools

Wechat DevTools MCP Skill (v0.9.20)

前置条件

ステップ 0：インストールと設定

pip install uv
uv tool install wechat-devtools-mcp            # 升级：uv tool install wechat-devtools-mcp --force --refresh

{
  "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 ブリッジを wechat-devtools として登録するため、同じ名前だと上書きされます）。macOS CLI のパスは /Applications/wechatwebdevtools.app/Contents/MacOS/cli です。各エディターの設定については README を参照してください。
• サービスポートを必ず有効にしてください：設定 → セキュリティ設定 → サービスポート。有効になっていない場合、すべての CLI 操作で CLI_TIMEOUT が発生します。
• 9222 が Chrome によく使用されているマシンでは、env に "WECHAT_CDP_PORT": "9333" を追加してください。Node.js は ≥ 18 が必要です。

ステップ 1：ランタイム環境の確認

まず wechat_ide(action='status') を 1 回呼び出して、すべての前提条件を確認してください。

確認項目	フィールド	失敗時
CLI がインストール済み	cli_exists: true	WECHAT_DEVTOOLS_CLI を設定
サービスポートが有効	service_port_enabled: true	false は必ず CLI_TIMEOUT が発生するため、設定で有効にしてください。null は読み取れなかった状態であり、無効という意味ではありません
プロジェクトパスが有効	project_exists: true	WECHAT_PROJECT_PATH を設定してください。project.config.json を含むルートディレクトリを指定する必要があります
Node.js が利用可能	node_available: true	Node.js ≥ 18 をインストール
CDP ポートが他のプロセスに使用されていない	cdp_port_occupant.kind が none / ide	foreign（よくあるのは Chrome）→ open(cdp_port=9333) を実行するか、WECHAT_CDP_PORT を設定
プロジェクトウィンドウが起動中	project_window_open: true（IDE が CDP を有効にして起動している場合のみ値が入り、それ以外は null）	false → start がウィンドウを自動的に再起動します
バージョンが一致	skill_version == mcp_version（status はプロジェクト内の skill のコピーを自動で読み取り、不一致の場合は message に表示されます）	uv tool upgrade wechat-devtools-mcp を実行するか、skill のコピーを同期
ログイン済み	is_login → logged_in: true	login(qr_format='terminal') で QR コードをスキャン
公式組み込み MCP	official_mcp.available	下記の振り分けルールを参照

環境の振り分けルール（IDE 2.x 組み込み MCP）

開発者ツール 2.x（2026-08-18 から公式 Stable）は、http://127.0.0.1:<ide_port>/mcp に MCP Server を組み込んでいます（47 個の原子ツール、うち 2 個は非推奨）。official_mcp.available: true で、公式 MCP が現在のエージェントに接続されている場合：

操作	どちらに任せるか
プロジェクトの起動・終了、ログイン、コンパイル、プレビュー、アップロード、npm ビルド、クリック／入力／スクロール、クラウド開発	公式ツールを優先し、同じ操作を両方で行わないでください
縦長画像の連結スクリーンショット	本 skill。公式の simulator_screenshot はビューポートのみを撮影し、長辺を 1280 に縮小した JPEG にします
CDP の構造化ログ（inspector cdp / navigate）	本 skill。収集前の過去のメッセージを再生でき、ノイズをフィルタリングできます
SOP C / D / I / J のタスク単位のワークフロー	本 skill が編成し、基本手順には公式ツールを呼び出せます

available: false（1.06、IDE が起動していない、ポートが変わった場合）または公式 MCP が接続されていない場合、本 skill がすべての機能を担います。基本操作のために公式 MCP をインストールするようユーザーに求めないでください。

効率化の原則

• IDE を開くのはセッション開始時の open 1 回だけです。コードを変更したら compile → page_data だけを実行してください（automator は自動的に再接続します）。再度 open する必要はありません。
• コードを変更せずにページを切り替える場合は、evaluate(fn_source="function(){ wx.reLaunch({url:'/pages/x/index'}); return 'ok' }") → page_data を実行してください。
• 接続が切断された場合、automator の操作／navigate／screenshot は start を 1 回自動で実行して再試行します（auto_recovered が返されます。副作用のある tap／input／call_method は接続段階で失敗した場合のみ再試行します）。それでも失敗する場合は、手動で start → page_data を実行してください。完全な復旧手順をすぐに行わないでください。

API クイックリファレンス

パラメーターと戻り値の完全な一覧は tool_reference.md を参照してください。

wechat_ide

action	機能	主なパラメーター／戻り値
open	IDE を起動してプロジェクトを開きます。cdp_enabled=true（デフォルト）の場合、最初に cdp_port の使用状況を確認します。他のブラウザーが使用中の場合は IDE を終了せずにエラーを返し、それ以外の場合は起動中の IDE を終了して CDP ポートを指定して再起動し、小プログラムの target が準備できてから起動時のヘルスチェックを行います	cdp_port（デフォルトは WECHAT_CDP_PORT または 9222。成功後、同じセッション内の inspector／navigate／compile では省略するとこの値が引き継がれます）；ide_runtime、cdp_ready、project_opened を返します。error がある場合は success:false と startup_errors を返します
login / is_login	QR コードでログイン／ログイン状態を確認	qr_format；logged_in
close / quit	プロジェクトウィンドウを閉じる／IDE を終了します（プロセスが実際に終了するまで待機し、上限は 10s）	quit は exited を返します
status	環境の診断	service_port_enabled、ide_port、official_mcp、mcp_version、skill_version（プロジェクト内のコピー。不一致の場合はヒントを表示）、cdp_port / cdp_port_occupant（ポートを使用しているのが IDE か他のブラウザーか）、project_window_open

wechat_build

action	機能	主なパラメーター／戻り値
compile	コンパイルして Error／Warning を取得し、成功後に automator を自動で再接続します（デフォルトの 9420 のみ）	cdp_port；errors、warnings、wxml_errors、npm_warning、automator_verified、fatal_errors、cdp_skipped（CDP ポートが他のブラウザーに使用されており、WXML の実行時エラーを収集できなかったことを示します）を返します
preview	プレビュー用 QR コードを生成	qr_format、qr_output（相対パスはプロジェクトルートからの相対）；qr_stale_warning はバンドルが更新されていない可能性を示します
upload	WeChat の管理画面にアップロードします。本番環境向けの操作です	version は必須、desc
build_npm	npm をビルドします。依存関係を追加／更新した後は必ず実行してください。実行しないと、実行時に module ... is not defined が発生します	なし
cache_clean	キャッシュをクリア	clean_type（デフォルトは compile。all は慎重に使用してください）

tabBar ページでは compile_condition が app のルートガードに上書きされる場合があります。ページ遷移には evaluate の使用がより確実です。

wechat_automator

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

action	功能	必填 / 返回
start	开自动化端口，CLI + TCP + WS 三重验证；窗口未加载完时自动重跑 cli auto（最多 3 轮）；WS 级最多等 45s（ready_timeout 可调，真机约 7~11s 才首次应答）	返回 verified、ready_after_ms；false 时先再 start 一次，不要先 open
tap / input	点击 / 输入	selector（input 另需 value）
element_info	元素 tagName/text/wxml/size/offset，style_prop 时带 style	selector
set_data	热更新页面 data，无需重编译	data_json；返回 updated_keys
call_method	调页面方法	method、args_json?；返回 return_value、path
call_wx / mock_wx	调 wx API / Mock 返回值（当前会话有效）。同步返回的 API（*Sync、getWindowInfo 等）自动经 evaluate 直调，返回 sync: true	method（mock 另需 result_json）
evaluate	逻辑层执行 JS	fn_source（推荐）或 expression；返回 result、mode
page_stack	页面栈	返回 depth、pages
page_data	当前页 data	expected_path? 会轮询等页面匹配；返回 path、data、path_mismatch
system_info / storage	系统信息 / 本地缓存	storage 传 key 取值，不传列 keys

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

action	功能	关键参数
cdp	CDP 采集 WXML 警告、渲染层报错、Runtime 错误。能回放采集前的历史消息	duration=10、detail_level、max_logs、cdp_port
console	automator 事件采集 console 与 JS 异常。只收连接后的事件	duration（排查异常 ≥8s）、log_type、tap_selector

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

wechat_screenshot

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

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

返回字段	含义	应对
is_scroll_view_page: true	页面靠 scroll-view 滚动，只截到视口	用 evaluate 读数据代替视觉确认
truncated: true	超分段上限，底部没拍到	full_page=false + scroll_top 分段截
content_gaps: N	固定头尾吃光重叠，N 处内容丢失	调大 overlap（如 150）重试
detection_confident: false	固定头尾识别不可靠	结果仅供参考

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（疑似参数名错）；CDP 端口被别的浏览器占着时照常跳转但 cdp_available: false 并附 cdp_warning；失联自动恢复后附 auto_recovered。
• 前提：start 已调用且项目以 cdp_enabled=true 打开。reLaunch 进入的页面云函数调用可能丢上下文，非 tabBar 页优先 evaluate + wx.navigateTo。

wechat_file

action	功能	必填 / 返回
project_info	project_config、app_config、directory、app.js/app.wxss 节选	无
list_pages	app.json 全部页面，含文件完整性	返回 pages[{path, complete, missing}]、total
read_page	页面四件套源码	page_path；返回 files{文件名: 内容}、resolved_base
read_file	任意单文件，最多 800 行	file_path；返回 content、resolved_path、truncated

路径口径统一：先按 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)    # 端口被别的浏览器占着会直接报错，换 cdp_port=9333（之后其它工具自动沿用）
  ↳ success=false + startup_errors → 先修复再继续
wechat_automator(action='start')               # 自带最多 45s 就绪等待；verified=false → 再 start 一次，不要先 open
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。

页面跳转

场景	方式
普通页	evaluate(fn_source="function(){ wx.navigateTo({url:'/pages/x/x?id=1'}); return 'ok' }")
tabBar 页	wechat_navigate(page_path='pages/x/index')
强制重置	同上用 wx.reLaunch
跳转后	page_data(expected_path='pages/x/x')，校验 path

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 → 数据没加载
wechat_automator(action='evaluate', fn_source='function(){ return wx.cloud.callFunction({name:"x",data:{}}) }')
                                                            # ② 直接调 API 拿完整返回，[object Object] 时必用
wechat_inspector(action='cdp', duration=5)                  # ③ 能回放刚才的错误
wechat_build(action='compile')                              # ④ 看 errors / wxml_errors

SOP D：全页面巡检

wechat_build(action='compile')
wechat_file(action='list_pages')
# 逐页顺序执行（禁止并行）：
wechat_navigate(page_path=page, wait_ms=3000)
wechat_automator(action='page_data', expected_path=page)    # path 不匹配 → 标记重定向；字段空 → evaluate 诊断
# 汇总：按 page_data 结果输出报告；只在异常页补截图

SOP E：Mock 集成测试（支付 / 权限 / 网络 / 适配）

mock_wx(method='requestPayment', result_json='{"errMsg":"requestPayment:ok"}')
mock_wx(method='getLocation',    result_json='{"latitude":23.1,"longitude":113.3}')
mock_wx(method='request',        result_json='{"errMsg":"request:fail timeout"}')   # 模拟超时
mock_wx(method='getSystemInfo',  result_json='{"theme":"dark","windowWidth":1024}') # 暗色 / 宽屏适配
tap(selector='.pay-btn') → page_data                                                 # 触发并验证

Mock 仅当前会话有效。拦截请求可用 fn_source="function(){ var o=wx.request; wx.request=function(p){ console.log(p.url); return o.apply(wx,arguments) }; return 'ok' }"。

SOP G：带 query 参数的子页面

wechat_file(action='read_page', page_path='pages/x/x')      # 看 onLoad(options) 的参数名
wechat_navigate(page_path='pages/x/x?id=123', wait_ms=3000)
wechat_automator(action='page_data')                        # 大部分为 null → 参数名错，回到第一步

SOP I：跨页面数据一致性

wechat_file(action='list_pages')
# 逐页：navigate → page_data(expected_path=page)，提取公共字段（如 points / level）记入比对表
# 比对同名字段：不一致 → evaluate 直接调 API 对比，检查子页面是否走了独立数据链路

SOP J：小程序 + 管理后台并行比对

管理后台走 Playwright MCP，小程序走本 MCP，两者端口不同可并行提取，比对在主进程串行做。automator 9420 独占，同一时刻只能有一个 agent 操作本 MCP。

CDP 日志策略

场景	参数
快速诊断	duration=5, detail_level='concise', max_logs=20
深度排查	duration=10, detail_level='full', max_logs=100
页面巡检	duration=3, detail_level='concise', max_logs=30

• concise 只回 errors + warnings；summary.errors > 0 再用 full 拿 source 定位，配合 read_file。
• cdp 会回放采集前的缓冲区（12 秒前的错误也能拿到），console 只收连接后的事件。
• 已自动过滤：[system]、WAService.js、WAWebview.js、IDE 外壳页；open 的启动检查还过滤 devtools:// 与 ide:///extensions/。
• 需要自己排除：devtools:// 来源的 console.assert、SharedArrayBufferIssue、wx.saveFile 即将废弃 类框架预警。
• ide:///extensions/inject/… 来源的 warning 不是噪音，是框架报的真实问题（无效 app.json 字段、API 废弃、WXSS 选择器不合法）。
• 计数可能被噪音抬高，最终以 page_data 为准。

page_data 必须校验 data.path 等于导航目标；不一致的常见原因：未登录被拦到登录页、云函数失败 fallback 首页、page_path 拼错、onLoad 条件跳转。传 expected_path 可轮询等待匹配，path_mismatch: true 时用 page_stack 看完整栈。

返回值与恢复

成功 {"success": true, "data": {...}, "message": "..."}，失败 {"success": false, "error_code": "...", "message": "...", "hint": "..."}。 error_code 只有 6 种：PARAM_MISSING、CLI_NOT_FOUND、PROJECT_PATH_MISSING、NODE_NOT_FOUND、CLI_TIMEOUT、UNKNOWN_ERROR。连接失败、跳转失败等都归 UNKNOWN_ERROR，看 message 与 hint。

连接断开恢复分三级： 0. 自动：动作本身会 start 一次再重试，成功时 data.auto_recovered 带 ready_after_ms。

1. 快速：start → page_data。
2. 完整：open(cdp_enabled=True) → start → compile → page_data。

故障速查

症状	原因	解决
CLI_TIMEOUT	服务端口未开 / IDE 未运行	status 看 service_port_enabled；开端口；open
open 返回 startup_errors	小程序启动阶段有致命错误	先修代码再 open
start 返回 verified=false（端口在听、小程序未应答）	IDE 仍在编译/加载项目；或项目窗口刚被其它会话的 cli close 关掉又重开（SessionEnd 钩子、常驻 bot 等）	直接再 start（可加大 ready_timeout）；连续 3 次失败才 open(cdp_enabled=True)。open 会杀 IDE、冷启动更慢，别把它当第一反应
CLI auto 连续 3 次返回成功但端口未监听	项目窗口没加载完或已关闭（cli auto 会假成功；纯 CLI open 后约需 15s）	稍等再 start；仍失败 open(cdp_enabled=True) 重启后再 start
动作仍返回 Failed connecting to ws://localhost:9420 / Connection closed	项目窗口被关（其它会话 cli close、手动关窗）或 automator 闲置后不应答；动作已自动 start 一次仍没救回	看 status 的 project_window_open；手动 start（cli auto 会重开窗口）→ page_data；再失败才 open(cdp_enabled=True)
CDP 采集失败 / 采到的全是别的东西	未以 cdp_enabled 打开，或 9222 被 Chrome 占用（status 的 cdp_port_occupant.kind 为 foreign 即是）	open(cdp_port=9333)，之后 inspector / navigate / compile 不传 cdp_port 自动沿用；长期设 WECHAT_CDP_PORT
Using AppID: undefined / appid missing	project_path 指向子目录 / 未登录	改为含 project.config.json 的根目录；is_login
navigate 后 page_data.path 与目标不一致	page_path 拼错、被重定向（未登录 / 参数错 / 云函数失败）、switchTab 未完成	list_pages 核对；查登录态与 onLoad 逻辑；增大 wait_ms
evaluate 返回 null 且 mode: "statement"	expression 走了语句模式没 return	改用 fn_source 并显式 return
元素未找到 / Element is obfuscated	不在当前页、selector 错、被遮挡	page_stack 确认页面；element_info 验证；换父节点
scroll-view 页长图只有一屏	automator 无法捕获 scroll-view 内部滚动	返回 is_scroll_view_page: true，改用 evaluate 读数据
长图看着连续但少一截	固定头尾吃光重叠	看 content_gaps，增大 overlap
截图看不到弹窗 / 拍到错误页面	overlay 不在同一渲染层 / 截图前页面被重置	以 page_data 为准；传 page_path
compile 成功但 IDE 显示红色 WXML 错误	WXML 错误走 IDE 内部通道	看 wxml_errors；检查中文引号、未闭合标签
运行时报 @babel/runtime/helpers/xxx is not defined	npm 依赖更新后未 build_npm	build_npm → compile，console(duration≥8, log_type='exception') 验证
工具行为异常 / 参数对不上（IDE 2.x）	注册名撞车：官方 bridge 也叫 wechat-devtools	注册名改 wechat-devtools-mcp；status 的 mcp_version 可确认调到谁
Windows 上 open 后项目没打开 / CDP 连不上（IDE 2.x）	旧版 Windows 分支没有 1.x/2.x 判定	升级到最新版；仍失败附 ide_runtime 反馈
ide:///extensions/inject/… 的 warning	框架报的真实应用问题	当真实告警处理，不要过滤

绝对红线

• ❌ open 返回 startup_errors 后继续测试
• ❌ 未确认 logged_in: true 就 preview / upload
• ❌ 对生产项目 cache_clean(clean_type='all')
• ❌ 脑补运行状态；同一失败操作重试超过 3 次（应转为诊断根因）
• ❌ 硬 sleep 等待，用 wait_ms 或 page_data(expected_path) 轮询
• ❌ start 返回 verified=false 就立刻 open 重启 IDE（先重试 start）
• ❌ SOP 里主动截图，只在用户要求或需要视觉确认时截
• ❌ 没改代码就 compile
• ❌ navigate 后不校验 page_data.path
• ❌ 多个 agent 并行使用 wechat_automator（9420 独占）
• ❌ 用 miniprogram/ 子目录作 project_path；WXML 属性值里用中文引号（工具无法检测）
• ✅ 自动化 / 截图前先 start；tap / input 前先 element_info 确认元素
• ✅ upload 前确认版本号递增、build_npm 已执行
• ✅ compile 后用 page_data 确认 automator 连接