flutter maestro MCP

Flutter Maestro MCP服务器

实验模型上下文协议（MCP）服务器，使AI代理能够通过VM服务与正在运行的Flutter应用程序交互并执行Maestro流。仅用于使用自定义MCP

先决条件

• Maestro CLI：运行Maestro流所需 run_maestro_flow 工具。

- 通过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代码（推荐）：

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. 使用 connect 具有此URI的工具
3. 尝试以下工具 inspect_ui 和 tap 与正在运行的示例应用程序交互

正在查找VM服务URI：

VM服务URI在Flutter应用程序启动时打印出来。您必须复制完整的URI，包括身份验证令牌：

• VS代码调试控制台：搜索“VM服务”或“天文台”
• Flutter CLI输出：查找“Dart VM服务正在侦听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 （必填-完整的VM服务WebSocket URI，包括Flutter应用程序输出中的auth令牌，例如。， 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 YAML流 maestro test.

- 论据： path