# harmony-mcp

[![npm version](https://img.shields.io/npm/v/@yujiamei/harmony-mcp.svg)](https://www.npmjs.com/package/@yujiamei/harmony-mcp)
[![npm downloads](https://img.shields.io/npm/dw/@yujiamei/harmony-mcp.svg)](https://www.npmjs.com/package/@yujiamei/harmony-mcp)
[![CI](https://github.com/xiaoxuzhu303-prog/harmony-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/xiaoxuzhu303-prog/harmony-mcp/actions/workflows/ci.yml)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue.svg)](https://registry.modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)

微信小程序与 HarmonyOS 设备自动化 MCP Server。让 Kiro、Cursor、Claude Desktop 等 AI 客户端直接执行本地开发者工具能力：编译诊断、合规预检、包体积分析、一键上传和鸿蒙设备操作。

当前 npm 稳定版：`v0.5.0`，共 `36` 个工具。

**不需要云开发，不需要小程序 CI 密钥，不需要 IP 白名单。默认通过微信开发者工具官方 CLI 工作。**

**[Quick Start](#quick-start) · [核心能力](#核心能力) · [工具列表](#工具列表) · [配置](#配置) · [FAQ](#faq)**

---

## Quick Start

### 前置条件

1. Node.js `>= 20`
2. 已安装微信开发者工具：[下载地址](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)
3. 微信开发者工具中已开启「设置 -> 安全 -> 服务端口」

### Kiro / Cursor / Claude Desktop

三类客户端配置内容相同，只是配置文件路径不同。

```json
{
  "mcpServers": {
    "harmony-mcp": {
      "command": "npx",
      "args": ["-y", "@yujiamei/harmony-mcp"]
    }
  }
}
```

常见配置路径：

| 客户端 | 配置文件 |
|------|----------|
| Kiro | `.kiro/settings/mcp.json` |
| Cursor | `.cursor/mcp.json` |
| Claude Desktop macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop Windows | `%APPDATA%\Claude\claude_desktop_config.json` |

Windows 如果 `npx` 启动不稳定，可以改用全局安装：

```bash
npm install -g @yujiamei/harmony-mcp
```

然后将配置改为：

```json
{
  "mcpServers": {
    "harmony-mcp": {
      "command": "harmony-mcp",
      "args": []
    }
  }
}
```

---

## 核心能力

| 场景 | 你可以对 AI 说 | 做什么 |
|------|----------------|--------|
| 一键发版 | "帮我发个版本，描述是修复购物车 bug" | 读取版本、构建 npm、上传代码 |
| 编译诊断 | "编译报错了，帮我定位" | 调用开发者工具编译，解析错误并给出修复建议 |
| 包体积分析 | "主包快超了，帮我看看" | 分析包体积、定位大文件、给出分包建议 |
| 合规预检 | "发版前检查一下合规" | 扫描 32 条审核高频规则 |
| 代码审计 | "帮我检查代码质量" | 扫描 14 条运行时规则并评分 |
| 鸿蒙设备 | "把这个 HAP 装到设备上" | 通过 HDC 安装、启动、看日志、传文件 |

### 一键发版

```text
你：帮我发个版本，描述是修复了购物车 bug
AI：读取项目信息... OK
    构建 npm... OK
    上传代码 v1.2.4... OK
    发版完成。去微信后台提交审核即可。
```

### 编译诊断

```text
你：编译报错了，帮我定位
AI：pages/cart/cart.js:42 Cannot find module 'utils/pay'
    类型：模块缺失
    源码：src/pages/cart/cart.tsx
    建议：检查 import 路径或补齐对应模块
```

### 合规预检

`wechat_compliance_check` 覆盖隐私弹窗、授权时机、虚拟支付、强制登录、web-view 域名、HTTPS、页面路径、tabBar、诱导分享、内容安全和敏感信息硬编码等高频审核问题。

---

## 工具列表

`v0.5.0` 稳定版共 36 个工具：

| 分类 | 数量 | 代表工具 |
|------|------|----------|
| 微信基础操作 | 10 | `wechat_preview`、`wechat_auto_preview`、`wechat_cache_clean` |
| 微信项目分析 | 4 | `wechat_project_info`、`wechat_package_size`、`wechat_subpackage_suggest` |
| 微信项目检查 | 4 | `wechat_config_validate`、`wechat_audit`、`wechat_compliance_check` |
| 微信智能流程 | 2 | `wechat_diagnose`、`wechat_publish` |
| 微信 CI / 环境 / 运行时 | 8 | `wechat_ci_preview`、`wechat_ready_check`、`wechat_runtime_diagnose` |
| HarmonyOS 设备操作 | 8 | `harmony_list_devices`、`harmony_install`、`harmony_log` |

完整工具表见 [docs/TOOLS.md](docs/TOOLS.md)。

---

## 配置

默认情况下无需配置。只有在微信开发者工具或 HDC 不在常见路径时，才需要在运行目录创建 `harmony-mcp.json`。

```json
{
  "cliPath": "D:\\Program Files\\Tencent\\微信web开发者工具\\cli.bat",
  "hdcPath": "D:\\Huawei\\Sdk\\openharmony\\toolchains\\hdc.exe",
  "appJsonPath": "src/app.json"
}
```

也可以通过环境变量指定微信开发者工具 CLI：

```bash
WECHAT_DEVTOOLS_CLI="D:\\Program Files\\Tencent\\微信web开发者工具\\cli.bat"
```

---

## Roadmap

下一阶段继续补强：

| 能力 | 状态 |
|------|------|
| HarmonyOS 真机验证矩阵 | 计划中 |
| uni-app / Taro 源码映射增强 | 计划中 |
| 运行时诊断 Beta 稳定化 | 持续迭代 |
| 工具清单自动校验 | 计划中 |

---

## MCP Prompts

在支持 MCP Prompts 的客户端中输入 `/`，可以看到 4 个快捷指令：

| 指令 | 功能 |
|------|------|
| `/harmony-check` | 一键环境预检 |
| `/harmony-audit` | 全量代码审计与评分报告 |
| `/harmony-shrink` | 包体积分析与分包建议 |
| `/harmony-publish` | 合规预检、编译诊断、确认发版 |

更多示例见 [docs/PROMPTS.md](docs/PROMPTS.md)。

---

## FAQ

### 连不上怎么办？

| 症状 | 常见原因 | 处理方式 |
|------|----------|----------|
| `npx` 启动报错 | Windows 环境兼容问题 | 改用全局安装：`npm i -g @yujiamei/harmony-mcp` |
| 下载超时 | 网络或 npm registry 问题 | 执行 `npm config set registry https://registry.npmmirror.com` 后重试 |
| 找不到微信开发者工具 | 安装路径非默认 | 配置 `WECHAT_DEVTOOLS_CLI` 或 `harmony-mcp.json.cliPath` |
| 需要重新登录 | 微信开发者工具登录态过期 | 对 AI 说"帮我登录"，扫码确认 |
| 工具调用无响应 | 服务端口未开启 | 微信开发者工具 -> 设置 -> 安全 -> 开启服务端口 |

### 支持跨端框架吗？

支持 uni-app、Taro、MPX 的基础识别与编译产物定位。当前稳定版已支持自动定位产物目录；更精确的源码映射增强正在 `main` 分支开发中。

### 会上传代码或修改文件吗？

只有调用上传、构建、初始化项目、鸿蒙安装等明确操作时才会产生外部动作。只读分析类工具会通过 MCP Tool Annotations 标注为只读，方便客户端做安全提示。

### 这是微信官方工具吗？

不是。本项目通过微信开发者工具官方公开 CLI 调用能力，不是微信官方产品。

---

## 相关文档

- [完整工具表](docs/TOOLS.md)
- [Prompt 指令库](docs/PROMPTS.md)
- [贡献指南](CONTRIBUTING.md)
- [安全政策](SECURITY.md)

---

## Disclaimer

本项目非微信官方产品，与腾讯公司无任何关联。

harmony-mcp 通过调用微信开发者工具[官方公开的 CLI 命令行接口](https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html)实现微信小程序相关能力，不涉及逆向工程、协议破解或非公开接口调用。使用本工具前，请确保你已阅读并同意[《微信小程序平台服务条款》](https://developers.weixin.qq.com/miniprogram/product/service/)。

"微信"及"小程序"为腾讯公司的注册商标，本项目中的使用仅用于描述兼容性，不构成任何官方背书。

本软件按"原样"提供，不附带任何明示或暗示的担保。作者不对因使用本软件导致的任何直接或间接损失承担责任。详见 [LICENSE](LICENSE)。

---

## License

MIT © [朱](https://github.com/xiaoxuzhu303-prog)