Metadata-Version: 2.4
Name: hypium-mcp
Version: 26.0.0.421
Summary: Hypium Model Context Protocol (MCP) for HarmonyOS device automation
Author-email: Hypium Team <hypium@example.com>
Keywords: harmonyos,automation,mcp,hypium,testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=3.0.0
Requires-Dist: hypium>=6.0.0
Requires-Dist: opencv-contrib-python>=4.8
Requires-Dist: opencv-python>=4.8
Requires-Dist: scikit-learn>=1.5.1
Requires-Dist: rich>=13.0.0
Requires-Dist: pillow>=10.0
Requires-Dist: av>=13.1.0
Requires-Dist: pyyaml>=6.0

# Hypium MCP

Hypium Model Context Protocol (MCP) 服务器，为 HarmonyOS 设备自动化提供强大的工具集。

## 功能特性

- 🚀 **丰富的设备操作工具**：支持点击、滑动、文本输入、手势操作等
- 📱 **应用管理**：应用安装、卸载、启动、停止、信息查询
- 🔍 **屏幕观察**：屏幕截图、布局分析、元素查找
- 🖱️ **鼠标操作**：鼠标点击、移动、滚动等
- 🎯 **系统手势**：返回、主页、通知中心、控制中心
- 🔧 **插件支持**：数据采集、报告生成等插件功能
- 🌐 **多种启动模式**：支持 stdio 和 streamable-http 模式
- ⚙️ **灵活配置**：支持环境变量和配置文件

## 安装

### 环境要求

- Python >= 3.10
- HarmonyOS 设备（已连接并配置 hdc）
- hdc 工具已安装并配置到 PATH

### 使用 pip 安装

```bash
pip install hypium-mcp
```

## 快速开始

### 1. 启动 MCP 服务器

#### 使用 stdio 模式

```bash
python -m hypium_mcp --service-mode stdio
```

#### 使用 HTTP 模式

```bash
python -m hypium_mcp --service-mode streamable-http --port 8000
```

#### 指定设备

```bash
python -m hypium_mcp --device-id <device_serial_number>
```

### 2. 在 Claude Desktop 中配置

在 Claude Desktop 的配置文件中添加：

```json
{
  "mcpServers": {
    "hypium": {
      "command": "python",
      "args": ["-m", "hypium_mcp"],
      "env": {
        "HYPIUM_MCP_DEVICE_ID": "<device_serial_number>"
      }
    }
  }
}
```

### 3. 列出可用工具

```bash
python -m hypium_mcp list
```

## 配置

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `HYPIUM_MCP_SERVER_NAME` | MCP 服务器名称 | `HypiumMCP` |
| `HYPIUM_MCP_SERVICE_MODE` | 服务模式 | `streamable-http` |
| `HYPIUM_MCP_HOST` | HTTP 服务器地址 | `localhost` |
| `HYPIUM_MCP_PORT` | HTTP 服务器端口（http: 8000, streamable-http: 8001, socket: 8002） | `8001` |
| `HYPIUM_MCP_DEVICE_ID` | 设备序列号 | `default` |
| `HYPIUM_MCP_HDC_HOST` | HDC 服务器地址 | `127.0.0.1` |
| `HYPIUM_MCP_HDC_PORT` | HDC 服务器端口 | `8710` |
| `HYPIUM_MCP_HDC_PATH` | HDC 可执行文件路径 | `""` |
| `HYPIUM_MCP_WORKING_DIR` | 工作目录 | `""` |
| `HYPIUM_MCP_OUTPUT_DIR` | 输出目录 | `./reports/hypium_mcp_*` |
| `HYPIUM_MCP_LOG_LEVEL` | 日志级别 | `INFO` |
| `HYPIUM_MCP_LOG_FILE` | 日志文件路径 | `None` |
| `HYPIUM_MCP_LOG_CONSOLE_ENABLE` | 是否启用控制台日志输出 | `True` |
| `HYPIUM_MCP_LOG_FILE_ENABLE` | 是否启用日志文件输出 | `True` |
| `HYPIUM_MCP_LOG_MAX_SIZE` | 单个日志文件最大字节数 | `5242880`（5MB） |
| `HYPIUM_MCP_LOG_MAX_NUM` | 日志文件最大保留数量 | `20` |
| `HYPIUM_MCP_TIMEOUT` | 设备连接超时时间（秒） | `30` |
| `HYPIUM_MCP_EXCLUDE_MODULE` | 全局排除的模块列表（逗号分隔） | `""` |
| `HYPIUM_MCP_INCLUDE_MODULE` | 全局包含的模块列表（逗号分隔） | `""` |
| `HYPIUM_MCP_EXCLUDE_TOOLS` | 全局排除的工具列表（逗号分隔） | `""` |
| `HYPIUM_MCP_INCLUDE_TOOLS` | 全局包含的工具列表（逗号分隔） | `""` |
| `HYPIUM_MCP_COORDINATE_VALUE_MODE` | 坐标值模式（`relative_1000`/`relative_1`/`absolute`） | `relative_1000` |
| `HYPIUM_MCP_COORDINATE_FORMAT` | 坐标参数格式（`combine`: pos=(x,y)，`split`: x, y 分离） | `combine` |
| `HYPIUM_MCP_MODE` | 工具模式 | `phone` |
| `HYPIUM_MCP_TOOLS_MODE_FILE` | 工具模式配置文件路径 | 自动查找 |
| `HYPIUM_MCP_TOOLS_MODE_JSON` | 工具模式 JSON 配置（直接传入） | `None` |
| `HYPIUM_MCP_ADD_LOG_PARAM` | 是否给工具添加日志参数，支持模型把工具调用的意图输出到工具参数中，便于生成步骤报告 | `True` |
| `HYPIUM_MCP_COLLECT_ENABLE` | 是否启用数据采集功能 | `False` |
| `HYPIUM_MCP_APP_CONFIG` | 应用名称映射配置文件路径 | 自动查找 |

