What can you do with this server?

This server provides MCP tools for HarmonyOS device discovery, app build/deploy, UI automation, E2E inspection, and log validation. * Discover connected devices and query installed package/bundle info. * Build HarmonyOS artifacts (HAP/HAR/HSP/APP/HNP), optionally integrating HSP/HNP modules. * Install, launch, and uninstall apps on devices or over wireless HDC endpoints. * Capture screenshots and inspect the UI tree, windows, and elements. * Automate UI interactions: click, long press, input text, swipe, drag, press key, and find/wait for elements. * Query device logs for errors or business markers with advanced filters, historical fallback, and context lines.

Which integrations are available for this server?

Provides tools for HarmonyOS app development, including building, deploying, UI automation, and logging for HarmonyOS devices.

How do I use harmonyos-dev-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@harmonyos-dev-mcp build my project and install on the connected device" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

harmonyos-dev-mcp

by Deslord319

Overview Schema Source Related Servers Discussions Admin

Python

Local

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 PyPI Python

What It Provides

The package exposes 18 MCP tools:

0.10.0 highlights

Run all 18 MCP tools directly on HarmonyOS with a pure-Python stdio server, bundled dependency stubs, and direct TCP HDC transport.
Route HDC commands through TCP when HDC_USE_TCP=1, including the shell prefix required by the TCP protocol.
Transfer files over TCP in parallel chunks for substantially faster device deployment.
Detect HarmonyOS SDK toolchains and use HARMONYOS_NODE_PATH without colliding with the standard Node.js NODE_PATH variable.
Verify input_text results on composite UI components as well as ordinary text fields.

Parameter notation:

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

Device-targeted tools also accept hdc_server? for wireless debugging by IP. Pass the wireless HDC endpoint, for example 192.168.43.34:35215, to route commands as hdc -t 192.168.43.34:35215 .... If both a device SN and an IP endpoint are needed, pass device_id as the SN and hdc_server as the IP endpoint; commands are routed as hdc -t <SN> -s <IP:port> .... You can also set HARMONYOS_HDC_SERVER as a default endpoint.

General tools:

Tool	Parameters
`list_devices`	`hdc_server?`
`query_package`	`device_id?`, `hdc_server?`, `bundle_name*`, `keyword?`, `info_type?="list"`
`logs_query`	`device_id?`, `hdc_server?`, `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?`, `hdc_server?`
`run_app`	`bundle_name`, `device_id?`, `hdc_server?`, `ability_name?`, `module_name?`, `auto_detect?=true`
`uninstall_app`	`bundle_name`, `device_id?`, `hdc_server?`

UI tools:

Tool	Parameters
`screenshot`	`device_id?`, `hdc_server?`, `local_path?`, `display_id?=0`, `left`, `top`, `right`, `bottom`
`click`	`device_id?`, `hdc_server?`, `x`, `y`, `element_handle`, `text`, `element_type`, `element_id`, `count?=1`, `bundle_name?`
`long_press`	`device_id?`, `hdc_server?`, `x`, `y`, `element_handle`, `text`, `element_type`, `element_id`, `bundle_name?`
`input_text`	`text`, `device_id?`, `hdc_server?`, `x`, `y`, `element_handle`, `element_text`, `element_type`, `element_id`, `bundle_name?`, `mode?="replace"`
`swipe`	`device_id?`, `hdc_server?`, `from_x`, `from_y`, `to_x`, `to_y`, `direction*`, `speed?=600`
`drag`	`device_id?`, `hdc_server?`, `from_x`, `from_y`, `to_x`, `to_y`, `speed?=600`
`press_key`	`key`, `modifiers?`, `device_id?`, `hdc_server?`
`find_elements`	`device_id?`, `hdc_server?`, `text`, `element_type`, `element_id*`, `bundle_name?`, `window_id?`

press_key accepts all 354 OpenHarmony InputKit KEYCODE_* definitions. Key names are case- and separator-insensitive, so KEYCODE_PAGE_UP, PageUp, and page-up are equivalent. Use input_text for strings and Chinese text.

click and long_press report dispatched=true, effect_verified=false when the device accepts the command. This confirms delivery, not an application state change.

For reliable text entry, call find_elements or wait_for_element first and pass the returned element_handle to input_text. A search target is also verified when it resolves to exactly one element. Coordinate mode cannot read the target value, so it sends the original text without cleanup tricks and returns dispatched=true, verified=false.

