watertian/wechat-devtools-mcp

Developer tools

112 stars 0 forks 品質 90 トレンド 90

Repository Install

将微信开发者工具 CLI 封装为 MCP (Model Context Protocol) 服务，使编辑器中的 AI 能够直接调用微信 CLI 命令，实现小程序**全流程闭环。

概要

将微信开发者工具 CLI 封装为 MCP (Model Context Protocol) 服务，使编辑器中的 AI 能够直接调用微信 CLI 命令，实现小程序**全流程闭环。

README

微信开发者工具 MCP Server (v0.9.10)

将微信开发者工具 CLI 封装为 MCP (Model Context Protocol) 服务，使编辑器中的 AI 能够直接调用微信 CLI 命令，实现小程序开发、测试、调试、自动化全流程闭环。

[!IMPORTANT] 本项目采用「瘦 MCP + 胖 Skill」架构：MCP Server 提供 7 个聚合 API，配套的 wechat-devtools Skill 提供 SOP 流程、参数速查和最佳实践。两者必须配合使用，缺少 Skill 时 AI 将无法按正确流程操作小程序。

已发布至官方 MCP Registry，支持跨平台（Windows / macOS）一键安装。

🌐 English Documentation →

🚀 安装与快速开始

Step 1 — 安装 MCP Server

推荐使用 uv，它能自动处理 Python 依赖并提供隔离的执行环境。

pip install uv                                  # 安装 uv（如已安装可跳过）
uv tool install wechat-devtools-mcp --force     # 一键安装到全局隔离环境

[!WARNING] 如果之前通过 pip install 安装过旧版本，请先卸载以避免版本冲突：
pip uninstall wechat-devtools-mcp
pip install 的路径（如 Python313/Scripts/）可能优先于 uv tool install 的路径（~/.local/bin/），导致实际运行旧版本。可通过 wechat_ide(action='status') 返回的 mcp_version 字段确认当前版本。

[!TIP]

查看已安装版本：

uv tool list | grep wechat    # 离线确认已安装版本

升级工具：如果编辑器正在运行 MCP 服务，需先终止进程再升级：

# Bash / CMD
taskkill /F /IM "wechat-devtools-mcp*" 2>/dev/null; uv tool upgrade wechat-devtools-mcp

# Windows PowerShell
Get-Process | Where-Object { $_.ProcessName -like "*wechat-devtools*" } | Stop-Process -Force
uv tool upgrade wechat-devtools-mcp

Agent 一键升级：

taskkill /F /IM "wechat-devtools-mcp*" 2>/dev/null; uv tool upgrade wechat-devtools-mcp && npx -y skills add WaterTian/wechat-devtools-mcp/.agents/skills/wechat-devtools

Step 2 — 开启开发者工具服务端口

[!WARNING] 必须手动开启，否则 AI 将无法下发任何指令。

操作路径：开发者工具 → 设置 → 安全设置 → 服务端口 → 开启

💡 可通过 wechat_ide(action='status') 验证端口是否已开启——如果返回连接失败，说明服务端口尚未启用。

Step 3 — 确认必要路径

请提前获取以下两个绝对路径，稍后需填入编辑器配置：

路径	Windows 示例	macOS 示例
微信开发者工具 CLI	`C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat`	`/Applications/wechatwebdevtools.app/Contents/MacOS/cli`
小程序项目根目录	`D:\MyProjects\mini-app`	`/Users//Projects/mini-app`

macOS 用户：JSON 配置中无需转义斜杠（/ 直接写）；Windows 用户需把 \ 写成 \\。

Step 4 — 编辑器配置

Step 5 — 安装 Skill（必须）

[!IMPORTANT] 本 MCP 必须配合 wechat-devtools Skill 使用。 Skill 包含 AI 操作小程序所需的全部 SOP 流程、参数速查和故障排查指南。未安装 Skill 时，AI 只能调用裸 API，无法自动执行标准化测试和调试流程。

方式一：npx skills add（Claude Code 用户）

npx -y skills add WaterTian/wechat-devtools-mcp/.agents/skills/wechat-devtools

会拉到 ~/.claude/skills/，Claude Code 自动加载。

方式二：手动放到 .agents/skills/（Trae 等基于 .agents/skills/ 加载的客户端）

在小程序项目根目录执行：

git clone --depth 1 https://github.com/WaterTian/wechat-devtools-mcp.git .wdm-tmp
mkdir -p .agents/skills
cp -r .wdm-tmp/.agents/skills/wechat-devtools .agents/skills/
rm -rf .wdm-tmp

完成后的目录结构：

your-project/
└── .agents/skills/
    └── wechat-devtools/
        ├── SKILL.md                # 主指令文件（SOP + 能力映射 + 红线规则）
        └── references/
            └── tool_reference.md   # 7 个聚合 API 完整参数参考

[!TIP] Trae 用户：确认 设置 → 技能与命令 → 启用 .agents 技能目录 开关已开启（默认开），保存后刷新即可在「技能 → 项目」tab 看到 wechat-devtools。

🛠️ 工具箱概要

MCP Server 提供 7 个聚合工具，覆盖小程序全生命周期：

