@deveco-codegenie/mcp 0.1.8-fix1 → 0.1.8-fix3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +334 -334
  2. package/index.js +42 -42
  3. package/package.json +5 -5
package/README.md CHANGED
@@ -1,334 +1,334 @@
1
- # mcp-server
2
-
3
- 基于MCP协议，将 HarmonyOS 开发工具链封装为标准 MCP 工具，供 AI 助手调用。
4
-
5
- ---
6
-
7
- ## 目录
8
-
9
- - [配置方式](#配置方式)
10
- - [环境变量配置](#环境变量配置)
11
- - [工程路径配置](#工程路径配置)
12
- - [主要功能](#主要功能)
13
- - [ArkTS 代码检查](#1-arkts-代码检查-check_ets_files)
14
- - [构建 HAP/HSP/HAR](#2-构建-haphsphar-build_project)
15
- - [启动应用](#3-启动应用-start_app仅-windows--macos)
16
- - [UI 树获取](#4-ui-树获取-get_app_ui_treewindows--macos)
17
- - [UI 操作](#5-ui-操作-perform_ui_actionwindows--macos)
18
- - [UI 自动化校验](#6-ui-自动化校验-verify_ui--get_ui_verification_log--save_ui_screenshot仅-windows--macos)
19
- - [HiLog 日志采集](#7-hilog-日志采集windows--macos)
20
- - [HarmonyOS 知识库搜索](#8-harmonyos-知识库搜索-harmonyos_knowledge_searchwindows--macos)
21
- - [平台支持](#平台支持)
22
-
23
- ---
24
-
25
- ## 配置方式
26
-
27
- 服务启动时按以下优先级加载配置，任意一种成功即停止继续尝试。
28
-
29
- ### 环境变量配置
30
-
31
- 服务优先读取以下环境变量来定位工具链安装目录：
32
-
33
- | 环境变量 | 适用平台 | 说明 |
34
- |----------|----------|------|
35
- | `DEVECO_PATH` | Windows / macOS | DevEco Studio 安装根目录，优先级最高 |
36
-
37
- **示例（macOS）：**
38
-
39
- ```bash
40
- export DEVECO_PATH="/Applications/DevEco-Studio.app/Contents"
41
- ```
42
-
43
- **示例（Windows PowerShell）：**
44
-
45
- ```powershell
46
- $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
47
- ```
48
-
49
- 若以上环境变量均未设置，服务会自动扫描 DevEco Studio 的常见安装路径。
50
-
51
- ### 工程路径配置
52
-
53
- 服务通过以下方式（按优先级）确定当前 HarmonyOS 项目的根目录：
54
-
55
- 1. **环境变量** `PROJECT_PATH`：直接指定工程根路径。
56
-
57
- ```bash
58
- export PROJECT_PATH="/path/to/your/harmonyos-project"
59
- ```
60
-
61
- 2. **MCP 根目录协议**：服务启动后向 MCP 客户端请求 `roots/list`，取第一个根目录作为工程路径。
62
-
63
- ### 工具组配置
64
-
65
- 服务将工具分为 **默认工具组** 和 **额外工具组**。默认工具组在服务启动时自动加载，而额外工具组需要通过环境变量显式激活。
66
-
67
- | 环境变量 | 说明 | 示例 |
68
- |----------|------|------|
69
- | `ADDITIONAL_TOOL_GROUPS` | 激活额外的工具组（逗号分隔） | `ui_integration_test,emulator_manager` |
70
-
71
- **默认加载的工具：**
72
- - ArkTS 代码检查、构建、同步
73
- - 启动应用、UI 树获取、UI 操作（仅限 Windows/macOS）
74
- - HiLog 日志采集、知识库搜索（仅限 Windows/macOS）
75
-
76
- **可选激活的额外工具组：**
77
-
78
- | 工具组名称 | 包含的工具 | 适用场景 |
79
- |------------|------------|----------|
80
- | `ui_integration_test` | `verify_ui`, `get_ui_verification_log`, `save_ui_screenshot` | 执行 UI 自动化脚本和意图校验 |
81
- | `emulator_manager` | `emulator_image_manager`,`emulator_management` | 管理模拟器镜像和实例 |
82
-
83
- ---
84
-
85
- ## 主要功能
86
-
87
- ### 1. ArkTS 代码检查（`check_ets_files`）
88
-
89
- 对指定的 `.ets` / `.ts` 文件执行静态诊断，返回语法错误、类型错误等诊断信息。
90
-
91
- **工具名称：** `check_ets_files`
92
-
93
- **参数：**
94
-
95
- | 参数 | 类型 | 说明 |
96
- |------|------|------|
97
- | `files` | `string[]` | 待检查的 ETS 文件路径列表 |
98
-
99
- **实现原理：** 服务内嵌 arkts-lang-server JS 脚本，通过 Node.js 启动 LSP 代理进程，以 LSP 协议与 ArkTS 语言服务通信，收集诊断结果后返回。
100
-
101
- ---
102
-
103
- ### 2. 构建 HAP/HSP/HAR（`build_project`）
104
-
105
- 调用 Hvigor 构建系统对 HarmonyOS 项目进行编译打包。
106
-
107
- **工具名称：** `build_project`
108
-
109
- **参数：**
110
-
111
- | 参数 | 类型 | 必填 | 说明 |
112
- |------|------|------|------|
113
- | `module` | `string` | 否 | 指定模块及 Target（如 `entry@default`）；省略则构建整个 APP |
114
- | `product` | `string` | 否 | 指定 Product 名称（仅构建整个 APP 时有效，与 `module` 互斥） |
115
- | `buildIntent` | `BuildIntent` | 否 | 构建意图，默认为 `LogVerification` |
116
- | `logPath` | `string` | 否 | 构建日志保存路径 |
117
-
118
- **构建意图（`BuildIntent`）：**
119
-
120
- | 枚举值 | 说明 |
121
- |--------|------|
122
- | `LogVerification`（默认） | 保留详细运行日志，支持断点调试 |
123
- | `UIDebug` | 支持获取界面元素与代码位置对应关系 |
124
- | `PerformanceProfile` | 开启代码优化，保留调试钩子，用于性能调优 |
125
- | `Release` | 极致压缩混淆，不支持断点调试（包体积最小） |
126
-
127
- 构建前会自动执行 `ohpm install` 安装依赖。
128
-
129
- ---
130
-
131
- ### 3. 启动应用（`start_app`）（仅 Windows / macOS）
132
-
133
- 在连接的真机或模拟器上安装并启动 HarmonyOS 应用。
134
-
135
- **工具名称：** `start_app`
136
-
137
- **参数：**
138
-
139
- | 参数 | 类型 | 说明 |
140
- |------|------|------|
141
- | `module` | `string` | 模块名称，默认为 `entry` |
142
- | `target` | `string` | 构建目标，默认为 `default` |
143
- | `hvd` | `string` | 目标设备名称或 ID（不指定则列出所有可用设备） |
144
- | `ability` | `string` | 要启动的 Ability 名称|
145
-
146
- 支持自动启动未运行的模拟器。
147
-
148
- ---
149
-
150
- ### 4. UI 树获取（`get_app_ui_tree`）（Windows / macOS）
151
-
152
- 抓取设备当前界面的 UI 树信息，保存为 JSON 文件。
153
-
154
- **工具名称：** `get_app_ui_tree`
155
-
156
- **参数：**
157
-
158
- | 参数 | 类型 | 说明 |
159
- |------|------|------|
160
- | `mode` | `simple \| full` | `simple`：窗口节点信息；`full`：完整 UI 树 |
161
- | `outputDirectory` | `string` | 保存 JSON 文件的目录绝对路径 |
162
- | `hvd` | `string` | 目标设备名称（单设备时可省略） |
163
-
164
- ---
165
-
166
- ### 5. UI 操作（`perform_ui_action`）（Windows / macOS）
167
-
168
- 对设备屏幕执行模拟操作。
169
-
170
- **工具名称：** `perform_ui_action`
171
-
172
- **支持的操作类型（`actionType`）：**
173
-
174
- | 操作类型 | 说明 | 主要参数 |
175
- |----------|------|----------|
176
- | `click` | 点击指定坐标 | `x`, `y` |
177
- | `inputText` | 在指定坐标输入文本 | `x`, `y`, `text` |
178
- | `directionalFling` | 方向滑动 | `direction`（0左/1右/2上/3下）, `velocity`, `stepLength` |
179
- | `keyEvent` | 模拟按键（支持组合键） | `key1`, `key2`, `key3` |
180
- | `screenshot` | 截图 | `savePath` |
181
-
182
- ---
183
-
184
- ### 6. HiLog 日志采集（Windows / macOS）
185
-
186
- 从真机或模拟器实时采集 HiLog 系统日志（或崩溃日志）。
187
-
188
- 内部通过 `hdc hilog` 命令采集日志，支持多维度过滤：
189
-
190
- | 过滤项 | 说明 |
191
- |--------|------|
192
- | `hvd` | 目标设备 |
193
- | `iscrashLog` | `true` 时采集崩溃日志（faultlog），默认采集普通 hilog |
194
- | `level` | 日志级别：`D` / `I` / `W` / `E` / `F` |
195
- | `tag` | 日志标签过滤 |
196
- | `domain` | 日志领域（如 `0xD002800`） |
197
- | `bundleName` | 应用包名（自动获取 PID 过滤） |
198
- | `keyword` | 关键字正则过滤（与 `tag` 互斥） |
199
- | `logSize` | 日志缓冲区大小，范围 64K–16M，默认 4M |
200
-
201
- ---
202
-
203
- ### 7. HarmonyOS 知识库搜索（`harmonyos_knowledge_search`）（Windows / macOS）
204
-
205
- 调用云端知识库，搜索 HarmonyOS 开发文档。
206
-
207
- **工具名称：** `harmonyos_knowledge_search`
208
-
209
- **参数：**
210
-
211
- | 参数 | 类型 | 说明 |
212
- |------|------|------|
213
- | `keywords` | `string[]` | 搜索关键词列表 |
214
- | `maxCharSize` | `number` | 最大返回字符数，默认 5000 |
215
-
216
- 支持搜索：API 参考、开发指南、最佳实践、常见问题、版本变更说明。
217
-
218
- ---
219
-
220
- ### 8. UI 自动化校验（`verify_ui` / `get_ui_verification_log` / `save_ui_screenshot`）（仅 Windows / macOS）
221
-
222
- > **注意**：此功能属于额外工具组，需设置环境变量 `ADDITIONAL_TOOL_GROUPS=ui_integration_test` 才能开启。
223
-
224
- 基于自然语言测试用例计划，在 HarmonyOS 设备上自动执行 UI 操作并验证结果。
225
-
226
- **功能特性：**
227
-
228
- - **自然语言驱动**：用中文描述测试步骤，无需编写代码
229
- - **智能 UI 识别**：基于 AI 视觉分析自动识别界面元素
230
- - **多种操作支持**：点击、滑动、输入文本、长按、启动应用等
231
- - **实时截图验证**：每步操作后自动截图验证是否成功
232
- - **截图保存**：可将每步截图保存到本地，便于复盘问题
233
- - **日志记录**：详细的测试过程日志，便于问题排查
234
-
235
- **环境要求：**
236
-
237
- 需配置以下环境变量以连接 AI 视觉模型服务（需支持 Function Call，如阿里云百炼 Qwen3-VL）：
238
-
239
- | 环境变量 | 说明 |
240
- |----------|------|
241
- | `UI_VERIFY_BASE_URL` | OpenAI 兼容接口地址 |
242
- | `UI_VERIFY_API_KEY` | API Key |
243
- | `UI_VERIFY_MODEL_NAME` | 模型名称（需支持视觉理解和 Function Call） |
244
-
245
- **MCP 配置示例：**
246
-
247
- ```json
248
- {
249
- "mcpServers": {
250
- "deveco-mcp": {
251
- "command": "cmd",
252
- "args": [
253
- "/C",
254
- "path/to/mcp-server.exe"
255
- ],
256
- "env": {
257
- "DEVECO_PATH": "path/to/DevEco Studio",
258
- "PROJECT_PATH": "${workspaceFolder}",
259
- "ADDITIONAL_TOOL_GROUPS": "ui_integration_test",
260
- "UI_VERIFY_API_KEY": "your-api-key",
261
- "UI_VERIFY_BASE_URL": "your-openai-compatible-base-url",
262
- "UI_VERIFY_MODEL_NAME": "your-model-name"
263
- }
264
- }
265
- }
266
- }
267
- ```
268
-
269
- ---
270
-
271
- **工具名称：** `verify_ui`（执行 UI 校验）
272
-
273
- | 参数 | 类型 | 必填 | 说明 |
274
- |------|------|------|------|
275
- | `bundleName` | `string` | 否 | 待测试应用的包名，不填时自动从项目 `AppScope/app.json5` 中获取 |
276
- | `testPlan` | `string` | 是 | 自然语言描述的测试用例计划，包含每步操作和预期结果 |
277
- | `freshStart` | `boolean` | 否 | 是否在测试前重新启动应用，默认 `false` |
278
-
279
- 返回字段：`successPart`（成功步骤描述）、`failPart`（失败步骤描述）、`id`（校验任务 ID，供后续查日志或截图使用）。
280
-
281
- ---
282
-
283
- **工具名称：** `get_ui_verification_log`（获取校验运行日志）
284
-
285
- | 参数 | 类型 | 必填 | 说明 |
286
- |------|------|------|------|
287
- | `id` | `string` | 是 | 校验任务 ID |
288
- | `maxLogSize` | `number` | 否 | 日志字符数上限，默认 5000，传 -1 不限制 |
289
- | `searchKeywords` | `string` | 否 | 日志搜索关键词，传空字符串获取完整日志 |
290
-
291
- ---
292
-
293
- **工具名称：** `save_ui_screenshot`（保存校验截图）
294
-
295
- | 参数 | 类型 | 必填 | 说明 |
296
- |------|------|------|------|
297
- | `id` | `string` | 是 | 校验任务 ID |
298
- | `dirname` | `string` | 是 | 截图保存目录（必须为绝对路径） |
299
-
300
- 返回该次校验每步操作的截图文件名列表。
301
-
302
- ---
303
-
304
- **最佳实践：**
305
-
306
- 在 AI 助手中配置好 MCP 后，建议在测试过程中加入以下指引，让 AI 自动串联完整开发测试流程：
307
-
308
- ```
309
- 开发完成后，请按以下流程完成验证：
310
- 1. 调用 build_project 编译构建项目
311
- 2. 调用 start_app 将应用安装并启动到设备
312
- 3. 调用 verify_ui 执行功能验证，用自然语言描述测试步骤和预期结果
313
- 4. 若验证失败，根据 failPart 描述定位问题，修复后重新执行上述流程，直到验证通过
314
- 5. 如需查看详细日志，使用 get_ui_verification_log 获取运行日志
315
- 6. 如需查看每步截图，使用 save_ui_screenshot 将截图保存到本地目录
316
- ```
317
-
318
- ---
319
-
320
-
321
- ## 平台支持
322
-
323
- | 功能 | Windows | macOS |
324
- |------|:-------:|:-----:|
325
- | ArkTS 代码检查 | ✅ | ✅ |
326
- | 构建 HAP/HSP/HAR | ✅ | ✅ |
327
- | 启动应用 | ✅ | ✅ |
328
- | UI 树获取 | ✅ | ✅ |
329
- | UI 操作 | ✅ | ✅ |
330
- | HiLog 日志采集 | ✅ | ✅ |
331
- | 知识库搜索 | ✅ | ✅ |
332
- | UI 自动化校验 | ✅ | ✅ |
333
-
334
- ---
1
+ # mcp-server
2
+
3
+ 基于MCP协议，将 HarmonyOS 开发工具链封装为标准 MCP 工具，供 AI 助手调用。
4
+
5
+ ---
6
+
7
+ ## 目录
8
+
9
+ - [配置方式](#配置方式)
10
+ - [环境变量配置](#环境变量配置)
11
+ - [工程路径配置](#工程路径配置)
12
+ - [主要功能](#主要功能)
13
+ - [ArkTS 代码检查](#1-arkts-代码检查-check_ets_files)
14
+ - [构建 HAP/HSP/HAR](#2-构建-haphsphar-build_project)
15
+ - [启动应用](#3-启动应用-start_app仅-windows--macos)
16
+ - [UI 树获取](#4-ui-树获取-get_app_ui_treewindows--macos)
17
+ - [UI 操作](#5-ui-操作-perform_ui_actionwindows--macos)
18
+ - [UI 自动化校验](#6-ui-自动化校验-verify_ui--get_ui_verification_log--save_ui_screenshot仅-windows--macos)
19
+ - [HiLog 日志采集](#7-hilog-日志采集windows--macos)
20
+ - [HarmonyOS 知识库搜索](#8-harmonyos-知识库搜索-harmonyos_knowledge_searchwindows--macos)
21
+ - [平台支持](#平台支持)
22
+
23
+ ---
24
+
25
+ ## 配置方式
26
+
27
+ 服务启动时按以下优先级加载配置，任意一种成功即停止继续尝试。
28
+
29
+ ### 环境变量配置
30
+
31
+ 服务优先读取以下环境变量来定位工具链安装目录：
32
+
33
+ | 环境变量 | 适用平台 | 说明 |
34
+ |----------|----------|------|
35
+ | `DEVECO_PATH` | Windows / macOS | DevEco Studio 安装根目录，优先级最高 |
36
+
37
+ **示例（macOS）：**
38
+
39
+ ```bash
40
+ export DEVECO_PATH="/Applications/DevEco-Studio.app/Contents"
41
+ ```
42
+
43
+ **示例（Windows PowerShell）：**
44
+
45
+ ```powershell
46
+ $env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
47
+ ```
48
+
49
+ 若以上环境变量均未设置，服务会自动扫描 DevEco Studio 的常见安装路径。
50
+
51
+ ### 工程路径配置
52
+
53
+ 服务通过以下方式（按优先级）确定当前 HarmonyOS 项目的根目录：
54
+
55
+ 1. **环境变量** `PROJECT_PATH`：直接指定工程根路径。
56
+
57
+ ```bash
58
+ export PROJECT_PATH="/path/to/your/harmonyos-project"
59
+ ```
60
+
61
+ 2. **MCP 根目录协议**：服务启动后向 MCP 客户端请求 `roots/list`，取第一个根目录作为工程路径。
62
+
63
+ ### 工具组配置
64
+
65
+ 服务将工具分为 **默认工具组** 和 **额外工具组**。默认工具组在服务启动时自动加载，而额外工具组需要通过环境变量显式激活。
66
+
67
+ | 环境变量 | 说明 | 示例 |
68
+ |----------|------|------|
69
+ | `ADDITIONAL_TOOL_GROUPS` | 激活额外的工具组（逗号分隔） | `ui_integration_test,emulator_manager` |
70
+
71
+ **默认加载的工具：**
72
+ - ArkTS 代码检查、构建、同步
73
+ - 启动应用、UI 树获取、UI 操作（仅限 Windows/macOS）
74
+ - HiLog 日志采集、知识库搜索（仅限 Windows/macOS）
75
+
76
+ **可选激活的额外工具组：**
77
+
78
+ | 工具组名称 | 包含的工具 | 适用场景 |
79
+ |------------|------------|----------|
80
+ | `ui_integration_test` | `verify_ui`, `get_ui_verification_log`, `save_ui_screenshot` | 执行 UI 自动化脚本和意图校验 |
81
+ | `emulator_manager` | `emulator_image_manager`,`emulator_management` | 管理模拟器镜像和实例 |
82
+
83
+ ---
84
+
85
+ ## 主要功能
86
+
87
+ ### 1. ArkTS 代码检查（`check_ets_files`）
88
+
89
+ 对指定的 `.ets` / `.ts` 文件执行静态诊断，返回语法错误、类型错误等诊断信息。
90
+
91
+ **工具名称：** `check_ets_files`
92
+
93
+ **参数：**
94
+
95
+ | 参数 | 类型 | 说明 |
96
+ |------|------|------|
97
+ | `files` | `string[]` | 待检查的 ETS 文件路径列表 |
98
+
99
+ **实现原理：** 服务内嵌 arkts-lang-server JS 脚本，通过 Node.js 启动 LSP 代理进程，以 LSP 协议与 ArkTS 语言服务通信，收集诊断结果后返回。
100
+
101
+ ---
102
+
103
+ ### 2. 构建 HAP/HSP/HAR（`build_project`）
104
+
105
+ 调用 Hvigor 构建系统对 HarmonyOS 项目进行编译打包。
106
+
107
+ **工具名称：** `build_project`
108
+
109
+ **参数：**
110
+
111
+ | 参数 | 类型 | 必填 | 说明 |
112
+ |------|------|------|------|
113
+ | `module` | `string` | 否 | 指定模块及 Target（如 `entry@default`）；省略则构建整个 APP |
114
+ | `product` | `string` | 否 | 指定 Product 名称（仅构建整个 APP 时有效，与 `module` 互斥） |
115
+ | `buildIntent` | `BuildIntent` | 否 | 构建意图，默认为 `LogVerification` |
116
+ | `logPath` | `string` | 否 | 构建日志保存路径 |
117
+
118
+ **构建意图（`BuildIntent`）：**
119
+
120
+ | 枚举值 | 说明 |
121
+ |--------|------|
122
+ | `LogVerification`（默认） | 保留详细运行日志，支持断点调试 |
123
+ | `UIDebug` | 支持获取界面元素与代码位置对应关系 |
124
+ | `PerformanceProfile` | 开启代码优化，保留调试钩子，用于性能调优 |
125
+ | `Release` | 极致压缩混淆，不支持断点调试（包体积最小） |
126
+
127
+ 构建前会自动执行 `ohpm install` 安装依赖。
128
+
129
+ ---
130
+
131
+ ### 3. 启动应用（`start_app`）（仅 Windows / macOS）
132
+
133
+ 在连接的真机或模拟器上安装并启动 HarmonyOS 应用。
134
+
135
+ **工具名称：** `start_app`
136
+
137
+ **参数：**
138
+
139
+ | 参数 | 类型 | 说明 |
140
+ |------|------|------|
141
+ | `module` | `string` | 模块名称，默认为 `entry` |
142
+ | `target` | `string` | 构建目标，默认为 `default` |
143
+ | `hvd` | `string` | 目标设备名称或 ID（不指定则列出所有可用设备） |
144
+ | `ability` | `string` | 要启动的 Ability 名称|
145
+
146
+ 支持自动启动未运行的模拟器。
147
+
148
+ ---
149
+
150
+ ### 4. UI 树获取（`get_app_ui_tree`）（Windows / macOS）
151
+
152
+ 抓取设备当前界面的 UI 树信息，保存为 JSON 文件。
153
+
154
+ **工具名称：** `get_app_ui_tree`
155
+
156
+ **参数：**
157
+
158
+ | 参数 | 类型 | 说明 |
159
+ |------|------|------|
160
+ | `mode` | `simple \| full` | `simple`：窗口节点信息；`full`：完整 UI 树 |
161
+ | `outputDirectory` | `string` | 保存 JSON 文件的目录绝对路径 |
162
+ | `hvd` | `string` | 目标设备名称（单设备时可省略） |
163
+
164
+ ---
165
+
166
+ ### 5. UI 操作（`perform_ui_action`）（Windows / macOS）
167
+
168
+ 对设备屏幕执行模拟操作。
169
+
170
+ **工具名称：** `perform_ui_action`
171
+
172
+ **支持的操作类型（`actionType`）：**
173
+
174
+ | 操作类型 | 说明 | 主要参数 |
175
+ |----------|------|----------|
176
+ | `click` | 点击指定坐标 | `x`, `y` |
177
+ | `inputText` | 在指定坐标输入文本 | `x`, `y`, `text` |
178
+ | `directionalFling` | 方向滑动 | `direction`（0左/1右/2上/3下）, `velocity`, `stepLength` |
179
+ | `keyEvent` | 模拟按键（支持组合键） | `key1`, `key2`, `key3` |
180
+ | `screenshot` | 截图 | `savePath` |
181
+
182
+ ---
183
+
184
+ ### 6. HiLog 日志采集（Windows / macOS）
185
+
186
+ 从真机或模拟器实时采集 HiLog 系统日志（或崩溃日志）。
187
+
188
+ 内部通过 `hdc hilog` 命令采集日志，支持多维度过滤：
189
+
190
+ | 过滤项 | 说明 |
191
+ |--------|------|
192
+ | `hvd` | 目标设备 |
193
+ | `iscrashLog` | `true` 时采集崩溃日志（faultlog），默认采集普通 hilog |
194
+ | `level` | 日志级别：`D` / `I` / `W` / `E` / `F` |
195
+ | `tag` | 日志标签过滤 |
196
+ | `domain` | 日志领域（如 `0xD002800`） |
197
+ | `bundleName` | 应用包名（自动获取 PID 过滤） |
198
+ | `keyword` | 关键字正则过滤（与 `tag` 互斥） |
199
+ | `logSize` | 日志缓冲区大小，范围 64K–16M，默认 4M |
200
+
201
+ ---
202
+
203
+ ### 7. HarmonyOS 知识库搜索（`harmonyos_knowledge_search`）（Windows / macOS）
204
+
205
+ 调用云端知识库，搜索 HarmonyOS 开发文档。
206
+
207
+ **工具名称：** `harmonyos_knowledge_search`
208
+
209
+ **参数：**
210
+
211
+ | 参数 | 类型 | 说明 |
212
+ |------|------|------|
213
+ | `keywords` | `string[]` | 搜索关键词列表 |
214
+ | `maxCharSize` | `number` | 最大返回字符数，默认 5000 |
215
+
216
+ 支持搜索：API 参考、开发指南、最佳实践、常见问题、版本变更说明。
217
+
218
+ ---
219
+
220
+ ### 8. UI 自动化校验（`verify_ui` / `get_ui_verification_log` / `save_ui_screenshot`）（仅 Windows / macOS）
221
+
222
+ > **注意**：此功能属于额外工具组，需设置环境变量 `ADDITIONAL_TOOL_GROUPS=ui_integration_test` 才能开启。
223
+
224
+ 基于自然语言测试用例计划，在 HarmonyOS 设备上自动执行 UI 操作并验证结果。
225
+
226
+ **功能特性：**
227
+
228
+ - **自然语言驱动**：用中文描述测试步骤，无需编写代码
229
+ - **智能 UI 识别**：基于 AI 视觉分析自动识别界面元素
230
+ - **多种操作支持**：点击、滑动、输入文本、长按、启动应用等
231
+ - **实时截图验证**：每步操作后自动截图验证是否成功
232
+ - **截图保存**：可将每步截图保存到本地，便于复盘问题
233
+ - **日志记录**：详细的测试过程日志，便于问题排查
234
+
235
+ **环境要求：**
236
+
237
+ 需配置以下环境变量以连接 AI 视觉模型服务（需支持 Function Call，如阿里云百炼 Qwen3-VL）：
238
+
239
+ | 环境变量 | 说明 |
240
+ |----------|------|
241
+ | `UI_VERIFY_BASE_URL` | OpenAI 兼容接口地址 |
242
+ | `UI_VERIFY_API_KEY` | API Key |
243
+ | `UI_VERIFY_MODEL_NAME` | 模型名称（需支持视觉理解和 Function Call） |
244
+
245
+ **MCP 配置示例：**
246
+
247
+ ```json
248
+ {
249
+ "mcpServers": {
250
+ "deveco-mcp": {
251
+ "command": "cmd",
252
+ "args": [
253
+ "/C",
254
+ "path/to/mcp-server.exe"
255
+ ],
256
+ "env": {
257
+ "DEVECO_PATH": "path/to/DevEco Studio",
258
+ "PROJECT_PATH": "${workspaceFolder}",
259
+ "ADDITIONAL_TOOL_GROUPS": "ui_integration_test",
260
+ "UI_VERIFY_API_KEY": "your-api-key",
261
+ "UI_VERIFY_BASE_URL": "your-openai-compatible-base-url",
262
+ "UI_VERIFY_MODEL_NAME": "your-model-name"
263
+ }
264
+ }
265
+ }
266
+ }
267
+ ```
268
+
269
+ ---
270
+
271
+ **工具名称：** `verify_ui`（执行 UI 校验）
272
+
273
+ | 参数 | 类型 | 必填 | 说明 |
274
+ |------|------|------|------|
275
+ | `bundleName` | `string` | 否 | 待测试应用的包名，不填时自动从项目 `AppScope/app.json5` 中获取 |
276
+ | `testPlan` | `string` | 是 | 自然语言描述的测试用例计划，包含每步操作和预期结果 |
277
+ | `freshStart` | `boolean` | 否 | 是否在测试前重新启动应用，默认 `false` |
278
+
279
+ 返回字段：`successPart`（成功步骤描述）、`failPart`（失败步骤描述）、`id`（校验任务 ID，供后续查日志或截图使用）。
280
+
281
+ ---
282
+
283
+ **工具名称：** `get_ui_verification_log`（获取校验运行日志）
284
+
285
+ | 参数 | 类型 | 必填 | 说明 |
286
+ |------|------|------|------|
287
+ | `id` | `string` | 是 | 校验任务 ID |
288
+ | `maxLogSize` | `number` | 否 | 日志字符数上限，默认 5000，传 -1 不限制 |
289
+ | `searchKeywords` | `string` | 否 | 日志搜索关键词，传空字符串获取完整日志 |
290
+
291
+ ---
292
+
293
+ **工具名称：** `save_ui_screenshot`（保存校验截图）
294
+
295
+ | 参数 | 类型 | 必填 | 说明 |
296
+ |------|------|------|------|
297
+ | `id` | `string` | 是 | 校验任务 ID |
298
+ | `dirname` | `string` | 是 | 截图保存目录（必须为绝对路径） |
299
+
300
+ 返回该次校验每步操作的截图文件名列表。
301
+
302
+ ---
303
+
304
+ **最佳实践：**
305
+
306
+ 在 AI 助手中配置好 MCP 后，建议在测试过程中加入以下指引，让 AI 自动串联完整开发测试流程：
307
+
308
+ ```
309
+ 开发完成后，请按以下流程完成验证：
310
+ 1. 调用 build_project 编译构建项目
311
+ 2. 调用 start_app 将应用安装并启动到设备
312
+ 3. 调用 verify_ui 执行功能验证，用自然语言描述测试步骤和预期结果
313
+ 4. 若验证失败，根据 failPart 描述定位问题，修复后重新执行上述流程，直到验证通过
314
+ 5. 如需查看详细日志，使用 get_ui_verification_log 获取运行日志
315
+ 6. 如需查看每步截图，使用 save_ui_screenshot 将截图保存到本地目录
316
+ ```
317
+
318
+ ---
319
+
320
+
321
+ ## 平台支持
322
+
323
+ | 功能 | Windows | macOS |
324
+ |------|:-------:|:-----:|
325
+ | ArkTS 代码检查 | ✅ | ✅ |
326
+ | 构建 HAP/HSP/HAR | ✅ | ✅ |
327
+ | 启动应用 | ✅ | ✅ |
328
+ | UI 树获取 | ✅ | ✅ |
329
+ | UI 操作 | ✅ | ✅ |
330
+ | HiLog 日志采集 | ✅ | ✅ |
331
+ | 知识库搜索 | ✅ | ✅ |
332
+ | UI 自动化校验 | ✅ | ✅ |
333
+
334
+ ---
package/index.js CHANGED
@@ -1,42 +1,42 @@
1
- #!/usr/bin/env node
2
-
3
- const { spawn } = require('child_process');
4
- const path = require('path');
5
- const os = require('os');
6
- const fs = require('fs');
7
-
8
- const platform = os.platform();
9
- const arch = os.arch();
10
-
11
- // Binary name in the platform-specific package's bin directory
12
- let binaryName = 'codegenie-mcp-server';
13
- if (platform === 'win32') {
14
- binaryName += '.exe';
15
- }
16
-
17
- const pkgName = `@deveco-codegenie/mcp-${platform}-${arch}`;
18
-
19
- try {
20
- // Try to find the binary in the platform-specific package
21
- const pkgPath = require.resolve(`${pkgName}/package.json`);
22
- const binPath = path.join(path.dirname(pkgPath), 'bin', binaryName);
23
-
24
- if (fs.existsSync(binPath)) {
25
- const child = spawn(binPath, process.argv.slice(2), { stdio: 'inherit' });
26
- child.on('exit', (code) => {
27
- process.exit(code === null ? 1 : code);
28
- });
29
- child.on('error', (err) => {
30
- console.error(`Error: Failed to start binary at ${binPath}:`, err);
31
- process.exit(1);
32
- });
33
- } else {
34
- console.error(`Error: Binary not found at ${binPath}`);
35
- process.exit(1);
36
- }
37
- } catch (e) {
38
- console.error(`Error: Could not find platform-specific package ${pkgName}`);
39
- console.error('Please make sure the package is installed correctly.');
40
- console.error(`Platform: ${platform}, Arch: ${arch}`);
41
- process.exit(1);
42
- }
1
+ #!/usr/bin/env node
2
+
3
+ const { spawn } = require('child_process');
4
+ const path = require('path');
5
+ const os = require('os');
6
+ const fs = require('fs');
7
+
8
+ const platform = os.platform();
9
+ const arch = os.arch();
10
+
11
+ // Binary name in the platform-specific package's bin directory
12
+ let binaryName = 'codegenie-mcp-server';
13
+ if (platform === 'win32') {
14
+ binaryName += '.exe';
15
+ }
16
+
17
+ const pkgName = `@deveco-codegenie/mcp-${platform}-${arch}`;
18
+
19
+ try {
20
+ // Try to find the binary in the platform-specific package
21
+ const pkgPath = require.resolve(`${pkgName}/package.json`);
22
+ const binPath = path.join(path.dirname(pkgPath), 'bin', binaryName);
23
+
24
+ if (fs.existsSync(binPath)) {
25
+ const child = spawn(binPath, process.argv.slice(2), { stdio: 'inherit' });
26
+ child.on('exit', (code) => {
27
+ process.exit(code === null ? 1 : code);
28
+ });
29
+ child.on('error', (err) => {
30
+ console.error(`Error: Failed to start binary at ${binPath}:`, err);
31
+ process.exit(1);
32
+ });
33
+ } else {
34
+ console.error(`Error: Binary not found at ${binPath}`);
35
+ process.exit(1);
36
+ }
37
+ } catch (e) {
38
+ console.error(`Error: Could not find platform-specific package ${pkgName}`);
39
+ console.error('Please make sure the package is installed correctly.');
40
+ console.error(`Platform: ${platform}, Arch: ${arch}`);
41
+ process.exit(1);
42
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deveco-codegenie/mcp",
3
- "version": "0.1.8-fix1",
3
+ "version": "0.1.8-fix3",
4
4
  "description": "MCP Server wrapper for npx",
5
5
  "main": "index.js",
6
6
  "bin": {
@@ -11,9 +11,9 @@
11
11
  },
12
12
  "dependencies": {},
13
13
  "optionalDependencies": {
14
- "@deveco-codegenie/mcp-win32-x64": "0.1.8-fix1",
15
- "@deveco-codegenie/mcp-darwin-x64": "0.1.8-fix1",
16
- "@deveco-codegenie/mcp-darwin-arm64": "0.1.8-fix1",
17
- "@deveco-codegenie/mcp-linux-x64": "0.1.8-fix1"
14
+ "@deveco-codegenie/mcp-win32-x64": "0.1.8-fix3",
15
+ "@deveco-codegenie/mcp-darwin-x64": "0.1.8-fix3",
16
+ "@deveco-codegenie/mcp-darwin-arm64": "0.1.8-fix3",
17
+ "@deveco-codegenie/mcp-linux-x64": "0.1.8-fix3"
18
18
  }
19
19
  }