### 工具模式配置

通过设置 `HYPIUM_MCP_MODE` 环境变量来指定工具模式，过滤或者保留不部分工具。

**内置模式：**

| 模式名称 | 说明 |
|----------|------|
| `default` | 显示所有支持的工具（无过滤） |
| `device_only` | 仅设备管理工具 |
| `no_gesture` | 排除手势工具 |
| `phone` | 手机操作模式（**默认模式**） |
| `pc` | PC 操作模式 |

**配置说明：**
- 默认模式为 `phone`，可通过设置 `HYPIUM_MCP_MODE=default` 显示所有工具
- 配置文件搜索顺序（优先级从高到低）：
  1. 环境变量 `HYPIUM_MCP_TOOLS_MODE_FILE` 指定的文件路径
  2. 当前工作目录下的 `hypium_mcp_tools_config.json`
  3. 包内默认配置文件 `hypium_mcp/config/hypium_mcp_tools_config.json`

**模块名称参考**：参考下方「支持的工具」小节，每个工具小节标题后括号内即为模块名称。

配置格式：
```json
{
  "模式名称": {
    "include_module": ["模块名1", "模块名2"],
    "exclude_module": ["模块名1", "模块名2"],
    "include_tools": ["工具名1", "工具名2"],
    "exclude_tools": ["工具名1", "工具名2"]
  }
}
```

**自定义配置示例：**

在当前工作目录创建 `hypium_mcp_tools_config.json`：
```json
{
  "custom_mode": {
    "include_module": ["basic", "screen", "observation"],
    "exclude_tools": ["press_key", "clear_app_data"]
  }
}
```

然后设置环境变量使用自定义模式：
```bash
export HYPIUM_MCP_MODE=custom_mode
python -m hypium_mcp
```

或者通过环境变量指定配置文件路径：
```bash
export HYPIUM_MCP_TOOLS_MODE_FILE=/path/to/custom_config.json
export HYPIUM_MCP_MODE=custom_mode
python -m hypium_mcp
```

### 应用名称映射配置

支持通过配置文件映射应用显示名称和包名，便于使用中文名称启动应用。

配置文件搜索路径：
1. `~/.hypium_mcp/app_config.json`（用户目录）
2. `./app_config.json`（当前工作目录）

配置格式：
```json
{
  "bundle_names": {
    "设置": "com.huawei.hmos.settings"
  },
  "main_abilities": {
    "com.huawei.hmos.settings": "com.huawei.hmos.settings.MainAbility"
  }
}
```

配置后可使用显示名称启动应用：
```
start_app("设置")  // 等同于 start_app("com.huawei.hmos.settings")
```

内置支持超过 225 个常用应用的名称映射。

### 坐标说明

所有传入坐标的工具均使用 **0~1000 的归一化坐标**，屏幕左上角为 `(0, 0)`，右下角为 `(1000, 1000)`。

坐标值会根据实际屏幕分辨率自动映射，无需关心设备的具体像素尺寸。例如：
- `(500, 500)` — 屏幕中心
- `(0, 0)` — 屏幕左上角
- `(1000, 1000)` — 屏幕右下角
- `(250, 500)` — 屏幕水平方向 1/4 处、垂直方向居中

#### 传入坐标的工具列表

**基础操作工具 (basic)**

| 工具名 | 坐标参数 | 说明 |
|--------|----------|------|
| `click` | `pos` | 在指定坐标执行点击操作 |
| `long_click` | `pos` | 在指定坐标执行长按操作 |
| `double_click` | `pos` | 在指定坐标执行双击操作 |
| `swipe` | `start`, `end` | 从起点坐标滑动到终点坐标 |
| `drag` | `start`, `end` | 从起点坐标拖拽到终点坐标 |

**鼠标工具 (mouse)**

