wechat-devtools-mcp 0.3.0

MCP Server for WeChat DevTools CLI - 微信开发者工具 MCP 服务

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

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

🚀 本 MCP Server 已正式提交至官方 MCP Registry，支持跨平台（Windows/macOS）一键安装。

---

🚀 安装与快速开始

[!IMPORTANT] 在开始之前，请务必提前确认并准备好以下两个路径，您需要在编辑器配置中手动输入它们：

1. 微信开发者工具 CLI 路径 (例如: C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat)
2. 您的小程序项目绝对路径 (例如: D:\\MyProjects\\mini-app)

1. 基础环境准备

如果你安装了 uv，可以使用以下命令直接运行，或直接将其配置在编辑器中，而无需手动管理依赖：

uvx wechat-devtools-mcp

[!TIP] 如果提示 uvx 命令找不到，请先执行 pip install uv。 uv tool list 查看mcp版本 uv tool upgrade wechat-devtools-mcp 升级全局工具wechat-devtools-mcp

# 1. 隔离环境安装包 (独立工具) 
uv tool install wechat-devtools-mcp --force

# 2. 查看独立工具包的环境安装目录
uv tool dir

⚙️ 编辑器配置

Claude Desktop / Antigravity

修改 claude_desktop_config.json 或 mcp_config.json (Antigravity)：

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

Kiro

编辑 ~/.kiro/settings/mcp.json：

{
  "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",
        "PYTHONIOENCODING": "utf-8"
      },
      "autoApprove": [
        "wechat_ide",
        "wechat_build",
        "wechat_automator",
        "wechat_inspector",
        "wechat_screenshot",
        "wechat_navigate",
        "wechat_file",
        "wechat_cloud"
      ]
    }
  }
}

OpenAI Codex

编辑 ~/.codex/config.toml（全局）或项目根目录下的 .codex/config.toml（项目级）：

[mcp_servers.wechat-devtools]
command = "uvx"
args = ["wechat-devtools-mcp"]

[mcp_servers.wechat-devtools.env]
WECHAT_DEVTOOLS_CLI = "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat"
WECHAT_PROJECT_PATH = "D:\\Your\\Project\\Path"

也可以通过 CLI 快速添加：

codex mcp add wechat-devtools \
  --env WECHAT_DEVTOOLS_CLI="C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat" \
  --env WECHAT_PROJECT_PATH="D:\\Your\\Project\\Path" \
  -- uvx wechat-devtools-mcp

配置完成后，在 Codex TUI 中输入 /mcp 可查看已激活的 MCP 服务。

---

Cursor / VS Code (MCP Plugin)

在 MCP 控制台中添加新 Server：

• Name: wechat-devtools
• Type: command
• Command: uvx wechat-devtools-mcp
• Environment Variables: 同上添加 WECHAT_DEVTOOLS_CLI 和 WECHAT_PROJECT_PATH。

WECHAT_DEVTOOLS_CLI 路径根据实际安装位置调整，注意反斜杠需要转义。

---

🛠️ 工具箱概要 (Toolbox Reference)

v0.3.0 采用「瘦 MCP + 胖 Skill」架构，提供 8 个聚合工具，覆盖小程序全生命周期。

工具	功能	支持的 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
wechat_cloud	云函数管理	env_list, func_list, func_info, func_deploy, func_download

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

---

🤖 AI 协作 SOP (最佳实践)

SOP 一：日常开发迭代

适用于日常功能开发、Bug 修复场景。

Step 1 — 初始化环境

wechat_ide(action='status')           # 诊断环境配置
wechat_ide(action='is_login')         # 检查登录状态
wechat_ide(action='open', cdp_enabled=True)   # 开启 IDE + CDP 端口
wechat_automator(action='start')      # 开启自动化端口 9420

Step 2 — 读取上下文

wechat_file(action='project_info')    # 获取项目完整信息
wechat_file(action='list_pages')      # 获取页面列表

直接在编辑器中打开目标页面的源码文件（JS/WXML/WXSS/JSON），按需修改代码。

Step 3 — 编译验证（循环）

修改代码 → wechat_build(action='compile') → 有报错则修复 → 再次 compile

Step 4 — 调试验收

wechat_navigate(page_path="pages/xxx/xxx", wait_ms=3000)
  ↓ 跳转页面，CDP 采集高清日志（WXML 警告、废弃 API、渲染层报错等）

