MCP 服务器

harmonyos-dev-mcp

Enables HarmonyOS device discovery, app build and deployment, UI automation, E2E inspection, and log validation through MCP tools.

README

HarmonyOS Dev MCP

harmonyos_dev_mcp provides HarmonyOS MCP tools for device discovery, app build and deployment, UI automation, E2E inspection, and log validation.

What It Provides

The package exposes 18 MCP tools:

Parameter notation:

name: required
name?: optional
name*: conditionally required, depending on the selected mode or target

General tools:

Tool	Parameters
`list_devices`	none
`query_package`	`device_id?`, `bundle_name*`, `keyword?`, `info_type?="list"`
`logs_query`	`device_id?`, `logs?`, `input_file?`, `input_files?`, `lines?=100`, `level?`, `tag?`, `tag_search?`, `keyword?`, `domain?`, `pid?`, `package_name?`, `start_time?`, `end_time?`, `seconds?`, `save_path?`, `time_expr?`, `include_crash?=false`, `mode?="errors"`, `marker_keywords?`, `fallback_to_historical?=false`, `realtime_wait_ms?=1000`, `context_lines?=0`

Build tools:

Tool	Parameters
`build_app`	`project_path`, `build_mode?="debug"`, `target?="hap"`, `product?="default"`, `module_name*`, `is_clean?=false`, `include_hsp?=false`, `hsp_module_names?`
`install_app`	`hap_path`, `device_id?`
`run_app`	`bundle_name`, `device_id?`, `ability_name?`, `module_name?`, `auto_detect?=true`
`uninstall_app`	`bundle_name`, `device_id?`

UI tools:

Tool	Parameters
`screenshot`	`device_id?`, `local_path?`, `display_id?=0`, `left`, `top`, `right`, `bottom`
`click_element`	`device_id?`, `x`, `y`, `element_handle`, `text`, `element_type`, `element_id`, `double_click?=false`, `bundle_name?`
`long_press_element`	`device_id?`, `x`, `y`, `element_handle`, `text`, `element_type`, `element_id`, `bundle_name?`
`input_text`	`device_id?`, `x`, `y`, `text`, `element_handle`, `element_text`, `element_type`, `element_id`, `bundle_name?`
`swipe`	`device_id?`, `from_x`, `from_y`, `to_x`, `to_y`, `direction*`, `speed?=600`
`drag`	`device_id?`, `from_x`, `from_y`, `to_x`, `to_y`, `speed?=600`
`press_key`	`device_id?`, `key`
`find_element`	`device_id?`, `text`, `element_type`, `element_id*`, `bundle_name?`, `window_id?`

E2E tools:

Tool	Parameters
`get_ui_tree`	`device_id?`, `bundle_name?`, `window_id?`
`list_windows`	`device_id?`, `bundle_name?`
`wait_element`	`device_id?`, `bundle_name?`, `window_id?`, `text`, `element_type`, `element_id*`, `state?="found"`, `timeout_ms?=5000`, `interval_ms?=300`

build_app supports HarmonyOS HAP, HAR, HSP, APP, and HNP build flows. HSP outputs can also be integrated into a HAP with include_hsp=true.

Detailed validation rules, result fields, errors, and examples are in the tool reference.

Layout

mcp_ho_dev/
|- src/harmonyos_dev_mcp/
|  |- build/                   # Hvigor build helpers, signing, packaging, and target handlers
|  |- device/hdc/              # HDC device, package, app, file, and UI adapters
|  |- logs/                    # Log query parsing and history support
|  |- runtime/                 # Server factory and explicit MCP tool registration
|  |- tools/                   # Public MCP tool entrypoints
|  |- ui/                      # UI tree parsing, selectors, actions, and normalization
|  |- utils/                   # Compatibility wrappers
|  `- _common/                 # Shared runtime infrastructure bundled in this package
|- tests/unit/                 # Unit tests grouped by domain
|- docs/                       # Public tool and log query documentation
|- scripts/                    # Release helpers
|- pyproject.toml              # Project metadata and build config
|- uv.lock
|- README.md

Requirements

Python 3.12+
DevEco Studio 5.0+
HarmonyOS SDK toolchains, including hdc
uv

Install

Install from PyPI:

pip install harmonyos-dev-mcp

Install from source for local development:

uv sync

Run

uv run harmonyos-dev-mcp

Check connected devices:

hdc list targets

Documentation

Build Examples

Build a debug HAP:

await build_app(r"C:\path\to\project", target="hap", build_mode="debug", product="default")

Build HSP modules and integrate them into a HAP:

await build_app(
    r"C:\path\to\project",
    target="hap",
    build_mode="debug",
    product="default",
    include_hsp=True,
    hsp_module_names=["library_one", "library_two"],
)

Build an HNP-injected HAP:

await build_app(r"C:\path\to\project", target="hnp", build_mode="debug", product="default")

Development

Run unit tests:

uv run pytest tests/unit -v

Run with coverage:

uv run pytest tests/unit -v --cov=harmonyos_dev_mcp

Build package artifacts:

uv build --out-dir dist --clear

Notes

build_app is a long-running tool. Set MCP tools/call timeout to at least 60s, and prefer 120s for cold builds.
build_app target="hnp" builds a base HAP, injects module HNP packages from entry/hnp, and signs the HAP through SDK packaging tools.
build_app target="hsp" builds shared modules; build_app target="hap" include_hsp=true can integrate one or more HSP outputs into the HAP.
logs_query supports errors and markers modes.
The shared infrastructure that used to live in a separate common package is bundled in harmonyos_dev_mcp._common.