工具	功能	支持的 action
`wechat_ide`	IDE 生命周期管理	`open` `login` `is_login` `close` `quit` `status`
`wechat_build`	构建与发布	`compile` `preview` `upload` `build_npm` `cache_clean`
`wechat_automator`	自动化交互	`start` `tap` `input` `element_info` `set_data` `call_method` `call_wx` `mock_wx` `evaluate` `page_stack` `page_data` `system_info` `storage`
`wechat_inspector`	运行时日志采集	`console` `cdp`
`wechat_screenshot`	界面截图（长图拼接）	—
`wechat_navigate`	跳转页面并采集 CDP 日志	—
`wechat_file`	项目文件读取	`project_info` `list_pages` `read_page` `read_file`

云函数与云数据库管理请使用 CloudBase MCP（manageFunctions / readNoSqlDatabaseContent 等），功能更完整且无 IDE 依赖。wechat_cloud 自 v0.9.5 起已禁用。

完整工具参数说明请参阅 MCP_DOC.md

🧠 Skill 内容详情

Skill 让 AI 在收到自然语言指令后，自动匹配并执行标准化操作流程：

你说的话	AI 执行的流程
“帮我检查所有页面有没有报错”	SOP D — 全页面巡检
“点击登录按钮，截图看看效果”	SOP B — UI 调试
“页面白屏了，帮我排查”	SOP C — 异常排查
“Mock 支付接口，测试支付流程”	SOP E — Mock 集成测试
“测试详情页，参数名是什么”	SOP G — 子页面测试
“对比各页面积分是否一致”	SOP I — 跨页面数据校验

Skill 包含

9 个 SOP 流程 — 初始化、UI 调试、异常排查、全页面巡检、Mock 集成测试、网络调试与 UI 适配、子页面测试、跨页面数据校验、并行数据比对
能力映射字典 — 7 个聚合工具 × 全部 action 的快速索引
CDP 渐进排查策略 — concise → full 两阶段，控制 Token 消耗
完整参数参考 — 每个 action 的必填/可选参数、返回示例、常用模板
故障排查手册 — 常见错误码与修复方式

安装方式见 Step 5 — 安装 Skill

💡 环境变量

变量名	说明	默认值	必填
`WECHAT_DEVTOOLS_CLI`	微信开发者工具 CLI 路径	—	是
`WECHAT_PROJECT_PATH`	默认小程序项目绝对路径	—	是
`WECHAT_CLI_TIMEOUT`	CLI 命令超时时间（秒）	`30`	否
`NODE_PATH`	Node.js 执行文件路径	`node`	否

❓ 常见问题

📋 版本历史

版本	说明
0.9.10	修复 page_path 静默失败：screenshot.js 导航后验证页面路径是否匹配，缺少 `/index` 后缀或页面不存在时返回明确错误而非静默拍下旧页面；node_bridge.py 修复 daemon handler 错误信息丢失（#5）
0.9.9	修复截图导致小程序重启：screenshot.js 对非 TabBar 页面的导航方式从 `reLaunch`（销毁全部页面栈）改为 `navigateTo`（非破坏性压栈），修复 macOS 环境下截图后模拟器重置问题（#4）
0.9.8	修复 automator 连接稳定性：daemon.js `currentPage()` 健康检查改为轮询重试（新连接 5 次 × 3s+1.5s），不再因页面加载慢丢弃已建立的 WebSocket 连接；`_action_start` 改用 `_run_cli` 同步检测 CLI 返回码，CLI 失败立即感知（#3）
0.9.7	修复 daemon 孤儿进程残留：daemon.js 增加父进程 watchdog，每 5 秒 `process.kill(ppid, 0)` 检测存活，父进程被杀后自动清理 WS 连接并退出（#2）
0.9.6	macOS 适配：`cdp_enabled=true` 模式跨平台启动（NW.js 主程序 `wechatdevtools` + `package.nw` 入口 + `pkill` 清理）；默认 CLI 路径按平台返回；Node.js 检测补 Homebrew/nvm 候选路径；README 增加 macOS 路径示例
0.9.5	修复 compile 健康检查永久失败的潜伏 bug（ui_debug.js 无 `page_stack` action，v0.9.0 以来 `automator_verified` 一直误报 false）；compile 对 `EACCES`/`EADDRINUSE`/`#initialize-error` 等致命 pattern 降级为 fail，杜绝「假成功发布旧 bundle」；preview 自动 resolve 相对路径 + mtime 新鲜度检测；`wechat_automator(action='start')` 升级为 TCP+WS 双重验证 + `retry_after_ms` 精确等待；compile 前检测 `miniprogram_npm` 过期发 warning；inspector 短 duration 捕获异常时发 warning；`wechat_cloud` 工具已禁用（改用 CloudBase MCP）
0.9.4	修复 switchTab 跳转不生效（改用 `miniProgram.switchTab()` 替代 `callWxMethod`）；compile 后重连稳定性（去冗余进程 + 3s 延迟 + WS 健康检查）；README 5 项 agent 友好性改进

参考文档

许可证

MIT

View this README on GitHub

インストール

uvx wechat-devtools-mcp

設定

{
  "mcpServers": {
    "wechat-devtools": {
      "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"
      }
    }
  }
}