@deveco-codegenie/mcp 0.1.7 → 0.1.8-fix2

package/README.md

@@ -1,187 +1,334 @@
-# CodeGenie MCP Server
+# mcp-server
 
-CodeGenie MCP Server 是一个专为 HarmonyOS 开发设计的 Model Context Protocol (MCP) 服务端。它旨在为 AI 辅助编程工具（如 Cursor, Trae 等）提供深度的 HarmonyOS 开发上下文感知能力，通过集成 DevEco Studio 环境信息和云端知识库，显著提升 HarmonyOS 应用开发的效率和准确性。
+基于MCP协议，将 HarmonyOS 开发工具链封装为标准 MCP 工具，供 AI 助手调用。
 
-## 主要特性
+---
 
-- **📚 HarmonyOS 知识库集成**
-  - 内置 `harmonyos_knowledge_search` 工具，直接对接云端知识库 API。
-  - 支持自然语言搜索 HarmonyOS 开发文档、API 参考和最佳实践。
-  - 智能检索相关代码片段和解决方案，辅助解决开发难题。
+## 目录
 
-- **🔧 DevEco Studio 深度整合**
-  - 自动检测本地 DevEco Studio 安装路径及 SDK 版本。
-  - 提供项目级上下文信息，包括工程结构、依赖关系等。
+- [配置方式](#配置方式)
+  - [环境变量配置](#环境变量配置)
+  - [工程路径配置](#工程路径配置)
+- [主要功能](#主要功能)
+  - [ArkTS 代码检查](#1-arkts-代码检查-check_ets_files)
+  - [构建 HAP/HSP/HAR](#2-构建-haphsphar-build_project)
+  - [启动应用](#3-启动应用-start_app仅-windows--macos)
+  - [UI 树获取](#4-ui-树获取-get_app_ui_treewindows--macos)
+  - [UI 操作](#5-ui-操作-perform_ui_actionwindows--macos)
+  - [UI 自动化校验](#6-ui-自动化校验-verify_ui--get_ui_verification_log--save_ui_screenshot仅-windows--macos)
+  - [HiLog 日志采集](#7-hilog-日志采集windows--macos)
+  - [HarmonyOS 知识库搜索](#8-harmonyos-知识库搜索-harmonyos_knowledge_searchwindows--macos)
+- [平台支持](#平台支持)
 
-- **🔌 灵活的扩展机制**
-  - 基于 Rust 实现的高性能 MCP 服务端。
-  - 提供 NPM 包装器，便于安装和集成到现有工作流中。
+---
 
-## 项目结构
+## 配置方式
 
-- `src-server/`: Rust 编写的 MCP 服务端核心逻辑。
-- `src-common/`: Rust 公共库，包含配置、日志、IPC 等通用模块。
-- `npm-wrapper/`: NPM 包封装，用于分发二进制文件。
-- `arkts-lang-server/`: ArkTS 语言服务相关组件。
+服务启动时按以下优先级加载配置，任意一种成功即停止继续尝试。
 
-## 快速开始
+### 环境变量配置
 
-### 前置要求
+服务优先读取以下环境变量来定位工具链安装目录：
 
-- Rust (用于编译后端)
-- Node.js & npm (用于构建前端)
+| 环境变量 | 适用平台 | 说明 |
+|----------|----------|------|
+| `DEVECO_PATH` | Windows / macOS | DevEco Studio 安装根目录，优先级最高 |
 
-### 构建与运行
+**示例（macOS）：**
 
-1. **编译后端**
-   ```bash
-   cargo build --release
-   ```
+```bash
+export DEVECO_PATH="/Applications/DevEco-Studio.app/Contents"
+```
+
+**示例（Windows PowerShell）：**
+
+```powershell
+$env:DEVECO_PATH = "C:\Program Files\Huawei\DevEco Studio"
+```
+
+若以上环境变量均未设置，服务会自动扫描 DevEco Studio 的常见安装路径。
+
+### 工程路径配置
+
+服务通过以下方式（按优先级）确定当前 HarmonyOS 项目的根目录：
+
+1. **环境变量** `PROJECT_PATH`：直接指定工程根路径。
 
-2. **运行服务**
    ```bash
-   ./target/release/mcp-server
+   export PROJECT_PATH="/path/to/your/harmonyos-project"
    ```
 
-## 🧪 单元测试
+2. **MCP 根目录协议**：服务启动后向 MCP 客户端请求 `roots/list`，取第一个根目录作为工程路径。
 
-项目包含集成测试，用于验证与 DevEco Studio 和 ArkTS 语言服务的集成功能。由于这些测试依赖于本地开发环境，你需要配置环境属性文件。
+### 工具组配置
 
-### 环境配置
+服务将工具分为 **默认工具组** 和 **额外工具组**。默认工具组在服务启动时自动加载，而额外工具组需要通过环境变量显式激活。
 
-在 `src-server/tests/` 目录下，有两个环境配置文件模板：
+| 环境变量 | 说明 | 示例 |
+|----------|------|------|
+| `ADDITIONAL_TOOL_GROUPS` | 激活额外的工具组（逗号分隔） | `ui_integration_test,emulator_manager` |
 
-1.  **`deveco_env.properties`**: 用于测试与 DevEco Studio 的深度集成（如启动应用、获取 UI 树等）。
-    - `DEVECO_PATH`: DevEco Studio 的安装根目录。
-    - `EMULATOR_NAME`: 自动化测试使用的模拟器名称，默认为 "Mate 70 Pro"。
+**默认加载的工具：**
+- ArkTS 代码检查、构建、同步
+- 启动应用、UI 树获取、UI 操作（仅限 Windows/macOS）
+- HiLog 日志采集、知识库搜索（仅限 Windows/macOS）
 
-2.  **`clt_env.properties`**: 用于测试与 HarmonyOS 命令行工具 (CLT) 的集成（如构建项目、代码检查等）。
-    - `CLT_PATH`: HarmonyOS Command Line Tools 的安装目录。
-    - `ARKTS_LANG_SERVER`: ArkTS 语言服务的可执行文件路径。
-    - `JAVA_HOME`: Java 运行时环境路径。
+**可选激活的额外工具组：**
 
-**设置方式：**
-编辑上述文件，为每个键填入你本地环境的实际路径。例如：
+| 工具组名称 | 包含的工具 | 适用场景 |
+|------------|------------|----------|
+| `ui_integration_test` | `verify_ui`, `get_ui_verification_log`, `save_ui_screenshot` | 执行 UI 自动化脚本和意图校验 |
+| `emulator_manager` | `emulator_image_manager`,`emulator_management` | 管理模拟器镜像和实例 |
 
-**`deveco_env.properties` 示例：**
-```properties
-DEVECO_PATH=D:\program_files\DevEco Studio
-EMULATOR_NAME=Mate 70 Pro
-```
+---
+
+## 主要功能
+
+### 1. ArkTS 代码检查（`check_ets_files`）
+
+对指定的 `.ets` / `.ts` 文件执行静态诊断，返回语法错误、类型错误等诊断信息。
+
+**工具名称：** `check_ets_files`
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `files` | `string[]` | 待检查的 ETS 文件路径列表 |
+
+**实现原理：** 服务内嵌 arkts-lang-server JS 脚本，通过 Node.js 启动 LSP 代理进程，以 LSP 协议与 ArkTS 语言服务通信，收集诊断结果后返回。
+
+---
+
+### 2. 构建 HAP/HSP/HAR（`build_project`）
+
+调用 Hvigor 构建系统对 HarmonyOS 项目进行编译打包。
+
+**工具名称：** `build_project`
+
+**参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `module` | `string` | 否 | 指定模块及 Target（如 `entry@default`）；省略则构建整个 APP |
+| `product` | `string` | 否 | 指定 Product 名称（仅构建整个 APP 时有效，与 `module` 互斥） |
+| `buildIntent` | `BuildIntent` | 否 | 构建意图，默认为 `LogVerification` |
+| `logPath` | `string` | 否 | 构建日志保存路径 |
+
+**构建意图（`BuildIntent`）：**
+
+| 枚举值 | 说明 |
+|--------|------|
+| `LogVerification`（默认） | 保留详细运行日志，支持断点调试 |
+| `UIDebug` | 支持获取界面元素与代码位置对应关系 |
+| `PerformanceProfile` | 开启代码优化，保留调试钩子，用于性能调优 |
+| `Release` | 极致压缩混淆，不支持断点调试（包体积最小） |
+
+构建前会自动执行 `ohpm install` 安装依赖。
+
+---
+
+### 3. 启动应用（`start_app`）（仅 Windows / macOS）
+
+在连接的真机或模拟器上安装并启动 HarmonyOS 应用。
+
+**工具名称：** `start_app`
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `module` | `string` | 模块名称，默认为 `entry` |
+| `target` | `string` | 构建目标，默认为 `default` |
+| `hvd` | `string` | 目标设备名称或 ID（不指定则列出所有可用设备） |
+| `ability` | `string` | 要启动的 Ability 名称|
+
+支持自动启动未运行的模拟器。
+
+---
+
+### 4. UI 树获取（`get_app_ui_tree`）（Windows / macOS）
+
+抓取设备当前界面的 UI 树信息，保存为 JSON 文件。
+
+**工具名称：** `get_app_ui_tree`
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `mode` | `simple \| full` | `simple`：窗口节点信息；`full`：完整 UI 树 |
+| `outputDirectory` | `string` | 保存 JSON 文件的目录绝对路径 |
+| `hvd` | `string` | 目标设备名称（单设备时可省略） |
+
+---
+
+### 5. UI 操作（`perform_ui_action`）（Windows / macOS）
+
+对设备屏幕执行模拟操作。
 
-**`clt_env.properties` 示例：**
-```properties
-CLT_PATH=D:\program_files\commandline-tools-windows-x64-6.0.2.640\command-line-tools
-ARKTS_LANG_SERVER=D:\program_files\DevEco Studio\plugins\openharmony
-JAVA_HOME=D:\program_files\DevEco Studio\jbr
+**工具名称：** `perform_ui_action`
+
+**支持的操作类型（`actionType`）：**
+
+| 操作类型 | 说明 | 主要参数 |
+|----------|------|----------|
+| `click` | 点击指定坐标 | `x`, `y` |
+| `inputText` | 在指定坐标输入文本 | `x`, `y`, `text` |
+| `directionalFling` | 方向滑动 | `direction`（0左/1右/2上/3下）, `velocity`, `stepLength` |
+| `keyEvent` | 模拟按键（支持组合键） | `key1`, `key2`, `key3` |
+| `screenshot` | 截图 | `savePath` |
+
+---
+
+### 6. HiLog 日志采集（Windows / macOS）
+
+从真机或模拟器实时采集 HiLog 系统日志（或崩溃日志）。
+
+内部通过 `hdc hilog` 命令采集日志，支持多维度过滤：
+
+| 过滤项 | 说明 |
+|--------|------|
+| `hvd` | 目标设备 |
+| `iscrashLog` | `true` 时采集崩溃日志（faultlog），默认采集普通 hilog |
+| `level` | 日志级别：`D` / `I` / `W` / `E` / `F` |
+| `tag` | 日志标签过滤 |
+| `domain` | 日志领域（如 `0xD002800`） |
+| `bundleName` | 应用包名（自动获取 PID 过滤） |
+| `keyword` | 关键字正则过滤（与 `tag` 互斥） |
+| `logSize` | 日志缓冲区大小，范围 64K–16M，默认 4M |
+
+---
+
+### 7. HarmonyOS 知识库搜索（`harmonyos_knowledge_search`）（Windows / macOS）
+
+调用云端知识库，搜索 HarmonyOS 开发文档。
+
+**工具名称：** `harmonyos_knowledge_search`
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `keywords` | `string[]` | 搜索关键词列表 |
+| `maxCharSize` | `number` | 最大返回字符数，默认 5000 |
+
+支持搜索：API 参考、开发指南、最佳实践、常见问题、版本变更说明。
+
+---
+
+### 8. UI 自动化校验（`verify_ui` / `get_ui_verification_log` / `save_ui_screenshot`）（仅 Windows / macOS）
+
+> **注意**：此功能属于额外工具组，需设置环境变量 `ADDITIONAL_TOOL_GROUPS=ui_integration_test` 才能开启。
+
+基于自然语言测试用例计划，在 HarmonyOS 设备上自动执行 UI 操作并验证结果。
+
+**功能特性：**
+
+- **自然语言驱动**：用中文描述测试步骤，无需编写代码
+- **智能 UI 识别**：基于 AI 视觉分析自动识别界面元素
+- **多种操作支持**：点击、滑动、输入文本、长按、启动应用等
+- **实时截图验证**：每步操作后自动截图验证是否成功
+- **截图保存**：可将每步截图保存到本地，便于复盘问题
+- **日志记录**：详细的测试过程日志，便于问题排查
+
+**环境要求：**
+
+需配置以下环境变量以连接 AI 视觉模型服务（需支持 Function Call，如阿里云百炼 Qwen3-VL）：
+
+| 环境变量 | 说明 |
+|----------|------|
+| `UI_VERIFY_BASE_URL` | OpenAI 兼容接口地址 |
+| `UI_VERIFY_API_KEY` | API Key |
+| `UI_VERIFY_MODEL_NAME` | 模型名称（需支持视觉理解和 Function Call） |
+
+**MCP 配置示例：**
+
+```json
+{
+  "mcpServers": {
+    "deveco-mcp": {
+      "command": "cmd",
+      "args": [
+        "/C",
+        "path/to/mcp-server.exe"
+      ],
+      "env": {
+        "DEVECO_PATH": "path/to/DevEco Studio",
+        "PROJECT_PATH": "${workspaceFolder}",
+        "ADDITIONAL_TOOL_GROUPS": "ui_integration_test",
+        "UI_VERIFY_API_KEY": "your-api-key",
+        "UI_VERIFY_BASE_URL": "your-openai-compatible-base-url",
+        "UI_VERIFY_MODEL_NAME": "your-model-name"
+      }
+    }
+  }
+}
 ```
 
-### 运行测试
+---
 
-在根目录下运行以下命令执行所有测试：
+**工具名称：** `verify_ui`（执行 UI 校验）
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `bundleName` | `string` | 否 | 待测试应用的包名，不填时自动从项目 `AppScope/app.json5` 中获取 |
+| `testPlan` | `string` | 是 | 自然语言描述的测试用例计划，包含每步操作和预期结果 |
+| `freshStart` | `boolean` | 否 | 是否在测试前重新启动应用，默认 `false` |
+
+返回字段：`successPart`（成功步骤描述）、`failPart`（失败步骤描述）、`id`（校验任务 ID，供后续查日志或截图使用）。
+
+---
+
+**工具名称：** `get_ui_verification_log`（获取校验运行日志）
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `string` | 是 | 校验任务 ID |
+| `maxLogSize` | `number` | 否 | 日志字符数上限，默认 5000，传 -1 不限制 |
+| `searchKeywords` | `string` | 否 | 日志搜索关键词，传空字符串获取完整日志 |
+
+---
+
+**工具名称：** `save_ui_screenshot`（保存校验截图）
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `string` | 是 | 校验任务 ID |
+| `dirname` | `string` | 是 | 截图保存目录（必须为绝对路径） |
+
+返回该次校验每步操作的截图文件名列表。
+
+---
+
+**最佳实践：**
+
+在 AI 助手中配置好 MCP 后，建议在测试过程中加入以下指引，让 AI 自动串联完整开发测试流程：
 
-```bash
-cargo test
 ```
+开发完成后，请按以下流程完成验证：
+1. 调用 build_project 编译构建项目
+2. 调用 start_app 将应用安装并启动到设备
+3. 调用 verify_ui 执行功能验证，用自然语言描述测试步骤和预期结果
+4. 若验证失败，根据 failPart 描述定位问题，修复后重新执行上述流程，直到验证通过
+5. 如需查看详细日志，使用 get_ui_verification_log 获取运行日志
+6. 如需查看每步截图，使用 save_ui_screenshot 将截图保存到本地目录
+```
+
+---
+
+
+## 平台支持
+
+| 功能 | Windows | macOS |
+|------|:-------:|:-----:|
+| ArkTS 代码检查 | ✅ | ✅ |
+| 构建 HAP/HSP/HAR | ✅ | ✅ |
+| 启动应用 | ✅ | ✅ |
+| UI 树获取 | ✅ | ✅ |
+| UI 操作 | ✅ | ✅ |
+| HiLog 日志采集 | ✅ | ✅ |
+| 知识库搜索 | ✅ | ✅ |
+| UI 自动化校验 | ✅ | ✅ |
 
-> **注意**：如果未设置 `DEVECO_PATH` 或 `CLT_PATH`，相关的集成测试将被跳过。
-
-## 🛠️ 辅助开发工具
-
-项目利用 `xtask` 模式提供了便捷的版本管理和分发构建工具。
-
-### 🧹 代码检查 (`cargo clippyall`)
-
-用于在本地开发环境中对支持的所有目标平台（Windows x64, macOS x64/arm64, Linux x64）运行 Clippy 静态检查。
-
-- **执行检查**：
-  ```bash
-  cargo clippyall
-  ```
-- **说明**：
-  该命令会自动安装所需的 Rust target（如果缺失），并依次对每个平台运行 `cargo clippy`，确保代码跨平台兼容性。
-
-### 🔢 版本更新 (`cargo bump`)
-
-用于同步更新项目中所有组件（Rust 核心、Common 库、ArkTS 语言服务、NPM 包装器）的版本号。
-
-- **更新版本**：
-  ```bash
-  cargo bump <new_version>
-  ```
-- **更新版本并自动提交**：
-  使用 `--commit` 参数会自动检查 Git 状态并在更新版本后创建 commit 和 tag。
-  ```bash
-  cargo bump <new_version> --commit
-  ```
-
-### 📋 变更日志 (`cargo changelog`)
-
-用于查看和生成项目的变更日志。支持灵活的范围指定，可以混合使用 tag 和 commit hash。
-
-- **查看最近两个版本的变更**（默认）：
-  ```bash
-  cargo changelog
-  ```
-- **查看指定范围的变更**：
-  ```bash
-  # 使用 tag
-  cargo changelog v0.1.0..v0.2.0
-  
-  # 使用 commit hash
-  cargo changelog abc123..def456
-  
-  # 混合使用（tag 和 hash）
-  cargo changelog v0.1.0..abc123      # tag 到 hash
-  cargo changelog def456..v0.2.0      # hash 到 tag
-  
-  # 使用 HEAD 查看未发布的变更
-  cargo changelog v0.2.0..HEAD        # 最新 tag 到当前 HEAD
-  ```
-
-### 📦 构建发布 (`cargo dist`)
-
-用于自动化构建多平台的二进制发布产物和 NPM 包。
-
-- **执行构建**：
-  ```bash
-  cargo dist
-  ```
-- **产物说明**：
-  构建结果存放在 `target/dist/` 目录，其典型的目录结构如下：
-
-  ```text
-  target/dist/
-  ├── npm/
-  │   ├── codegenie-mcp-server/             # NPM 主包，用于分发和运行
-  │   │   ├── package.json                  # 定义 bin、dependencies 等
-  │   │   ├── index.js                      # 运行时自动检测平台并加载对应二进制
-  │   │   └── README.md
-  │   ├── codegenie-mcp-server-win32-x64/   # Windows (x64)
-  │   │   ├── bin/mcp-server.exe
-  │   │   ├── package.json
-  │   │   └── README.md
-  │   ├── codegenie-mcp-server-darwin-x64/  # macOS (Intel)
-  │   │   ├── bin/mcp-server
-  │   │   ├── package.json
-  │   │   └── README.md
-  │   ├── codegenie-mcp-server-darwin-arm64/ # macOS (Apple Silicon)
-  │   │   ├── bin/mcp-server
-  │   │   ├── package.json
-  │   │   └── README.md
-  │   └── codegenie-mcp-server-linux-x64/   # Linux (x64)
-  │       ├── bin/mcp-server
-  │       ├── package.json
-  │       └── README.md
-  ├── mcp-server-v{version}-{platform}.zip  # 平台压缩包
-  │   └── mcp-server/                       # 内部根目录
-  │       ├── mcp-server (or .exe)          # 可执行文件
-  │       ├── README.md                     # 项目说明
-  │       └── LICENSE                       # 授权协议
-  ├── mcp-server-v{version}-{triple}{ext}   # 原始二进制文件
-  └── arkts-lang-server-{version}.js        # 编译并混淆后的 ArkTS 语言服务脚本
-  ```
-
-  - **NPM 平台包**：通过 `optionalDependencies` 机制，实现在不同平台上自动安装正确的二进制文件。
-  - **ZIP 压缩包**：提供给不使用 NPM 的用户手动下载和集成。
-  - **ArkTS 语言服务**：独立打包的 JS 脚本，供 MCP 服务端调用以执行 ArkTS 相关的静态检查和分析。
+---

package/index.js

@@ -9,7 +9,7 @@ const platform = os.platform();
 const arch = os.arch();
 
 // Binary name in the platform-specific package's bin directory
-let binaryName = 'mcp-server';
+let binaryName = 'codegenie-mcp-server';
 if (platform === 'win32') {
   binaryName += '.exe';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deveco-codegenie/mcp",
-  "version": "0.1.7",
+  "version": "0.1.8-fix2",
   "description": "MCP Server wrapper for npx",
   "main": "index.js",
   "bin": {
@@ -11,9 +11,9 @@
   },
   "dependencies": {},
   "optionalDependencies": {
-    "@deveco-codegenie/mcp-win32-x64": "0.1.7",
-    "@deveco-codegenie/mcp-darwin-x64": "0.1.7",
-    "@deveco-codegenie/mcp-darwin-arm64": "0.1.7",
-    "@deveco-codegenie/mcp-linux-x64": "0.1.7"
+    "@deveco-codegenie/mcp-win32-x64": "0.1.8-fix2",
+    "@deveco-codegenie/mcp-darwin-x64": "0.1.8-fix2",
+    "@deveco-codegenie/mcp-darwin-arm64": "0.1.8-fix2",
+    "@deveco-codegenie/mcp-linux-x64": "0.1.8-fix2"
   }
 }