devecocli-mcp

统一鸿蒙（HarmonyOS）开发 MCP 服务：精选、封装、编排 deveco-cli 的技能与能力，让 AI 像搜索 RAG 知识库一样检索能力 → 一键调用 CLI → 快捷查询官方文档。

底层引擎：deveco-cli（openharmony-sig，封装 hvigor/ohpm/hdc/hilog 工具链 + 本地官方文档库 + 技能市场）

🚀 快速安装（一句话）

把下面这句话原样复制给任意 AI 编码客户端（Claude Code / opencode / Cursor / DevEco Code 等），它会按本仓库引导完成 skill + MCP 的安装：

按照仓库引导配置 https://github.com/kelai141/devecocli-mcp 中的内容，注意基于本地环境调整，注意询问用户配置于工作区或全局

AI 执行时须遵守：

• 不假设平台：Windows / macOS / Linux 的命令与路径不同，以本地实际环境为准

• 先询问用户：MCP 配置到工作区（项目级）还是全局（用户级）；SKILL 装到哪个 agent

• 验证收尾：调用 MCP status 工具确认 devecocli / 文档库 / 工程三项就绪

Related MCP server: harmonyos-dev-mcp

为什么需要它

快速开始（手动安装）

前置要求

# 1. 安装 devecocli（执行引擎）
npm install -g @deveco/deveco-cli
# 2. 确保已安装 DevEco Studio（工具链定位）并初始化文档库（首次 docs 命令会自动初始化）

安装本服务

npm install -g devecocli-mcp     # 或本地构建: npm run build

接入任意 MCP 客户端（一行配置）

Claude Code / Cursor / opencode / DevEco Code 等（标准格式，工作区级 <project>/.mcp.json）：

{
  "mcpServers": {
    "devecocli-mcp": {
      "command": "devecocli-mcp",
      "env": {
        "PROJECT_PATH": "${workspaceFolder}"
      }
    }
  }
}

• 全局级：Claude Code ~/.claude.json、Cursor ~/.cursor/mcp.json、opencode ~/.config/opencode/opencode.json（Windows %APPDATA%\opencode\）、codex ~/.codex/config.toml（TOML 格式）

• PROJECT_PATH 可选：缺省自动从客户端 workspace root / 当前目录探测鸿蒙工程

• opencode 使用 "type": "local" 格式（参见 deveco-cli 配置规范）

安装教学 Skill（推荐）

# 复制 SKILL.md 到你的 agent skills 目录，例如 Claude Code：
cp SKILL.md ~/.claude/skills/deveco-unified-mcp/SKILL.md

SKILL 是操作手册（安装后注入 AI 上下文：工作流/工具速查/高频规范/Recipes/Troubleshooting），MCP 是执行层——两者配套使用，安装引导以本 README 为准。

工具一览（8 个）

另有 MCP Prompt harmonyos-dev（工作流教学）与 Resource capability://registry（完整注册表）、guide://harmonyos-dev（操作指南）。

精选能力注册表（v1，22 项）

• 工程：project.create

• 构建：build.project、build.clean

• 运行：app.run、app.preview（多设备预览器）

• 设备：device.list、device.view

• 模拟器：emulator.list、emulator.start、emulator.stop

• 日志：log.get、log.crash

• 文档：docs.search、docs.read、docs.catalog

• 技能市场：skills.find、skills.list、skills.add、skills.remove

• 初始化：init.skill、init.mcp

• 维护：cli.update

架构

src/
├── registry/     # 精选能力注册表（22 项，含教学字段）
├── retrieval/    # CJK 分词 + BM25 + 同义词组（离线零配置）
├── executor/     # devecocli 子进程封装（跨平台/超时/截断）+ 能力调度
├── skills/       # 技能市场直连客户端（matrix.openharmony.cn）
├── tools/        # 工具实现与能力卡格式化
├── server.ts     # MCP Server（8 工具 + prompt + resource）
├── prompts.ts    # harmonyos-dev 工作流教学（注入层核心）
└── index.ts      # stdio 入口

开发

npm install
npm run build      # tsup → dist/index.js
npm test           # vitest（含 top-1 命中率验收）
npm run typecheck

工作原理

• 执行引擎：子进程调用 devecocli（DEVECO_CLI_SKIP_VERSION_CHECK=1 跳过每次调用的版本检查，加速响应）；参数数组传递防注入；非 TTY 下输出无 ANSI 干扰

• 文档通道：devecocli docs search --format json 结构化解析；文档库由 devecocli 自动初始化（SQLite FTS5 + jieba，离线可用）

• 检索层：中文 bigram 分词 + BM25 + 同义词组（每组至多一次加成），纯本地毫秒级

• 技能市场：直连 matrix.openharmony.cn API（HMOS 标签，过滤 DevEco 标签），结构化返回

License

MIT