# devecocli-mcp

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

> 底层引擎：[deveco-cli](https://gitcode.com/openharmony-sig/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）结构化检索 |

## 快速开始（手动安装）

### 前置要求

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

### 安装本服务

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

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

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

```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 配置规范](https://gitcode.com/openharmony-sig/deveco-cli)）

### 安装教学 Skill（推荐）

```bash
# 复制 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 入口
```

## 开发

```bash
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