Content
<div align="center">
<img src="docs/logo.svg" width="84" alt="wx-mp-mcp logo">
# Tool List
**Reverse Engineering of WeChat Mini Programs**
Transforming the signature and encrypted parameters of mini program interfaces into a **local Node.js script** that can run directly.
<br>
</div>
> A MCP (Model Context Protocol) Server, integrated into your AI coding tools (Claude Code / Cursor / Codex), enables AI to automatically complete WeChat mini program **decryption → packet capture → signature analysis → local reproduction**.
---
<h2><img src="docs/sec-features.svg" height="26" align="middle"> Three Core Capabilities</h2>
<table>
<tr>
<td align="center" width="33%" valign="top">
<img src="docs/icon-unpack.svg" width="60" alt="">
**Real-time Decryption**
`Mac + Windows`
Directly reads encrypted packages (`.wxapkg`) from disk and decrypts them into readable JavaScript source code. Supports main package, sub-packages, and plugins. WeChat can be closed.
</td>
<td align="center" width="33%" valign="top">
<img src="docs/icon-capture.svg" width="60" alt="">
**Packet Capture**
`mitmproxy interception`
HTTPS proxy intercepts real requests from mini programs and automatically saves them as structured samples, including URL, parameters, and `sign` signature fields.
</td>
<td align="center" width="33%" valign="top">
<img src="docs/icon-analyze.svg" width="60" alt="">
**AI Offline Analysis**
`Local Node.js black box`
AI reads JavaScript to locate signature algorithms, exhaustively deduces and reproduces the signature, and exports an independent signature script that does not rely on WeChat.
</td>
</tr>
</table>
> 🛡️ **Non-invasive**: The entire process only involves reading encrypted packages from disk, walking through proxy passive traffic capture, and running decompiled code copies in Node.js. No attachment to WeChat process, no memory modification, and no debugging port opening.
---
<h2><img src="docs/sec-flow.svg" height="26" align="middle"> Workflow</h2>
<table>
<tr>
<td align="center" width="120"><img src="docs/icon-unpack.svg" width="50"><br><b>Decryption Analysis</b><br><sub><code>mp_analyze</code></sub></td>
<td align="center"><b>→</b></td>
<td align="center" width="120"><img src="docs/icon-capture.svg" width="50"><br><b>Capture Real Samples</b><br><sub><code>mp_capture_*</code></sub></td>
<td align="center"><b>→</b></td>
<td align="center" width="120"><img src="docs/wf-crack.svg" width="50"><br><b>Cracking / Sandbox</b><br><sub><code>mp_sign_crack</code></sub></td>
<td align="center"><b>→</b></td>
<td align="center" width="120"><img src="docs/icon-export.svg" width="50"><br><b>Export</b><br><sub><code>mp_sandbox_export</code></sub></td>
<td align="center"><b>→</b></td>
<td align="center" width="120"><img src="docs/wf-result.svg" width="50"><br><b>Local Signature</b><br><sub><code>node signer.mjs</code></sub></td>
</tr>
</table>
For most non-obfuscated mini programs, `mp_analyze` can locate the signature and generate reproduction code in one step. For obfuscated or encrypted signatures, the **packet capture → cracking / sandbox** branch is used.
---
<h2><img src="docs/sec-start.svg" height="26" align="middle"> Quick Start</h2>
### 1. Installation
**Method 1 (Recommended)** - Tell your AI coding tool:
```
Help me install the mcp tool: wx-mp-mcp
Project address: https://github.com/WhiteNightShadow/wx-mp-mcp
```
The AI will automatically clone, install dependencies, build, and configure MCP.
**Method 2** - Manual:
```bash
git clone https://github.com/WhiteNightShadow/wx-mp-mcp.git
cd wx-mp-mcp && npm install && npm run build
```
### 2. Configure to Client
<details>
<summary><b>Cursor (.cursor/mcp.json)</b></summary>
```json
{
"mcpServers": {
"wx-mp-mcp": {
"command": "node",
"args": ["/absolute/path/wx-mp-mcp/dist/index.js"]
}
}
}
```
</details>
<details>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add wx-mp-mcp -- node /absolute/path/wx-mp-mcp/dist/index.js
```
</details>
> **Additional preparation for packet capture**: Install `mitmproxy` on your local machine (`pip install mitmproxy` or `brew install mitmproxy`), and set your mobile device's WiFi proxy to point to your local IP address and port 8080. Install the CA certificate.
### 3. Example Usage
Tell the AI to analyze the mini program:
> Analyze the interface `POST https://api.xxx.com/order/create` of the mini program `wxXXXXXXXXXXXXXXXX`, locate its `sign` signature algorithm, and export a local Node.js signature script.
After completion, run the script locally:
```bash
node signer.mjs '{"ts":"1719000000","orderId":"123"}'
# → Output sign, reproduce interface request without WeChat
```
---
<h2><img src="docs/sec-tools.svg" height="26" align="middle"> Tool List (12)</h2>
| Tool | Function |
|------|------|
| <img src="docs/icon-unpack.svg" height="18" align="middle"> **Decryption Analysis** | |
| `mp_list_apps` | List all mini programs cached on the local machine (appid / version / package count) |
| `mp_decrypt` | Decrypt and extract a single `.wxapkg` (pass appid to find the latest or pass file path) |
| `mp_analyze` | **One-click analysis**: Decrypt and decompile (main package + sub-packages + plugins) → signature/encryption location → API extraction → reproduction code generation → report (including `crackHint`: candidate keys + algorithms + parameter sequence) |
| `mp_analyze_all` | Batch analyze all cached mini programs on the local machine |
| <img src="docs/icon-capture.svg" height="18" align="middle"> **Packet Capture** | |
| `mp_capture_start` | Start mitmproxy proxy packet capture, requests are automatically saved as structured JSONL (default: 8080, filterable by URL) |
| `mp_capture_list` | View captured requests, automatically mark `sign` / `token` and other signature fields |
| `mp_capture_stop` | Stop packet capture, return file path and request count |
| `mp_capture_import` | **Import existing packet capture** → unify into JSONL (HAR / cURL / JSON body / JSONL, direct use of existing captures, no need for proxy) |
| <img src="docs/wf-crack.svg" height="18" align="middle"> **Signature Cracking** | |
| `mp_sign_crack` | Signature exhaustion: captured samples → parameter subset enumeration × algorithm (HMAC/MD5/SHA/AES/DES/3DES) → precise formula deduction and reproduction code generation (pass `report` to directly consume `mp_analyze` candidate keys + algorithms) |
| <img src="docs/icon-analyze.svg" height="18" align="middle"> **Offline Sandbox** | |
| `mp_sandbox_modules` | List all modules in the bundle, locate SDK signature module position |
| `mp_sandbox_run` | Load `app-service.js` in an offline Node.js sandbox, execute arbitrary JavaScript (directly call signature functions for verification) |
| `mp_sandbox_export` | **Export independent signature script**: track dependencies, extract minimal module subset, generate self-contained `.mjs` without relying on sandbox / bundle |
**Analysis output** (in `static/out/<appid>/`): readable source tree `app/`, report `report.json` + `REPORT.md`, reproduction code `repro.node.mjs` + `repro.python.py`, independent signature script `signer.mjs`.
---
<h2><img src="docs/sec-feedback.svg" height="26" align="middle"> Feedback / Contact</h2>
For problems, bug reports, or discussion of reverse engineering ideas, welcome to add WeChat:
> **WeChat ID: `han8888v8888`** (add friend and remark "wx-mp-mcp")
---
<h2><img src="docs/sec-changelog.svg" height="26" align="middle"> Changelog</h2>
**v0.1.2** — Sandbox general reinforcement (practical experience)
- **Realm self-consistency**: Sandbox no longer injects outer built-in, `[].push === Array.prototype.push`, JSVMP/bytecode interpreter no longer crashes.
- **Webpack lazy module loading**: Covers global jsonp and embedded `{id:fn}` two forms, only instantiates target module subtree, does not guide app.
- **Multi-bundle collaboration**: When sub-package signature SDK depends on main package runtime, `bundle_paths` are spliced and loaded once.
- **JSVMP friendly**: `runInContext(code, ms)` with timeout execution (synchronous deadlock can be interrupted), call and clear heartbeat timer; supplement `wx.getRandomValues`/`getLogManager`, `performance`/`atob`/`btoa`, configurable UA.
- **Gateway signature detection**: Identify `hmac-auth` / `x-hmac-digest` / `mtgsig` / `wsgsig` / `__NS_sig` and other signature protocols, eliminate "heavy signature but report no signature" false negatives.
- **Decryption ↔ sandbox path unification** + error cleaning (no longer spit out entire source code / command line).
**v0.1.1**
- Added `mp_capture_import`: existing packet capture (HAR / cURL / JSON body / JSONL) one-click unification, direct feeding of existing captures, no need for proxy.
- **Analyze → crack automatic bridge**: `mp_analyze` report more吐 `crackHint` (candidate keys + algorithms + parameter sequence), `mp_sign_crack` pass `report` direct consumption, reduce manual handling.
**v0.1.0**
- 11 tools complete the entire chain: **real-time decryption → mitmproxy packet capture → AI offline analysis → export local Node.js black box script**, exposed to any AI Agent through MCP.
- **Mac + Windows** cache directory automatic detection (`WXAPKG_ROOT` can be manually specified).
- **Non-invasive**: disk encryption package offline decryption (V1MMWX) + passive packet capture + Node.js vm sandbox, no memory rewriting, no process injection.
- **Multi-signal signature determination**: interceptor / security SDK / signature header / response decryption joint determination, avoid "false report no signature".
---
> ⚠️ Only used for **owned / authorized** mini program security analysis and interface docking. Not for unauthorized access, bypassing others' system security mechanisms, or violating service terms.
