内容
# Flutter Maestro MCP 服务器
实验性的模型上下文协议（MCP）服务器，允许 AI 代理通过 VM 服务与正在运行的 Flutter 应用程序交互并执行 Maestro 流。仅用于测试自定义 MCP
## 前置条件
- **Maestro CLI**：运行 `run_maestro_flow` 工具的 Maestro 流所需。
- 通过 Homebrew 安装：`brew install maestro`
- 或按照[官方安装指南](https://maestro.mobile.dev/getting-started/installing-maestro)
## 安装
1. 克隆此仓库。
2. 运行 `dart pub get` 以安装依赖项。
## 配置
### VS Code
将以下内容添加到 MCP 设置文件（通常为 `~/.vscode/mcp.json` 或类似文件，具体取决于扩展）中：
```json
{
"servers": {
"flutter-maestro": {
"command": "dart",
"args": [
"/绝对路径/to/flutter_maestro_mcp/bin/flutter_maestro_mcp.dart"
]
}
}
}
```
**注意：** 将 `/绝对路径/to/flutter_maestro_mcp` 替换为克隆仓库的实际路径。
## 使用示例应用进行测试
该仓库包含一个示例 Flutter 应用程序，通过测试钩子验证 MCP 服务器功能。
**使用 VS Code（推荐）：**
1. 在 VS Code 中打开仓库。
2. 进入 **运行和调试** 并选择 **"Flutter 示例应用"**。
3. 从调试控制台复制 VM 服务 URI。
**使用命令行：**
1. 导航到 `example/`。
2. 运行应用：`flutter run`。
3. 从输出中记录 VM 服务 URI（例如 `ws://127.0.0.1:12345/ws`）。
**运行后：**
1. 从 Flutter 应用输出中复制完整的 VM 服务 URI。
2. 使用此 URI 的 `connect` 工具。
3. 尝试使用 `inspect_ui` 和 `tap` 等工具与正在运行的示例应用交互。
**查找 VM 服务 URI：**
VM 服务 URI 在 Flutter 应用启动时打印。您必须复制包含身份验证令牌的完整 URI：
- **VS Code 调试控制台**：搜索“VM 服务”或“Observatory”。
- **Flutter CLI 输出**：查找“Dart VM 服务正在监听 ws://...”。
- **URI 格式**：`ws://127.0.0.1:端口/身份验证令牌/ws`。
- **示例**：`ws://127.0.0.1:59548/-ppep2G-MyI=/ws`。
⚠️ **重要：** 不支持自动发现。您必须提供包含身份验证令牌的完整 URI。令牌仅在应用启动时打印一次，之后无法检索。
## 可用工具
- **`connect`**：使用其 VM 服务 URI 连接到正在运行的 Flutter 应用。
- 参数：`uri`（必需 - 包含 Flutter 应用输出中的身份验证令牌的完整 VM 服务 WebSocket URI，例如 `ws://127.0.0.1:59548/-ppep2G-MyI=/ws`）
- **`disconnect`**：断开与当前 Flutter 应用的连接。
- **`inspect_ui`**：获取当前 UI 层次结构的简化 JSON 表示（键、文本、语义）。
- **`tap`**：点击匹配条件的部件。
- 参数：`key`、`text`、`tooltip`、`semantics`
- **`enter_text`**：在匹配条件的部件中输入文本。
- 参数：`input`（必需）以及匹配参数（`key`、`text`等）
- **`scroll_to`**：滚动直到部件可见。
- 参数：匹配参数（`key`、`text`等）
- **`take_screenshot`**：拍摄当前屏幕的截图。
- **`get_logs`**：检索应用程序日志。
- **`hot_reload`**：触发热重载。
- **`write_maestro_flow`**：将 Maestro YAML 流写入文件。
- 参数：`path`、`content`
- **`run_maestro_flow`**：使用 `maestro test` 运行 Maestro YAML 流。
- 参数：`path`
