wechat-devtools-mcp

# wechat-devtools-mcp > Skill by [ara.so](https://ara.so) — Devtools Skills collection. ## Overview `wechat-devtools-mcp` wraps the WeChat Developer Tools CLI as an MCP (Model Context Protocol) server, enabling AI coding agents to control the WeChat IDE programmatically. It provides 7 aggregated tools covering the full mini program lifecycle: IDE management, build/deploy, automated testing, debugging, screenshots, and file operations. **Architecture**: Thin MCP (7 tools) + Fat Skill (SOPs, parameter references, guardrails). The Skill is **required** — without it, AI agents cannot execute standard workflows correctly. **Platform**: Cross-platform (Windows/macOS). Published to official [MCP Registry](https://modelcontextprotocol.io/). ## Installation ### 1. Install MCP Server ```bash # Install uv if not present pip install uv # Install wechat-devtools-mcp globally uv tool install wechat-devtools-mcp --force ``` **Upgrade**: ```bash # Kill running instances first taskkill /F /IM "wechat-devtools-mcp*" 2>/dev/null uv tool upgrade wechat-devtools-mcp ``` ### 2. Enable WeChat IDE Service Port **Critical**: Open WeChat Developer Tools → Settings → Security → Service Port → Enable. Verify with `wechat_ide(action='status')` — connection failure means the port is disabled. ### 3. Configure MCP Client **Claude Desktop / Antigravity** (`claude_desktop_config.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:\\Projects\\my-miniapp" } } } } ``` **macOS** (Claude Code `.mcp.json` in project root): ```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/Projects/my-miniapp", "NODE_PATH": "/opt/homebrew/bin/node" } } } } ``` **Environment Variables**: - `WECHAT_DEVTOOLS_CLI`: Absolute path to CLI (`cli.bat` on Windows, `cli` on macOS) - `WECHAT_PROJECT_PATH`: Absolute path to mini program project root - Windows: Escape backslashes (`\\`), macOS: Use forward slashes ### 4. Install Skill (Required) **Claude Code**: ```bash npx -y skills add WaterTian/wechat-devtools-mcp/.agents/skills/wechat-devtools ``` **Other clients** (place in `.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 ``` Result: ``` project/ └── .agents/skills/ └── wechat-devtools/ ├── SKILL.md # Main SOPs + capability map └── references/ └── tool_reference.md # Full API parameter docs ``` ## Core Tools ### 1. `wechat_ide` — IDE Lifecycle **Actions**: `open`, `login`, `is_login`, `close`, `quit`, `status` ```python # Open IDE and load project wechat_ide(action='open') # Check login status wechat_ide(action='is_login') # Get IDE connection status + MCP version wechat_ide(action='status') # Close project (keeps IDE running) wechat_ide(action='close') # Quit IDE entirely wechat_ide(action='quit') ``` **Key patterns**: - Always call `status` first to verify IDE connectivity - `open` is idempotent — won't fail if already open - Use `close` between test sessions, `quit` only when necessary ### 2. `wechat_build` — Build & Deploy **Actions**: `compile`, `preview`, `upload`, `build_npm`, `cache_clean` ```python # Full compilation wechat_build(action='compile') # Generate preview QR code result = wechat_build( action='preview', extra_args={ 'qr_format': 'terminal', # or 'image', 'base64' 'qr_output': '/tmp/qr.png', 'compile_condition': '{"pathName":"pages/index/index"}' } ) # Upload to WeChat backend (production) wechat_build( action='upload', extra_args={ 'version': '1.0.0', 'desc': 'Initial release' } ) # Build npm dependencies wechat_build(action='build_npm') # Clean cache before rebuild wechat_build(action='cache_clean') ``` **QR formats**: - `terminal`: ASCII art in console - `image`: Save to `qr_output` path - `base64`: Data URI string ### 3. `wechat_automator` — Automated Testing **Actions**: `start`, `tap`, `input`, `element_info`, `set_data`, `call_method`, `call_wx`, `mock_wx`, `evaluate`, `page_stack`, `page_data`, `system_info`, `storage` ```python # Start automation session wechat_automator(action='start') # Tap element by selector wechat_automator( action='tap', extra_args={ 'selector': '.login-btn', 'wait_for': 2000 # Wait 2s after tap } ) # Input text wechat_automator( action='input', extra_args={ 'selector': 'input.username', 'text': 'testuser' } ) # Get element properties wechat_automator( action='element_info', extra_args={'selector': '.status-text'} ) # Mock WeChat API wechat_automator( action='mock_wx', extra_args={ 'api': 'request', 'result': 'success', 'data': '{"code": 200, "data": {"user": "mock"}}' } ) # Get page data wechat_automator(action='page_data') # Execute JavaScript wechat_automator( action='evaluate', extra_args={'code': 'getCurrentPages()[0].data.userInfo'} ) ``` **Selector syntax**: - `.class-name` — Class selector - `#id` — ID selector - `view.item[data-id="123"]` — Attribute selector - Use `>>>` for shadow DOM: `custom-component >>> .inner-element` ### 4. `wechat_inspector` — Runtime Logs **Actions**: `console`, `cdp` ```python # Capture console logs (10 seconds) logs = wechat_inspector( action='console', extra_args={'duration': 10} ) # Capture Chrome DevTools Protocol events cdp_logs = wechat_inspector( action='cdp', extra_args={ 'duration': 5, 'events': ['Network.requestWillBeSent', 'Runtime.consoleAPICalled'] } ) ``` **Use cases**: - Detect runtime errors before they crash - Monitor network requests during user flow - Capture console.log/warn/error for debugging ### 5. `wechat_screenshot` — Visual Testing ```python # Screenshot current page wechat_screenshot(extra_args={'full_page': True}) # Screenshot specific element wechat_screenshot(extra_args={ 'selector': '.product-list', 'full_page': False }) ``` Returns base64-encoded PNG. For long pages, automatically stitches scrolling captures. ### 6. `wechat_navigate` — Navigation + Log Capture ```python # Navigate to page and capture CDP logs wechat_navigate(extra_args={ 'page': 'pages/detail/detail', 'query': 'id=123', 'log_duration': 3 }) ``` Combines `wx.navigateTo()` + `wechat_inspector(cdp)` in one call. ### 7. `wechat_file` — Project Introspection **Actions**: `project_info`, `list_pages`, `read_page`, `read_file` ```python # Get project.config.json wechat_file(action='project_info') # List all pages in app.json wechat_file(action='list_pages') # Read page source (WXML + WXSS + JS + JSON) wechat_file( action='read_page', extra_args={'page_path': 'pages/index/index'} ) # Read arbitrary file wechat_file( action='read_file', extra_args={'file_path': 'utils/request.js'} ) ``` ## Standard Operating Procedures (SOPs) ### SOP A: Initial Setup Verification 1. `wechat_ide(status)` — Verify IDE connectivity 2. `wechat_file(project_info)` — Confirm project loaded 3. `wechat_ide(is_login)` — Check login status 4. If not logged in: `wechat_ide(login)` and wait for user scan ### SOP B: UI Debugging Workflow 1. `wechat_automator(start)` — Begin session 2. `wechat_navigate(page='target/page', log_duration=3)` 3. `wechat_screenshot(full_page=True)` — Capture UI state 4. `wechat_inspector(console, duration=5)` — Check for errors 5. `wechat_automator(page_data)` — Inspect data bindings ### SOP C: Error Investigation 1. `wechat_inspector(console, duration=10)` — Capture logs 2. `wechat_automator(page_stack)` — Check navigation state 3. `wechat_file(read_page, page_path=<current>)` — Review source 4. `wechat_automator(evaluate, code='getApp().globalData')` — Check global state ### SOP D: Full Page Health Check ```python pages = wechat_file(action='list_pages') for page in pages['pages']: wechat_navigate(extra_args={'page': page, 'log_duration': 2}) logs = wechat_inspector(action='console', extra_args={'duration': 2}) if 'error' in logs.lower(): print(f"❌ {page}: {logs}") else: print(f"✅ {page}: OK") ``` ### SOP E: Mock-Based Integration Test 1. `wechat_automator(start)` 2. `wechat_automator(mock_wx, api='request', result='success', data=<mock_json>)` 3. `wechat_automator(tap, selector='.trigger-request-btn')` 4. `wechat_inspector(console, duration=3)` — Verify mock response handling 5. `wechat_automator(page_data)` — Check UI updated correctly ### SOP F: Deployment Workflow 1. `wechat_build(cache_clean)` — Fresh build 2. `wechat_build(compile)` — Check for errors 3. If errors: Stop and report 4. `wechat_build(preview)` — Generate test QR 5. User scans and validates 6. `wechat_build(upload, version=<semver>, desc=<changelog>)` ### SOP G: Page Parameter Discovery ```python # Find page query params from source source = wechat_file(action='read_page', extra_args={'page_path': 'pages/detail/detail'}) # Parse onLoad(options) in JS file # Extract options keys: id, type, etc. ``` ## Configuration Patterns ### Multi-Project Setup For multiple mini programs, create project-specific `.mcp.json`: ```json { "mcpServers": { "wechat-shop": {