@deriv-com/fe-mcp-servers 0.0.11 → 0.0.12

package/dist/maestro-ai/README.md

@@ -147,6 +147,37 @@ Returns common Maestro patterns with "when to use" guidance.
 - Pattern YAML code
 - Usage guidance for each pattern
 
+### `maestro_ensure_installed` Tool
+
+⚠️ **PREREQUISITE**: Call this FIRST before using `maestro_write_test` or `maestro_run_all_tests`!
+
+Checks if Maestro CLI is installed and automatically installs it if missing.
+
+**When to Call:**
+
+- ALWAYS before `maestro_write_test` (when execute=true)
+- ALWAYS before `maestro_run_all_tests`
+- When setting up a new development environment
+
+**Parameters:**
+
+- `autoInstall` (boolean, optional): Whether to automatically install if not found (default: true)
+- `forceReinstall` (boolean, optional): Whether to force reinstall even if already installed (default: false)
+
+**Returns:**
+
+- `installed`: boolean - Whether Maestro is now installed
+- `version`: string - Installed version (if available)
+- `wasInstalled`: boolean - Whether this call performed the installation
+- `message`: string - Status message
+- `details`: object - Additional info (path, install method)
+
+**Installation Method:**
+
+```bash
+curl -fsSL "https://get.maestro.mobile.dev" | bash
+```
+
 ### `maestro_analyze_changes` Tool
 
 Automatically analyzes actual git changes in a repository and provides test recommendations.
@@ -164,6 +195,122 @@ Automatically analyzes actual git changes in a repository and provides test reco
 - Interactive elements detected (onClick, Button, Form, etc.)
 - Suggested flow type and whether to create tests
 
+---
+
+## 🚀 Test Execution Tools
+
+### `maestro_write_test` Tool
+
+Writes a Maestro test YAML file to disk.
+
+**Parameters:**
+
+- `yaml` (string, required): The YAML content to write
+- `fileName` (string, required): Name of the file (e.g., "login_test.yaml")
+- `directory` (string, optional): Target directory (default: "maestro")
+- `basePath` (string, optional): Project base path (default: current directory)
+
+**Returns:**
+
+- `success`: boolean
+- `filePath`: Path where file was written
+- `message`: Status message
+
+### `maestro_execute_test` Tool
+
+Executes a single Maestro test file using the Maestro CLI.
+
+**Prerequisites:**
+
+- Maestro CLI must be installed (`curl -fsSL https://get.maestro.dev | bash`)
+- A device/simulator must be running
+
+**Parameters:**
+
+- `flowFile` (string, required): Path to the .yaml flow file
+- `deviceId` (string, optional): Target device ID
+- `env` (object, optional): Environment variables to pass
+- `timeout` (number, optional): Execution timeout in ms (default: 120000)
+
+**Returns:**
+
+- `success`: boolean
+- `output`: Test output/logs
+- `exitCode`: Process exit code
+- `duration`: Execution time in ms
+
+### `maestro_execute_tests_sequential` Tool
+
+Executes multiple Maestro test files sequentially with aggregated results.
+
+**Parameters:**
+
+- `flowFiles` (array, required): Array of flow file paths to execute
+- `deviceId` (string, optional): Target device ID
+- `env` (object, optional): Environment variables to pass
+- `stopOnFailure` (boolean, optional): Stop on first failure (default: false)
+
+**Returns:**
+
+- `success`: boolean (true if all tests passed)
+- `results`: Array of individual test results
+- `summary`: Aggregated statistics (passed, failed, skipped, duration)
+
+### `maestro_generate_and_run` Tool
+
+All-in-one workflow: Generate, write, and execute a Maestro test.
+
+**Parameters:**
+
+- `feature` (string, required): Feature being tested
+- `action` (string, required): Action being tested
+- `flowType` (string, required): Flow type (auth, form, sidebar, modal, navigation, extended)
+- `basePath` (string, optional): Project base path
+- `deviceId` (string, optional): Target device ID
+- `env` (object, optional): Environment variables
+- `execute` (boolean, optional): Execute after writing (default: true)
+- `changedElements` (array, optional): List of changed UI elements
+- `existingTests` (array, optional): List of existing related test files
+
+**Returns:**
+
+- `generation`: Generated template and guidelines
+- `write`: File write result
+- `execution`: Test execution results (if execute=true)
+- `summary`: Human-readable summary
+
+### `maestro_discover_tests` Tool
+
+Discovers all Maestro test files in a directory.
+
+**Parameters:**
+
+- `directory` (string, optional): Directory to search (default: "maestro")
+- `basePath` (string, optional): Project base path
+
+**Returns:**
+
+- `files`: Array of file paths
+- `count`: Number of files found
+
+### `maestro_run_all_tests` Tool
+
+Runs all Maestro tests in a directory sequentially.
+
+**Parameters:**
+
+- `directory` (string, optional): Directory containing tests (default: "maestro")
+- `basePath` (string, optional): Project base path
+- `deviceId` (string, optional): Target device ID
+- `env` (object, optional): Environment variables
+- `stopOnFailure` (boolean, optional): Stop on first failure (default: false)
+
+**Returns:**
+
+- `discovery`: List of discovered test files
+- `execution`: Results with pass/fail status for each test
+- `summary`: Aggregated statistics
+
 ## 🎯 Usage Examples
 
 Once configured in your MCP client, you can use the tools in your conversations:
