wechat-devtools-mcp

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

[![PyPI version](https://img.shields.io/pypi/v/wechat-devtools-mcp.svg)](https://pypi.org/project/wechat-devtools-mcp/)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue.svg)](https://modelcontextprotocol.io/docs/concepts/mcp-registry)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![English](https://img.shields.io/badge/lang-English-blue.svg)](./README_EN.md)

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

<!-- mcp-name: io.github.WaterTian/wechat-devtools-mcp -->

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

**已发布至官方 [MCP Registry](https://modelcontextprotocol.io/)**，支持跨平台（Windows / macOS）一键安装。

---

> **🌐 [English Documentation →](./README_EN.md)**

---

## 🚀 安装与快速开始

### Step 1 — 安装 MCP Server

推荐使用 [uv](https://github.com/astral-sh/uv)，它能自动处理 Python 依赖并提供隔离的执行环境。

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

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

> [!WARNING]
> **版本兼容性**：≥0.9.11 支持 mcp 1.x 与 2.x 双版本（依赖声明 `mcp[cli]>=1.9,<3`）。**≤0.9.10 与 mcp ≥2.0 不兼容**（新装会报 `ModuleNotFoundError: mcp.server.fastmcp`，见 [#9](https://github.com/WaterTian/wechat-devtools-mcp/issues/9)）--钉版用户请升级到 ≥0.9.11，或安装时追加 `--with "mcp<2"`。

> [!TIP]
> - 查看实际运行版本（≥0.9.13）：
>   ```bash
>   wechat-devtools-mcp --version    # 零依赖打印实际安装版本；uvx 复用已装环境不自拉最新，此命令可直接确认
>   uv tool list | grep wechat       # 离线确认已安装版本
>   ```
> - 升级工具：如果编辑器正在运行 MCP 服务，需先终止进程再升级：
>   ```bash
>   # Bash / CMD
>   taskkill /F /IM "wechat-devtools-mcp*" 2>/dev/null; uv tool upgrade wechat-devtools-mcp
>   ```
>   ```powershell
>   # Windows PowerShell
>   Get-Process | Where-Object { $_.ProcessName -like "*wechat-devtools*" } | Stop-Process -Force
>   uv tool upgrade wechat-devtools-mcp
>   ```
> - Agent 一键升级：
>   ```bash
>   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/<you>/Projects/mini-app` |

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

### Step 4 — 编辑器配置

<details>
<summary><b>Claude Desktop / Antigravity</b></summary>

修改 `claude_desktop_config.json` 或 `mcp_config.json`（Antigravity）：

```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"
      }
    }
  }
}
```
</details>

<details>
<summary><b>Kiro</b></summary>

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

```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"
      ]
    }
  }
}
```
</details>

<details>
<summary><b>OpenAI Codex</b></summary>

编辑 `~/.codex/config.toml`（全局）或 `.codex/config.toml`（项目级）：

```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 快速添加：

```bash
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
```
</details>

<details>
<summary><b>Cursor / VS Code (MCP Plugin)</b></summary>

在 MCP 控制台中添加新 Server：

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

> Windows 下路径中的反斜杠需要转义（`\\`）。
</details>

<details>
<summary><b>Claude Code 项目级 <code>.mcp.json</code>（仓库内开发推荐）</b></summary>

如果你用 Claude Code 在小程序仓库里开发，可以建项目级 `.mcp.json`（自动跟随仓库、对协作者生效）。

**Windows** — 仓库根目录 `.mcp.json`：

```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"
      }
    }
  }
}
```

**macOS** — 仓库根目录 `.mcp.json`：

```json
{
  "mcpServers": {
    "wechat-devtools": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["wechat-devtools-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
        "WECHAT_DEVTOOLS_CLI": "/Applications/wechatwebdevtools.app/Contents/MacOS/cli",
        "WECHAT_PROJECT_PATH": "/Users/<you>/WeChatProjects/<project>",
        "NODE_PATH": "/opt/homebrew/bin/node"
      }
    }
  }
}
```

> macOS 三个关键差异：
> - `command` 必须用绝对路径 `/opt/homebrew/bin/uvx`（Claude Code spawn 子进程时 `PATH` 不含 Homebrew）
> - `env.PATH` 必须显式注入（同时配 `npx`-based MCP 如 cloudbase / chrome-devtools 时尤其需要，否则 `npx` 的 `#!/usr/bin/env node` 找不到 Node）
> - `NODE_PATH` 推荐显式指定，作为 daemon 启动时的双保险

> 同时配置多个 MCP（cloudbase / chrome-devtools 等）时，每个 server 都按相同模式处理 `command` 绝对路径与 `env.PATH`。
</details>

<details>
<summary><b>Trae IDE（全局 <code>mcp.json</code>）</b></summary>

Trae v1.3.0+ 支持 MCP。**AI 面板 → 右上角设置 → MCP → 添加 → 手动配置**，粘贴下方 JSON 后保存。

**Windows**：

```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"
      }
    }
  }
}
```

**macOS**：

```json
{
  "mcpServers": {
    "wechat-devtools": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["wechat-devtools-mcp"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
        "WECHAT_DEVTOOLS_CLI": "/Applications/wechatwebdevtools.app/Contents/MacOS/cli",
        "WECHAT_PROJECT_PATH": "/Users/<you>/WeChatProjects/<project>",
        "NODE_PATH": "/opt/homebrew/bin/node"
      }
    }
  }
}
```

直接编辑配置文件也可：
- Windows: `%APPDATA%\Trae\User\globalStorage\mcp.json`
- macOS: `~/Library/Application Support/Trae/User/globalStorage/mcp.json`

> [!IMPORTANT]
> 聊天框必须选 **「Builder with MCP」** 智能体，普通智能体不调 MCP 工具。建议同时安装 wechat-devtools Skill（Step 5），让 AI 按 SOP 顺序调用。
</details>

### Step 5 — 安装 Skill（必须）

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

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

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

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

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

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

```bash
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](https://github.com/TencentCloudBase/CloudBase-AI-ToolKit)（`manageFunctions` / `readNoSqlDatabaseContent` 等），功能更完整且无 IDE 依赖。`wechat_cloud` 自 v0.9.5 起已禁用。
>
> 完整工具参数说明请参阅 **[MCP_DOC.md](./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 消耗
- **完整参数参考** — 每个 ac