HarmonyOS Toolchain MCP（鸿蒙工具链 MCP 套件 / harmony-build）

让 AI Agent（Claude Code / Cursor / Codex / 自研）真正能操作鸿蒙工程。 这是 提案四-鸿蒙工具链MCP-Server化.md 的代码实现。

Changelog

v0.2.2 (2026-05-22)

• 🔁 例行重发：与 v0.2.1 功能等价，无新增改动；用于覆盖 npx 缓存

v0.2.1 (2026-05-22)

• 🐛 修复 npx harmony-build 启动时报 Cannot find package '@harmony-mcp/common' 的问题：把 7 个子包对 @harmony-mcp/common 的包名引用全部改为相对路径，使发布产物自包含、无外部 workspace 依赖

v0.2.0 (2026-05-21)

• ✅ 新增聚合入口 harmony-build MCP Server：一进程、一个 stdio 连接，聚合 7 个子能力包共 31 个工具
• ✅ 工具名加 <namespace>_ 前缀，避免不同子包重名（如 hdc_list_devices / hvigor_build_hap / dev_run_app）
• ✅ 提供 npx harmony-build 一行启动；支持配置到 Claude Code / Cursor / JoyCode 的 mcpServers 中
• ✅ 发布到 npm 官方源，包名 harmony-build

快速接入（v0.2.0）

{
  "mcpServers": {
    "harmony-build": {
      "command": "npx",
      "args": ["-y", "harmony-build"]
    }
  }
}

包总览

| 包 | 作用 | 主要 Tool/Resource | |---|---|---| | @harmony-mcp/all ⭐ | 聚合包：一进程提供下面所有能力（推广首选） | 自动给每个工具加 <ns>_ 前缀，共 31 个工具 | | @harmony-mcp/hdc | 设备 / 安装 / 截屏 / 日志 | list_devices、install_hap、uninstall、start_ability、stop_ability、hilog_capture、screencap | | @harmony-mcp/hvigor | 构建 / 清理 / 签名 / 日志解析 | build_hap、clean、sign_hap、parse_build_log、run_task | | @harmony-mcp/profiler | 性能 trace 抓取 + 分析（最高价值） | capture_trace、analyze_trace、capture_and_analyze、cold_start_breakdown | | @harmony-mcp/arkanalyzer | ArkTS 静态分析 / 影响面 | find_references、impact_analysis、list_components、count_state_vars | | @harmony-mcp/arkcheck | 高性能编码规则（内置 10 条） | lint_file、lint_project、explain_rule、list_rules | | @harmony-mcp/knowledge | RAG 知识库（公司 SOP / 最佳实践） | search_kb、read_doc + harmony-kb:// Resources | | @harmony-mcp/dev | DevEco Run 等价编排 | run_app、start_log_stream、read_log_stream、stop_log_stream、list_log_streams | | @harmony-mcp/common | 公共：安全 shell、沙箱、日志、MCP 脚手架 | — |

30 秒开跑

cd scripts/mcp
npm install
npm run build
npm run demo          # 跑端到端验证（不需要鸿蒙设备）

demo 会启动三个 MCP server 子进程，用真实 MCP 协议跑：

• arkcheck 扫一段故意写错的 ArkTS → 命中 4 条规则
• arkanalyzer 在本仓库跑组件统计
• knowledge 在 docs/ + proposals/ 里搜关键字

接入 JoyCode（一键脚本）

推荐：聚合模式（一个 server 装下所有）

cd scripts/mcp
npm run install:joycode               # 默认 = 聚合模式，沙箱根 = 本仓库根目录
# 指定一个鸿蒙工程作为沙箱根：
npm run install:joycode -- --project-dir /ABS/PATH/TO/your/harmony/project

脚本会：

1. 自动备份 ~/.joycode/joycode-mcp.json 到 *.bak-<时间戳>
2. 注册 1 个 harmony-mcp server（聚合 7 个子能力，共 31 个工具）
3. 重启 JoyCode 后即可使用

聚合模式下，工具名带 namespace 前缀：hdc_list_devices / hvigor_build_hap / dev_run_app / arkcheck_lint_project ……

试一下：

"用 hdc_list_devices 看看连了什么设备" "用 dev_run_app 把工程 /XX 跑到设备上，盯 10 秒日志"

