# hdc-mcp-server

**Repository Path**: stesen/hdc-mcp-server

## Basic Information

- **Project Name**: hdc-mcp-server
- **Description**: 鸿蒙hdc命令mcp
- **Primary Language**: NodeJS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-17
- **Last Updated**: 2026-02-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HarmonyOS HDC MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)

HarmonyOS HDC (HarmonyOS Device Connector) 的 MCP (Model Context Protocol) 服务实现。通过 MCP 协议，AI 助手可以与 HarmonyOS/OpenHarmony 设备进行交互，实现设备调试、应用管理、性能分析等功能。

## 功能特性

### 🔧 设备管理
- 列出连接的设备（USB/TCP）
- TCP 设备连接与断开
- 设备信息查询（型号、版本、分辨率等）

### 💻 Shell 命令
- 远程 Shell 命令执行
- 应用沙箱内执行命令
- 交互式 Shell 支持

### 📦 应用管理
- 安装/卸载 HAP/HSP/APP 包
- 应用启动/停止/强制停止
- 已安装应用列表查询
- 应用数据清除

### 📁 文件传输
- 本地到设备的文件发送
- 设备到本地的文件接收
- 目录内容列表

### 🔌 端口转发
- 正向端口转发（本地→设备）
- 反向端口转发（设备→本地）
- 端口转发列表管理

### 📝 HiLog 日志系统
- 日志查询与过滤（类型、级别、标签）
- 实时日志监控
- 日志缓冲区管理
- 日志级别设置

### 📊 HiDumper 系统信息
- 内存使用查询（整机/进程）
- CPU 使用查询与频率监控
- 系统服务列表与详情
- 网络/存储信息查询
- 故障日志获取
- JS 堆内存分析（ArkTS）
- IPC 统计信息
- 压缩导出功能

### 🚀 AA (Ability Assistant)
- Ability 启动/停止
- 调试模式管理（attach/detach）
- 等待调试状态设置
- 测试框架支持
- 内存级别压力测试

### 📦 BM (Bundle Manager)
- 应用包安装/卸载/查询
- 共享库查询与管理
- 依赖关系分析
- AOT 编译控制
- 快速修复（Hotfix）
- 插件管理
- 设备 UDID 获取

### 🔥 HiPerf 性能分析
- CPU 性能采样
- 热点函数分析
- 性能计数器统计
- 火焰图数据生成
- 多事件采样支持

### 📈 HiProfiler 综合调优
- CPU 性能调优
- 内存分析
- IO 分析
- 网络分析
- 图形渲染分析

### 📡 HiSysEvent 系统事件
- 历史事件查询（FAULT/STATISTIC/SECURITY/BEHAVIOR）
- 实时事件订阅
- 事件导出到文件
- 多条件过滤查询

## 安装

### 环境要求
- Node.js >= 18.0.0
- HarmonyOS SDK（包含 hdc 工具）

### 安装步骤

```bash
# 克隆仓库
git clone <repository-url>
cd hdc-mcp-server

# 安装依赖
npm install

# 编译 TypeScript
npm run build
```

## 配置

### 环境变量

| 环境变量 | 说明 | 默认值 |
|----------|------|--------|
| `HDC_MCP_SERVER_PATH` | HDC 可执行文件路径 | 从 PATH 自动查找 |
| `HDC_MCP_SERVER_PORT` | HDC Server 端口 | 8710 |
| `HDC_MCP_LOG_LEVEL` | 日志级别 (debug/info/warn/error) | info |
| `HDC_MCP_CONFIG_PATH` | 配置文件路径 | ~/.config/hdc-mcp/config.yaml |

### 配置文件

创建配置文件 `~/.config/hdc-mcp/config.yaml`：

```yaml
# HDC 配置
hdc:
  path: "/path/to/hdc"  # HDC 可执行文件路径
  serverPort: 8710
  defaultTimeout: 30000
  maxRetries: 3

# Server 配置
server:
  name: "hdc-mcp-server"
  version: "1.0.0"

# 日志配置
logging:
  level: "info"
  file: null  # 设置为文件路径可输出到文件

# 安全配置
security:
  forbiddenPaths:
    - "/data/misc"
    - "/system"
    - "/dev/mem"
    - "/dev/kmem"
```

