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

package/dist/maestro-ai/README.md

@@ -31,12 +31,30 @@ Add to your MCP client configuration (e.g., in Cursor settings):
       "command": "node",
       "args": [
         "/Users/user/.nvm/versions/node/v20.17.0/lib/node_modules/@deriv-com/fe-mcp-servers/dist/maestro-ai/mcp-server.js"
-      ]
+      ],
+      "env": {
+        "CLICKUP_API_TOKEN": "${env:CLICKUP_API_TOKEN}",
+        "CLICKUP_AC_SOURCE": "${env:CLICKUP_AC_SOURCE}"
+      }
     }
   }
 }
 ```
 
+### Environment Variables (Optional - for ClickUp Integration)
+
+Set these in your shell profile (`.bashrc`, `.zshrc`, etc.):
+
+```bash
+# ClickUp API token for fetching task acceptance criteria
+export CLICKUP_API_TOKEN="pk_your_api_token_here"
+
+# Source for acceptance criteria (default: "checklist:Acceptance Criteria")
+# Supports: checklist:Name, custom_field:Name, description
+# Multiple sources: "checklist:Acceptance Criteria,custom_field:AC,description"
+export CLICKUP_AC_SOURCE="checklist:Acceptance Criteria"
+```
+
 ## 🛠️ Development Structure
 
 ### Source Code (Development)
@@ -197,6 +215,108 @@ Automatically analyzes actual git changes in a repository and provides test reco
 
 ---
 
+## 🔗 ClickUp Integration Tools
+
+These tools enable test generation based on ClickUp task acceptance criteria.
+
+### `clickup_fetch_task` Tool
+
+Fetches a ClickUp task by URL to extract acceptance criteria for test generation.
+
+**ASK FIRST Pattern:**
+When called WITHOUT a `taskUrl`, this tool returns a prompt asking the user:
+
+> "Do you have a ClickUp task URL for this feature? Paste the URL to generate tests based on acceptance criteria, or type 'skip' to continue with git-based analysis only."
+
+**Parameters:**
+
+- `taskUrl` (string, optional): ClickUp task URL. If omitted, returns a prompt. Use "skip" to bypass.
+
+**URL Formats Supported:**
+
+- `https://app.clickup.com/t/abc123`
+- `https://app.clickup.com/t/86abc123`
+- `https://app.clickup.com/{workspace}/v/...?p=abc123`
+
+**Returns:**
+
+- If no URL: `{ needsInput: true, prompt: "..." }` - asking for URL
+- If URL provided: Full task object with checklists, custom fields, description
+- If "skip": `{ skipped: true }` - continue without ClickUp
+
+**Environment Variable Required:** `CLICKUP_API_TOKEN`
+
+### `validate_acceptance_criteria` Tool
+
+Parses and validates acceptance criteria from a ClickUp task for testability.
+
+**Parameters:**
+
+- `task` (object, required): ClickUp task object from `clickup_fetch_task`
+- `acSource` (string, optional): AC source specification (uses `CLICKUP_AC_SOURCE` env var if not provided)
+
+**AC Source Formats:**
+
+- `checklist:Checklist Name` - Parse from a specific checklist
+- `custom_field:Field Name` - Parse from a custom field
+- `description` - Parse from task description
+- Multiple: `"checklist:Acceptance Criteria,custom_field:AC,description"`
+
+**Returns:**
+
+- `validatedItems`: Array of AC items with testability analysis
+- `testableCount`: Number of items that can be tested via Maestro
+- `suggestedFlowTypes`: Recommended flow types based on AC content
+
+### `map_AC_to_UI` Tool
+
+⚠️ **HARD VALIDATION** - Maps acceptance criteria items to UI elements and **FAILS on mismatches**.
+
+This tool performs strict validation of AC against actual UI implementation. If the AC specifies one value but the UI has a different value, this tool will:
+
+1. **FAIL** (`success: false`)
+2. **Report** the exact mismatch
+3. **Block** test generation until resolved
+
+**Example:** If AC says "20 days option" but the UI has "Last 30 days", this is a **validation error** - the test should NOT be generated until the discrepancy is resolved.
+
+**Parameters:**
+
+- `acItems` (array, optional): Validated AC items. If omitted, uses git-only analysis (soft mode).
+- `repoPath` (string, optional): Path to git repository (default: current directory)
+- `changedFiles` (array, optional): List of changed files (auto-detected if omitted)
+
+**Returns:**
+
+- `success`: **false** if any AC doesn't match UI, **true** if all validated
+- `validationErrors`: Array of mismatches with AC expected vs UI actual
+- `validationWarnings`: Items that couldn't be fully verified
+- `actualUITexts`: Sample of UI text strings extracted from source code
+- `mappings`: Array of AC items with validation status
+- `matchedCount`: Number of fully validated items
+- `failedCount`: Number of items that failed validation
+- `recommendations`: Action items if validation fails
+
+**When Validation Fails (success: false):**
+
+🛑 **STOP THE WORKFLOW** - Output recommendation and END.
+
+```
+❌ Validation Failed - Cannot generate tests.
+
+Mismatches found:
+- "Yearly" - Not found in UI
+- "20 days" - Not found. Available: "Last 7 days", "Last 30 days", "Last 90 days"
+
+Recommendation: Update the ClickUp AC to match actual UI, OR fix the implementation.
+
+Workflow stopped. Re-run after resolving mismatches.
+```
+
+❌ **FORBIDDEN:** Continuing to generate tests, asking questions, or modifying tests to match UI.
+
+---
+
 ## 🚀 Test Execution Tools
 
 ### `maestro_write_test` Tool
