Content
# harmony-mcp
[](https://www.npmjs.com/package/@yujiamei/harmony-mcp)
[](https://www.npmjs.com/package/@yujiamei/harmony-mcp)
[](https://github.com/xiaoxuzhu303-prog/harmony-mcp/actions/workflows/ci.yml)
[](https://registry.modelcontextprotocol.io)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
> Tell AI "Help me release a version", and then take a sip of water, it's done.
AI copilot for Mini Program developers - Understands your project, diagnoses compilation errors, and releases with one click.
**No cloud development required, no key needed, no whitelist needed. Just install and use.**
**[Quick Start](#quick-start) · [Actual Effect](#actual-effect) · [Tool List](#tool-list) · [FAQ](#faq)**
## Why Choose harmony-mcp?
| Your Pain Point | Previous Solution | Current Solution |
|----------|-----------|-----------|
| Release | Change version number → Build npm → Upload → 3 manual steps | Tell AI "Help me release a version" |
| Compilation Error | Check logs → Find files → Modify code → Recompile | Tell AI "Compilation error, help me fix" |
| Package Size Exceeded | Manual analysis → Guess which one is large → Try to split | Tell AI "Package exceeded, what to do" |
| Audit Rejected | Flip documentation → Check private API → Supplement permission statement | Tell AI "Check compliance before release" |
| Code Quality | Manual review → Find problems based on experience | Tell AI "Help me check code quality" |
**Zero configuration · No key required · No cloud development required · Supports uni-app / Taro / mpx**
### 🆕 v0.4.2 Major Update
- **Compliance detection significantly expanded** — From 15 rules to **32 audit rules**, covering high-frequency rejection scenarios such as privacy pop-ups, authorization timing, virtual payment, mandatory login, webview domain name, HTTPS forced, etc.
- **HarmonyOS device operation** — Added 8 HarmonyOS tools, supporting HAP installation/uninstallation/launching/logs/file transfer
- **Linter 14 rules** — Added wx:for no key, large page JS, timer not cleaned detection
- **Underlying unified** — CliResult structured return + Tool Annotations fully annotated
## Quick Start
> 💡 The configuration content for the three ends (Kiro / Cursor / Claude Desktop) is the same, only the file path is different.
### Kiro
Add the following to `.kiro/settings/mcp.json`:
```json
{
"mcpServers": {
"harmony-mcp": {
"command": "npx",
"args": ["-y", "@yujiamei/harmony-mcp"]
}
}
}
```
### Cursor
Add the following to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"harmony-mcp": {
"command": "npx",
"args": ["-y", "@yujiamei/harmony-mcp"]
}
}
}
```
### Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"harmony-mcp": {
"command": "npx",
"args": ["-y", "@yujiamei/harmony-mcp"]
}
}
}
```
### Global Installation (Recommended for Windows users)
If npx startup has issues (common on Windows), use global installation instead:
```bash
npm install -g @yujiamei/harmony-mcp
```
Then change the `"command"` to `"harmony-mcp"` and `"args"` to `[]` in the configuration.
> That's it. No second step.
### Prerequisites
1. **Node.js >= 18**
2. **WeChat Developer Tools** installed ([download](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html))
3. Developer tools "Settings → Security → Service port" **enabled**
> 💡 WeChat Developer Tools installed in the default path will automatically detect, no additional configuration needed.
## Actual Effect
### One-Click Release
```
You: Help me release a version, the description is fixing the shopping cart bug
AI: Reading project information... ✓
Building npm... ✓
Uploading code v1.2.4... ✓
Release completed! Go to WeChat backend to submit audit.
```
### Compilation Diagnosis → Automatic Repair
```
You: Compilation error, help me fix
AI: ✗ pages/cart/cart.js:42 - Cannot find module 'utils/pay'
Type: Module missing | Source: src/pages/cart/cart.tsx
Reading file and repairing...
✓ Recompiled successfully! 0 errors
Detected 2 runtime risks:
- setData not throttled (line 15)
- Calling wx.getLocation but no permission statement
```
### Package Size Analysis + Intelligent Sub-Packaging
```
You: Package exceeded, help me check
AI: Main package 1.8MB / 2MB ████████░░ 90%
Volume attribution: pages/detail moved to sub-package can save 430KB
Generated sub-package plan + preloadRule configuration
Want me to help you modify app.json?
```
## Core Capabilities
### Release Automation
Complete version increment + npm build + upload with one sentence. Automatically pop up confirmation box (Elicitation) before release to prevent misoperation.
### Compilation Loop
Error → Locate → Repair → Recompile, AI automatically cycles until zero errors. Supports cross-framework source code path mapping (Taro→.tsx / uni-app→.vue).
### Intelligent Volume
Package volume analysis + volume attribution (accurate to component level) + intelligent sub-package plan + sub-package volume simulation + preload configuration generation.
### Compliance Pre-Check
**32 audit rules** full scan: privacy API permissions + privacy pop-ups + authorization timing + virtual payment + mandatory login + webview domain name + page path + tabBar configuration + induced sharing + content security + HTTPS forced + sensitive information hardcoding. Distinguish 🔴 high-risk must-modify/🟡 suggested optimization, each with repair solution.
### Code Audit
14 runtime rule scans + A/B/C/D scoring + visual report. setData performance, asynchronous errors, permission missing, expired API, wx:for no key, timer leak all covered.
## Comparison with Other Solutions
| | harmony-mcp | cloudbase-mcp | miniprogram-ci |
|--|:-----------:|:-------------:|:--------------:|
| Cloud Development Required | ❌ | ✅ Must | ❌ |
| Key/Whitelist Required | ❌ | ✅ | ✅ |
| AI Direct Call | ✅ | ✅ | ❌ |
| Understands Project Structure | ✅ | ❌ | ❌ |
| Compilation Error Automatic Repair | ✅ | ❌ | ❌ |
| Intelligent Sub-Packaging + Attribution | ✅ | ❌ | ❌ |
| Compliance Pre-Check (32 rules) | ✅ | ❌ | ❌ |
| Code Quality Audit (14 rules) | ✅ | ❌ | ❌ |
| Cross-Framework Support | ✅ | ❌ | ❌ |
| HarmonyOS Device Operation | ✅ | ❌ | ❌ |
| Zero Configuration | ✅ | ❌ | ❌ |
**harmony-mcp for 70% ordinary Mini Program developers who don't use cloud development.**
## Tool List
### WeChat Mini Program (20 tools)
| You say | Tool | What it does |
|----------|------|--------|
| "Help me release a version" | `wechat_publish` | Version increment + npm build + upload |
| "Compilation error, help me fix" | `wechat_diagnose` | Compilation + error analysis + automatic repair cycle |
| "Check compliance before release" | `wechat_compliance_check` | 32 audit rules full scan |
| "Help me check code quality" | `wechat_audit` | 14 rule scans + scoring |
| "Package exceeded, what to do" | `wechat_package_size` | Volume analysis + progress bar report |
| "How to split package if main package exceeded" | `wechat_subpackage_suggest` | Attribution + sub-package plan + volume simulation |
| "Help me check this project" | `wechat_project_info` | Project overview (AppID/pages/configuration) |
| "What pages are there" | `wechat_page_list` | Main package + sub-package page list |
| "Is the configuration okay" | `wechat_config_validate` | Verify project.config + app.json |
| "Are there issues with dependencies" | `wechat_dependency_check` | npm dependency health check |
| "Help me create a new Mini Program" | `wechat_init_project` | Generate project skeleton (3 templates) |
| "Is the environment okay" | `wechat_ready_check` | Full-chain pre-check (6 items) |
| "Preview" | `wechat_preview` | Generate preview QR code |
| "Upload version 1.2.0" | `wechat_upload` | Upload code to WeChat backend |
| "Build npm" | `wechat_build_npm` | Build npm dependencies |
| "Help me login" | `wechat_cli_login` | Pop up login QR code |
| "Open project" | `wechat_open_project` | Open in developer tools |
| "Close project" | `wechat_close_project` | Close current project |
| "Reset file cache" | `wechat_reset_fileutils` | Reset file listener |
| "Check environment" | `wechat_self_test` | Environment self-test |
### HarmonyOS (8 tools) 🆕 `Beta`
> ⚠️ HarmonyOS tools completed development and unit testing, but not yet verified in real device environments. Welcome developers with HarmonyOS devices to help test and provide feedback.
| You say | Tool | What it does |
|----------|------|--------|
| "What HarmonyOS devices are there" | `harmony_list_devices` | List connected devices/模拟器 |
| "Install on device" | `harmony_install` | Install HAP package |
| "Uninstall this app" | `harmony_uninstall` | Uninstall app |
| "Run on device" | `harmony_start` | Launch Ability |
| "Check device logs" | `harmony_log` | View hilog logs |
| "Transfer file to device" | `harmony_file_push` | Push file to device |
| "Pull file from device" | `harmony_file_pull` | Pull file from device |
| "Is HarmonyOS environment okay" | `harmony_ready_check` | HDC + device pre-check |
## MCP Prompts
In MCP Prompts-supported clients, type `/` to see:
| Command | Function |
|------|------|
| `/harmony-check` | One-click environment pre-check |
| `/harmony-audit` | Full code audit + scoring report |
| `/harmony-shrink` | Package volume analysis → automatic sub-package plan |
| `/harmony-publish` | Compliance pre-check → compilation diagnosis → confirm release |
## FAQ
### Can't connect? Troubleshooting list
| Symptom | Cause | Solution |
|------|------|------|
| npx startup error | Windows npx compatibility issue | Use global installation: `npm i -g @yujiamei/harmony-mcp`, then change command to `harmony-mcp` |
| Download timeout | Company intranet/Taobao mirror | `npm config set registry https://registry.npmmirror.com` and retry |
| "WeChat Developer Tools not found" | Non-default installation path | Create `harmony-mcp.json` in project root directory: `{"cliPath": "D:\\your path\\cli.bat"}` |
| "Need to login again" | Login status expired | Tell AI "Help me login", scan QR code |
| Tool invocation no response | Service port not enabled | Developer tools → Settings → Security → Enable service port |
### Other questions
<details>
<summary>Does it support Mac?</summary>
Supports. Automatically detects macOS common installation paths.
</details>
<details>
<summary>Does it support uni-app / Taro / mpx?</summary>
Supports. Automatically identifies framework and locates compilation output. If output doesn't exist, prompts to compile first.
</details>
<details>
<summary>Are there issues with Chinese paths?</summary>
No. Fully verified under Chinese paths.
</details>
<details>
<summary>What are the capability boundaries?</summary>
- ✅ Compilation layer issues (syntax errors, module missing, configuration errors) — Fully automatic repair
- ✅ Runtime risks (setData performance, asynchronous errors, permission missing) — Static scan detection
- ⚠️ Runtime logic bugs (white screen, interface timing, business logic) — Beyond current capabilities
</details>
## More Resources
- [Prompt Command Library](docs/PROMPTS.md) — Don't know how to talk to AI? Complete scenario command reference here
- [Changelog](ZxxDocs/CHANGELOG.md) — What each version does
- [Contribution Guide](CONTRIBUTING.md) — Welcome to raise issues and PRs
## Support Project
If harmony-mcp helps you, give a ⭐ **Star** as the biggest support!
Stars help more Mini Program developers discover this tool, and it's also the motivation for me to maintain it.
## Disclaimer
This project is **not an official WeChat product**, and has no affiliation with Tencent.
harmony-mcp implements functionality by calling WeChat Developer Tools [officially disclosed CLI command-line interface](https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html), without involving reverse engineering, protocol cracking, or non-public interface calls. Before using this tool, please ensure you have read and agreed to [WeChat Mini Program Platform Service Terms](https://developers.weixin.qq.com/miniprogram/product/service/).
"WeChat" and "Mini Program" are registered trademarks of Tencent, and their use here is for compatibility description only, not constituting any official endorsement.
**This software is provided "as is", without any express or implied warranty.** The author is not responsible for any direct or indirect losses caused by using this software. See [LICENSE](LICENSE).
## License
MIT © [Zhu](https://github.com/xiaoxuzhu303-prog)
