AI导哈

HarmonyOS开发辅助工具

一个为HarmonyOS开发设计的模型上下文协议服务器，支持AI助手与HarmonyOS项目、设备和应用程序交互。

  • by FadingLight9291117
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 FadingLight9291117/mcp-harmonyos

使用说明

MCP HarmonyOS

npm: https://www.npmjs.com/package/mcp-harmonyos

用于HarmonyOS开发的模型上下文协议（MCP）服务器。该服务器使像Claude这样的人工智能助手能够与HarmonyOS项目、设备和应用程序进行交互。

特征

  • 设备管理：列出并查询连接的HarmonyOS设备
  • 项目信息：读取项目配置、模块和生成输出
  • 应用管理：列出并检查设备上已安装的应用程序
  • 构建验证：检查构建输出和项目结构

先决条件

  • Node.js 18+
  • HarmonyOS DevEco Studio（用于hdc命令行工具）
  • hdc 必须在PATH中可用

安装

全局安装（推荐）

npm install -g mcp-harmonyos

或与npx一起使用

npx mcp-harmonyos

配置

对于OpenCode

添加到您的 ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "harmonyos": {
      "type": "local",
      "command": ["npx", "-y", "mcp-harmonyos"],
      "enabled": true
    }
  }
}

适用于克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "harmonyos": {
      "command": "mcp-harmonyos"
    }
  }
}

可用工具

设备管理

harmonyos_list_devices

列出所有连接的HarmonyOS设备。

退货：具有UDID和状态的设备阵列

[
  {
    "udid": "7001005458323933328a01bcf4251a00",
    "status": "connected"
  }
]

harmonyos_get_device_info

获取特定设备的详细信息。

参数:

  • deviceId （string）：设备UDID

退货：设备信息，包括型号、制造商、操作系统版本等。

{
  "udid": "7001005458323933328a01bcf4251a00",
  "model": "HUAWEI Mate 60 Pro",
  "brand": "HUAWEI",
  "manufacturer": "HUAWEI",
  "osVersion": "4.0.0",
  "sdkVersion": "11",
  "buildId": "Mate60Pro 4.0.0.96"
}

项目信息

harmonyos_get_project_info

从app.json5获取HarmonyOS项目信息。

参数:

  • projectPath （string）：HarmonyOS项目根的绝对路径

退货：项目元数据，包括bundleName、版本和模块

{
  "bundleName": "com.example.myapp",
  "versionCode": 1000000,
  "versionName": "1.0.0",
  "minCompatibleVersionCode": 1000000,
  "targetAPIVersion": 11,
  "modules": ["entry", "library"]
}

harmonyos_list_modules

列出项目中的所有模块及其类型（HAP/HSP/HAR）。

参数:

  • projectPath （string）：HarmonyOS项目根的绝对路径

退货：包含名称、类型和路径的模块数组

[
  {
    "name": "entry",
    "type": "HAP",
    "path": "/path/to/project/entry",
    "srcPath": "entry"
  },
  {
    "name": "library",
    "type": "HSP",
    "path": "/path/to/project/library",
    "srcPath": "library"
  }
]

harmonyos_check_build_outputs

检查是否存在构建输出并列出它们。

参数:

  • projectPath （string）：HarmonyOS项目根的绝对路径

退货：构建输出信息

{
  "hasOutputs": true,
  "outputDir": "/path/to/project/outputs",
  "files": ["entry-default-signed.hap", "library-default-signed.hsp"],
  "haps": ["entry-default-signed.hap"],
  "hsps": ["library-default-signed.hsp"]
}

应用管理

harmonyos_list_installed_apps

列出设备上安装的所有应用程序。

参数:

  • deviceId （string）：设备UDID

退货：已安装的应用程序阵列

[
  {
    "bundleName": "com.example.myapp",
    "versionCode": "1000000",
    "versionName": "1.0.0"
  }
]

harmonyos_get_app_info

获取已安装应用程序的详细信息。

参数:

  • deviceId （string）：设备UDID
  • bundleName （string）：应用程序包名称

退货：详细的申请信息

{
  "bundleName": "com.example.myapp",
  "versionCode": "1000000",
  "versionName": "1.0.0",
  "uid": "20010044",
  "installTime": "2026-02-15 10:30:00",
  "updateTime": "2026-02-15 10:30:00",
  "isSystemApp": false,
  "isRemovable": true
}

使用示例

使用OpenCode

配置MCP服务器后，您可以向OpenCode提出以下问题：

"List all connected HarmonyOS devices"
"What's the bundleName of the project in /path/to/my/project?"
"Check if there are build outputs in my project"
"List all installed apps on device 7001005458323933328a01bcf4251a00"
"Show me information about com.example.myapp on my device"

OpenCode将使用MCP工具查询信息，并可以将其与bash命令结合用于构建和部署：

"Build the project and deploy to device"
# OpenCode will:
# 1. Use harmonyos_get_project_info to get bundleName
# 2. Use bash: hvigorw assembleApp --no-daemon
# 3. Use harmonyos_check_build_outputs to verify
# 4. Use bash: hdc file send and bm install to deploy
# 5. Use bash: aa start to launch the app

设计理念

此MCP服务器遵循“轻量级查询+外部操作”模式：

  • MCP工具 提供快速、结构化的查询（设备信息、项目元数据、应用程序状态）
  • Bash命令 处理长时间运行的操作（构建、部署）
  • AI助手 智能地将两者结合起来，以实现完整的工作流程

该设计确保：

  • ✅ 快速响应时间（所有查询<1秒）
  • ✅ 长版本没有超时问题
  • ✅ 清除错误消息和日志
  • ✅ 易于维护和扩展

发展

从源代码构建

git clone <your-repo>
cd mcp-harmonyos
npm install
npm run build
npm start

项目结构

mcp-harmonyos/
├── src/
│   ├── server.ts              # Main MCP server implementation
│   └── types/
│       └── harmonyos-types.ts # TypeScript type definitions
├── build/                      # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

故障排除

“找不到hdc命令”

确保已安装DevEco Studio hdc 在您的路径中：

# macOS/Linux
export PATH="$PATH:/path/to/deveco-studio/tools"

# Windows
set PATH=%PATH%;C:\path\to\deveco-studio\tools

“未连接任何设备”

  1. 在设备上启用开发人员选项（点击内部版本号7次）
  2. 启用USB调试
  3. 通过USB连接设备
  4. 跑 hdc list targets 验证连接

“未找到app.json5”

确保提供项目根目录的绝对路径（其中 AppScope/app.json5 位于）。

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。

相关资源

相关 MCP