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 / 文档库 / 工程三项就绪

为什么需要它

痛点	本服务的解法
deveco-cli 能力多而杂，AI 不知道用哪个	`capability_search`：22 项精选能力注册表，BM25 + 同义词 RAG 式检索，能力卡自带教学
每个 AI 工具的 MCP 配置格式不一	标准 MCP 服务，任何客户端一行配置接入
LLM 缺乏鸿蒙知识	`docs_search`/`docs_read`/`docs_tree`：2000+ 万字官方文档离线全文检索 + 目录导航
技能市场找包难	`skills_find`：直连技能市场（matrix.openharmony.cn）结构化检索

快速开始（手动安装）

前置要求

# 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 个）

工具	说明
`capability_search`	RAG 式检索精选能力（自然语言 → 能力卡：参数/示例/避坑）
`capability_run`	按能力 ID 执行（参数校验 → devecocli 子进程 / 市场 API）
`capability_list`	浏览全部能力（按分类）
`docs_search`	官方文档全文检索（6 类目录，离线）
`docs_read`	按文档 ID 读取全文
`docs_catalog`	文档分类列表
`skills_find`	技能市场搜索
`status`	环境健康检查（devecocli/文档库/工程）

另有 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