Flutter Maestro MCP

🚀 Flutter Maestro MCP Server

这是一个实验性的模型上下文协议（MCP）服务器，它允许AI代理通过VM服务与正在运行的Flutter应用程序进行交互，并执行Maestro流程。仅用于自定义MCP的试验。

🚀 快速开始

🔍 前提条件

• Maestro CLI：使用run_maestro_flow工具运行Maestro流程时需要。
  • 通过Homebrew安装：brew install maestro
  • 或者遵循官方安装指南

📦 安装指南

1. 克隆此仓库。
2. 运行dart pub get安装依赖项。

⚙️ 配置

VS Code

将以下内容添加到您的MCP设置文件（通常是~/.vscode/mcp.json或类似文件，具体取决于扩展）中：

{
  "servers": {
    "flutter-maestro": {
      "command": "dart",
      "args": [
        "/absolute/path/to/flutter_maestro_mcp/bin/flutter_maestro_mcp.dart"
      ]
    }
  }
}

注意：将/absolute/path/to/flutter_maestro_mcp替换为您克隆仓库的实际路径。

💻 使用示例

使用示例应用进行测试

此仓库包含一个使用测试钩子进行检测的示例Flutter应用程序，用于验证MCP服务器的功能。

使用VS Code（推荐）：

1. 在VS Code中打开仓库。
2. 转到运行和调试，选择**“Flutter Example App”**。
3. 从调试控制台复制VM服务URI。

使用命令行：

1. 导航到example/目录。
2. 运行应用程序：flutter run。
3. 从输出中记录VM服务URI（例如，ws://127.0.0.1:12345/ws）。

应用运行后：

1. 从Flutter应用输出中复制完整的VM服务URI。
2. 使用connect工具连接此URI。
3. 尝试使用inspect_ui和tap等工具与正在运行的示例应用进行交互。

查找VM服务URI： 当您的Flutter应用启动时，会打印VM服务URI。您必须复制包含认证令牌的完整URI：

• VS Code调试控制台：搜索“VM Service”或“Observatory”。
• Flutter CLI输出：查找“The Dart VM service is listening on ws://...”。
• URI格式：ws://127.0.0.1:PORT/AUTH_TOKEN/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