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