wechat_screenshot(output_path="D:/screenshots/xxx.png")
  ↓ 全页面长图截图验收

---

SOP 二：全页面巡检（截图 + 高清日志）

适用于回归测试、UI 验收、发布前全量检查。

前提：已完成 SOP 一的 Step 1 初始化，且 cdp_enabled=True。

Step 1 — 获取页面列表

wechat_file(action='list_pages')

Step 2 — 对每个页面依次执行（循环）

⚠️ 重要：必须按顺序逐个页面执行，不可并行。

① wechat_navigate(page_path="<页面路径>", wait_ms=3000)
     ↓ 跳转到目标页面，采集 CDP 高清日志

② wechat_screenshot(output_path="<输出目录>/<页面名>.png")
     ↓ 截取当前页面长图并保存

③ 重复步骤 ① 和 ②，直到所有页面巡检完成

Step 3 — 汇总分析

AI 对所有页面的日志和截图进行汇总，输出：

• 各页面是否存在 JS 异常 / WXML 警告 / 废弃 API
• 截图路径列表，供人工 UI 核查

完整指令示例（直接发给 AI）：

请对项目所有页面进行全量巡检：
1. 调用 wechat_file(action='list_pages') 获取页面列表
2. 对每个页面依次执行：
   - wechat_navigate 跳转并采集 CDP 高清日志（wait_ms=3000）
   - wechat_screenshot 截图保存到 D:/screenshots/<页面名>.png
3. 最后汇总所有页面的异常和警告（cdp_logs.summary）

---

💡 环境变量说明

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

---

🔄 升级

# 先终止占用进程
Get-Process | Where-Object { $_.ProcessName -like "*wechat-devtools*" } | Stop-Process -Force
# 重新安装最新版
uv tool install wechat-devtools-mcp --reinstall

---

❓ 常见问题

uv tool upgrade 报错"另一个程序正在使用此文件"

MCP 服务进程仍在运行，需先终止：

Get-Process | Where-Object { $_.ProcessName -like "*wechat-devtools*" } | Stop-Process -Force
Start-Sleep -Seconds 2
uv tool install wechat-devtools-mcp --reinstall

wechat_inspector(action='cdp') 返回"CDP 采集失败"

开发者工具已有实例运行时，--remote-debugging-port 参数会被忽略，导致 9222 端口未绑定。解决方法：不要手动启动开发者工具，直接调用 wechat_ide(action='open', cdp_enabled=True)，它会自动 kill 已有进程并以 CDP 模式重新启动。

查看当前安装版本

uv tool list

---

📋 版本历史

版本	说明
0.3.0	重大重构：44 个工具聚合为 8 个 API（wechat_ide/build/automator/inspector/screenshot/navigate/file/cloud）；server.py 从 3175 行压缩为 60 行；CDP 日志 v2（结构化 JSON + detail_level + max_logs）；新增 cdp_core.js 共享模块；新增 SKILL.md 知识库
0.2.6	文档更新：README 编辑器配置章节新增 OpenAI Codex 配置说明
0.2.5	新增 Kiro 编辑器配置说明
0.2.4	截图滚动拼接修复：将 sharp 替换为纯 JS 的 jimp
0.2.3	发布包优化：排除 scripts/ 源码文件，仅保留 scripts/dist/ 构建产物
0.2.2	wechat_get_cdp_logs 移入 core 预设；Node.js 脚本改为 bundle-only 模式
0.2.1	版本更新与文档完善
0.2.0	wechat_navigate_and_capture 改用 CDP 高清日志采集；core 预设精简为 13 个核心工具
0.1.9	fix: 修复源码文件 UTF-8 编码乱码问题
0.1.8	fix: Windows 下 uvx 启动时中文路径导致 UnicodeDecodeError
0.1.7	新增 WECHAT_TOOLS_PRESET core/full 工具集预设；新增 MCP_DOC.md
0.1.6	wechat_open(cdp_enabled=true) 自动 kill 已有进程
0.1.5	修复 Windows 平台 stdio 阻塞问题
0.1.4	添加 CDP 日志、截图、自动化等功能
0.1.3	初始版本

---

参考文档

• 微信开发者工具 CLI 官方文档
• 小程序自动化 SDK

---

许可证

MIT