# @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",
        "--prefer-online",
        "@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
