wmpf-mcp

wmpf-mcp is a dependency-free MCP stdio server for AI-assisted debugging of Windows WeChat Mini Programs through WMPFDebugger.

It connects to the CDP WebSocket exposed by WMPFDebugger, normally ws://127.0.0.1:62000, and exposes MCP tools for JavaScript evaluation, script inspection, breakpoints, debugger control, and network inspection.

Requirements

• Windows WeChat and WMPFDebugger running successfully.

• Node.js >=22 for the built-in WebSocket implementation.

• A mini program that you own or are authorized to inspect.

Quick Start

node .\src\server.js

Use a different local WebSocket URL with either option:

node .\src\server.js --ws ws://127.0.0.1:62000
$env:WMPF_CDP_WS="ws://127.0.0.1:62000"
node .\src\server.js

MCP Client Config

{
  "mcpServers": {
    "wmpf": {
      "command": "node",
      "args": [
        "C:\\path\\to\\wmpf-mcp\\src\\server.js"
      ],
      "env": {
        "WMPF_CDP_WS": "ws://127.0.0.1:62000"
      }
    }
  }
}

Tools

• connect: Connect to the WMPFDebugger CDP WebSocket.

• status: Show connection, cache, pause, and CDP domain status.

• runtime_evaluate: Evaluate JavaScript through Runtime.evaluate.

• cdp_call: Call a raw Chrome DevTools Protocol method.

• list_scripts: List scripts observed from Debugger.scriptParsed.

• get_script_source: Read source for a CDP scriptId.

• search_scripts: Search loaded script sources by text or regular expression.

• set_breakpoint_by_url: Set a breakpoint using a URL regex.

• debugger_control: Pause, resume, step over, step into, or step out.

• list_network_requests: List cached requests with sensitive data redacted by default.

• get_response_body: Read a response body by CDP requestId.

• last_events: Show recent raw CDP events for compatibility diagnostics.

Example network query:

{
  "limit": 100,
  "include_sensitive": false
}

Set include_sensitive to true only when the debugging task requires original authorization headers, cookies, or request bodies.

Security

• WebSocket connections are restricted to localhost, 127.0.0.1, and ::1 by default.

• Set WMPF_ALLOW_REMOTE=1 only when you intentionally need a remote debugger.

• WebSocket URLs containing embedded credentials are rejected.

• Authorization headers, cookies, and request bodies are redacted by default.

• runtime_evaluate and cdp_call can execute code or mutate debugger state.

Configuration

Invalid numeric configuration values fall back to their safe defaults.

Development

npm run check
npm test

WMPFDebugger may not implement every CDP method exactly like a full Chrome browser. Use cdp_call and last_events to diagnose protocol compatibility issues.

AI 调试优化

v0.2.0 增加了一组更适合 AI 直接操作的小程序调试工具：

断点 / 单步

• search_scripts: 在已加载脚本里按文本或正则搜索，可返回上下文。

• set_breakpoint_on_text: 搜索匹配文本并直接打断点，适合让 AI 用函数名、接口名、关键变量名定位。

• set_breakpoint_by_script_id: 已知 scriptId 和行号时精确打断点。

• list_breakpoints / remove_breakpoint: 查看和移除本次 MCP 会话设置的断点。

• paused_info: 断住后获取命中断点、调用栈和 callFrameId。

• evaluate_on_callframe: 在暂停栈帧里执行表达式，查看局部变量、参数、this 等。

推荐流程：

{ "query": "functionNameOrApiKeyword", "filter": "appservice", "context_lines": 2 }

{ "query": "functionNameOrApiKeyword", "filter": "appservice", "occurrence": 1 }

断住后：

{ "include_scopes": true }

{ "call_frame_id": "CALL_FRAME_ID", "expression": "JSON.stringify({ arg0, thisKeys: Object.keys(this || {}) })" }

抓包 / HAR

• network_capture_control: 开始、停止或清空网络抓包缓存。

• list_network_requests: 按 URL、正则、method、status、type、mime、failed 过滤请求。

• get_request_detail: 查看单个请求，可同时拉响应体。

• export_network_har: 导出当前缓存为 HAR-like JSON，方便交给 AI 汇总接口行为。

推荐流程：

{ "action": "start", "clear": true, "disable_cache": true }

复现小程序操作后：

{ "url_filter": "/api/", "limit": 100, "include_sensitive": false }

再查看单条响应：

{ "request_id": "REQUEST_ID", "include_body": true, "include_sensitive": false }