@@ -237,6 +384,58 @@ env:
 3. **Quick Reference**: `maestro_cheat_sheet()`
 4. **Pattern Lookup**: `maestro_pattern(patternType: "login")`
 5. **UI Discovery**: `maestro_ui_inspection()`
+6. **Pre-check Installation**: `maestro_ensure_installed()` - Verifies Maestro CLI is ready
+
+### Test Execution Use Cases
+
+6. **Generate & Run Test**:
+
+```
+maestro_generate_and_run(
+  feature: "Login",
+  action: "OAuth flow",
+  flowType: "auth",
+  basePath: "/path/to/project"
+)
+```
+
+7. **Run All Tests in Directory**:
+
+```
+maestro_run_all_tests(
+  directory: "maestro",
+  basePath: "/path/to/project",
+  stopOnFailure: false
+)
+```
+
+8. **Execute Specific Tests Sequentially**:
+
+```
+maestro_execute_tests_sequential(
+  flowFiles: ["maestro/login.yaml", "maestro/checkout.yaml"],
+  env: { "BASE_URL": "https://staging.example.com" }
+)
+```
+
+9. **Write Test File Only (No Execution)**:
+
+```
+maestro_write_test(
+  yaml: "<generated yaml content>",
+  fileName: "user_settings_reset.yaml",
+  basePath: "/path/to/project"
+)
+```
+
+10. **Discover Available Tests**:
+
+```
+maestro_discover_tests(
+  directory: "maestro",
+  basePath: "/path/to/project"
+)
+```
 
 ## Flow Types
 
@@ -259,6 +458,73 @@ env:
 | `lastCommit` | Most recent commit             | `git diff HEAD~1`                |
 | `branch`     | Compare to base branch         | `git diff {baseBranch}...HEAD`   |
 
