harmony-mcp

对 AI 说"帮我发个版本"，然后喝口水，完事了。

小程序开发者的 AI 副驾驶 —— 能理解你的项目、帮你一键发版、诊断编译错误的 MCP Server。

不需要云开发，不需要密钥，不需要白名单。装上就能用。

---

🚀 v0.2.3 重大更新：精准度与智能度跃升

🔍 跨框架智能识别 — 丢 uni-app/Taro/mpx 源码目录进来，自动定位到 dist/build/mp-weixin 编译产物。传编译产物目录也能回溯识别框架来源，并警告 AI 不要直接改产物文件。

� 体积分析精准化 — 白名单过滤（只算 .js/.wxml/.wxss/.json/图片/字体），不再把 README/lock 文件算进体积。官方口径获取失败时明确标注"已降级为本地扫描"。

🎯 体积归因引擎 — 告诉你"把页面 X 移到分包能省 430KB（含独占组件 video-player）"，不再是泛泛的"建议分包"。

�️ 运行时静态扫描 — 编译通过后自动检测 5 类运行时隐患：setData 无节流、异步未处理、数据过大、权限缺失、过期 API。

🔄 自动恢复链路 — 命令失败时自动执行 open→reset→retry，展示每步结果。

✅ 全链路预检 — wechat_ready_check 一次性检测 CLI/进程/登录态/端口/项目合法性，每项带修复 SOP。

---

⚡ 快速开始

在你的 AI 工具（Kiro / Claude Desktop / Cursor 等）的 MCP 配置中添加：

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

前置条件

1. Node.js >= 18
2. 微信开发者工具已安装（下载）
3. 开发者工具「设置 → 安全 → 服务端口」已开启

💡 微信开发者工具安装在默认路径时会自动检测，无需额外配置。

---

✨ 能做什么

一键发版

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

一句话搞定原来 3-4 步的手动操作：版本递增 → npm 构建 → 上传代码。

包体积分析

你：包体积快超了，帮我看看
AI：📊 主包 1.8MB / 2MB（警告！）
    📁 images/ 占 42%（建议压缩）
    📁 vendor/ 占 28%（建议分包）
    💡 优化建议：1. 图片转 WebP  2. lodash 换 lodash-es  3. 大页面移入分包

编译诊断 → 自动修复

你：编译报错了帮我修
AI：❌ pages/cart/cart.js:42 - Cannot find module 'utils/pay'
    🔍 类型：模块缺失 | 指令：READ_FILE_AND_PATCH
    🔧 正在读取文件并修复...
    ✅ 重新编译通过！0 错误
    ⚠️ 检测到 2 个运行时隐患：
       - RT001: onPageScroll 中 setData 未节流（第 15 行）
       - RT004: 调用 wx.getLocation 但未声明权限

AI 自动读取报错文件、修复代码、重新编译验证，直到零报错。编译通过后还会扫描运行时隐患。

跨框架支持

你：分析一下 D:\projects\my-uniapp 的包体积
AI：🔍 检测到 uni-app 项目，已自动定位到编译产物: dist/build/mp-weixin
    📊 主包 1.6MB / 2MB
    ⚠️ 当前处于编译产物目录，改代码请去源码目录修改！
    🎯 体积归因：pages/detail 移到分包可省 430KB（含独占组件 video-player）

---

📋 全部工具（17 个）

工具	功能	说一句话就能触发
wechat_diagnose	编译诊断 + 自动修复 + 运行时隐患扫描	"编译报错了帮我修"
wechat_publish	一键发版（支持跨框架项目）	"帮我发个版本"
wechat_package_size	包体积分析 + 官方精度 + 口径标注	"包超了吗"
wechat_subpackage_suggest	智能分包 + 体积归因 + 瘦身建议	"主包超了怎么办"
wechat_ready_check	全链路预检（CLI/登录/端口/项目）	"环境正常吗"
wechat_project_info	读取项目配置（支持 uni-app/Taro/mpx）	"帮我看看这个项目"
wechat_page_list	列出所有页面	"有哪些页面"
wechat_config_validate	配置文件校验	"配置有没有问题"
wechat_dependency_check	依赖健康检查	"依赖有问题吗"
wechat_preview	预览小程序	"预览一下"
wechat_upload	上传代码	"上传 1.2.0 版本"
wechat_build_npm	构建 npm	"构建一下 npm"
wechat_cli_login	登录开发者工具	"帮我登录"
wechat_open_project	打开项目	"打开项目"
wechat_close_project	关闭项目	"关闭项目"
wechat_reset_fileutils	重置文件监听	"重置文件缓存"
wechat_self_test	环境自检	"检查一下环境"

---

🆚 与其他方案的区别

	harmony-mcp	cloudbase-mcp	miniprogram-ci
需要云开发	❌	✅ 必须	❌
需要密钥/白名单	❌	✅	✅
AI 可直接调用	✅	✅	❌
能理解项目结构	✅	❌	❌
一键发版	✅	❌	❌
编译报错自动修复	✅	❌	❌
智能分包建议	✅	❌	❌
零配置使用	✅	❌	❌

harmony-mcp 面向不用云开发的 70% 普通小程序开发者。赛道内唯一能做到 AI 编译闭环的产品。

---

❓ 常见问题

提示"找不到微信开发者工具"

确认开发者工具已安装。如果安装在非默认路径，在项目根目录创建 harmony-mcp.json：

{
  "cliPath": "D:\\你的路径\\cli.bat"
}

提示"需要重新登录"

微信开发者工具登录态过期了。对 AI 说"帮我登录"，扫码即可。

支持 Mac 吗？

支持。自动检测 macOS 常见安装路径（/Applications/wechatwebdevtools.app 等）。

支持 uni-app / Taro / mpx 吗？

支持。传入源码目录会自动识别框架类型并定位到编译产物（如 dist/build/mp-weixin）。如果产物不存在，会提示你先执行编译命令。

中文路径有问题吗？

没有。已在 D:\ZhuoMian\朱晓旭\ 这类中文路径下充分验证，CLI 调用全部用双引号包裹。

能力边界

• ✅ 编译层问题（语法错误、模块缺失、配置错误）— 全自动修复
• ✅ 运行时隐患（setData 性能、异步错误、权限缺失）— 静态扫描检测
• ⚠️ 运行时逻辑 bug（白屏、接口时序、业务逻辑）— 超出当前能力，需人工调试

---

License

MIT © 朱