使用说明

项目简介

Maestro MCP服务器是一个基于 Model Context Protocol (MCP) 构建的应用后端，它将 Maestro 移动自动化测试工具的功能以标准化的 MCP 协议形式暴露出来，使得支持 MCP 协议的 LLM 客户端（如 Claude Desktop, Cursor, Windsurf 等）能够方便地调用 Maestro 的功能。

通过 Maestro MCP服务器，LLM 客户端可以：

获取 Maestro 语法速查表 (Cheat Sheet)：快速了解 Maestro 脚本语法。
运行 Maestro 代码片段 (Run Code)：执行指定的 Maestro 脚本代码，实现自动化操作。
运行 Maestro 测试流程文件 (Run Flow Files)：执行完整的 Maestro 测试流程文件。
启动设备 (Start Device)：根据指定的操作系统和平台启动模拟器或真机设备。
获取设备界面层级结构 (Get Hierarchy)：获取当前设备的界面元素层级结构，用于元素定位和操作。
查询 Maestro 文档 (Query Docs)：查询 Maestro 官方文档，获取操作指南和技术细节。
检查 Maestro 语法 (Check Syntax)：验证 Maestro 代码片段的语法是否正确。

主要功能点

资源 (Resources):
- 提供 Maestro 语法速查表资源，方便 LLM 客户端快速查阅。
工具 (Tools):
- 提供一系列工具，封装了 Maestro CLI 的核心功能，例如：
  - 'get_cheat_sheet': 获取 Maestro 语法速查表。
  - 'run_code': 运行 Maestro 代码片段。
  - 'run_flow_files': 运行 Maestro 测试流程文件。
  - 'start_device': 启动设备。
  - 'get_hierarchy': 获取设备界面层级结构。
  - 'query_docs': 查询 Maestro 文档。
  - 'check_syntax': 检查 Maestro 语法。

安装步骤

环境准备: 确保已安装 Python 环境，并配置好 pip 包管理器。
安装 Maestro MCP 服务器: 打开终端，运行以下命令安装 'maestro-mcp' 包：
```
pip install maestro-mcp
```
请参考 Maestro MCP 安装文档获取更详细的安装指南。

服务器配置

MCP 客户端需要配置服务器连接信息才能与 Maestro MCP 服务器通信。以下是一个 MCP 客户端配置示例 (JSON 格式)，用于连接到本地运行的 Maestro MCP 服务器：

{
  "serverName": "Maestro MCP",
  "command": "uv",
  "args": [
    "run",
    "mcp.py"
  ],
  "transport": "stdio"
}

配置参数说明:

'serverName': 服务器名称，可以自定义，用于在客户端标识不同的 MCP 服务器。
'command': 启动 Maestro MCP 服务器的命令。这里使用 'uv run mcp.py'，假设您已安装 'uv' 并将项目中的 'mcp.py' 文件作为入口点。 请确保您已安装 'uv' (可以使用 'pip install uv') 并位于您的系统 PATH 环境变量中。
'args': 启动命令的参数，这里是 '["run", "mcp.py"]'，指定 'uv' 运行 'mcp.py' 文件。
'transport': 传输协议，默认为 'stdio' (标准输入输出)。 Maestro MCP 服务器也可能支持其他传输协议，但此配置示例使用 'stdio'。

重要提示:

Maestro CLI 配置: Maestro MCP 服务器依赖于 Maestro CLI。 请务必先安装并配置好 Maestro CLI，确保 'maestro' 命令可以在终端中正常运行。 您可能需要设置 'MAESTRO_BINARY_PATH' 环境变量来指定 Maestro CLI 的路径，以及配置 'MAESTRO_API_KEY' 或使用 'maestro login' 登录 Maestro 账号。
uv 安装: 示例配置使用了 'uv run mcp.py' 启动服务器。 'uv' 是一个快速的 Python 包安装器和运行器，如果您的环境中没有 'uv'，请先安装 'uv' (可以使用 'pip install uv')。您也可以根据您的环境选择其他 ASGI 服务器运行方式，例如 'hypercorn' 或 'uvicorn'，并相应修改 'command' 和 'args' 配置。

基本使用方法

启动 Maestro MCP 服务器: 在安装好 'maestro-mcp' 包和配置好 Maestro CLI 环境后，打开终端，进入 'mcp.py' 文件所在的目录，运行配置中指定的启动命令，例如 'uv run mcp.py'。服务器成功启动后，通常会在终端输出日志信息。
配置 MCP 客户端: 在支持 MCP 协议的 LLM 客户端中，根据上述 服务器配置 部分的示例，配置连接到 Maestro MCP 服务器。确保客户端配置的 'command' 和 'args' 与您实际启动服务器的命令一致。
在 LLM 客户端中使用 Maestro 功能: 连接成功后，您就可以在 LLM 客户端中发现 Maestro MCP 服务器提供的 Resources 和 Tools。根据您的需求，调用相应的 Tool 来执行自动化测试任务，或访问 Resource 获取 Maestro 语法速查表等信息。具体操作方式请参考您使用的 LLM 客户端的文档。

关键词