{
  "markdown": "# 微信开发者工具 MCP Server (v0.9.18)\n\n[![PyPI version](https://img.shields.io/pypi/v/wechat-devtools-mcp.svg)](https://pypi.org/project/wechat-devtools-mcp/)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue.svg)](https://modelcontextprotocol.io/docs/concepts/mcp-registry)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![English](https://img.shields.io/badge/lang-English-blue.svg)](./README_EN.md)\n\n> 把微信开发者工具封装为 [MCP](https://modelcontextprotocol.io/) 服务，让编辑器里的 AI 直接完成小程序的**编译、预览、调试、自动化测试**闭环。Windows / macOS，已上架官方 MCP Registry。\n\n<!-- mcp-name: io.github.WaterTian/wechat-devtools-mcp -->\n\n> [!IMPORTANT]\n> 「瘦 MCP + 胖 Skill」：MCP Server 只提供 7 个聚合工具，操作流程与最佳实践都在配套的 [wechat-devtools Skill](#step-5--安装-skill必须) 里。**两者必须一起装**。\n\n---\n\n## 🤝 与官方能力的关系\n\n微信开发者工具 **2.x 自 2026-08-18 起为官方 Stable**（1.06 已下架），IDE 内建 MCP Server（47 个原子工具）。两者互补，不是替代：\n\n| 场景 | 用谁 |\n|------|------|\n| 打开项目 / 编译 / 预览 / 上传 / 点击输入 / 云开发 | 2.x 优先官方内建 MCP（`wechat_ide(action='status')` 的 `official_mcp.available` 为 `true` 即可用） |\n| **长图拼接截图**（固定头尾识别，拍不全如实上报） | 本项目。官方只截视口并压到长边 1280 JPEG |\n| **CDP 结构化日志**（回放采集前的历史、按页面归类、去噪） | 本项目。官方只读缓存 |\n| **任务级 SOP**（一句话跑完巡检 / 异常排查 / 跨页面校验） | 本项目 Skill |\n| 存量 1.06.x（NW.js） | 本项目继续兼容；官方内建 MCP 仅 2.x 有 |\n\n> ⚠ 官方 IDE 把自家 bridge 注册为 `wechat-devtools`。本文示例统一用 **`wechat-devtools-mcp`** 避免撞名；旧名配置仍可用，只在同一 agent 同时接入两者时才需区分。\n\n---\n\n## 🚀 快速开始\n\n### Step 1 — 安装 MCP Server\n\n```bash\npip install uv                                  # 如已装可跳过\nuv tool install wechat-devtools-mcp --force\nwechat-devtools-mcp --version                   # 确认实际运行版本\n```\n\n> [!WARNING]\n> 曾用 `pip install` 装过旧版的，先 `pip uninstall wechat-devtools-mcp`，否则旧路径优先于 uv。\n> ≤0.9.10 与 mcp SDK ≥2.0 不兼容（报 `ModuleNotFoundError: mcp.server.fastmcp`），请升到 ≥0.9.11。\n\n升级前先停掉编辑器里正在跑的 MCP 进程，再 `uv tool upgrade wechat-devtools-mcp`。\n\n### Step 2 — 开启开发者工具服务端口\n\n`开发者工具` → `设置` → `安全设置` → `服务端口` → `开启`。不开则所有操作报 `CLI_TIMEOUT`。\n\n### Step 3 — 准备两个绝对路径\n\n| 路径 | Windows | macOS |\n|------|---------|-------|\n| 开发者工具 CLI | `C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat` | `/Applications/wechatwebdevtools.app/Contents/MacOS/cli` |\n| 小程序项目根目录 | `D:\\MyProjects\\mini-app` | `/Users/<you>/Projects/mini-app` |\n\nJSON 里 Windows 路径的 `\\` 要写成 `\\\\`；macOS 的 `/` 不用转义。\n\n### Step 4 — 编辑器配置\n\n标准配置（Claude Desktop / Antigravity / Kiro / Trae / Claude Code `.mcp.json` 通用）：\n\n```json\n{\n  \"mcpServers\": {\n    \"wechat-devtools-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"wechat-devtools-mcp\"],\n      \"env\": {\n        \"WECHAT_DEVTOOLS_CLI\": \"C:\\\\Program Files (x86)\\\\Tencent\\\\微信web开发者工具\\\\cli.bat\",\n        \"WECHAT_PROJECT_PATH\": \"D:\\\\Your\\\\Project\\\\Path\"\n      }\n    }\n  }\n}\n```\n\n| 编辑器 | 配置位置 | 差异 |\n|--------|----------|------|\n| Claude Desktop / Antigravity | `claude_desktop_config.json` / `mcp_config.json` | 无 |\n| Claude Code（项目级） | 仓库根目录 `.mcp.json` | macOS 下 `command` 用绝对路径 `/opt/homebrew/bin/uvx`，并在 `env` 加 `\"PATH\": \"/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin\"` 与 `\"NODE_PATH\": \"/opt/homebrew/bin/node\"`（GUI 子进程不带 Homebrew PATH） |\n| Kiro | `~/.kiro/settings/mcp.json` | 可加 `\"autoApprove\": [\"wechat_ide\",\"wechat_build\",\"wechat_automator\",\"wechat_inspector\",\"wechat_screenshot\",\"wechat_navigate\",\"wechat_file\"]` |\n| Trae ≥1.3 | AI 面板 → 设置 → MCP → 手动配置；或 `%APPDATA%\\Trae\\User\\globalStorage\\mcp.json` / `~/Library/Application Support/Trae/User/globalStorage/mcp.json` | 聊天须选 **Builder with MCP** 智能体；macOS 同 Claude Code 的绝对路径写法 |\n| Cursor / VS Code | MCP 面板新增 server | Name `wechat-devtools-mcp`，Command `uvx wechat-devtools-mcp`，环境变量同上 |\n| OpenAI Codex | `~/.codex/config.toml` | TOML，见下 |\n\n```toml\n[mcp_servers.wechat-devtools-mcp]\ncommand = \"uvx\"\nargs = [\"wechat-devtools-mcp\"]\n\n[mcp_servers.wechat-devtools-mcp.env]\nWECHAT_DEVTOOLS_CLI = \"C:\\\\Program Files (x86)\\\\Tencent\\\\微信web开发者工具\\\\cli.bat\"\nWECHAT_PROJECT_PATH = \"D:\\\\Your\\\\Project\\\\Path\"\n```\n\n### Step 5 — 安装 Skill（必须）\n\n```bash\nnpx -y skills add WaterTian/wechat-devtools-mcp/.agents/skills/wechat-devtools\n```\n\n不走 `npx skills` 的客户端（如 Trae）：把仓库的 `.agents/skills/wechat-devtools/` 整个复制到小程序项目的 `.agents/skills/` 下即可。Skill 含 9 条 SOP、7 工具全 action 速查、CDP 渐进排查策略与故障手册，详见 [SKILL.md](./.agents/skills/wechat-devtools/SKILL.md)。\n\n---\n\n## 🛠️ 工具箱\n\n| 工具 | 用途 | action / 关键参数 |\n|------|------|------------------|\n| `wechat_ide` | IDE 生命周期与环境诊断 | `open` `login` `is_login` `close` `quit` `status` |\n| `wechat_build` | 构建与发布 | `compile` `preview` `upload` `build_npm` `cache_clean` |\n| `wechat_automator` | 自动化交互与运行时查询 | `start` `tap` `input` `element_info` `set_data` `call_method` `call_wx` `mock_wx` `evaluate` `page_stack` `page_data` `system_info` `storage` |\n| `wechat_inspector` | 运行时日志采集 | `console` `cdp` |\n| `wechat_screenshot` | 长图拼接截图 | `full_page` `page_path` `scroll_top` |\n| `wechat_navigate` | 跳转并采集 CDP 日志 | `page_path` |\n| `wechat_file` | 项目文件读取 | `project_info` `list_pages` `read_page` `read_file` |\n\n完整参数见 [MCP_DOC.md](./MCP_DOC.md)。云函数与云数据库请用 [CloudBase MCP](https://github.com/TencentCloudBase/CloudBase-AI-ToolKit)。\n\n---\n\n## 💡 环境变量\n\n| 变量 | 说明 | 默认 |\n|------|------|------|\n| `WECHAT_DEVTOOLS_CLI` | 开发者工具 CLI 路径（**必填**） | — |\n| `WECHAT_PROJECT_PATH` | 默认项目根目录（**必填**） | — |\n| `WECHAT_CLI_TIMEOUT` | CLI 超时秒数 | `30` |\n| `NODE_PATH` | Node.js 可执行文件 | `node` |\n\n---\n\n## ❓ 常见问题\n\n| 症状 | 处理 |\n|------|------|\n| 一直报 `CLI_TIMEOUT` | 服务端口没开，见 Step 2；`wechat_ide(action='status')` 的 `service_port_enabled` 可自查 |\n| CDP 采集失败 / 采到的全是 Chrome | 9222 被占用。`open(cdp_port=9223)`，且 `inspector` / `navigate` / `build` 用同一个 `cdp_port` |\n| Windows 中文乱码或 `UnicodeDecodeError` | `env` 加 `\"PYTHONIOENCODING\": \"utf-8\"` |\n| 装了新版仍跑旧版 | `pip uninstall wechat-devtools-mcp`，再用 `wechat-devtools-mcp --version` 确认 |\n| IDE 2.x 下工具行为异常 | 注册名与官方 `wechat-devtools` 撞车，改用 `wechat-devtools-mcp` |\n\n---\n\n## 📋 版本历史\n\n| 版本 | 日期 | 摘要 |\n|------|------|------|\n| 0.9.18 | 2026-09-04 | Windows 2.x 真机闭环：状态目录 `User Data` 层、就绪判据、`quit` 等退出、噪音过滤；新增真机冒烟脚本 |\n| 0.9.17 | 2026-09-03 | 适配开发者工具 2.x Stable；evaluate 新增 `fn_source`；`open` 提速约 4 倍；Windows 1.x/2.x 双轨判定 |\n| 0.9.16 | 2026-08-27 | 长页面截图全面修复；源码开源 |\n| 0.9.15 | 2026-08-20 | 适配开发者工具 2.x（Electron）；修复 CDP 采集自 0.9.0 起恒为 0 条 |\n| 0.9.14 | 2026-08-20 | `wechat_file` 路径口径统一；`cdp_port` 透传修复 |\n| 0.9.13 | 2026-08-18 | `--version` 早退；文档核对修复 |\n\n完整逐版本说明见 [CHANGELOG.md](./CHANGELOG.md)。\n\n---\n\n## 参考\n\n- [微信开发者工具 CLI](https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html) · [小程序自动化 SDK](https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/quick-start.html)\n- 许可证：MIT\n",
  "bytes": 6457,
  "sha": "f39f554cd575d6442076e943498a9d3c99e62c2137ab10499c953d6dd4a3cad6",
  "repo_slug": "watertian/wechat-devtools-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_watertian_wechat_devtools_mcp_0c6db51c/readme"
}