### HDC 路径配置

如果 hdc 不在系统 PATH 中，可以通过以下方式指定：

1. **环境变量方式**
```bash
export HDC_MCP_SERVER_PATH="/path/to/HarmonyOS/sdk/toolchains/hdc"
```

2. **配置文件方式**
在 `config.yaml` 中设置 `hdc.path`

3. **自动查找**
程序会自动在以下位置查找 hdc：
- 系统 PATH
- HarmonyOS SDK 默认安装路径
- Windows: `%LOCALAPPDATA%\\OpenHarmony\\Sdk`
- macOS: `~/Library/OpenHarmony/Sdk`
- Linux: `~/openharmony/sdk`

## 使用

### 作为 MCP Server 使用

#### Claude Desktop 配置

编辑 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "hdc": {
      "command": "node",
      "args": ["/path/to/hdc-mcp-server/dist/index.js"],
      "env": {
        "HDC_MCP_SERVER_PATH": "/path/to/hdc"
      }
    }
  }
}
```

#### VS Code 配置

在 `.vscode/mcp.json` 中添加：

```json
{
  "inputs": [],
  "servers": [
    {
      "name": "hdc",
      "command": "node",
      "args": ["/path/to/hdc-mcp-server/dist/index.js"],
      "env": {
        "HDC_MCP_SERVER_PATH": "/path/to/hdc"
      }
    }
  ]
}
```

### 命令行使用

```bash
# 直接运行
npm start

# 或使用 npx
npx hdc-mcp-server

# 指定配置文件
HDC_MCP_CONFIG_PATH=/path/to/config.yaml npm start
```

### 开发模式

```bash
# 开发模式（自动编译）
npm run dev

# 类型检查
npm run typecheck
```

## 使用示例

### 设备管理

```
用户: 查看连接的设备
AI: 我来帮您查看当前连接的设备列表。

[调用 device_list]

发现以下设备：
1. 设备 ID: ABCD1234
   连接类型: USB
   型号: HUAWEI Mate 60
   系统版本: HarmonyOS 4.0
   状态: 已连接
```

### 应用安装

```
用户: 在设备 ABCD1234 上安装 /Users/dev/app.hap
AI: 我来帮您在设备上安装应用。

[调用 app_install]

应用安装成功！
- 包名: com.example.myapp
- 版本: 1.0.0
- 安装路径: /data/app/el1/bundle/public/com.example.myapp
```

### 日志查询

```
用户: 查看 com.example.myapp 的错误日志
AI: 我来帮您查询该应用的错误日志。

[调用 hilog_query]

HiLog 查询结果（Error 级别）：

[2026-02-17 10:23:45.123] E 01234/MyApp: Failed to load resource
[2026-02-17 10:23:46.456] E 01234/MyApp: Network request timeout
```

### 性能分析

```
用户: 分析 com.example.myapp 的 CPU 性能
AI: 我来帮您进行性能分析。

[调用 hiperf_record]
正在录制性能数据... 持续时间: 10秒

[调用 hiperf_report]
性能分析报告：
热点函数：
1. ArkTSFunction::Execute() - 35.2%
2. OHOS::Rosen::RSNode::Render() - 18.7%
3. malloc() - 12.3%
```

### 调试模式

```
用户: 以调试模式启动 com.example.myapp
AI: 我来帮您以调试模式启动该应用。

[调用 aa_attach]
应用已进入调试模式