+## 🔄 Complete Workflow Example
+
+### ⚠️ IMPORTANT: Always Check Installation First!
+
+When a user asks to "generate and run test cases" or use Maestro, follow this order:
+
+```bash
+# Step 0: ALWAYS check Maestro installation first!
+maestro_ensure_installed()
+
+# If not installed, the tool will automatically install it via:
+# curl -fsSL "https://get.maestro.mobile.dev" | bash
+```
+
+### End-to-End: Analyze Changes → Generate → Execute
+
+```bash
+# Step 0: Ensure Maestro is installed (REQUIRED)
+maestro_ensure_installed()
+
+# Step 1: Analyze git changes to see what needs testing
+maestro_analyze_changes(repoPath: "/path/to/project", changeType: "staged")
+
+# Output shows: Settings.tsx changed with onClick handler
+# Suggested flow type: form
+
+# Step 2: Generate and run the test in one call
+maestro_generate_and_run(
+  feature: "User Settings",
+  action: "Reset defaults",
+  flowType: "form",
+  basePath: "/path/to/project",
+  env: { "BASE_URL": "https://localhost:8443" }
+)
+
+# Output:
+# - File written to: /path/to/project/maestro/user_settings_reset_defaults.yaml
+# - Test executed: ✅ Passed (duration: 12.5s)
+```
+
+### Sequential Test Suite Execution
+
+```bash
+# Step 0: Ensure Maestro is installed (REQUIRED)
+maestro_ensure_installed()
+
+# Discover all tests
+maestro_discover_tests(basePath: "/path/to/project")
+# Output: Found 5 test files
+
+# Run all tests with stop-on-failure
+maestro_run_all_tests(
+  basePath: "/path/to/project",
+  stopOnFailure: true,
+  env: { "BASE_URL": "https://staging.example.com" }
+)
+
+# Output:
+# ✅ login_basic.yaml (8.2s)
+# ✅ user_settings_open.yaml (5.1s)
+# ❌ checkout_submit.yaml (12.3s) - FAILED
+# ⏭️ payment_confirm.yaml - SKIPPED
+# ⏭️ logout.yaml - SKIPPED
+#
+# Summary: 2 passed, 1 failed, 2 skipped
+```
+
 ## 📊 Examples
 
 ### Auth Flow Template
@@ -280,6 +546,9 @@ env:
 - tapOn:
     text: "Next"
     repeat: 3
+- tapOn:
+    text: "Got it"
+    repeat: 3
 - tapOn:
     text: "Log in"
 - inputText: ${USER_EMAIL}

package/dist/maestro-ai/mcp-server.js

@@ -18492,7 +18492,17 @@ var StdioServerTransport = class {
 };
 
 // maestro-ai/src/mcp.js