input_text never toggles the active IME. Internally it uses direct entry for short ASCII digits, native paste for Unicode or long text, and a verified sentinel-assisted paste for other ASCII text. The sentinel is removed only after the exact sentinel-bearing value is observed. Paste strategies may replace the device clipboard; check clipboard_modified in the result.

Handle and search modes first click the target, then observe both focused=true and a foreground target window before dispatching text. Set INPUT_FOCUS_TIMEOUT_MS to change the default 5000ms focus budget. A background or occluded target that does not acquire focus returns INPUT_FOCUS_TIMEOUT without dispatching text.

Input verification also uses a deadline rather than a fixed delay. Set INPUT_VERIFY_TIMEOUT_MS to change the default 15000ms value budget. Successful observations return immediately. Password fields and some Web/Chromium accessibility fields may not expose or accept deterministic text operations; these return a verification error with the last observed actual_text instead of claiming success. A failed write may still leave partial text in the target.

E2E tools:

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

wait_for_element.timeout_ms is a strict wall-clock budget covering device queries, polling sleeps, and the stability confirmation. When the budget expires, the tool returns WAIT_TIMEOUT without starting another observation; timeout_ms=0 returns immediately without querying the device.

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
|  |- harmonyos/               # HarmonyOS on-device adapter (TCP hdc client + standalone MCP server + stubs)
|  `- _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

HarmonyOS on-device (additional)

No DevEco Studio or pip/uv needed — stubs are bundled in-repo
hdc server must be started in TCP mode from HiShell (see Run)

Install

Install from PyPI:

pip install harmonyos-dev-mcp

Install from source for local development:

uv sync

Use uv run for development commands so Python resolves this checkout instead of another globally installed harmonyos-dev-mcp version:

uv run python -c "import harmonyos_dev_mcp; print(harmonyos_dev_mcp.__file__)"

Run

Windows / macOS

uv run harmonyos-dev-mcp

HarmonyOS (On-Device)

On HarmonyOS devices, the sandbox blocks subprocess hdc calls (UDS isolation) and Python native extensions (pydantic_core .so blocked by SELinux). The harmonyos/ adapter solves both:

TCP hdc client — connects to hdc server over TCP directly, no subprocess
Standalone MCP server — pure Python JSON-RPC over stdio, no fastmcp
Bundled stubs — fastmcp/mcp/loguru stubs shipped in-repo

All 18 tools work without modification — hdc_base.py checks HDC_USE_TCP=1 and routes commands through TCP instead of subprocess.

Prerequisites (one-time, in HiShell):

hdc -s 0.0.0.0:8710 start -r
hdc tconn 127.0.0.1:$(param get persist.hdc.port)

Run:

HDC_USE_TCP=1 \
HARMONYOS_HDC_SERVER=127.0.0.1:8710 \
PYTHONPATH=<repo>/src/harmonyos_dev_mcp/harmonyos/stubs:<repo>/src \
python3 -c "from harmonyos_dev_mcp.harmonyos.mcp_server import main; main()"

python3 -m and script-file invocation fail on HarmonyOS due to libpython3.12.so not loading in subprocess context. Use -c instead.

One-command setup (auto-detects Python, SDK, hdc; outputs importable JSON):

bash src/harmonyos_dev_mcp/harmonyos/setup.sh

Check connected devices:

hdc list targets

Use wireless debugging by IP:

await list_devices(hdc_server="192.168.43.34:35215")
await install_app(r"C:\path\to\app.hap", hdc_server="192.168.43.34:35215")

Or set a default endpoint:

set HARMONYOS_HDC_SERVER=192.168.43.34:35215

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.
On HarmonyOS devices, set HDC_USE_TCP=1 to switch from subprocess hdc calls to direct TCP connections. This bypasses the sandbox UDS isolation. See HarmonyOS (On-Device) for details.

License

Apache License 2.0

Available Tools

18 tools

build_appC

Build HarmonyOS artifact.

ParametersJSON Schema

Name	Required	Default
`target`	No	hap
`product`	No	default
`is_clean`	No
`build_mode`	No	debug
`include_hsp`	No
`module_name`	No
`project_path`	Yes
`hsp_module_names`	No

TDQS

C2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. 'Build' implies a write operation, but there is no mention of whether it is destructive, requires specific permissions, or has side effects (e.g., cleaning previous builds). The schema includes 'is_clean' but description does not address it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely short (4 words), which is under-specification rather than efficient conciseness. It fails to include necessary details that would fit in a concise but informative description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 8 parameters, no output schema, and no parameter descriptions, the description is grossly inadequate. It does not explain what the tool returns, how to interpret results, or any constraints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning the description must compensate for explaining all 8 parameters. It provides zero information about parameters like target, product, build_mode, etc., leaving the agent with no additional semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Build HarmonyOS artifact' provides a verb (build) and a resource (HarmonyOS artifact), making the general purpose clear. However, it lacks specificity about what kind of artifact (e.g., HAP, HAR) and does not differentiate from sibling tools like run_app or install_app.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, context (e.g., need for a configured project), or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

click_elementD

ParametersJSON Schema

Name	Required	Description	Default
`x`	No
`y`	No
`text`	No
`device_id`	No
`element_id`	No
`hdc_server`	No
`bundle_name`	No
`double_click`	No
`element_type`	No
`element_handle`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

dragD

ParametersJSON Schema

Name	Required	Description	Default
`to_x`	No
`to_y`	No
`speed`	No
`from_x`	No
`from_y`	No
`device_id`	No
`hdc_server`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_elementD

ParametersJSON Schema

Name	Required	Description	Default
`text`	No
`device_id`	No
`window_id`	No
`element_id`	No
`hdc_server`	No
`bundle_name`	No
`element_type`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_ui_treeD

ParametersJSON Schema

Name	Required	Description	Default
`device_id`	No
`window_id`	No
`hdc_server`	No
`bundle_name`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

input_textD

ParametersJSON Schema

Name	Required	Description	Default
`x`	No
`y`	No
`text`	No
`device_id`	No
`element_id`	No
`hdc_server`	No
`bundle_name`	No
`element_text`	No
`element_type`	No
`element_handle`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

install_appD

ParametersJSON Schema

Name	Required	Description	Default
`hap_path`	Yes
`device_id`	No
`hdc_server`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_devicesD

ParametersJSON Schema

Name	Required	Description	Default
`hdc_server`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_windowsD

ParametersJSON Schema

Name	Required	Description	Default
`device_id`	No
`hdc_server`	No
`bundle_name`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

logs_queryC

Query HarmonyOS logs for errors or business markers.

Default mode focuses on actionable errors. Use mode="markers" to confirm success or failure markers such as picker save results.

ParametersJSON Schema

Name	Required	Default
`pid`	No
`tag`	No
`logs`	No
`mode`	No	errors
`level`	No
`lines`	No
`domain`	No
`keyword`	No
`seconds`	No
`end_time`	No
`device_id`	No
`save_path`	No
`time_expr`	No
`hdc_server`	No
`input_file`	No
`start_time`	No
`tag_search`	No
`input_files`	No
`package_name`	No
`context_lines`	No
`include_crash`	No
`marker_keywords`	No
`realtime_wait_ms`	No
`fallback_to_historical`	No

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only mentions default behavior (error-focused) and a mode for markers, but does not disclose read-only nature, side effects, rate limits, or authentication needs. The 24 parameters are not addressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

While the description is concise (2 sentences), it is under-specified for a tool with 24 parameters. It lacks structure and does not earn its place by adding value beyond the name. Additional sentences or bullet points for key parameters would improve it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high parameter count (24), no schema descriptions, no output schema, and no annotations, the description is severely incomplete. It does not explain return format, filtering logic, time ranges, or how to use most parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only covers the 'mode' parameter minimally. Over 20 parameters (e.g., pid, tag, lines, keyword) are completely undocumented, providing virtually no semantic guidance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool queries HarmonyOS logs for errors or business markers, with a specific verb and resource. It distinguishes from sibling tools (UI actions/app management) by focusing on log querying.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: default mode for errors and explicit guidance on using mode parameter for markers. However, it does not explicitly state when not to use this tool or reference alternatives, though sibling differentiation is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

long_press_elementD

ParametersJSON Schema

Name	Required	Description	Default
`x`	No
`y`	No
`text`	No
`device_id`	No
`element_id`	No
`hdc_server`	No
`bundle_name`	No
`element_type`	No
`element_handle`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

press_keyD

ParametersJSON Schema

Name	Required	Description	Default
`key`	No
`device_id`	No
`hdc_server`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_packageD

ParametersJSON Schema

Name	Required	Default
`keyword`	No
`device_id`	No
`info_type`	No	list
`hdc_server`	No
`bundle_name`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_appD

ParametersJSON Schema

Name	Required	Description	Default
`device_id`	No
`hdc_server`	No
`auto_detect`	No
`bundle_name`	Yes
`module_name`	No
`ability_name`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

screenshotD

ParametersJSON Schema

Name	Required	Description	Default
`top`	No
`left`	No
`right`	No
`bottom`	No
`device_id`	No
`display_id`	No
`hdc_server`	No
`local_path`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

swipeD

ParametersJSON Schema

Name	Required	Description	Default
`to_x`	No
`to_y`	No
`speed`	No
`from_x`	No
`from_y`	No
`device_id`	No
`direction`	No
`hdc_server`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

uninstall_appD

ParametersJSON Schema

Name	Required	Description	Default
`device_id`	No
`hdc_server`	No
`bundle_name`	Yes

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

wait_elementD

ParametersJSON Schema

Name	Required	Default
`text`	No
`state`	No	found
`device_id`	No
`window_id`	No
`element_id`	No
`hdc_server`	No
`timeout_ms`	No
`bundle_name`	No
`interval_ms`	No
`element_type`	No

TDQS

D1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

18 tool updatesv0.8.3Jun 27, 2026
- First observedbuild_app
- First observedclick_element
- First observeddrag
- First observedfind_element
- First observedget_ui_tree
- First observedinput_text
- First observedinstall_app
- First observedlist_devices
- First observedlist_windows
- First observedlogs_query
- First observedlong_press_element
- First observedpress_key
- First observedquery_package
- First observedrun_app
- First observedscreenshot
- First observedswipe
- First observeduninstall_app
- First observedwait_element

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

D1.6/5.0

Scored 2026-06-27 03:10 across 18 tools

Disambiguation2/5

Many tools (e.g., click_element, drag, find_element) lack descriptions, making them indistinguishable. Even with names, similar actions (press_key vs click_element) are ambiguous without documentation.

Naming Consistency2/5

Naming patterns are mixed: verb_noun (click_element, install_app) appears, but also single words (screenshot, swipe) and object_verb (logs_query). Inconsistent convention hinders predictability.

Tool Count4/5

With 18 tools, the count is slightly above the ideal 3–15 range for a focused server, but still reasonable for UI automation and app lifecycle management. Not excessive.

Completeness3/5

The tools cover basic CI/CD and UI automation (build, install, uninstall, run, UI interactions, logs). However, missing descriptions and lack of update/debug tools suggest notable gaps in full lifecycle support.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

HuaweiCloud DevKit (Community Preview)
io.github.glqff
Community preview of HuaweiCloud DevKit MCP server (official: io.github.huaweicloud)
Cloud Platforms Developer Tools
1
Appcircle MCP
io.appcircle
MCP server for Appcircle mobile CI/CD platform.
CI/CD & DevOps Developer Tools
2
androidcliagentgate-mcp
com.clauxel.androidcliagentgate
Remote MCP for Android CLI agent build gate, structured receipts, audit logs, and reviewer-ready evi
Developer Tools CI/CD & DevOps Command Line
2
Os Automation Mcp C
io.github.varvararatta
MCP server for OS Automation
OS Automation Command Line
2

Related MCP Servers

Android UI Agent MCP Server
App Automation Testing & QA Tools
physics91
F
license
Not graded
quality
D
maintenance
Provides Android UI automation tools via MCP, enabling device interaction, UI snapshot, and gesture recording.
Updated 8 months ago (2026-01-16 04:50 UTC)
-
MCP Security Server
Developer Tools File Systems
danduh
A
license
B
quality
C
maintenance
Enables file operations, npm package management, and configuration checking through MCP.
Updated 4 days ago (2026-09-19 14:56 UTC)
10
4 npm
1
MIT
local-docker-mcp
Virtualization Code Execution Developer Tools
Jatin-Gurwani
F
license
Not graded
quality
D
maintenance
Enables Docker container management and test execution via MCP tools, supporting image building, container operations, and automated test runs.
Updated 2 months ago (2026-07-21 16:23 UTC)
-
haplane
Developer Tools Command Line
LeonTing1010
A
license
Not graded
quality
B
maintenance
MCP server for automating HarmonyOS HAP signing, installation, and verification on devices, enabling natural-language-driven deployment workflows.
Updated 2 months ago (2026-07-27 09:02 UTC)
72 npm
MIT

HarmonyOS Dev MCP

Links

What It Provides

0.10.0 highlights

Layout

Requirements

HarmonyOS on-device (additional)

Install

Run

Windows / macOS

HarmonyOS (On-Device)

Documentation

Build Examples

Development

Notes

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers