# wmpf-mcp

`wmpf-mcp` is a dependency-free MCP stdio server for AI-assisted debugging of Windows WeChat Mini Programs through [WMPFDebugger](https://github.com/evi0s/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

```powershell
node .\src\server.js
```

Use a different local WebSocket URL with either option:

```powershell
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

```json
{
  "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:

```json
{
  "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

```powershell
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 等。

推荐流程：

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

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

断住后：

```json
{ "include_scopes": true }
```

```json
{ "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 汇总接口行为。

推荐流程：

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

复现小程序操作后：

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

再查看单条响应：

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