Metadata-Version: 2.4
Name: harmonyos-dev-mcp
Version: 0.8.1
Summary: HarmonyOS MCP service for device automation, app deployment, UI interaction, E2E support, and log validation.
Project-URL: Homepage, https://github.com/Deslord319/harmonyos-dev-mcp
Project-URL: Repository, https://github.com/Deslord319/harmonyos-dev-mcp
Project-URL: Documentation, https://github.com/Deslord319/harmonyos-dev-mcp/tree/main/docs
Project-URL: Issues, https://github.com/Deslord319/harmonyos-dev-mcp/issues
Author-email: huduanmu <772927148@qq.com>
Requires-Python: >=3.12
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: loguru>=0.7.0
Description-Content-Type: text/markdown

# HarmonyOS Dev MCP

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

[![Version](https://img.shields.io/badge/version-0.8.1-blue)](pyproject.toml)
[![PyPI](https://img.shields.io/pypi/v/harmonyos-dev-mcp.svg)](https://pypi.org/project/harmonyos-dev-mcp/)
[![Python](https://img.shields.io/badge/python-3.12+-blue)](https://www.python.org/)

## Links

- PyPI: [harmonyos-dev-mcp](https://pypi.org/project/harmonyos-dev-mcp/)
- Tool reference: [docs/tool_reference.md](docs/tool_reference.md)
- Logs query guide: [docs/logs_query.md](docs/logs_query.md)

## 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](docs/tool_reference.md).

## Layout

```text
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:

```bash
pip install harmonyos-dev-mcp
```

Install from source for local development:

```bash
uv sync
```

## Run

```bash
uv run harmonyos-dev-mcp
```

Check connected devices:

```bash
hdc list targets
```

## Documentation

- [Tool Reference](docs/tool_reference.md)
- [Logs Query Guide](docs/logs_query.md)

## Build Examples

Build a debug HAP:

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

Build HSP modules and integrate them into a HAP:

```python
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:

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

## Development

Run unit tests:

```bash
uv run pytest tests/unit -v
```

Run with coverage:

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

Build package artifacts:

```bash
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`.

## License

Apache License 2.0
