{"_id":"@ai-arkts/harmony-tools","name":"@ai-arkts/harmony-tools","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@ai-arkts/harmony-tools","version":"1.0.0","description":"MCP server for HarmonyOS development — compilation, device control, hdc log, UI dump, doc search","type":"module","bin":{"harmony-tools":"bin/run.js"},"publishConfig":{"access":"public"},"main":"dist/index.js","scripts":{"start":"node --import tsx/esm src/index.ts","typecheck":"node --import tsx/esm ./node_modules/typescript/lib/tsc.js --noEmit","prepublishOnly":"node --import tsx/esm ./node_modules/typescript/lib/tsc.js --noEmit","prepack":"node --import tsx/esm ./node_modules/typescript/lib/tsc.js --noEmit"},"keywords":["harmonyos","harmony","hdc","mcp","model-context-protocol","dev-eco","openharmony","automation","testing"],"repository":{"type":"git","url":"git+https://github.com/MoonlitDropOfBlood/harmony-tools.git"},"author":"","license":"MIT","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.9.0","tsx":"^4.19.0"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.7.0"},"gitHead":"69ecdbeb6fcba92f4bf1d236fd8a0b053fb0c426","_id":"@ai-arkts/harmony-tools@1.0.0","bugs":{"url":"https://github.com/MoonlitDropOfBlood/harmony-tools/issues"},"homepage":"https://github.com/MoonlitDropOfBlood/harmony-tools#readme","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-wUGLs2YAgZ8IwkY1bvkD4YVH3KJUKAP6dCsR1Y/Hx4N4b7DwnSR06YSZsHtCuIHS+93N+hBat1kfbRb7KqTgHw==","shasum":"9548b6803192a9f34d895c428958a28aac4b1c18","tarball":"https://registry.npmjs.org/@ai-arkts/harmony-tools/-/harmony-tools-1.0.0.tgz","fileCount":19,"unpackedSize":80021,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCLbRYKeirqraLkqsHlgmCPMIM7ICqLUCeDE1H3uy/4BwIhAP6jFXqH7sdBvWI8iBcfqHuAU6bK34tGjTG0P8Cva+3N"}]},"_npmUser":{"name":"dukebywwh","email":"wwhbygx@sina.com"},"directories":{},"maintainers":[{"name":"dukebywwh","email":"wwhbygx@sina.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/harmony-tools_1.0.0_1780508565456_0.8985161909405028"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-03T17:42:45.298Z","1.0.0":"2026-06-03T17:42:45.641Z","modified":"2026-06-03T17:42:45.878Z"},"maintainers":[{"name":"dukebywwh","email":"wwhbygx@sina.com"}],"description":"MCP server for HarmonyOS development — compilation, device control, hdc log, UI dump, doc search","homepage":"https://github.com/MoonlitDropOfBlood/harmony-tools#readme","keywords":["harmonyos","harmony","hdc","mcp","model-context-protocol","dev-eco","openharmony","automation","testing"],"repository":{"type":"git","url":"git+https://github.com/MoonlitDropOfBlood/harmony-tools.git"},"bugs":{"url":"https://github.com/MoonlitDropOfBlood/harmony-tools/issues"},"license":"MIT","readme":"# @ai-arkts/harmony-tools\n\n[![npm version](https://img.shields.io/npm/v/@ai-arkts/harmony-tools)](https://www.npmjs.com/package/@ai-arkts/harmony-tools)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n**MCP (Model Context Protocol) server for HarmonyOS development.**  \nProvides 15 tools for compilation, device control, log collection, UI dump, and documentation search — all accessible via hdc.\n\n---\n\n## Installation\n\n```bash\n# Run directly (no install needed)\nnpx @ai-arkts/harmony-tools\n```\n\nOr install globally:\n\n```bash\nnpm install -g @ai-arkts/harmony-tools\nharmony-tools\n```\n\n## Prerequisites\n\n- **Node.js >= 18**\n- **DevEco Studio** installed (for hdc, hvigorw, SDK)\n- **HarmonyOS device** connected via USB/Wi-Fi\n- Set `DEVECO_HOME` environment variable to DevEco Studio install path (auto-detected on Windows)\n\n---\n\n## MCP Configuration\n\nAdd to your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"harmony-tools\": {\n      \"command\": \"npx\",\n      \"args\": [\"@ai-arkts/harmony-tools\"]\n    }\n  }\n}\n```\n\n---\n\n## Tools\n\n### Documentation\n\n| Tool | Description |\n|---|---|\n| `search_hmos_doc` | Search HarmonyOS official documentation by keyword |\n| `fetch_hmos_doc` | Fetch a doc page by URL and extract targeted sections |\n| `read_hmos_doc` | Read a doc section by object_id and optional section_id |\n\n### Build & Deploy\n\n| Tool | Description |\n|---|---|\n| `hmos_compilation` | Compile HarmonyOS project with hvigorw (assembleHap) |\n| `hmos_run` | Build → install HAP → launch app in one step |\n\n### Device Operations\n\n| Tool | Description |\n|---|---|\n| `device_tap` | Tap at screen coordinates |\n| `device_double_tap` | Double tap at coordinates |\n| `device_swipe` | Swipe from (x1,y1) to (x2,y2) |\n| `device_press_key` | Press key (Home / Back) |\n| `device_input_text` | Input text at coordinates (auto-clears existing content) |\n| `device_long_click` | Long click at coordinates |\n| `device_start_app` | Start an app by bundle name |\n| `device_sleep` | Wait for a duration (ms) |\n| `device_dump_ui` | Get current page UI tree as JSON (for precise element positioning) |\n\n### Diagnostics\n\n| Tool | Description |\n|---|---|\n| `hdc_log` | Collect / clear / list device logs via hilog |\n| `hmos_jscrash_report` | Analyze ArkTS/JS crash logs into error type, stack, suspected file |\n\n---\n\n## Key Features\n\n### 🔑 UI Tree Coordinate Enhancement\n\nInstead of relying solely on model \"guessed\" coordinates from screenshots, `device_dump_ui` retrieves the exact UI control tree, enabling precise element targeting by bounds:\n\n```\n1. Call device_dump_ui → get UI tree JSON\n2. Search tree for target element by text/type/description\n3. Extract bounds: [x1,y1][x2,y2]\n4. Click center: ((x1+x2)/2, (y1+y2)/2)\n```\n\n### 🔑 Log-Based Verification\n\nCombine 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.\n\n---\n\n## Quick Start\n\n### Build and Run an App\n\n```\nhmos_compilation(project_abs_path=\"D:/MyProject\")\nhmos_run(project_abs_path=\"D:/MyProject\", build_mode=\"debug\")\n```\n\n### Collect App Logs\n\n```\nhdc_log(action=\"clear\")\n# ... perform operations ...\nhdc_log(action=\"collect\", bundle_name=\"com.example.app\", log_prefix=\"[MY_APP]\")\n```\n\n### Analyze a Crash\n\n```\nhdc_log(action=\"collect\", lines=4000)\nhmos_jscrash_report(crash_log=\"<collected logs>\")\n```\n\n### Search Documentation\n\n```\nsearch_hmos_doc(keyword=\"ArkTS @State\", catalog=\"harmonyos-guides\")\n```\n\n---\n\n## Environment Variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `DEVECO_HOME` | Auto-detected | DevEco Studio install path |\n| `PATH` | — | Must include hdc/hvigorw/node if DEVECO_HOME is not set |\n\nAuto-detection paths (Windows):\n- `C:\\Program Files\\DevEco Studio`\n- `C:\\Program Files (x86)\\DevEco Studio`\n- `%USERPROFILE%\\DevEco Studio`\n\n---\n\n## Package Contents\n\n```\nbin/run.js              ← CLI entry point (node --import tsx)\nsrc/index.ts            ← MCP server (stdio transport)\nsrc/lib/\n├── hmos_env.ts         ← DevEco env detection, hdc path resolution\n├── hmos_doc_api.ts     ← HarmonyOS doc API client\n├── hmos_doc_cache.ts   ← Doc cache & section parser\n└── runCmd.ts           ← Cross-platform subprocess wrapper\nsrc/tools/              ← 15 MCP tool implementations\nsrc/devices/\n└── harmony.ts          ← HarmonyDevice: hdc device abstraction\n```\n\n---\n\n## Acknowledgement\n\nMost of the tools in this project are extracted and adapted from the [codegenie-test](https://gitcode.com/codegenie/codegenie-test) project. Key adaptations:\n\n- **Plugin tool format → MCP protocol**: Converted custom tool definitions to standard MCP (Model Context Protocol)\n- **Runtime adaptation**: Replaced platform-specific APIs with standard Node.js `child_process.spawn` and `fs/promises`\n- **Reusable device abstraction**: Extracted `HarmonyDevice` class with UI tree dump (`device_dump_ui`) and PID-based log filtering\n- **Added 8 device operation MCP tools**: tap, doubleTap, swipe, pressKey, inputText, longClick, startApp, sleep\n\n---\n\n## Related\n\n- [@ai-arkts](https://www.npmjs.com/~ai-arkts) — HarmonyOS tooling organization\n- [harmony-test-agent](harmony-test-agent.md) — E2E automation test agent definition\n- [E2E Auto Test Skill](skills/e2e-auto-test/SKILL.md) — Orchestration skill for automated end-to-end testing\n\n---\n\n## License\n\nMIT","readmeFilename":"README.md","_rev":"1-21ef9d57245aa66b712af408d90bc8a5"}