[调用 aa_start]
启动命令执行成功：
- 包名: com.example.myapp
- Ability: EntryAbility
- 调试模式: 已启用
```

## 项目结构

```
hdc-mcp-server/
├── src/
│   ├── index.ts              # 入口文件
│   ├── server.ts             # MCP Server 实现
│   ├── config.ts             # 配置管理
│   ├── hdc/
│   │   ├── client.ts         # HDC 客户端封装
│   │   ├── commands.ts       # HDC 命令定义
│   │   └── parser.ts         # 输出解析器
│   ├── tools/                # Tools 实现
│   │   ├── device.ts         # 设备管理
│   │   ├── shell.ts          # Shell 命令
│   │   ├── app.ts            # 应用管理
│   │   ├── file.ts           # 文件传输
│   │   ├── port.ts           # 端口转发
│   │   ├── hilog.ts          # HiLog
│   │   ├── hidumper.ts       # HiDumper
│   │   ├── aa.ts             # AA
│   │   ├── bm.ts             # BM
│   │   ├── hiperf.ts         # HiPerf
│   │   ├── hiprofiler.ts     # HiProfiler
│   │   ├── hisysevent.ts     # HiSysEvent
│   │   └── debug.ts          # 调试辅助
│   ├── resources/            # Resources 实现
│   │   ├── devices.ts
│   │   ├── logs.ts
│   │   ├── system.ts
│   │   ├── files.ts
│   │   ├── events.ts
│   │   ├── apps.ts
│   │   ├── process.ts
│   │   └── performance.ts
│   ├── prompts/              # Prompts 模板
│   │   └── templates.ts
│   └── types/                # TypeScript 类型
│       └── index.ts
├── dist/                     # 编译输出
├── bin/                      # CLI 入口
├── config/                   # 配置文件
└── README.md
```

## Tools 列表

### 设备管理
- `device_list` - 列出所有已连接设备
- `device_connect` - TCP 连接设备
- `device_disconnect` - 断开 TCP 设备
- `device_info` - 获取设备详细信息

### Shell
- `shell_exec` - 执行 Shell 命令
- `shell_interactive` - 启动交互式 Shell

### 应用管理
- `app_install` - 安装应用
- `app_uninstall` - 卸载应用
- `app_list` - 列出已安装应用
- `app_start` - 启动应用
- `app_stop` - 停止应用

### 文件传输
- `file_send` - 发送文件到设备
- `file_recv` - 从设备接收文件

### HiLog
- `hilog_query` - 查询日志
- `hilog_clear` - 清除日志
- `hilog_set_level` - 设置日志级别

### HiDumper
- `hidumper_memory` - 查询内存
- `hidumper_cpu` - 查询 CPU
- `hidumper_services` - 查询系统服务
- `hidumper_fault` - 获取故障日志
- `hidumper_jsheap` - JS 堆内存分析

### AA
- `aa_start` - 启动 Ability
- `aa_force_stop` - 强制停止进程
- `aa_attach` - 进入调试模式

### BM
- `bm_dump` - 查询应用信息
- `bm_get_udid` - 获取设备 UDID

### HiPerf
- `hiperf_record` - 录制性能数据
- `hiperf_report` - 生成性能报告

### HiSysEvent
- `hisysevent_query` - 查询系统事件

## Resources

- `hdc://devices` - 设备列表
- `hdc://device/{deviceId}/info` - 设备信息
- `hdc://device/{deviceId}/apps` - 应用列表
- `hdc://device/{deviceId}/logs/hilog` - HiLog 日志
- `hdc://device/{deviceId}/system/memory` - 系统内存
- `hdc://device/{deviceId}/system/cpu` - CPU 信息

## 故障排查

### HDC 命令未找到

```
Error: hdc command not found
```

解决方案：
1. 确认 HarmonyOS SDK 已安装
2. 设置 `HDC_MCP_SERVER_PATH` 环境变量
3. 将 hdc 添加到系统 PATH

### 设备未授权

```
Error: device unauthorized
```

解决方案：
1. 在设备上开启 USB 调试
2. 授权当前电脑
3. 重新插拔 USB

### 权限不足

```
Error: permission denied
```

解决方案：
1. 确认应用使用调试证书签名
2. 检查 hdc shell 权限

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

[MIT](LICENSE)

## 相关资源

- [HarmonyOS 官方文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides)
- [MCP 协议规范](https://modelcontextprotocol.io/)
- [OpenHarmony 项目](https://gitee.com/openharmony)

## 更新日志

### v1.0.0
- 初始版本发布
- 支持完整的 HDC 功能封装
- 支持 HiLog、HiDumper、AA、BM、HiPerf、HiProfiler、HiSysEvent 工具
- 提供 12 个 Prompt 模板