harmonyos-dep-mcp

鸿蒙（HarmonyOS）依赖兼容性查询 MCP Server。

功能

• 依赖兼容性查询：输入依赖列表（语言 + 包名），返回每个依赖的鸿蒙支持状态
• 技能轨迹查询：列出所有技能轨迹的动作清单（list-skill-actions），按编号批量获取解决方案（get-skill-solutions）
• 双路查询：优先按依赖包名（dependency_name）查询；未命中时按鸿蒙适配包名（harmony_solution）反向查询，命中即判定为可原生兼容
• 大小写不敏感查询：包名匹配不区分大小写（COLLATE NOCASE），LODASH 与 lodash 等价
• 动态语言兼容：语言参数不限制枚举，支持别名归一化（nodejs→node、c++→cpp 等），未知语言通过 hint 反馈回路引导模型自我修正
• 启动后台预热同步：服务启动时立即在后台拉取全量数据（依赖映射 + 技能轨迹并行），利用进程启动到首次工具调用之间的时间窗口完成预热；工具调用时最多等待 5 秒搭车预热结果，避免首次全量拉取阻塞响应、触发 MCP 60 秒超时
• 每次查询增量同步：调用工具时自动从远端拉取增量数据，同步失败时携带具体错误原因（连接失败 / 超时 / HTTP 状态码），不中断查询，继续使用本地缓存
• 纯 JS 依赖：HTTP 请求基于 Node 内置 node:http/node:https，SQLite 基于 sql.js 的 asm.js 版本（纯 JS，无 WASM 依赖），无 native 编译，全平台（Windows/macOS/Linux/鸿蒙）直接运行

前置要求

• Node.js >= 22

安装

# 全局安装
npm install -g harmonyos-dep-mcp

# 或通过 npx 直接运行（无需安装）
npx -y harmonyos-dep-mcp

配置

环境变量

| 变量 | 必填 | 说明 | |------|------|------| | HARMONY_DB_URL | 否 | 远端服务地址。未配置时查询会提示"未配置 HARMONY_DB_URL 环境变量"，并使用本地缓存数据 |

MCP 客户端配置

Claude Desktop / Cursor / VS Code 等支持 MCP 的客户端：

{
  "mcpServers": {
    "harmonyos-dep": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "harmonyos-dep-mcp"],
      "env": {
        "HARMONY_DB_URL": "http://your-server:8080"
      }
    }
  }
}

工具

check-harmony-support

查询依赖列表的鸿蒙支持状态。每次调用时自动从远端拉取最新数据。

输入参数：

{
  "dependencies": [
    { "language": "python", "name": "requests" },
    { "language": "nodejs", "name": "lodash" }
  ]
}

• language：语言标识（字符串，不限制枚举）。规范值如 node、python、cpp、rust、go 等，以数据库实际收录为准。常见别名（如 nodejs、c++、python3）会自动归一化。
• name：依赖包名（匹配不区分大小写）

双路查询机制：

1. 第一路（按依赖包名）：按 dependency_name + language 精确查询。命中则返回数据库记录（含 harmonySolution 鸿蒙适配方案）
2. 第二路（按鸿蒙适配包名）：第一路未命中时，再按 harmony_solution + language 反向查询。命中说明用户输入的包名本身就是鸿蒙适配包，结果归一化为：name 保持用户输入、supported: true、nativelyCompatible: true、harmonySolution: null

例如查询 @ohos-ports/axios：第一路未命中（数据库中只有 axios 的原始记录），第二路按 harmony_solution 命中，直接判定该鸿蒙适配包可原生兼容。

返回示例：

{
  "results": [
    {
      "name": "requests",
      "language": "python",
      "supported": true,
      "nativelyCompatible": false,
      "harmonySolution": "使用 ohpm 等效替代包"
    }
  ],
  "dataSource": "local",
  "mappingVersion": "2026-07-23 17:07:05",
  "updatedAt": "2026-07-23 17:07:05"
}

语言未收录时的反馈：

