@ai-arkts/harmony-tools

MCP (Model Context Protocol) server for HarmonyOS development.
Provides 15 tools for compilation, device control, log collection, UI dump, and documentation search — all accessible via hdc.

Installation

# Run directly (no install needed)
npx @ai-arkts/harmony-tools

Or install globally:

npm install -g @ai-arkts/harmony-tools
harmony-tools

Prerequisites

• Node.js >= 18
• DevEco Studio installed (for hdc, hvigorw, SDK)
• HarmonyOS device connected via USB/Wi-Fi
• Set DEVECO_HOME environment variable to DevEco Studio install path (auto-detected on Windows)

MCP Configuration

Add to your MCP client config:

{
  "mcpServers": {
    "harmony-tools": {
      "command": "npx",
      "args": ["@ai-arkts/harmony-tools"]
    }
  }
}

Tools

Documentation

| Tool | Description | |---|---| | search_hmos_doc | Search HarmonyOS official documentation by keyword | | fetch_hmos_doc | Fetch a doc page by URL and extract targeted sections | | read_hmos_doc | Read a doc section by object_id and optional section_id |

Build & Deploy

| Tool | Description | |---|---| | hmos_compilation | Compile HarmonyOS project with hvigorw (assembleHap) | | hmos_run | Build → install HAP → launch app in one step |

Device Operations

| Tool | Description | |---|---| | device_tap | Tap at screen coordinates | | device_double_tap | Double tap at coordinates | | device_swipe | Swipe from (x1,y1) to (x2,y2) | | device_press_key | Press key (Home / Back) | | device_input_text | Input text at coordinates (auto-clears existing content) | | device_long_click | Long click at coordinates | | device_start_app | Start an app by bundle name | | device_sleep | Wait for a duration (ms) | | device_dump_ui | Get current page UI tree as JSON (for precise element positioning) |

Diagnostics

| Tool | Description | |---|---| | hdc_log | Collect / clear / list device logs via hilog | | hmos_jscrash_report | Analyze ArkTS/JS crash logs into error type, stack, suspected file |

Key Features

🔑 UI Tree Coordinate Enhancement

Instead of relying solely on model "guessed" coordinates from screenshots, device_dump_ui retrieves the exact UI control tree, enabling precise element targeting by bounds:

1. Call device_dump_ui → get UI tree JSON
2. Search tree for target element by text/type/description
3. Extract bounds: [x1,y1][x2,y2]
4. Click center: ((x1+x2)/2, (y1+y2)/2)

🔑 Log-Based Verification

Combine with hdc_log and hmos_jscrash_report for non-UI functional testing — collect app logs by bundle name (filtered by PID) and verify against expected patterns.

Quick Start

Build and Run an App

hmos_compilation(project_abs_path="D:/MyProject")
hmos_run(project_abs_path="D:/MyProject", build_mode="debug")

Collect App Logs

hdc_log(action="clear")
# ... perform operations ...
hdc_log(action="collect", bundle_name="com.example.app", log_prefix="[MY_APP]")

Analyze a Crash

hdc_log(action="collect", lines=4000)
hmos_jscrash_report(crash_log="<collected logs>")

Search Documentation

search_hmos_doc(keyword="ArkTS @State", catalog="harmonyos-guides")

Environment Variables

| Variable | Required | Description | |---|---|---| | DEVECO_HOME | Auto-detected | DevEco Studio install path | | PATH | — | Must include hdc/hvigorw/node if DEVECO_HOME is not set |

Auto-detection paths (Windows):

• C:\Program Files\DevEco Studio
• C:\Program Files (x86)\DevEco Studio
• %USERPROFILE%\DevEco Studio

Package Contents

bin/run.js              ← CLI entry point (node --import tsx)
src/index.ts            ← MCP server (stdio transport)
src/lib/
├── hmos_env.ts         ← DevEco env detection, hdc path resolution
├── hmos_doc_api.ts     ← HarmonyOS doc API client
├── hmos_doc_cache.ts   ← Doc cache & section parser
└── runCmd.ts           ← Cross-platform subprocess wrapper
src/tools/              ← 15 MCP tool implementations
src/devices/
└── harmony.ts          ← HarmonyDevice: hdc device abstraction

Acknowledgement

Most of the tools in this project are extracted and adapted from the codegenie-test project. Key adaptations:

• Plugin tool format → MCP protocol: Converted custom tool definitions to standard MCP (Model Context Protocol)
• Runtime adaptation: Replaced platform-specific APIs with standard Node.js child_process.spawn and fs/promises
• Reusable device abstraction: Extracted HarmonyDevice class with UI tree dump (device_dump_ui) and PID-based log filtering
• Added 8 device operation MCP tools: tap, doubleTap, swipe, pressKey, inputText, longClick, startApp, sleep

Related

• @ai-arkts — HarmonyOS tooling organization
• harmony-test-agent — E2E automation test agent definition
• E2E Auto Test Skill — Orchestration skill for automated end-to-end testing

License

MIT