@weadmin/weixin-minigame-helper-mcp 0.1.3

package/README.md

@@ -0,0 +1,158 @@
+# @weadmin/weixin-minigame-helper-mcp
+
+WeChat Mini Game MCP Server — Preview, debug, real-device test and publish WeChat Mini Games from any MCP-compatible AI coding assistant.
+
+## Overview
+
+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 test, and publish WeChat Mini Games — all through natural language.
+
+## Quick Start
+
+### Use with npx (recommended)
+
+No installation needed. Configure your MCP client with:
+
+```json
+{
+  "mcpServers": {
+    "weixin-minigame-helper": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@weadmin/weixin-minigame-helper-mcp@latest"
+      ]
+    }
+  }
+}
+```
+
+### Global install
+
+```bash
+npm install -g @weadmin/weixin-minigame-helper-mcp
+```
+
+Then configure your MCP client with:
+
+```json
+{
+  "mcpServers": {
+    "weixin-minigame-helper": {
+      "command": "weixin-minigame-helper-mcp"
+    }
+  }
+}
+```
+
+## MCP Tools
+
+This server exposes the following tools:
+
+### `run_game`
+
+Start a WeChat Mini Game preview. Launches a local dev server and serves the game in a browser.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `workspacePath` | string | ✅ | Absolute path to the Mini Game directory (must contain `game.js`) |
+
+**Returns:** Local preview URL and port number.
+
+### `reload_game`
+
+Hot-reload the running game preview. If the game is not running yet, it starts automatically.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `workspacePath` | string | Only if game not running | Absolute path to the Mini Game directory |
+
+**Returns:** Confirmation with the preview URL.
+
+### `get_logs`
+
+Retrieve console log entries (log / warn / error) from the running game.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `filter` | string | ❌ | JavaScript regex pattern to filter log messages (case-insensitive) |
+
+**Returns:** Formatted log entries with timestamps and log levels.
+
+### `real_device_preview`
+
+Build and upload the game to WeChat servers for real device testing. Generates a QR code that can be scanned with WeChat.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `workspacePath` | string | ✅ | Absolute path to the Mini Game directory |
+
+**Requires:** AppID and upload private key (see [Configuration](#configuration)).
+
+**Returns:** QR code displayed in the browser preview page.
+
+### `publish`
+
+Upload the game to the WeChat platform as a development version.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `workspacePath` | string | ✅ | Absolute path to the Mini Game directory |
+| `version` | string | ✅ | Version number (semver, e.g. `"1.0.0"`) |
+| `desc` | string | ❌ | Optional release notes |
+
+**Returns:** Upload confirmation with version and AppID info.
+
+> **Note:** This uploads as a development version. To promote to experience/production, use the [WeChat MP Admin Console](https://mp.weixin.qq.com/).
+
+## Configuration
+
+For real-device preview and publish, you need to provide:
+
+1. **AppID** — Your WeChat Mini Game AppID
+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)
+
+### Option 1: Browser UI
+
+1. Start a preview with `run_game`
+2. Click the ⚙️ settings button in the browser preview page
+3. Fill in your AppID and upload the private key file
+
+### Option 2: Environment Variables
+
+```bash
+export WECHAT_APPID="your_appid_here"
+export WECHAT_PRIVATE_KEY_PATH="/path/to/private.key"
+# Or provide the key content directly:
+export WECHAT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
+```
+
+### IP Whitelist
+
+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.
+
+> **Tip:** The preview page displays your current public IP in the top-right corner for easy copying.
+
+## How It Works
+
+```
+AI Assistant ←→ MCP Protocol (stdio) ←→ This Server ←→ Local Dev Server + miniprogram-ci
+                                                              ↓
+                                                        Browser Preview
+                                                        Real Device QR
+                                                        WeChat Upload
+```
+
+1. The MCP server starts a local Express dev server for game preview
+2. Game source files are compiled (ES modules → WeChat-compatible JS) and served in browser
+3. File changes are watched via chokidar for hot-reload
+4. Real-device preview and publish use [miniprogram-ci](https://www.npmjs.com/package/miniprogram-ci) for WeChat platform integration
+
+## Requirements
+
+- **Node.js** >= 16
+- A WeChat Mini Game project with `game.js` entry file
+- For real-device / publish: WeChat AppID + upload private key
+
+## License
+
+MIT