@yujiamei/harmony-mcp

v0.5.0

Published

16 days ago

中国本土化开发者工具 MCP Server —— 微信小程序、鸿蒙设备自动化

0High
0Medium
0Low

yujiamei

mcp model-context-protocol wechat miniprogram harmonyos devtools automation ai

harmony-mcp

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

当前 npm 稳定版：v0.4.2，共 28 个工具。

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

Quick Start · 核心能力 · 工具列表 · 配置 · FAQ

Quick Start

前置条件

Node.js >= 20
已安装微信开发者工具：下载地址
微信开发者工具中已开启「设置 -> 安全 -> 服务端口」

Kiro / Cursor / Claude Desktop

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

{
  "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 启动不稳定，可以改用全局安装：

npm install -g @yujiamei/harmony-mcp

然后将配置改为：

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

核心能力

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

一键发版

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

编译诊断

你：编译报错了，帮我定位
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.4.2 稳定版共 28 个工具：

| 分类 | 数量 | 代表工具 | |------|------|----------| | 微信基础操作 | 7 | wechat_preview、wechat_upload、wechat_build_npm | | 微信项目分析 | 8 | wechat_project_info、wechat_package_size、wechat_compliance_check | | 微信智能流程 | 5 | wechat_diagnose、wechat_publish、wechat_init_project | | HarmonyOS 设备操作 | 8 | harmony_list_devices、harmony_install、harmony_log |

完整工具表见 docs/TOOLS.md。

配置

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

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

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

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

Roadmap

main 分支正在开发下一批能力，尚未发布到 npm 稳定版：

| 能力 | 状态 | |------|------| | 微信 CLI v2 补强：自动预览、自动化启动、缓存清理 | 源码已完成，待发布 | | miniprogram-ci 双模式：cli / ci / auto | 源码已完成，待发布 | | uni-app / Taro 源码映射增强 | 源码已完成，待发布 | | 运行时诊断 Beta：console、异常、页面栈采集 | 源码已完成，待发布 |

为了避免安装体验和文档承诺不一致，README 主体只描述 npm 当前稳定版能力。

MCP Prompts

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

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

更多示例见 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 调用能力，不是微信官方产品。

Disclaimer

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

harmony-mcp 通过调用微信开发者工具官方公开的 CLI 命令行接口实现微信小程序相关能力，不涉及逆向工程、协议破解或非公开接口调用。使用本工具前，请确保你已阅读并同意《微信小程序平台服务条款》。

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

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