多 server 模式（需要单独禁用某能力时）

npm run install:joycode -- --multi     # 装 7 个独立 harmony-* server

适合：需要在 JoyCode UI 里单独关掉某个能力（如不让 AI 跑 hvigor）；或要求强进程隔离（一个工具崩不影响其他）。

两种模式不能并存：要切换的话先手动从 ~/.joycode/joycode-mcp.json 删掉旧的 harmony-* 条目再重装，或加 --force。

接入 Claude Code

把下面内容粘进 ~/.config/claude-code/mcp_servers.json（或工程内 .mcp.json）：

{
  "mcpServers": {
    "harmony-hdc": {
      "command": "node",
      "args": ["/ABS/PATH/TO/scripts/mcp/packages/hdc-mcp/dist/index.js"]
    },
    "harmony-hvigor": {
      "command": "node",
      "args": ["/ABS/PATH/TO/scripts/mcp/packages/hvigor-mcp/dist/index.js"]
    },
    "harmony-profiler": {
      "command": "node",
      "args": ["/ABS/PATH/TO/scripts/mcp/packages/profiler-mcp/dist/index.js"]
    },
    "harmony-arkanalyzer": {
      "command": "node",
      "args": ["/ABS/PATH/TO/scripts/mcp/packages/arkanalyzer-mcp/dist/index.js"]
    },
    "harmony-arkcheck": {
      "command": "node",
      "args": ["/ABS/PATH/TO/scripts/mcp/packages/arkcheck-mcp/dist/index.js"]
    },
    "harmony-knowledge": {
      "command": "node",
      "args": ["/ABS/PATH/TO/scripts/mcp/packages/harmony-knowledge-mcp/dist/index.js"],
      "env": {
        "HARMONY_KB_ROOTS": "/ABS/PATH/TO/docs:/ABS/PATH/TO/proposals"
      }
   }
  }
}

接入 Cursor

~/.cursor/mcp.json（全局）或工程根 .cursor/mcp.json（项目级）格式同上。

环境变量约定

| 变量 | 默认 | 作用 | |---|---|---| | HARMONY_MCP_ALLOWED_ROOTS | 空（推荐留空） | 额外允许的工程根目录白名单（多个用 PATH 分隔符）。v0.2 起非必填：sandbox 会从工具入参里的 project_dir / file_path 自动向上寻找 hvigorw / hvigorfile.ts / oh-package.json5 / build-profile.json5 等鸿蒙工程标志文件并加入白名单，切换工程无需任何配置或重启。只有当你想给非鸿蒙工程的目录预先开通访问权限，或者希望显式收紧白名单时才需要设置。 | | HARMONY_MCP_LOG_LEVEL | info | 日志等级：debug/info/warn/error | | HDC_BIN | hdc | hdc 可执行路径 | | HDC_TARGET | — | 默认设备序列号 | | HVIGOR_BIN | hvigorw | hvigor 可执行路径 | | HARMONY_KB_ROOTS | ./docs:./proposals | knowledge MCP 暴露的知识库根 | | HARMONY_ARKANALYZER_JAR | — | 预留：外部 ArkAnalyzer JAR 接入（本期未启用） |

沙箱自动识别机制（v0.2）

• harmony-hvigor（要执行 shell 的工具）：只允许操作"看起来是鸿蒙工程"的目录——即向上能找到 hvigorw / hvigorfile.ts / build-profile.json5 / oh-package.json5 之一。这一限制不能被关闭，避免 Agent 误把 hvigor 跑到非工程目录。
• harmony-arkcheck / harmony-arkanalyzer（只读静态分析）：拿到 project_dir / file_path 时优先按上面的规则识别工程根；若识别不到，会把传入的目录本身作为合法根加入沙箱，方便扫描任意 TS / ArkTS 目录。
• harmony-hdc / harmony-profiler / harmony-knowledge：本身不依赖工程沙箱（操作的是设备 / 临时 trace 文件 / 文档资源），与该变量无关。

⚠️ 如果只在某次终端里 export HARMONY_MCP_ALLOWED_ROOTS=...，重启 IDE 或新终端会失效。推荐做法是直接什么都不设，让自动识别工作；要持久化才考虑写进 ~/.zshrc / IDE 的 MCP 配置 env 块。

