wechat-dev-mcp AGENTS.md

AI Agent Workflow Guide for WeChat DevTools MCP

This guide helps AI agents (Claude, Cursor, Windsurf) effectively use the WeChat DevTools MCP server.

The server supports two project types, auto-detected from project.config.json:

• compileType: "miniprogram" → mini-program (pages + DOM)
• compileType: "game" → mini-game (canvas, no pages/DOM)

Getting Started

Step 1: Establish Connection

// Use 'launch' to open a project (auto-detects type):
{
  "name": "launch",
  "arguments": {
    "projectPath": "/absolute/path/to/your/project",
    "cdpEndpoint": "ws://127.0.0.1:9421/<id>"   // optional, mini-game deep debug
  }
}

// Or 'connect' to attach to an already running DevTools:
{
  "name": "connect",
  "arguments": {
    "wsEndpoint": "ws://localhost:9420",
    "projectPath": "/absolute/path/to/your/project"
  }
}

Step 2: Wait for Readiness

After launching:

• Mini-program: use wait_ready or check_health until compilationStatus: "ready".
• Mini-game: readiness is detected via GameGlobal runtime liveness (NOT pages). check_health shows compilationStatus: "game_running" and projectType: "game".

Step 3: Detect Project Type

Always check projectType from check_health (or get_project_type) before choosing tools:

{ "name": "check_health" }
// Response includes: connected, projectType, engineType, pageReady, cdpConnected, tips

• projectType: "program" → use page/DOM tools.
• projectType: "game" → use evaluate, call_wx_method, game_*, game_touch, screenshot.

Tool masking: ListTools auto-hides mini-program-only tools (navigate, get_element, tap_element, …) when connected to a mini-game, and hides mini-game-only tools when connected to a mini-program. You won't see irrelevant tools.

For Mini-Programs (projectType: "program")

Use: get_page_data, get_element, tap_element, navigate_to, etc.

For Mini-Games (projectType: "game")

Use: evaluate, call_wx_method, game_get_info, game_touch, game_canvas_screenshot, game_get_fps, game_webgl_debug, game_get_network_logs, game_export_vconsole, screenshot. Avoid: get_page_data, get_element, tap_element, navigate_to — these require pages and will be rejected.