@@ -458,18 +578,78 @@ maestro_discover_tests(
 | `lastCommit` | Most recent commit             | `git diff HEAD~1`                |
 | `branch`     | Compare to base branch         | `git diff {baseBranch}...HEAD`   |
 
-## 🔄 Complete Workflow Example
+## 🔄 Complete Workflow Examples
+
+### ⚠️ IMPORTANT: Standard Workflow Order
+
+When a user asks to "generate and run test cases" or use Maestro, follow this exact sequence:
+
+```bash
+# Step 1: ALWAYS check Maestro installation first!
+maestro_ensure_installed()
+
+# Step 2: ALWAYS ask for ClickUp URL (this is mandatory!)
+clickup_fetch_task()
+# This prompts the user: "Do you have a ClickUp task URL?"
 
-### ⚠️ IMPORTANT: Always Check Installation First!
+# Step 3+: Based on user response, continue workflow
+```
 
-When a user asks to "generate and run test cases" or use Maestro, follow this order:
+### Workflow with ClickUp Integration (ASK FIRST)
+
+When user prompts: "use maestro-ai to generate and run tests"
 
 ```bash
-# Step 0: ALWAYS check Maestro installation first!
+# Step 1: 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
+# Step 2: ASK for ClickUp task URL
+clickup_fetch_task()
+# Returns: "Do you have a ClickUp task URL for this feature?
+#           Paste the URL or type 'skip' to continue."
+
+# If user provides URL (e.g., "https://app.clickup.com/t/abc123"):
+clickup_fetch_task(taskUrl: "https://app.clickup.com/t/abc123")
+# Extracts task ID, fetches task data
+
+# Step 3: Parse acceptance criteria
+validate_acceptance_criteria(task: <task_from_step_2>)
+# Returns: validatedItems with testability scores
+
+# Step 4: Analyze git changes
+maestro_analyze_changes(repoPath: ".")
+
+# Step 5: Map AC to UI elements
+map_AC_to_UI(
+  acItems: <validated_items>,
+  repoPath: ".",
+  changedFiles: <from_git_analysis>
+)
+
+# Step 6-7: Generate and write test
+maestro_generate_test(...)
+maestro_write_test(...)
+```
+
+### Workflow without ClickUp (Skip)
+
+```bash
+# Step 1: ALWAYS check Maestro installation first!
+maestro_ensure_installed()
+
+# Step 2: ASK for ClickUp task URL
+clickup_fetch_task()
+# User responds: "skip"
+
+# Step 3: Analyze git changes (normal flow)
+maestro_analyze_changes(repoPath: ".")
+
+# Step 4: Map based on git analysis only
+map_AC_to_UI(repoPath: ".")
+
+# Step 5-6: Generate and write test
+maestro_generate_test(...)
+maestro_write_test(...)
 ```
 
 ### End-to-End: Analyze Changes → Generate → Execute