当传入的语言不在数据库中时，结果仍会返回（supported: false），同时附带 hint 字段列出当前收录的语言类型，引导模型修正后重试：

{
  "results": [
    { "name": "stdlib", "language": "kotlin", "supported": false, ... }
  ],
  "hint": "以下 language 在数据库中暂无数据: kotlin\n当前数据库收录语言: node, python, cpp"
}

远端同步失败时的反馈：

同步失败不中断查询，继续使用本地缓存数据，错误信息附加到 hint：

{
  "results": [ ... ],
  "hint": "远端同步失败: 连接失败: ECONNREFUSED（使用本地缓存数据）"
}

list-skill-actions

获取所有技能轨迹的编号和动作清单（不含解决方案），按编号升序。每次调用时先等待后台预热（最多 5 秒），再从远端拉取技能轨迹增量数据。

输入参数： 无

返回示例：

{
  "success": true,
  "message": "查询成功",
  "data": [
    { "id": 1, "action": "在 DevEco Studio 中创建 HarmonyOS 项目", "updatedAt": "2026-08-20 10:00:00" },
    { "id": 2, "action": "使用 ohpm 安装依赖包", "updatedAt": "2026-08-20 10:05:00" }
  ]
}

首次同步进行中或远端同步失败时，结果仍返回，同时通过 hint 字段说明原因。

get-skill-solutions

根据编号列表批量获取技能轨迹的解决方案（含动作描述和更新时间），与 list-skill-actions 配合使用：先列出动作清单，再按需获取解决方案详情。

输入参数：

{ "ids": [1, 2, 3] }

• ids：技能轨迹编号列表（整数数组，最多 100 个）

返回示例：

{
  "success": true,
  "message": "查询成功",
  "data": [
    {
      "id": 1,
      "action": "在 DevEco Studio 中创建 HarmonyOS 项目",
      "solution": "打开 DevEco Studio，选择 File > New > Create Project...",
      "updatedAt": "2026-08-20 10:00:00"
    }
  ]
}

不存在的编号不包含在结果中，通过 hint 反馈：

{
  "success": true,
  "message": "查询成功",
  "data": [ ... ],
  "hint": "以下编号未找到: 99, 100"
}

运行机制

1. 启动 → 从 dist/data/harmony_dep.db 加载本地数据库（路径基于 index.js 所在目录，不依赖运行时工作目录），文件不存在时自动创建空表
2. 后台预热 → 数据库加载后立即在后台启动全量同步（依赖映射 + 技能轨迹并行），不阻塞服务启动；同步完成后释放等待句柄，后续调用零开销
3. 查询 → 每次调用工具时，先等待后台同步（最多 5 秒，预热完成则立即返回），再拉取增量数据，随后查本地库；首次同步超过 5 秒时返回已有数据并附带 hint"首次同步进行中"
4. 增量更新 → 依赖映射调用 /mapping/updated?since=<最新更新时间>，技能轨迹调用 /skill/trace/updated?since=<最新更新时间>，分页拉取变更数据并 upsert 到本地库；同步进行中的重复调用直接跳过，不重复拉取
5. 落盘 → 每次更新后立即将数据库写入磁盘

远端接口约定

GET /mapping/updated?since={timestamp}&page={n}&pageSize={size}
GET /skill/trace/updated?since={timestamp}&page={n}&pageSize={size}

返回格式：

{
  "data": [
    {
      "dependencyName": "requests",
      "language": "python",
      "supported": true,
      "nativelyCompatible": false,
      "harmonySolution": "使用 ohpm 等效替代包",
      "updatedAt": "2026-07-23 17:07:05"
    }
  ],
  "totalPages": 21
}

/skill/trace/updated 返回格式：

{
  "data": [
    {
      "id": 1,
      "action": "在 DevEco Studio 中创建 HarmonyOS 项目",
      "solution": "打开 DevEco Studio，选择 File > New > Create Project...",
      "updatedAt": "2026-08-20 10:00:00"
    }
  ],
  "totalPages": 1
}

License

MIT