-import { execSync } from "child_process";
+import { execSync, spawn } from "child_process";
+import {
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  openSync,
+  closeSync,
+  fsyncSync
+} from "fs";
+import { join, dirname } from "path";
 var FLOW_TYPES = {
   auth: {
     description: "Login, signup, or password reset flows",
@@ -18520,6 +18530,156 @@ var FLOW_TYPES = {
     requiresOnboarding: false
   }
 };
+function isMaestroInstalled() {
+  try {
+    execSync("which maestro", { encoding: "utf-8", stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function installMaestro() {
+  const installCmd = 'curl -fsSL "https://get.maestro.mobile.dev" | bash';
+  try {
+    try {
+      execSync(installCmd, {
+        encoding: "utf-8",
+        stdio: "pipe",
+        shell: "/bin/bash",
+        timeout: 12e4
+        // 2 minute timeout for install
+      });
+    } catch (curlError) {
+      const curlOutput = curlError.stderr || curlError.stdout || curlError.message;
+      throw new Error(`Installation failed: ${curlOutput}`);
+    }
+    if (isMaestroInstalled()) {
+      return {
+        success: true,
+        message: "\u2705 Maestro CLI installed successfully!",
+        method: "curl"
+      };
+    }
+    const homeDir = process.env.HOME || process.env.USERPROFILE;
+    const maestroBin = join(homeDir, ".maestro", "bin");
+    process.env.PATH = `${maestroBin}:${process.env.PATH}`;
+    try {
+      execSync(`${join(maestroBin, "maestro")} --version`, {
+        encoding: "utf-8",
+        stdio: "pipe"
+      });
+      return {
+        success: true,
+        message: `\u2705 Maestro CLI installed successfully! Added ${maestroBin} to PATH.`,
+        method: "curl"
+      };
+    } catch {
+      return {
+        success: false,
+        message: `\u26A0\uFE0F Maestro installed but not in PATH. Add ${maestroBin} to your PATH and restart your terminal.`,
+        method: "curl"
+      };
+    }
+  } catch (error2) {
+    return {
+      success: false,
+      message: `\u274C Failed to install Maestro: ${error2.message}
+
+Manual install:
+${installCmd}`,
+      method: "curl"
+    };
+  }
+}
+function ensureMaestroAvailable() {
+  if (isMaestroInstalled()) {
+    return {
+      available: true,
+      message: "Maestro CLI is available",
+      installed: false
+    };
+  }
+  const installResult = installMaestro();
+  return {
+    available: installResult.success,
+    message: installResult.message,
+    installed: installResult.success
+  };
+}
+function getMaestroVersion() {
+  try {
+    const version2 = execSync("maestro --version", {
+      encoding: "utf-8",
+      stdio: "pipe"
+    }).trim();
+    return version2;
+  } catch {
+    return null;
+  }
+}
+function ensureMaestroInstalled(options = {}) {
+  const { autoInstall = true, forceReinstall = false } = options;
+  const result = {
+    installed: false,
+    version: null,
+    wasInstalled: false,
+    message: "",
+    details: {
+      installMethod: null,
+      path: null
+    }
+  };
+  const alreadyInstalled = isMaestroInstalled();
+  const currentVersion = alreadyInstalled ? getMaestroVersion() : null;
+  if (alreadyInstalled && !forceReinstall) {
+    result.installed = true;
+    result.version = currentVersion;
+    result.wasInstalled = false;
+    result.message = `\u2705 Maestro CLI is already installed (${currentVersion || "version unknown"})`;
+    try {
+      const path = execSync("which maestro", {
+        encoding: "utf-8",
+        stdio: "pipe"
+      }).trim();
+      result.details.path = path;
+    } catch {
+    }
+    return result;
+  }
+  if (!autoInstall) {
+    result.installed = false;
+    result.version = null;
+    result.wasInstalled = false;
+    result.message = `\u274C Maestro CLI is not installed. Set autoInstall: true to install automatically.`;
+    result.details.installCommand = 'curl -fsSL "https://get.maestro.mobile.dev" | bash';
+    return result;
+  }
+  const installResult = installMaestro();
+  if (installResult.success) {
+    const newVersion = getMaestroVersion();
+    result.installed = true;
+    result.version = newVersion;
+    result.wasInstalled = true;
+    result.message = installResult.message;
+    result.details.installMethod = installResult.method;
+    try {
+      const path = execSync("which maestro", {
+        encoding: "utf-8",
+        stdio: "pipe"
+      }).trim();
+      result.details.path = path;
+    } catch {
+    }
+  } else {
+    result.installed = false;
+    result.version = null;
+    result.wasInstalled = false;
+    result.message = installResult.message;
+    result.details.installMethod = installResult.method;
+    result.details.installCommand = 'curl -fsSL "https://get.maestro.mobile.dev" | bash';
+  }
+  return result;
+}
 function getMaestroCheatSheet() {
   const commands = [
     {
@@ -19289,6 +19449,305 @@ ${analysis.shouldCreateTest ? `1. Review the changed UI files above
     }
   };
 }
+function writeTestFile(options = {}) {
+  const {
+    yaml,
+    fileName,
+    directory = "maestro",
+    basePath = process.cwd(),
+    execute = true,
+    deviceId = null,
+    env = {},
+    feature = "",
+    action = "",
+    flowType = null,
+    changedElements = [],
+    existingTests = []
+  } = options;
+  const generation = generateMaestroTest({
+    feature,
+    action,
+    flowType,
+    changedElements,
+    existingTests
+  });
+  if (!yaml || !fileName) {
+    return {
+      success: false,
+      filePath: null,
+      message: "\u274C Missing required parameters: yaml and fileName are required"
+    };
+  }
+  const normalizedFileName = fileName.endsWith(".yaml") ? fileName : `${fileName}.yaml`;
+  const targetDir = join(basePath, directory);
+  const filePath = join(targetDir, normalizedFileName);
+  try {
+    if (!existsSync(targetDir)) {
+      mkdirSync(targetDir, { recursive: true });
+    }
+    writeFileSync(filePath, yaml, "utf-8");
+    const fd = openSync(filePath, "r");
+    fsyncSync(fd);
+    closeSync(fd);
+    const result = {
+      success: true,
+      filePath,
+      message: `\u2705 Test file written successfully to: ${filePath}`,
+      generation
+      // Include test generation guidelines and instructions
+    };
+    if (execute) {
+      const sleep = (ms) => {
+        const end = Date.now() + ms;
+        while (Date.now() < end) {
+        }
+      };
+      sleep(500);
+      const execution = executeTest({
+        flowFile: filePath,
+        deviceId,
+        env
+      });
+      result.execution = execution;
+      result.message += execution.success ? "\n\u2705 Test executed successfully!" : "\n\u274C Test execution failed.";
+    }
+    return result;
+  } catch (error2) {
+    return {
+      success: false,
+      filePath: null,
+      message: `\u274C Failed to write test file: ${error2.message}`
+    };
+  }
+}
+function executeTest(options = {}) {
+  const { flowFile, deviceId = null, env = {}, timeout = 12e4 } = options;
+  if (!flowFile) {
+    return {
+      success: false,
+      output: "\u274C Missing required parameter: flowFile",
+      exitCode: 1,
+      duration: 0
+    };
+  }
+  const maestroCheck = ensureMaestroAvailable();
+  if (!maestroCheck.available) {
+    return {
+      success: false,
+      output: maestroCheck.message,
+      exitCode: 1,
+      duration: 0,
+      maestroInstalled: false
+    };
+  }
+  const args = ["test"];
+  if (deviceId) {
+    args.push("--device", deviceId);
+  }
+  Object.entries(env).forEach(([key, value]) => {
+    args.push("-e", `${key}=${value}`);
+  });
+  args.push(flowFile);
+  const command = `maestro ${args.join(" ")}`;
+  const startTime = Date.now();
+  try {
+    const output = execSync(command, {
+      encoding: "utf-8",
+      timeout,
+      maxBuffer: 10 * 1024 * 1024,
+      env: { ...process.env, ...env }
+    });
+    const duration3 = Date.now() - startTime;
+    return {
+      success: true,
+      output: `${maestroCheck.installed ? "\u{1F4E6} " + maestroCheck.message + "\n\n" : ""}\u2705 Test passed!
+
+Command: ${command}
+
+${output}`,
+      exitCode: 0,
+      duration: duration3,
+      command,
+      maestroInstalled: maestroCheck.installed
+    };
+  } catch (error2) {
+    const duration3 = Date.now() - startTime;
+    const output = error2.stdout || error2.stderr || error2.message;
+    return {
+      success: false,
+      output: `${maestroCheck.installed ? "\u{1F4E6} " + maestroCheck.message + "\n\n" : ""}\u274C Test failed!
+
+Command: ${command}
+
+${output}`,
+      exitCode: error2.status || 1,
+      duration: duration3,
+      command,
+      maestroInstalled: maestroCheck.installed
+    };
+  }
+}
+function executeTestsSequentially(options = {}) {
+  const {
+    flowFiles = [],
+    deviceId = null,
+    env = {},
+    stopOnFailure = false
+  } = options;
+  if (!flowFiles || flowFiles.length === 0) {
+    return {
+      success: false,
+      results: [],
+      summary: {
+        total: 0,
+        passed: 0,
+        failed: 0,
+        skipped: 0,
+        totalDuration: 0
+      }
+    };
+  }
+  const results = [];
+  let stopped = false;
+  for (const flowFile of flowFiles) {
+    if (stopped) {
+      results.push({
+        flowFile,
+        success: false,
+        output: "\u23ED\uFE0F Skipped due to previous failure",
+        exitCode: -1,
+        duration: 0,
+        skipped: true
+      });
+      continue;
+    }
+    const result = executeTest({ flowFile, deviceId, env });
+    results.push({
+      flowFile,
+      ...result,
+      skipped: false
+    });
+    if (!result.success && stopOnFailure) {
+      stopped = true;
+    }
+  }
+  const passed = results.filter((r) => r.success).length;
+  const failed = results.filter((r) => !r.success && !r.skipped).length;
+  const skipped = results.filter((r) => r.skipped).length;
+  const totalDuration = results.reduce((sum, r) => sum + r.duration, 0);
+  return {
+    success: failed === 0,
+    results,
+    summary: {
+      total: flowFiles.length,
+      passed,
+      failed,
+      skipped,
+      totalDuration,
+      report: `
+## \u{1F4CA} Test Execution Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Tests | ${flowFiles.length} |
+| \u2705 Passed | ${passed} |
+| \u274C Failed | ${failed} |
+| \u23ED\uFE0F Skipped | ${skipped} |
+| \u23F1\uFE0F Duration | ${(totalDuration / 1e3).toFixed(2)}s |
+
+### Results by Flow:
+${results.map(
+        (r) => `- ${r.success ? "\u2705" : r.skipped ? "\u23ED\uFE0F" : "\u274C"} \`${r.flowFile}\` (${(r.duration / 1e3).toFixed(2)}s)`
+      ).join("\n")}
+`
+    }
+  };
+}
+function discoverTestFiles(options = {}) {
+  const { directory = "maestro", basePath = process.cwd() } = options;
+  const targetDir = join(basePath, directory);
+  if (!existsSync(targetDir)) {
+    return {
+      files: [],
+      count: 0,
+      message: `\u274C Directory not found: ${targetDir}`
+    };
+  }
+  try {
+    const result = execSync(`find "${targetDir}" -name "*.yaml" -type f`, {
+      encoding: "utf-8"
+    });
+    const files = result.trim().split("\n").filter(Boolean);
+    return {
+      files,
+      count: files.length,
+      message: `Found ${files.length} test file(s) in ${targetDir}`
+    };
+  } catch (error2) {
+    return {
+      files: [],
+      count: 0,
+      message: `\u274C Error discovering files: ${error2.message}`
+    };
+  }
+}
+function runAllTests(options = {}) {
+  const {
+    directory = "maestro",
+    basePath = process.cwd(),
+    deviceId = null,
+    env = {},
+    stopOnFailure = false,
+    files = null
+  } = options;
+  let discovery;
+  let filesToRun;
+  if (files && Array.isArray(files) && files.length > 0) {
+    filesToRun = files.map((f) => {
+      if (f.startsWith("/")) {
+        return f;
+      }
+      return join(basePath, f);
+    });
+    discovery = {
+      files: filesToRun,
+      count: filesToRun.length,
+      message: `Using ${filesToRun.length} specified test file(s)`,
+      mode: "specified"
+    };
+  } else {
+    discovery = discoverTestFiles({ directory, basePath });
+    discovery.mode = "discovered";
+    filesToRun = discovery.files;
+  }
+  if (!filesToRun || filesToRun.length === 0) {
+    return {
+      discovery,
+      execution: {
+        success: false,
+        results: [],
+        summary: {
+          total: 0,
+          passed: 0,
+          failed: 0,
+          skipped: 0,
+          totalDuration: 0,
+          report: "No test files found to execute."
+        }
+      }
+    };
+  }
+  const execution = executeTestsSequentially({
+    flowFiles: filesToRun,
+    deviceId,
+    env,
+    stopOnFailure
+  });
+  return {
+    discovery,
+    execution
+  };
+}
 
 // maestro-ai/src/mcp-server.js
 var transport = new StdioServerTransport();
@@ -19306,6 +19765,53 @@ var server = new Server(
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return {
     tools: [
+      {
+        name: "maestro_ensure_installed",
+        description: `\u26A0\uFE0F PREREQUISITE: Call this FIRST before using maestro_write_test or maestro_run_all_tests!
+
+Checks if Maestro CLI is installed and automatically installs it if missing.
+
+## \u{1F6A8} CRITICAL: Always Call First
+When a user asks to "generate and run tests" or "run Maestro tests", you MUST:
+1. FIRST call maestro_ensure_installed() to verify/install Maestro CLI
+2. THEN proceed with test generation/execution tools
+
+## Purpose
+Ensures Maestro CLI is available before running any Maestro commands. This tool:
+- Checks if Maestro CLI is installed on the system
+- Automatically installs it if missing (via Homebrew or curl)
+- Returns version and path information
+
+## When to Use
+- ALWAYS before maestro_write_test (if execute=true)
+- ALWAYS before maestro_run_all_tests
+- When setting up a new development environment
+- To troubleshoot Maestro installation issues
+
+## Installation Method
+Uses curl installer: \`curl -fsSL "https://get.maestro.mobile.dev" | bash\`
+
+## Output
+- installed: Whether Maestro is now installed
+- version: Installed version (if available)
+- wasInstalled: Whether this call performed the installation
+- message: Status message
+- details: Additional info (path, install method)`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            autoInstall: {
+              type: "boolean",
+              description: "Whether to automatically install Maestro if not found (default: true)"
+            },
+            forceReinstall: {
+              type: "boolean",
+              description: "Whether to force reinstall even if already installed (default: false)"
+            }
+          },
+          required: []
+        }
+      },
       {
         name: "maestro_generate_test",
         description: `Generates comprehensive Maestro test instructions for web applications.
@@ -19542,6 +20048,198 @@ Automatically runs git commands to:
           },
           required: ["repoPath"]
         }
+      },
+      {
+        name: "maestro_write_test",
+        description: `Writes a Maestro test YAML file to disk and automatically executes it.
+
+## \u{1F6A8} PREREQUISITE: Call maestro_ensure_installed() FIRST before using this tool!
+
+## Purpose
+Saves generated test YAML to a file and AUTOMATICALLY RUNS IT. This is the primary tool for "generate and run" workflows.
+
+## IMPORTANT
+- \u26A0\uFE0F ALWAYS call maestro_ensure_installed() first to ensure Maestro CLI is available!
+- This tool ALREADY executes the test by default - do NOT call maestro_run_all_tests after this!
+- Use this for running newly generated tests
+- The execution result is included in the response
+- This tool internally calls maestro_generate_test to provide guidelines and instructions
+
+## Parameters
+- yaml: The YAML content to write (required)
+- fileName: Name of the file, e.g., "login_test.yaml" (required)
+- directory: Target directory (default: "maestro")
+- basePath: Project base path (default: current directory)
+- execute: Whether to auto-execute after writing (default: true)
+- deviceId: Device ID for execution (optional)
+- env: Environment variables for execution (optional)
+- feature: Feature being tested (for test generation guidelines)
+- action: Action being tested (for test generation guidelines)
+- flowType: Type of flow template (auth, sidebar, form, modal, navigation, extended)
+- changedElements: List of UI elements that were changed
+- existingTests: List of existing related test files
+
+## Output
+- success: boolean
+- filePath: Path where file was written
+- message: Status message
+- generation: Test generation guidelines and instructions (from maestro_generate_test)
+- execution: Test execution results (if execute=true)`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            yaml: {
+              type: "string",
+              description: "The YAML content to write"
+            },
+            fileName: {
+              type: "string",
+              description: 'Name of the file (e.g., "login_test.yaml")'
+            },
+            directory: {
+              type: "string",
+              description: 'Target directory (default: "maestro")'
+            },
+            basePath: {
+              type: "string",
+              description: "Project base path (default: current directory)"
+            },
+            execute: {
+              type: "boolean",
+              description: "Whether to auto-execute the test after writing (default: true)"
+            },
+            deviceId: {
+              type: "string",
+              description: "Device ID to run on (optional)"
+            },
+            env: {
+              type: "object",
+              description: "Environment variables to pass",
+              additionalProperties: { type: "string" }
+            },
+            feature: {
+              type: "string",
+              description: 'Feature being tested for generation guidelines (e.g., "User Settings")'
+            },
+            action: {
+              type: "string",
+              description: 'Action being tested for generation guidelines (e.g., "Reset defaults")'
+            },
+            flowType: {
+              type: "string",
+              enum: [
+                "auth",
+                "sidebar",
+                "form",
+                "modal",
+                "navigation",
+                "extended"
+              ],
+              description: "Type of flow template for generation guidelines"
+            },
+            changedElements: {
+              type: "array",
+              items: { type: "string" },
+              description: "List of UI elements that were changed (from git diff)"
+            },
+            existingTests: {
+              type: "array",
+              items: { type: "string" },
+              description: "List of existing related test files to potentially extend"
+            }
+          },
+          required: ["yaml", "fileName"]
+        }
+      },
+      {
+        name: "maestro_discover_tests",
+        description: `Discovers all Maestro test files in a directory.
+
+## Purpose
+Lists all .yaml test files in the maestro/ directory.
+
+## Parameters
+- directory: Directory to search (default: "maestro")
+- basePath: Project base path
+
+## Output
+- files: Array of file paths
+- count: Number of files found`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            directory: {
+              type: "string",
+              description: 'Directory to search (default: "maestro")'
+            },
+            basePath: {
+              type: "string",
+              description: "Project base path"
+            }
+          },
+          required: []
+        }
+      },
+      {
+        name: "maestro_run_all_tests",
+        description: `Runs the ENTIRE Maestro test suite.
+
+## \u{1F6A8} PREREQUISITE: Call maestro_ensure_installed() FIRST before using this tool!
+
+## \u26A0\uFE0F ONLY use when user EXPLICITLY asks to "run all tests" or "run the test suite"
+
+## DO NOT USE for:
+- "generate and run test cases" \u2192 use maestro_write_test instead (it auto-executes)
+- Running a newly generated test \u2192 maestro_write_test already does this
+- Any workflow that involves generating new tests
+
+## Purpose
+Discovers and executes ALL existing .yaml test files in the maestro/ directory.
+
+## Parameters
+- files: Specific test file paths (optional)
+- directory: Directory containing tests (default: "maestro")
+- basePath: Project base path
+- deviceId: Target device ID
+- env: Environment variables
+- stopOnFailure: Stop on first failure (default: false)
+
+## Output
+- discovery: List of test files found
+- execution: Results with pass/fail status for each test
+- summary: Aggregated statistics`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            files: {
+              type: "array",
+              items: { type: "string" },
+              description: "Specific test file paths to run (if provided, only these files are executed instead of discovering all)"
+            },
+            directory: {
+              type: "string",
+              description: 'Directory containing tests (default: "maestro") - only used if files is not provided'
+            },
+            basePath: {
+              type: "string",
+              description: "Project base path"
+            },
+            deviceId: {
+              type: "string",
+              description: "Device ID to run on"
+            },
+            env: {
+              type: "object",
+              description: "Environment variables",
+              additionalProperties: { type: "string" }
+            },
+            stopOnFailure: {
+              type: "boolean",
+              description: "Stop on first failure (default: false)"
+            }
+          },
+          required: []
+        }
       }
     ]
   };
@@ -19550,6 +20248,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   let result;
   switch (name) {
+    case "maestro_ensure_installed": {
+      const { autoInstall, forceReinstall } = args || {};
+      result = ensureMaestroInstalled({
+        autoInstall: autoInstall !== false,
+        // defaults to true
+        forceReinstall: forceReinstall || false
+      });
+      break;
+    }
     case "maestro_generate_test": {
       const { feature, action, flowType, changedElements, existingTests } = args || {};
       result = generateMaestroTest({
@@ -19600,6 +20307,58 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       });
       break;
     }
+    case "maestro_write_test": {
+      const {
+        yaml,
+        fileName,
+        directory,
+        basePath,
+        execute,
+        deviceId,
+        env,
+        feature,
+        action,
+        flowType,
+        changedElements,
+        existingTests
+      } = args || {};
+      result = writeTestFile({
+        yaml,
+        fileName,
+        directory: directory || "maestro",
+        basePath: basePath || process.cwd(),
+        execute: execute !== false,
+        // defaults to true
+        deviceId: deviceId || null,
+        env: env || {},
+        feature: feature || "",
+        action: action || "",
+        flowType: flowType || null,
+        changedElements: changedElements || [],
+        existingTests: existingTests || []
+      });
+      break;
+    }
+    case "maestro_discover_tests": {
+      const { directory, basePath } = args || {};
+      result = discoverTestFiles({
+        directory: directory || "maestro",
+        basePath: basePath || process.cwd()
+      });
+      break;
+    }
+    case "maestro_run_all_tests": {
+      const { files, directory, basePath, deviceId, env, stopOnFailure } = args || {};
+      result = runAllTests({
+        files: files || null,
+        directory: directory || "maestro",
+        basePath: basePath || process.cwd(),
+        deviceId: deviceId || null,
+        env: env || {},
+        stopOnFailure: stopOnFailure || false
+      });
+      break;
+    }
     default:
       throw new Error(`Unknown tool: ${name}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deriv-com/fe-mcp-servers",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Collection of Front-End Model Context Protocol (MCP) servers for reusability and standardization",
   "type": "module",
   "bin": {