@weadmin/weixin-minigame-helper-mcp 0.1.22 → 0.1.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +205 -162
  2. package/SKILL.md +252 -251
  3. package/mcp/game-bundler-worker.js +1 -1
  4. package/mcp/index.js +45 -7
  5. package/media/wx-compat.js +1 -1
  6. package/package.json +3 -2
  7. package/templates/localization.html +13 -0
  8. package/templates/onboarding.html +13 -0
  9. package/templates/preview.html +13 -13
package/README.md CHANGED
@@ -1,162 +1,205 @@
1
- # @weadmin/weixin-minigame-helper-mcp
2
-
3
- WeChat Mini Game MCP Server — Preview, debug, real-device preview and publish WeChat Mini Games from any MCP-compatible AI coding assistant.
4
-
5
- ## Overview
6
-
7
- This package provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI coding assistants (such as Claude, CodeBuddy, Cursor, etc.) to preview, hot-reload, real-device preview, and publish WeChat Mini Games — all through natural language.
8
-
9
- ## Quick Start
10
-
11
- ### Use with npx (recommended)
12
-
13
- No installation needed. Configure your MCP client with:
14
-
15
- ```json
16
- {
17
- "mcpServers": {
18
- "weixin-minigame-helper": {
19
- "command": "npx",
20
- "args": [
21
- "-y",
22
- "--prefer-online",
23
- "@weadmin/weixin-minigame-helper-mcp@latest"
24
- ]
25
- }
26
- }
27
- }
28
- ```
29
-
30
- ### Global install
31
-
32
- ```bash
33
- npm install -g @weadmin/weixin-minigame-helper-mcp
34
- ```
35
-
36
- Then configure your MCP client with:
37
-
38
- ```json
39
- {
40
- "mcpServers": {
41
- "weixin-minigame-helper": {
42
- "command": "weixin-minigame-helper-mcp"
43
- }
44
- }
45
- }
46
- ```
47
-
48
- ## MCP Tools
49
-
50
- This server exposes the following tools:
51
-
52
- ### `run_game`
53
-
54
- Start or hot-reload a WeChat Mini Game preview. Idempotent — call this every time the game code is created or modified. The first call launches a local dev server and serves the game in a browser; subsequent calls re-bundle the code and refresh the open preview page automatically. The preview URL and port stay the same across calls.
55
-
56
- | Parameter | Type | Required | Description |
57
- |---|---|---|---|
58
- | `workspacePath` | string | ✅ | Absolute path to the Mini Game directory (must contain `game.js`) |
59
-
60
- **Returns:** Local preview URL and port number (stable across calls).
61
-
62
- ### `get_logs`
63
-
64
- Retrieve console log entries (log / warn / error) from the running game.
65
-
66
- | Parameter | Type | Required | Description |
67
- |---|---|---|---|
68
- | `filter` | string | ❌ | JavaScript regex pattern to filter log messages (case-insensitive) |
69
-
70
- **Returns:** Formatted log entries with timestamps and log levels.
71
-
72
- ### `capture_screenshot`
73
-
74
- Capture a screenshot of the currently running game canvas. Supports all game types: Canvas2D, WebGL (Unity, Cocos, Three.js, etc.).
75
-
76
- | Parameter | Type | Required | Description |
77
- |---|---|---|---|
78
- | `format` | string | ❌ | Image format: `"image/png"` (default) or `"image/jpeg"` |
79
- | `quality` | number | ❌ | JPEG quality 0-1 (default: 0.92). Ignored for PNG |
80
-
81
- **Requires:** Game must be running (call `run_game` first).
82
-
83
- **Returns:** Base64-encoded screenshot image of the game canvas.
84
-
85
- ### `real_device_preview`
86
-
87
- Build and upload the game to WeChat servers for real device preview. Generates a QR code that can be scanned with WeChat.
88
-
89
- | Parameter | Type | Required | Description |
90
- |---|---|---|---|
91
- | `workspacePath` | string | ✅ | Absolute path to the Mini Game directory |
92
-
93
- **Requires:** AppID and upload private key (see [Configuration](#configuration)).
94
-
95
- **Returns:** QR code displayed in the browser preview page.
96
-
97
- ### `publish`
98
-
99
- Upload the game to the WeChat platform as a development version.
100
-
101
- | Parameter | Type | Required | Description |
102
- |---|---|---|---|
103
- | `workspacePath` | string | ✅ | Absolute path to the Mini Game directory |
104
- | `version` | string | ✅ | Version number (semver, e.g. `"1.0.0"`) |
105
- | `desc` | string | ❌ | Optional release notes |
106
-
107
- **Returns:** Upload confirmation with version and AppID info.
108
-
109
- > **Note:** This uploads as a development version. To promote to experience/production, use the [WeChat MP Admin Console](https://mp.weixin.qq.com/).
110
-
111
- ## Configuration
112
-
113
- For real-device preview and publish, you need to provide:
114
-
115
- 1. **AppID** — Your WeChat Mini Game AppID
116
- 2. **Upload Private Key** — The private key file for CI uploads (download from [WeChat MP Admin Console](https://mp.weixin.qq.com/) → Development → Development Settings → Mini Program Code Upload Key)
117
-
118
- ### Option 1: Browser UI
119
-
120
- 1. Start a preview with `run_game`
121
- 2. Click the ⚙️ settings button in the browser preview page
122
- 3. Fill in your AppID and upload the private key file
123
-
124
- ### Option 2: Environment Variables
125
-
126
- ```bash
127
- export WECHAT_APPID="your_appid_here"
128
- export WECHAT_PRIVATE_KEY_PATH="/path/to/private.key"
129
- # Or provide the key content directly:
130
- export WECHAT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
131
- ```
132
-
133
- ### IP Whitelist
134
-
135
- WeChat requires your server's public IP to be whitelisted for CI uploads. Add your IP in [WeChat MP Admin Console](https://mp.weixin.qq.com/) → Development → Development Settings → IP Whitelist.
136
-
137
- > **Tip:** The preview page displays your current public IP in the top-right corner for easy copying.
138
-
139
- ## How It Works
140
-
141
- ```
142
- AI Assistant ←→ MCP Protocol (stdio) ←→ This Server ←→ Local Dev Server + miniprogram-ci
143
- ↓
144
- Browser Preview
145
- Real Device QR
146
- WeChat Upload
147
- ```
148
-
149
- 1. The MCP server starts a local Express dev server for game preview
150
- 2. Game source files are pre-bundled into a single browser-compatible IIFE and served via the local dev server
151
- 3. File changes trigger a re-bundle; the open preview page reloads automatically without changing port or URL
152
- 4. Real-device preview and publish use [miniprogram-ci](https://www.npmjs.com/package/miniprogram-ci) for WeChat platform integration
153
-
154
- ## Requirements
155
-
156
- - **Node.js** >= 16
157
- - A WeChat Mini Game project with `game.js` entry file
158
- - For real-device / publish: WeChat AppID + upload private key
159
-
160
- ## License
161
-
162
- MIT
1
+ # @weadmin/weixin-minigame-helper-mcp
2
+
3
+ Mini Game Developer Helper MCP Server — Preview, debug, real-device preview and publish WeChat Mini Games from any MCP-compatible AI coding assistant.
4
+
5
+ ## Overview
6
+
7
+ This package provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI coding assistants (such as Claude, CodeBuddy, Cursor, etc.) to preview, hot-reload, real-device preview, and publish WeChat Mini Games — all through natural language.
8
+
9
+ ## Quick Start
10
+
11
+ ### Use with npx (recommended)
12
+
13
+ No installation needed. Configure your MCP client with:
14
+
15
+ ```json
16
+ {
17
+ "mcpServers": {
18
+ "weixin-minigame-helper": {
19
+ "command": "npx",
20
+ "args": [
21
+ "-y",
22
+ "--prefer-online",
23
+ "@weadmin/weixin-minigame-helper-mcp@latest"
24
+ ]
25
+ }
26
+ }
27
+ }
28
+ ```
29
+
30
+ ### Global install
31
+
32
+ ```bash
33
+ npm install -g @weadmin/weixin-minigame-helper-mcp
34
+ ```
35
+
36
+ Then configure your MCP client with:
37
+
38
+ ```json
39
+ {
40
+ "mcpServers": {
41
+ "weixin-minigame-helper": {
42
+ "command": "weixin-minigame-helper-mcp"
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ ## MCP Tools
49
+
50
+ This server exposes the following tools:
51
+
52
+ ### `run_game`
53
+
54
+ Start or hot-reload a WeChat Mini Game preview. Idempotent — call this every time the game code is created or modified. The first call launches a local dev server and serves the game in a browser; subsequent calls re-bundle the code and refresh the open preview page automatically. The preview URL and port stay the same across calls.
55
+
56
+ | Parameter | Type | Required | Description |
57
+ |---|---|---|---|
58
+ | `workspacePath` | string | Yes | Absolute path to the Mini Game directory (must contain `game.js`) |
59
+
60
+ **Returns:** Local preview URL and port number (stable across calls).
61
+
62
+ ### `get_logs`
63
+
64
+ Retrieve console log entries (log / warn / error) from the running game.
65
+
66
+ | Parameter | Type | Required | Description |
67
+ |---|---|---|---|
68
+ | `filter` | string | No | JavaScript regex pattern to filter log messages (case-insensitive) |
69
+
70
+ **Returns:** Formatted log entries with timestamps and log levels.
71
+
72
+ ### `capture_screenshot`
73
+
74
+ Capture a screenshot of the currently running game canvas. Supports all game types: Canvas2D, WebGL (Unity, Cocos, Three.js, etc.).
75
+
76
+ | Parameter | Type | Required | Description |
77
+ |---|---|---|---|
78
+ | `format` | string | No | Image format: `"image/jpeg"` (default, smaller size) or `"image/png"` (lossless, larger) |
79
+ | `quality` | number | No | JPEG quality 0-1 (default: 0.8). Ignored for PNG |
80
+ | `output` | string | No | `"data"` (default) returns the image inline as base64; `"path"` saves it under `.weixin-minigame-helper/screenshots/` and returns the absolute file path |
81
+
82
+ **Requires:** Game must be running (call `run_game` first).
83
+
84
+ **Returns:** Base64-encoded screenshot of the game canvas (or the saved file path when `output="path"`).
85
+
86
+ ### `capture_screenshot_burst`
87
+
88
+ Start a multi-frame (burst) screenshot capture session. Frames are saved as individual files in the OS temp directory.
89
+
90
+ | Parameter | Type | Required | Description |
91
+ |---|---|---|---|
92
+ | `mode` | string | Yes | `"timed"` = auto-stop after `durationMs` (call blocks until done); `"manual"` = start and return a `sessionId` immediately |
93
+ | `fps` | number | No | Frames per second. Default 2, capped at 10 |
94
+ | `durationMs` | number | No | Capture duration for `mode="timed"`. Max 60000. Required when `mode="timed"` |
95
+ | `format` | string | No | `"image/jpeg"` (default, recommended) or `"image/png"` (much larger, slower) |
96
+ | `quality` | number | No | JPEG quality 0-1 (default: 0.8). Ignored for PNG |
97
+
98
+ **Requires:** Game must be running (call `run_game` first).
99
+
100
+ **Returns:** Absolute file paths of captured frames (in the OS temp directory).
101
+
102
+ ### `stop_screenshot_burst`
103
+
104
+ Stop an active burst session started with `capture_screenshot_burst` (`mode="manual"`) and retrieve all captured frame paths.
105
+
106
+ | Parameter | Type | Required | Description |
107
+ |---|---|---|---|
108
+ | `sessionId` | string | Yes | The `sessionId` returned by `capture_screenshot_burst` when `mode="manual"` |
109
+
110
+ **Returns:** Absolute file paths of all frames captured so far.
111
+
112
+ ### `real_device_preview`
113
+
114
+ Build and upload the game to WeChat servers for real device preview. Generates a QR code that can be scanned with WeChat.
115
+
116
+ | Parameter | Type | Required | Description |
117
+ |---|---|---|---|
118
+ | `workspacePath` | string | Yes | Absolute path to the Mini Game directory |
119
+
120
+ **Requires:** AppID and upload private key (see [Configuration](#configuration)).
121
+
122
+ **Returns:** QR code displayed in the browser preview page.
123
+
124
+ ### `publish`
125
+
126
+ Upload the game to the WeChat platform as a development version.
127
+
128
+ | Parameter | Type | Required | Description |
129
+ |---|---|---|---|
130
+ | `workspacePath` | string | Yes | Absolute path to the Mini Game directory |
131
+ | `version` | string | Yes | Version number (semver, e.g. `"1.0.0"`) |
132
+ | `desc` | string | No | Optional release notes |
133
+
134
+ **Returns:** Upload confirmation with version and AppID info.
135
+
136
+ > **Note:** This uploads as a development version. To promote to experience/production, use the [WeChat MP Admin Console](https://mp.weixin.qq.com/).
137
+
138
+ ### Onboarding workflow tools (`mp_*`)
139
+
140
+ The server also exposes a set of `mp_*` tools for the WeChat Mini Game launch/onboarding workflow (login, filling in game info, filing/ICP, qualification review, version submission and status query):
141
+
142
+ - `mp_get_onboarding` — read the current onboarding workflow state
143
+ - `mp_save_onboarding` — save onboarding workflow state (incremental deep-merge)
144
+ - `mp_sync_onboarding` — sync workflow state to the UI panel (allowSkip: barrier stop)
145
+ - `mp_advance_step` — atomically validate + mark done + focus the next step
146
+ - `mp_validate_step` — validate a step's completion requirements only
147
+ - `mp_analyze_game_info` — analyze the project code for AI-generated fields
148
+ - `mp_analyze_qualification_files` — parse qualification materials
149
+ - `mp_switch_game` / `mp_get_active_game_status` / `mp_scan_candidate_projects` — active game management
150
+ - `mp_api` — unified gateway for the 20 platform CGI actions (get_app_info, query_status, submit_record, submit_game_record, submit_version, submit_audit, rollback_version, stop_service, get_version_list, get_dev_version_list, submit_version_by_agent, get_game_intro, submit_game_intro, get_icpe_sign_summary, save_icpe_signed_file, upload_blob, download_blob, get_qc_info, submit_qc_info, get_notifications)
151
+
152
+ Each tool's parameters are described in the MCP `ListTools` response.
153
+
154
+ ## Configuration
155
+
156
+ For real-device preview and publish, you need to provide:
157
+
158
+ 1. **AppID** — Your WeChat Mini Game AppID
159
+ 2. **Upload Private Key** — The private key file for CI uploads (download from [WeChat MP Admin Console](https://mp.weixin.qq.com/) → Development → Development Settings → Mini Program Code Upload Key)
160
+
161
+ ### Option 1: Browser UI
162
+
163
+ 1. Start a preview with `run_game`
164
+ 2. Click the settings (gear) button in the browser preview page
165
+ 3. Fill in your AppID and upload the private key file
166
+
167
+ ### Option 2: Environment Variables
168
+
169
+ ```bash
170
+ export WECHAT_APPID="your_appid_here"
171
+ export WECHAT_PRIVATE_KEY_PATH="/path/to/private.key"
172
+ # Or provide the key content directly:
173
+ export WECHAT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
174
+ ```
175
+
176
+ ### IP Whitelist
177
+
178
+ WeChat requires your server's public IP to be whitelisted for CI uploads. Add your IP in [WeChat MP Admin Console](https://mp.weixin.qq.com/) → Development → Development Settings → IP Whitelist.
179
+
180
+ > **Tip:** The preview page displays your current public IP in the top-right corner for easy copying.
181
+
182
+ ## How It Works
183
+
184
+ ```
185
+ AI Assistant ←→ MCP Protocol (stdio) ←→ This Server ←→ Local Dev Server + miniprogram-ci
186
+ ↓
187
+ Browser Preview
188
+ Real Device QR
189
+ WeChat Upload
190
+ ```
191
+
192
+ 1. The MCP server starts a local Express dev server for game preview
193
+ 2. Game source files are pre-bundled into a single browser-compatible IIFE and served via the local dev server
194
+ 3. File changes trigger a re-bundle; the open preview page reloads automatically without changing port or URL
195
+ 4. Real-device preview and publish use [miniprogram-ci](https://www.npmjs.com/package/miniprogram-ci) for WeChat platform integration
196
+
197
+ ## Requirements
198
+
199
+ - **Node.js** >= 16
200
+ - A WeChat Mini Game project with `game.js` entry file
201
+ - For real-device / publish: WeChat AppID + upload private key
202
+
203
+ ## License
204
+
205
+ MIT