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

Variable	Default	Description
WMPF_CDP_WS	ws://127.0.0.1:62000	Default debugger WebSocket URL.
WMPF_CDP_TIMEOUT_MS	10000	CDP connection and request timeout.
WMPF_MAX_SCRIPT_CACHE	2000	Maximum cached script metadata entries.
WMPF_MAX_NETWORK_CACHE	1000	Maximum cached network entries.
WMPF_MAX_EVENT_CACHE	200	Maximum recent CDP events.
WMPF_ALLOW_REMOTE	unset	Set to 1 to allow non-local WebSocket hosts.

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 }