一个典型 Agent 工作流

用户：在 Cursor 里说"帮我修首页冷启动卡顿"

Agent 自动编排：

1. harmony-arkanalyzer  list_components      → 找到 EntryAbility / IndexPage
2. harmony-hdc          list_devices         → 选第一台设备
3. harmony-profiler     cold_start_breakdown → force-stop → start → 抓 5s trace → 分析
4. (Agent 推理：发现 main 线程 readFileSync 耗时 230ms)
5. harmony-arkcheck     explain_rule ARK004  → 拿到修复建议文案
6. harmony-knowledge    search_kb "异步 IO"   → 找到公司性能 SOP
7. (Agent 修改源码：readFileSync → await fs.read)
8. harmony-hvigor       build_hap            → 编译验证
9. harmony-hdc          install_hap          → 装回设备复测
10. harmony-profiler    cold_start_breakdown → 复验，确认 jank 消失

全程无人工 IDE 操作。

安全模型

• 沙箱：所有"读写工程文件"的工具都受 HARMONY_MCP_ALLOWED_ROOTS 限制，无法逃逸。
• shell 白名单：hdc shell 只允许调用约定子命令（aa / hilog / hitrace / snapshot_display 等），杜绝任意命令注入。
• 超时强制：每条命令都有上限（默认 60s，trace 类按 duration+15s 计算），子进程 kill -9 兜底。
• stdout 协议保留：日志统一写 stderr，stdout 仅放 MCP 协议消息。
• 本地化：所有 server 在本机进程执行，不向公网/任意第三方发送数据。

内置 ArkCheck 规则（first pass）

| ID | 严重度 | 标题 | |---|---|---| | ARK001 | warning | 高频 build() 中使用 console.log | | ARK002 | warning | ForEach 缺少 key 生成器 | | ARK003 | info | 长列表使用 ForEach 而非 LazyForEach | | ARK004 | error | 主线程同步 IO（readSync 等） | | ARK005 | warning | 组件中 new 大对象未做缓存 | | ARK006 | info | 嵌套 Stack/Column 过深（>6 层） | | ARK007 | warning | Worker/TaskPool 选择不当 | | ARK008 | error | 明文权限/敏感字符串硬编码 | | ARK009 | info | setInterval 未在 aboutToDisappear 清理 | | ARK010 | info | Image 未指定大小，整图解码 |

参考：华为《2025 HarmonyOS 高性能规则检测创新实践》、最佳实践文档。

与现有"四提案"的关系

提案一  AI MR 摘要        ← 调用 arkanalyzer.impact_analysis 自动带"影响面"
提案二  AI Code Review    ← 调用 arkcheck + arkanalyzer 升级到"看语义"
提案三  AI 单测生成        ← 调用 hvigor.build_hap 实现 Self-Refine 闭环
新性能  Profiler AI 分析   ← 100% 基于 profiler-mcp

MCP 化是 1+2+3 共同的底座。

路线图

• [x] P0 hdc-mcp MVP + Claude Code 端到端验证
• [x] P1 hvigor-mcp + profiler-mcp 跑通"改→build→trace→分析"闭环
• [x] P2 arkanalyzer-mcp + arkcheck-mcp（内置版）
• [x] P3 harmony-knowledge-mcp（RAG）
• [ ] P4 SSE transport + 多用户共享部署
• [ ] P5 接入官方 ArkAnalyzer JAR（替换内置 regex 版）
• [ ] P6 ArkCheck 二进制接入（同上）
• [ ] P7 profiler 升级为推理模型直读 .htrace 二进制

目录结构

scripts/mcp/
├── package.json                          # npm workspaces 根
├── tsconfig.base.json                    # 公共 TS 配置
├── demo/run-demo.mjs                     # 端到端 demo（无需鸿蒙设备）
└── packages/
    ├── mcp-common/                       # 公共库
    ├── hdc-mcp/
    ├── hvigor-mcp/
    ├── profiler-mcp/
    ├── arkanalyzer-mcp/
    ├── arkcheck-mcp/
    └── harmony-knowledge-mcp/

License

Apache-2.0