| 工具名 | 坐标参数 | 说明 |
|--------|----------|------|
| `mouse_click` | `pos` | 鼠标点击 |
| `mouse_double_click` | `pos` | 鼠标双击 |
| `mouse_long_click` | `pos` | 鼠标长按 |
| `mouse_move_to` | `pos` | 鼠标移动到指定坐标 |
| `mouse_move` | `start`, `end` | 鼠标从起点移动到终点 |
| `mouse_drag` | `start`, `end` | 鼠标从起点拖拽到终点 |
| `mouse_scroll` | `pos` | 在指定坐标处鼠标滚动 |

**通用手势工具 (general_gesture)**

| 工具名 | 坐标参数 | 说明 |
|--------|----------|------|
| `pinch_in` | `pos`（可选） | 双指捏合缩小，不传则作用于整个屏幕 |
| `pinch_out` | `pos`（可选） | 双指捏合放大，不传则作用于整个屏幕 |
| `rotate_gesture` | `pos`（可选） | 旋转手势，不传则作用于整个屏幕 |

**系统手势工具 (system_gesture)**

| 工具名 | 坐标参数 | 说明 |
|--------|----------|------|
| `drag_to_xiaoyi` | `pos` | 拖拽指定坐标处的元素到小艺助手 |

## 支持的工具

### 设备管理工具 (device_manager)

| 工具名 | 说明 |
|--------|------|
| `list_devices` | 列出所有已连接的设备 |
| `get_current_device` | 获取当前使用的设备信息 |
| `connect_device` | 连接到指定设备 |
| `release_device` | 释放指定设备 |

### 基础操作工具 (basic)

| 工具名 | 说明 |
|--------|------|
| `click` | 在指定坐标执行点击操作 |
| `long_click` | 在指定坐标执行长按操作 |
| `double_click` | 在指定坐标执行双击操作 |
| `swipe` | 从起点滑动到终点 |
| `drag` | 拖拽操作 |
| `go_back` | 返回操作 |
| `go_home` | 返回主页 |
| `wait` | 等待指定时间 |
| `press_key` | 按下指定按键 |
| `input_text` | 输入文本 |
| `clear_text` | 清除文本 |
| `start_app` | 启动应用程序 |
| `stop_app` | 停止应用程序 |
| `clear_recent_task` | 清除最近任务 |

### 屏幕工具 (screen)

| 工具名 | 说明 |
|--------|------|
| `screen_off` | 关闭屏幕 |
| `screen_on` | 打开屏幕 |
| `unlock_screen` | 解锁屏幕 |
| `rotate_screen` | 旋转屏幕 |

### 观察工具 (observation)

| 工具名 | 说明 |
|--------|------|
| `screenshot` | 获取屏幕截图 |
| `layout` | 获取屏幕布局信息 |
| `find_elements` | 查找满足条件的 UI 元素 |

### 系统手势工具 (system_gesture)

| 工具名 | 说明 |
|--------|------|
| `open_control_center` | 打开控制中心 |
| `open_notification_center` | 打开通知中心 |
| `drag_to_xiaoyi` | 拖拽到小艺助手 |
| `enter_recent_task` | 进入最近任务 |

### 通用手势工具 (general_gesture)

| 工具名 | 说明 |
|--------|------|
| `pinch_in` | 双指捏合缩小 |
| `pinch_out` | 双指捏合放大 |
| `rotate_gesture` | 旋转手势 |

### 鼠标工具 (mouse)

| 工具名 | 说明 |
|--------|------|
| `mouse_click` | 鼠标点击 |
| `mouse_double_click` | 鼠标双击 |
| `mouse_long_click` | 鼠标长按 |
| `mouse_move_to` | 鼠标移动到指定位置 |
| `mouse_move` | 鼠标移动 |
| `mouse_drag` | 鼠标拖拽 |
| `mouse_scroll` | 鼠标滚动 |

### 应用管理工具 (app_manager)

| 工具名 | 说明 |
|--------|------|
| `get_current_app` | 获取当前运行的应用 |
| `has_app` | 检查应用是否已安装 |
| `stop_all_app` | 停止所有应用 |
| `clear_app_data` | 清除应用数据 |
| `install_app` | 安装应用 |
| `uninstall_app` | 卸载应用 |

### Toast 工具 (toast)

| 工具名 | 说明 |
|--------|------|
| `start_listen_toast` | 开始监听 Toast 消息 |
| `get_toast` | 获取 Toast 消息 |

### 插件工具 (plugins)

| 工具名 | 说明 |
|--------|------|
| `start_data_collect` | 开始数据采集 |
| `stop_data_collect` | 停止数据采集 |
| `generate_report` | 生成报告 |

### 键盘工具 (keyboard)

| 工具名 | 说明 |
|--------|------|
| `press_shortcut` | 按下组合快捷键（如 `ctrl+c`、`ctrl+shift+z`、`alt+tab`） |

### 应用管理扩展工具 (app_manager_ext)

| 工具名 | 说明 |
|--------|------|
| `start_app_by_deep_link` | 通过 Deep Link 启动应用 |

### MCP 管理工具 (mcp_manager)

| 工具名 | 说明 |
|--------|------|
| `mcp_clean_up` | 清理 MCP 会话资源 |
