wechat-devtools-mcp 0.1.0__tar.gz

wechat_devtools_mcp-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist/
+build/
+*.egg-info/
+.venv/
+.env
+.idea/
+.vscode/mcp.json
+.cursor/mcp.json

wechat_devtools_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WaterTian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wechat_devtools_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: wechat-devtools-mcp
+Version: 0.1.0
+Summary: MCP Server for WeChat DevTools CLI - 微信开发者工具 MCP 服务
+Project-URL: Homepage, https://github.com/WaterTian/wechat-devtools
+Project-URL: Repository, https://github.com/WaterTian/wechat-devtools.git
+Project-URL: Issues, https://github.com/WaterTian/wechat-devtools/issues
+Author-email: WaterTian <changewater@qq.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# 微信开发者工具 MCP Server
+
+[![PyPI version](https://img.shields.io/pypi/v/wechat-devtools-mcp.svg)](https://pypi.org/project/wechat-devtools-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> 将微信开发者工具 CLI 封装为 [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) 服务，使编辑器中的 AI 能够直接调用微信 CLI 命令，实现小程序**开发、测试、调试、自动化**全流程闭环。
+
+<!-- mcp-name: io.github.WaterTian/wechat-devtools -->
+
+参考文档：
+
+- [微信开发者工具 CLI](https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html)
+- [小程序自动化 SDK](https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/quick-start.html)
+
+---
+
+## 能力概览
+
+### v4.0 — 自动化交互
+
+| 能力 | 说明 |
+|------|------|
+| **点击 UI 元素** | 通过 CSS 选择器模拟 `tap` 点击任意元素 |
+| **表单输入** | 向 `input` / `textarea` 输入文本内容 |
+| **修改页面 Data** | 动态 `setData` 热更新 UI，免编译 |
+| **调用页面方法** | 远程触发 `onPullDownRefresh` 等页面方法 |
+| **获取元素详情** | 读取元素 text / wxml / style / size / offset |
+| **Mock wx API** | 覆盖 `showModal`、`chooseLocation` 等系统调用返回值 |
+| **调用 wx API** | 直接执行 `wx.setNavigationBarTitle` 等接口 |
+| **页面导航栈** | 查看完整的页面栈信息 |
+
+### v3.x — 实时调试
+>
+> 💡 **核心建议**：在排查问题和采集日志时，**强烈建议直接使用 `wechat_get_cdp_logs`获取 CDP 高清日志**。
+
+| 能力 | 说明 |
+|------|------|
+| **CDP 高清日志** | 🆕 **[推荐]** 捕获底层 WXML 警告、网络报错、系统事件和完整堆栈 |
+| **Console 日志** | 实时捕获页面层级 `console.log/warn/error` 输出 |
+| **异常监控** | 监听 JS 异常（含完整调用栈） |
+| **持久连接** | 自动化端口一次开启常驻，多工具顺序调用无需重连 |
+
+---
+
+## 安装与配置
+
+### 1. 全局安装 (推荐)
+
+使用 `pip` 即可直接安装：
+
+```bash
+pip install wechat-devtools-mcp
+```
+
+或者使用 `uvx` 直接运行（无需安装）：
+
+```bash
+uvx wechat-devtools-mcp
+```
+
+### 2. Node.js 依赖 (自动化功能必需)
+
+部分高级调试功能涉及 `miniprogram-automator`，安装包后需在对应目录下初始化 Node.js 环境：
+
+```bash
+# 进入包安装目录下的 scripts 文件夹执行
+npm install
+```
+
+### 3. 编辑器配置
+
+#### VS Code / Cursor / Claude Desktop
+
+在 MCP 配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "wechat-devtools": {
+      "command": "wechat-devtools-mcp",
+      "env": {
+        "WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat",
+        "WECHAT_PROJECT_PATH": "D:\\path\\to\\your\\miniprogram"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 环境变量说明
+
+| 变量名 | 说明 | 默认值 | 必填 |
+|--------|------|--------|------|
+| `WECHAT_DEVTOOLS_CLI` | 微信开发者工具 CLI 路径 | 无 | **是** |
+| `WECHAT_PROJECT_PATH` | 默认小程序项目绝对路径 | 无 | **是** |
+| `WECHAT_CLI_TIMEOUT` | CLI 命令超时时间（秒） | `60` | 否 |
+| `NODE_PATH` | Node.js 可执行文件路径 | `node` | 否 |
+
+---
+
+## AI 开发工作流指南
+
+1. **理解上下文**: `wechat_project_info` + `wechat_read_page`
+2. **执行修改**: (编写代码) -> `wechat_compile_check` (检查编译)
+3. **效果预览**: `wechat_preview_page`
+4. **自动化巡检**: `wechat_auto` -> `wechat_capture_screenshot` -> `wechat_get_cdp_logs`
+
+---
+
+## 目录结构 (源码)
+
+```
+wechat-devtools-mcp/
+├── pyproject.toml             # Python 项目定义
+├── server.json                # MCP Registry 元数据
+├── LICENSE                    # MIT 许可证
+├── src/
+│   └── wechat_devtools_mcp/
+│       ├── server.py          # MCP Server 主入口
+│       └── scripts/           # Node.js 辅助脚本
+```
+
+## 许可证
+
+MIT

wechat_devtools_mcp-0.1.0/README.md

@@ -0,0 +1,127 @@
+# 微信开发者工具 MCP Server
+
+[![PyPI version](https://img.shields.io/pypi/v/wechat-devtools-mcp.svg)](https://pypi.org/project/wechat-devtools-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> 将微信开发者工具 CLI 封装为 [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) 服务，使编辑器中的 AI 能够直接调用微信 CLI 命令，实现小程序**开发、测试、调试、自动化**全流程闭环。
+
+<!-- mcp-name: io.github.WaterTian/wechat-devtools -->
+
+参考文档：
+
+- [微信开发者工具 CLI](https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html)
+- [小程序自动化 SDK](https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/quick-start.html)
+
+---
+
+## 能力概览
+
+### v4.0 — 自动化交互
+
+| 能力 | 说明 |
+|------|------|
+| **点击 UI 元素** | 通过 CSS 选择器模拟 `tap` 点击任意元素 |
+| **表单输入** | 向 `input` / `textarea` 输入文本内容 |
+| **修改页面 Data** | 动态 `setData` 热更新 UI，免编译 |
+| **调用页面方法** | 远程触发 `onPullDownRefresh` 等页面方法 |
+| **获取元素详情** | 读取元素 text / wxml / style / size / offset |
+| **Mock wx API** | 覆盖 `showModal`、`chooseLocation` 等系统调用返回值 |
+| **调用 wx API** | 直接执行 `wx.setNavigationBarTitle` 等接口 |
+| **页面导航栈** | 查看完整的页面栈信息 |
+
+### v3.x — 实时调试
+>
+> 💡 **核心建议**：在排查问题和采集日志时，**强烈建议直接使用 `wechat_get_cdp_logs`获取 CDP 高清日志**。
+
+| 能力 | 说明 |
+|------|------|
+| **CDP 高清日志** | 🆕 **[推荐]** 捕获底层 WXML 警告、网络报错、系统事件和完整堆栈 |
+| **Console 日志** | 实时捕获页面层级 `console.log/warn/error` 输出 |
+| **异常监控** | 监听 JS 异常（含完整调用栈） |
+| **持久连接** | 自动化端口一次开启常驻，多工具顺序调用无需重连 |
+
+---
+
+## 安装与配置
+
+### 1. 全局安装 (推荐)
+
+使用 `pip` 即可直接安装：
+
+```bash
+pip install wechat-devtools-mcp
+```
+
+或者使用 `uvx` 直接运行（无需安装）：
+
+```bash
+uvx wechat-devtools-mcp
+```
+
+### 2. Node.js 依赖 (自动化功能必需)
+
+部分高级调试功能涉及 `miniprogram-automator`，安装包后需在对应目录下初始化 Node.js 环境：
+
+```bash
+# 进入包安装目录下的 scripts 文件夹执行
+npm install
+```
+
+### 3. 编辑器配置
+
+#### VS Code / Cursor / Claude Desktop
+
+在 MCP 配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "wechat-devtools": {
+      "command": "wechat-devtools-mcp",
+      "env": {
+        "WECHAT_DEVTOOLS_CLI": "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat",
+        "WECHAT_PROJECT_PATH": "D:\\path\\to\\your\\miniprogram"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 环境变量说明
+
+| 变量名 | 说明 | 默认值 | 必填 |
+|--------|------|--------|------|
+| `WECHAT_DEVTOOLS_CLI` | 微信开发者工具 CLI 路径 | 无 | **是** |
+| `WECHAT_PROJECT_PATH` | 默认小程序项目绝对路径 | 无 | **是** |
+| `WECHAT_CLI_TIMEOUT` | CLI 命令超时时间（秒） | `60` | 否 |
+| `NODE_PATH` | Node.js 可执行文件路径 | `node` | 否 |
+
+---
+
+## AI 开发工作流指南
+
+1. **理解上下文**: `wechat_project_info` + `wechat_read_page`
+2. **执行修改**: (编写代码) -> `wechat_compile_check` (检查编译)
+3. **效果预览**: `wechat_preview_page`
+4. **自动化巡检**: `wechat_auto` -> `wechat_capture_screenshot` -> `wechat_get_cdp_logs`
+
+---
+
+## 目录结构 (源码)
+
+```
+wechat-devtools-mcp/
+├── pyproject.toml             # Python 项目定义
+├── server.json                # MCP Registry 元数据
+├── LICENSE                    # MIT 许可证
+├── src/
+│   └── wechat_devtools_mcp/
+│       ├── server.py          # MCP Server 主入口
+│       └── scripts/           # Node.js 辅助脚本
+```
+
+## 许可证
+
+MIT

wechat_devtools_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "wechat-devtools-mcp"
+version = "0.1.0"
+description = "MCP Server for WeChat DevTools CLI - 微信开发者工具 MCP 服务"
+readme = "README.md"
+authors = [
+    { name = "WaterTian", email = "changewater@qq.com" }
+]
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "mcp[cli]",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/WaterTian/wechat-devtools"
+Repository = "https://github.com/WaterTian/wechat-devtools.git"
+Issues = "https://github.com/WaterTian/wechat-devtools/issues"
+
+[project.scripts]
+wechat-devtools-mcp = "wechat_devtools_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wechat_devtools_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src/wechat_devtools_mcp",
+    "/README.md",
+    "LICENSE",
+]

wechat_devtools_mcp-0.1.0/src/wechat_devtools_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

wechat_devtools_mcp-0.1.0/src/wechat_devtools_mcp/scripts/automation.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * automation.js
+ * 统一的自动化操作脚本，支持 UI 交互、页面状态修改、wx API 调用等。
+ *
+ * 用法：
+ *   node automation.js --port <端口> --action <操作> [其他参数]
+ *
+ * 支持的 action：
+ *   setData       --data <JSON>                  设置页面 Data
+ *   callMethod    --method <方法名> [--args <JSON>]  调用页面方法
+ *   tap           --selector <CSS选择器>           点击元素
+ *   elementInfo   --selector <CSS选择器> [--prop <属性>]  获取元素信息
+ *   input         --selector <CSS选择器> --value <值>     输入内容
+ *   mockWx        --method <wx方法> --result <JSON>       Mock wx API
+ *   callWx        --method <wx方法> [--args <JSON>]       调用 wx API
+ *   pageStack                                             获取页面栈
+ */
+
+'use strict';
+
+const automator = require('miniprogram-automator');
+
+/**
+ * 解析命令行参数
+ */
+function parseArgs(argv) {
+    const args = { port: 9420, action: '' };
+    for (let i = 2; i < argv.length; i++) {
+        switch (argv[i]) {
+            case '--port': args.port = parseInt(argv[++i], 10); break;
+            case '--action': args.action = argv[++i]; break;
+            case '--selector': args.selector = argv[++i]; break;
+            case '--data': args.data = argv[++i]; break;
+            case '--method': args.method = argv[++i]; break;
+            case '--args': args.args = argv[++i]; break;
+            case '--value': args.value = argv[++i]; break;
+            case '--result': args.result = argv[++i]; break;
+            case '--prop': args.prop = argv[++i]; break;
+        }
+    }
+    return args;
+}
+
+/**
+ * 安全解析 JSON 字符串
+ */
+function safeParseJson(str, fallback) {
+    if (!str) return fallback;
+    try { return JSON.parse(str); } catch (e) { return fallback; }
+}
+
+async function main() {
+    const args = parseArgs(process.argv);
+    const { port, action } = args;
+
+    let miniProgram = null;
+
+    try {
+        miniProgram = await automator.connect({
+            wsEndpoint: `ws://localhost:${port}`,
+        });
+
+        let result = { success: true, action };
+
+        switch (action) {
+
+            // ── 设置页面 Data ──
+            case 'setData': {
+                const data = safeParseJson(args.data, null);
+                if (!data) throw new Error('缺失 --data 参数或 JSON 格式错误');
+                const page = await miniProgram.currentPage();
+                await page.setData(data);
+                result.path = page.path;
+                result.updatedKeys = Object.keys(data);
+                break;
+            }
+
+            // ── 调用页面方法 ──
+            case 'callMethod': {
+                if (!args.method) throw new Error('缺失 --method 参数');
+                const page = await miniProgram.currentPage();
+                const methodArgs = safeParseJson(args.args, []);
+                const callResult = await page.callMethod(args.method, ...methodArgs);
+                result.path = page.path;
+                result.method = args.method;
+                result.returnValue = callResult;
+                break;
+            }
+
+            // ── 点击元素 ──
+            case 'tap': {
+                if (!args.selector) throw new Error('缺失 --selector 参数');
+                const page = await miniProgram.currentPage();
+                const el = await page.$(args.selector);
+                if (!el) throw new Error(`未找到元素: ${args.selector}`);
+                await el.tap();
+                result.selector = args.selector;
+                result.tapped = true;
+                break;
+            }
+
+            // ── 获取元素信息 ──
+            case 'elementInfo': {
+                if (!args.selector) throw new Error('缺失 --selector 参数');
+                const page = await miniProgram.currentPage();
+                const el = await page.$(args.selector);
+                if (!el) throw new Error(`未找到元素: ${args.selector}`);
+
+                const info = {
+                    tagName: el.tagName,
+                    text: await el.text(),
+                    wxml: await el.wxml(),
+                    size: await el.size(),
+                    offset: await el.offset(),
+                };
+
+                // 如果指定了具体样式属性
+                if (args.prop) {
+                    info.style = {};
+                    info.style[args.prop] = await el.style(args.prop);
+                }
+
+                result.selector = args.selector;
+                result.element = info;
+                break;
+            }
+
+            // ── 输入内容 ──
+            case 'input': {
+                if (!args.selector) throw new Error('缺失 --selector 参数');
+                if (args.value === undefined) throw new Error('缺失 --value 参数');
+                const page = await miniProgram.currentPage();
+                const el = await page.$(args.selector);
+                if (!el) throw new Error(`未找到元素: ${args.selector}`);
+                await el.input(args.value);
+                result.selector = args.selector;
+                result.inputValue = args.value;
+                break;
+            }
+
+            // ── Mock wx API ──
+            case 'mockWx': {
+                if (!args.method) throw new Error('缺失 --method 参数');
+                const mockResult = safeParseJson(args.result, null);
+                if (mockResult === null) throw new Error('缺失 --result 参数或 JSON 格式错误');
+                await miniProgram.mockWxMethod(args.method, mockResult);
+                result.method = args.method;
+                result.mocked = true;
+                break;
+            }
+
+            // ── 调用 wx API ──
+            case 'callWx': {
+                if (!args.method) throw new Error('缺失 --method 参数');
+                const wxArgs = safeParseJson(args.args, []);
+                // callWxMethod 接受展开参数
+                const wxResult = await miniProgram.callWxMethod(args.method, ...wxArgs);
+                result.method = args.method;
+                result.returnValue = wxResult;
+                break;
+            }
+
+            // ── 获取页面栈 ──
+            case 'pageStack': {
+                const stack = await miniProgram.pageStack();
+                result.pages = stack.map(p => ({ path: p.path, query: p.query }));
+                result.depth = stack.length;
+                break;
+            }
+
+            default:
+                throw new Error(`未知 action: ${action}`);
+        }
+
+        process.stdout.write(JSON.stringify(result, null, 2));
+        // 不调用 disconnect()，保持 IDE 自动化会话存活
+        process.exit(0);
+
+    } catch (err) {
+        process.stdout.write(JSON.stringify({
+            success: false,
+            action,
+            error: err.message || String(err),
+        }, null, 2));
+        // 不调用 disconnect()，进程退出时自动清理连接
+        process.exit(0);
+    }
+}
+
+main();

wechat_devtools_mcp-0.1.0/src/wechat_devtools_mcp/scripts/cdp_listener.js

@@ -0,0 +1,103 @@
+const WebSocket = require('./node_modules/ws');
+const http = require('http');
+
+async function getTargets() {
+    return new Promise((resolve, reject) => {
+        const req = http.get('http://127.0.0.1:9222/json/list', (res) => {
+            let data = '';
+            res.on('data', (chunk) => data += chunk);
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(data));
+                } catch (e) {
+                    resolve([]);
+                }
+            });
+        });
+        req.on('error', reject);
+        req.end();
+    });
+}
+
+const duration = parseInt(process.argv[2]) || 15;
+const activeConnections = new Map();
+let logs = [];
+
+function addLog(type, targetUrl, targetType, data) {
+    logs.push({
+        timestamp: new Date().toISOString(),
+        type: type,
+        url: targetUrl,
+        targetType: targetType,
+        content: data
+    });
+}
+
+async function monitorTarget(target) {
+    if (activeConnections.has(target.id)) return;
+
+    // 排除 IDE 自身的 UI 界面，采集小程序相关的所有目标
+    const isIdeUI = target.url && (target.url.startsWith('devtools://') || target.url.startsWith('chrome-extension://') || target.url === '微信开发者工具');
+    if (isIdeUI && target.type !== 'webview') return;
+
+    activeConnections.set(target.id, true);
+    process.stderr.write(`[ATTACHING] ${target.type} - ${target.url}\n`);
+
+    try {
+        const ws = new WebSocket(target.webSocketDebuggerUrl);
+
+        ws.on('open', () => {
+            ws.send(JSON.stringify({ id: 1, method: 'Console.enable' }));
+            ws.send(JSON.stringify({ id: 2, method: 'Runtime.enable' }));
+            ws.send(JSON.stringify({ id: 3, method: 'Log.enable' }));
+        });
+
+        ws.on('message', (data) => {
+            try {
+                const msg = JSON.parse(data);
+                const method = msg.method;
+                const params = msg.params;
+
+                if (!method) return;
+
+                if (method === 'Console.messageAdded') {
+                    addLog('CONSOLE', target.url, target.type, params.message);
+                }
+                else if (method === 'Runtime.consoleAPICalled') {
+                    addLog('RUNTIME_CONSOLE', target.url, target.type, {
+                        type: params.type,
+                        args: params.args.map(a => a.value || a.description || 'unserializable')
+                    });
+                }
+                else if (method === 'Runtime.exceptionThrown') {
+                    addLog('EXCEPTION', target.url, target.type, params.exceptionDetails);
+                }
+            } catch (e) { }
+        });
+
+        ws.on('close', () => activeConnections.delete(target.id));
+        ws.on('error', () => activeConnections.delete(target.id));
+    } catch (e) {
+        activeConnections.delete(target.id);
+    }
+}
+
+async function run() {
+    process.stderr.write(`Full capture monitoring for ${duration} seconds...\n`);
+
+    setTimeout(() => {
+        console.log(JSON.stringify(logs, null, 2));
+        process.exit(0);
+    }, duration * 1000);
+
+    const interval = setInterval(async () => {
+        try {
+            const targets = await getTargets();
+            for (const target of targets) {
+                await monitorTarget(target);
+            }
+        } catch (e) { }
+    }, 1000);
+}
+
+run();