@minicor/mcp-server 3.1.5 → 3.2.0

package/skills/general/desktop-uiautomation.md

@@ -0,0 +1,80 @@
+---
+name: desktop-uiautomation
+description: Desktop RPA patterns using uiautomation, pywinauto, and pyautogui. Framework selection by app type, element-based selectors over coordinates, wait-for-element patterns, retry strategies, popup dismissal. Use when building desktop automations or Windows app RPA.
+category: general
+tags: [desktop, uiautomation, pywinauto, pyautogui, windows, jab]
+priority: 10
+---
+
+# Desktop UI Automation
+
+## Framework Selection
+
+
+| App Type                     | Framework                               |
+| ---------------------------- | --------------------------------------- |
+| .NET / WPF / WinForms        | `uiautomation` (default) or `pywinauto` |
+| Java / Swing                 | `jab` (Java Access Bridge)              |
+| Electron / web-based desktop | `pywinauto` or `pyautogui`              |
+| Legacy Win32                 | `uiautomation`                          |
+| Unknown                      | Start with `uiautomation`               |
+
+
+Desktop scripts use `/execute` and run **one at a time** per VM (the physical screen is shared).
+
+## Wait for Elements (Never `time.sleep` for UI Waits)
+
+```python
+for _ in range(20):
+    el = auto.WindowControl(Name="Patient Search")
+    if el.Exists(0.5): break
+    time.sleep(0.5)
+else:
+    raise TimeoutError("Patient Search not found after 10s")
+```
+
+## Click by Element Selector (Not Coordinates)
+
+```python
+# YES — element-based, resilient
+auto.ButtonControl(Name="Find").Click()
+
+# NO — coordinate-based, fragile
+# pyautogui.click(517, 432)
+```
+
+## Retry Flaky Actions
+
+```python
+for attempt in range(3):
+    try:
+        auto.ButtonControl(Name="Find").Click()
+        time.sleep(1)
+        if auto.ListControl(Name="Results").Exists(1): break
+    except Exception:
+        if attempt == 2: raise
+        time.sleep(2)
+```
+
+## Dismiss Popups (Check Before Major Actions)
+
+```python
+popup = auto.WindowControl(searchDepth=1, RegexName=".*Error.*|.*Warning.*")
+if popup.Exists(0.5):
+    close_btn = popup.ButtonControl(Name="Close")
+    ok_btn = popup.ButtonControl(Name="OK")
+    if close_btn.Exists(0.5):
+        close_btn.Click()
+    elif ok_btn.Exists(0.5):
+        ok_btn.Click()
+```
+
+## Output (Always Structured JSON)
+
+```python
+print(json.dumps({"status": "success", "patient": name, "data": results}))
+```
+
+## Mixed Browser + Desktop
+
+Some browser automations need the physical screen (OS alerts, file upload dialogs, native file picker, CAPTCHA). These **cannot use `/execute/browser`** — use `/execute` instead and treat as desktop automation.

package/skills/general/rpa-testing-workflow.md

@@ -0,0 +1,145 @@
+---
+name: rpa-testing-workflow
+description: Mandatory testing workflow for RPA steps. Prescriptive tool call sequences for per-step testing through the Minicor executor, polling execution status, taking screenshots during runs, and end-to-end validation. Use EVERY TIME you build or modify RPA workflows.
+category: general
+tags: [testing, workflow, execution, validation, mandatory]
+priority: 100
+---
+
+# RPA Testing Workflow
+
+This skill is MANDATORY. Every RPA step must be tested through the Minicor executor, not just `vm_execute_script`. Follow these exact sequences.
+
+## Why `vm_execute_script` Is Not Enough
+
+`vm_execute_script` runs raw Python directly on the VM. It does NOT go through the Minicor workflow engine. This means:
+
+- `{{config.username}}`, `{{config.password}}`, and all `{{config.*}}` variables are NOT resolved — they appear as literal text
+- `data.input` interpolation does NOT work — the JS wrapper that injects input values is not executed
+- `data.step_N.response` references to previous step outputs do NOT work
+- The `lam.httpRequest` / `lam.rpa` dispatch wrapper is NOT executed
+- Recording, execution tracking, and monitoring are NOT triggered
+
+A script that passes via `vm_execute_script` can and WILL fail when run through `execute_workflow`. You MUST test through the real executor.
+
+## Per-Step Testing (After Each `create_rpa_flow`)
+
+After saving a step with `create_rpa_flow`, IMMEDIATELY test it through Minicor:
+
+### Step 1: Run the step in isolation
+
+```
+execute_workflow_async(
+  workflowId: <workflow_id>,
+  input: { ... real test data ... },
+  configurationId: <config_store_id>,
+  start_from_step: <this_step_order>,
+  end_at_step: <this_step_order>
+)
+```
+
+This runs ONLY this step through the real Minicor executor with config variable resolution and the JS wrapper.
+
+### Step 2: Poll execution status
+
+```
+Loop every 5-10 seconds:
+  get_execution_status(workflowId, executionId)
+  
+  While status is "RUNNING" or "PENDING":
+    - Take vm_screenshot to watch progress on the VM
+    - Continue polling
+    
+  When status is "COMPLETED":
+    - Take vm_screenshot to verify final state
+    - Call get_full_execution to see step output and any recordings
+    - Proceed to next step
+    
+  When status is "FAILED" or "ERROR":
+    - Take vm_screenshot to see the error state
+    - Call diagnose_execution for failure analysis
+    - Call get_full_execution for detailed error output
+    - Go to failure recovery (below)
+```
+
+### Step 3: Verify the result
+
+After the step completes successfully:
+- `vm_screenshot` to visually confirm the expected state
+- Check the execution output via `get_full_execution` — verify the step produced the expected data
+- If the step reads data, verify the output JSON is correct
+
+### Step 4: Only then proceed to the next step
+
+Do NOT start writing the next step until the current one passes through the executor.
+
+## Failure Recovery
+
+When a step fails through the Minicor executor:
+
+1. `diagnose_execution(workflowId, executionId)` — get failure analysis with hints
+2. `get_full_execution(workflowId, executionId)` — see stdout, stderr, exit code, recording
+3. `vm_screenshot` — see what state the VM is in
+4. Identify the cause:
+   - **Config variable not resolving?** Check the config store has the right properties
+   - **Data passing broken?** Check the JS wrapper interpolation — load `get_skill("data-passing-between-steps")`
+   - **Script error?** Fix the Python, but test the fix through the executor, NOT `vm_execute_script`
+5. `update_flow(flowId, program: <fixed_code>)` — update the step code
+6. Re-run `execute_workflow_async` with `start_from_step`/`end_at_step` again
+7. Repeat until the step passes through the executor
+
+CRITICAL: Do NOT use `vm_execute_script` to "verify" a fix. The fix must pass through `execute_workflow_async`.
+
+## End-to-End Testing
+
+After ALL steps pass individually through the executor:
+
+### Full workflow test
+
+```
+execute_workflow_async(
+  workflowId: <workflow_id>,
+  input: { ... real production-like data ... },
+  configurationId: <config_store_id>
+)
+```
+
+No `start_from_step` / `end_at_step` — run the ENTIRE workflow.
+
+### Monitor the full run
+
+```
+Loop every 5-10 seconds:
+  get_execution_status(workflowId, executionId)
+  vm_screenshot  (every 2-3 polls to watch progress)
+  
+  On completion:
+    get_full_execution to verify all steps produced correct output
+    vm_screenshot to verify final state
+    
+  On failure:
+    diagnose_execution
+    Identify which step failed
+    Fix with update_flow
+    Re-run the FULL workflow (not just the failing step)
+```
+
+### Completion criteria
+
+The workflow is NOT done until:
+- `execute_workflow_async` returns with all steps in "COMPLETED" status
+- The output data is correct (verify via `get_full_execution`)
+- The VM is in the expected final state (verify via `vm_screenshot`)
+
+For production workflows, also:
+- Run the workflow a second time to verify idempotency
+- Verify state verification passes (expectedPreState/expectedPostState)
+
+## Common Mistakes to Avoid
+
+1. **Testing with `vm_execute_script` and declaring done** — this is the #1 mistake. Always use `execute_workflow_async`.
+2. **Not using `configurationId`** — config variables only resolve when a config store is attached to the execution.
+3. **Fixing a script and testing with `vm_execute_script`** — even fixes must be verified through the executor.
+4. **Not polling `get_execution_status`** — the async execution runs in the background. You must poll to know when it finishes.
+5. **Skipping per-step testing** — testing only end-to-end makes it hard to isolate failures. Test each step individually first.
+6. **Not taking screenshots during execution** — screenshots while the workflow runs show you what's actually happening on the VM.

package/skills/general/session-keepalive.md

@@ -0,0 +1,101 @@
+---
+name: session-keepalive
+description: Patterns for keeping RPA sessions alive using scheduled agents, health checks, and auto-recovery. Detecting session timeouts, re-authentication sequences, monitoring agent setup. Use when hardening production workflows that depend on persistent app sessions.
+category: general
+tags: [session, keepalive, monitoring, scheduled, recovery, production]
+priority: 8
+---
+
+# Session Keepalive
+
+Production RPA workflows depend on an active, authenticated session. Sessions time out. This skill covers how to detect and recover from session loss automatically.
+
+## The Problem
+
+- Web apps log you out after inactivity (15-60 minutes typically)
+- Desktop apps lock or disconnect after RDP session timeout
+- Citrix sessions disconnect after idle periods
+- Data workflows fail silently when the session is gone
+
+## Solution: Scheduled Health Check Agent
+
+### Step 1: Build a Smart Launch workflow
+
+Load `get_skill("smart-launch-patterns")` and build a Smart Launch workflow first. This is the recovery mechanism.
+
+### Step 2: Create a scheduled monitoring agent
+
+```
+create_agent(
+  name: "session-keepalive",
+  task: "Run the Smart Launch workflow to verify the session is active. If it fails, take a screenshot, diagnose, and report.",
+  mode: "scheduled",
+  cronSchedule: "*/5 * * * *",
+  workspaceId: <id>,
+  vmUrl: "<tunnel_url>",
+  watchWorkflowId: <smart_launch_workflow_id>
+)
+```
+
+### Step 3: Add failure monitoring
+
+```
+create_agent(
+  name: "session-monitor",
+  task: "When the Smart Launch fails, take a screenshot, check what went wrong, re-run Smart Launch, and notify Slack.",
+  mode: "monitor",
+  watchWorkflowId: <smart_launch_workflow_id>,
+  recoveryTask: "Take a screenshot. If login page is showing, the session expired — re-run Smart Launch. If the app crashed, restart it. Report results to Slack.",
+  slackWebhookUrl: "<webhook>",
+  workspaceId: <id>,
+  vmUrl: "<tunnel_url>"
+)
+```
+
+## Detecting Session Loss
+
+### Browser (CDP)
+
+```python
+# Check if still on the app page vs redirected to login
+current_url = cdp_eval(ws, 'window.location.href')
+if '/login' in current_url or '/lock' in current_url:
+    print("Session expired — need to re-authenticate")
+```
+
+### Desktop (uiautomation)
+
+```python
+# Check if the expected signed-in element still exists
+window = auto.WindowControl(searchDepth=1, Name='MyApp')
+if not window.Exists(3):
+    print("App window gone — need to relaunch")
+else:
+    signed_in_indicator = window.HyperlinkControl(Name='Dashboard')
+    if not signed_in_indicator.Exists(3):
+        print("Signed out — need to re-authenticate")
+```
+
+## Recovery Sequence
+
+1. Take a screenshot to document the failure state
+2. Run the Smart Launch workflow
+3. Verify the session is restored (check for the signed-in indicator)
+4. If still failing, try a full restart (close app, relaunch, login)
+5. Report results via Slack webhook or issue update
+
+## RDP/Citrix Session Management
+
+For desktop automations that require an active RDP session:
+- The VM's MDS handles this — it runs as a scheduled task in the interactive session
+- If the RDP session disconnects, MDS continues running but UI automation may fail
+- The health check detects this (window controls become unresponsive)
+- Recovery: The VM service can trigger a reconnect via `start_mds_on_vm`
+
+## Production Checklist
+
+- [ ] Smart Launch workflow built and tested
+- [ ] Scheduled keepalive agent created (5-minute interval)
+- [ ] Monitor agent watching Smart Launch for failures
+- [ ] Slack notifications configured for failure alerts
+- [ ] Recovery task handles all known failure modes (timeout, crash, disconnect)

package/skills/general/smart-launch-patterns.md

@@ -0,0 +1,213 @@
+---
+name: smart-launch-patterns
+description: Patterns for building Smart Launch workflows that ensure an app is running and authenticated before data workflows execute. Browser launch via CDP, desktop app launch via uiautomation, login/unlock detection, credential injection, MFA handling, popup dismissal. Use when building session management or app launch automation.
+category: general
+tags: [smart-launch, session, login, authentication, browser, desktop, cdp, mfa]
+priority: 9
+---
+
+# Smart Launch Patterns
+
+A Smart Launch workflow ensures the target application is running and authenticated before any data workflow executes. Every production workspace needs one.
+
+## When to Build a Smart Launch
+
+- **Production**: Always. Data workflows depend on an active session.
+- **POC**: Skip it. Test with a manually opened app.
+
+## Browser Smart Launch (CDP)
+
+Pattern from PracticeFusion (Hillside workspace):
+
+### Step 1: Check if browser is running
+
+```python
+import urllib.request, json
+
+def get_cdp_ws(tab_filter='myapp'):
+    try:
+        resp = urllib.request.urlopen('http://127.0.0.1:9222/json')
+        tabs = json.loads(resp.read())
+        for tab in tabs:
+            if tab_filter in tab.get('url', ''):
+                return tab['webSocketDebuggerUrl']
+        return tabs[0]['webSocketDebuggerUrl'] if tabs else None
+    except:
+        return None
+```
+
+### Step 2: Launch browser if not running
+
+```python
+import subprocess, time
+
+def launch_browser(url):
+    subprocess.Popen([
+        r'C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe',
+        '--remote-debugging-port=9222',
+        '--remote-allow-origins=*',
+        '--start-maximized',
+        '--no-first-run',
+        url
+    ])
+    time.sleep(8)
+```
+
+### Step 3: Detect state (login vs locked vs logged-in)
+
+```python
+current_url = cdp_eval(ws, 'window.location.href')
+
+if '/lock' in current_url:
+    # Screen locked — unlock with password
+    unlock_screen(ws, password)
+elif '/login' in current_url:
+    # On login page — enter credentials
+    login(ws, username, password)
+elif '/app/' in current_url:
+    # Already logged in — ready
+    pass
+else:
+    # Unknown state — navigate to login
+    cdp_navigate(ws, login_url)
+```
+
+### Step 4: Inject credentials (React-safe)
+
+Escape credentials before injecting into JS to handle special characters (`'`, `\`, etc.):
+
+```python
+safe_user = username.replace('\\', '\\\\').replace("'", "\\'")
+safe_pass = password.replace('\\', '\\\\').replace("'", "\\'")
+```
+
+Then use the escaped values in the CDP eval:
+
+```python
+cdp_eval(ws, f"""
+(function() {{
+    var emailInput = document.querySelector('input[type="email"]');
+    var pwInput = document.querySelector('input[type="password"]');
+    var setter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype, "value"
+    ).set;
+    if (emailInput) {{
+        setter.call(emailInput, '{username}');
+        emailInput.dispatchEvent(new Event('input', {{bubbles: true}}));
+        emailInput.dispatchEvent(new Event('change', {{bubbles: true}}));
+    }}
+    if (pwInput) {{
+        setter.call(pwInput, '{password}');
+        pwInput.dispatchEvent(new Event('input', {{bubbles: true}}));
+        pwInput.dispatchEvent(new Event('change', {{bubbles: true}}));
+    }}
+    var btns = document.querySelectorAll('button');
+    for (var i = 0; i < btns.length; i++) {{
+        if (btns[i].textContent.trim().toLowerCase().includes('log in')) {{
+            btns[i].click(); break;
+        }}
+    }}
+}})();
+""")
+```
+
+### Step 5: Handle MFA
+
+After login, check if MFA is required:
+- If URL contains 'securitycheck' or 'securitycode', MFA is needed
+- Use `tfa_generate_totp` or `tfa_request_sms_otp` to get the code
+- Inject the code via CDP
+
+## Desktop Smart Launch (uiautomation)
+
+Pattern from athenaPractice (Novelle workspace):
+
+### Step 1: Check if window exists
+
+```python
+import uiautomation as auto
+
+win = auto.WindowControl(searchDepth=1, Name='athenaPractice')
+window_exists = win.Exists(3)
+```
+
+### Step 2: Conditional launch
+
+```python
+if not window_exists:
+    import subprocess, os
+    app_path = os.path.join(os.environ["PUBLIC"], "Desktop", "MyApp.lnk")
+    subprocess.Popen(["powershell", "-Command", f'Start-Process "{app_path}"'])
+    time.sleep(15)
+```
+
+### Step 3: Check if signed in
+
+Look for a known UI element that only appears when logged in:
+
+```python
+window = auto.WindowControl(searchDepth=1, Name='athenaPractice')
+window.SetActive()
+
+# Look for an element that proves we're signed in
+chart = window.HyperlinkControl(Name='Chart')
+signed_in = chart.Exists(3)
+
+if not signed_in:
+    # Also try other control types
+    chart = window.TextControl(Name='Chart')
+    signed_in = chart.Exists(1)
+```
+
+### Step 4: Conditional login
+
+Use data passing to skip steps that aren't needed:
+
+```javascript
+(data) => {
+  const windowExists = data.step_1?.response?.resultData?.windowExists ?? false;
+  if (windowExists) {
+    return {"skipped": true, "message": "Window already exists"};
+  }
+  // Otherwise return the launch script
+  return { "lam.rpa": { script: launchScript, channelId: "{{config.channelId}}" } };
+}
+```
+
+### Step 5: Dismiss popups
+
+After login, dismiss any startup dialogs:
+
+```python
+import time
+time.sleep(3)
+popup = auto.WindowControl(searchDepth=1, RegexName=".*Update.*|.*Notice.*|.*Alert.*")
+if popup.Exists(2):
+    ok_btn = popup.ButtonControl(Name="OK") or popup.ButtonControl(Name="Close")
+    if ok_btn.Exists(1):
+        ok_btn.Click()
+```
+
+## Workflow Structure
+
+A typical Smart Launch workflow has 4-6 steps:
+1. Check if app/browser is running
+2. Launch if not running
+3. Check if signed in
+4. Login if not signed in
+5. Handle MFA (if applicable)
+6. Dismiss popups
+
+Use conditional execution via the JS wrapper — steps can return `{"skipped": true}` when not needed.
+
+## Config Store Setup
+
+Smart Launch workflows reference credentials from config stores:
+- `{{config.username}}` / `{{config.password}}` — app credentials
+- `{{config.url}}` — login URL
+- `{{config.channelId}}` — RPA channel ID for desktop dispatch
+- `{{config.totp_secret_id}}` — for TOTP-based MFA
+
+## Health Check Pattern
+
+Create a simple workflow that runs the Smart Launch and reports status. Schedule it via `create_agent mode: "scheduled"` with a cron expression (e.g., every 5 minutes). This keeps the session alive and auto-recovers from timeouts.

package/skills/general/state-verification.md

@@ -0,0 +1,56 @@
+---
+name: state-verification
+description: LLM-based UI state verification for RPA steps using expectedPreState and expectedPostState. How to use generate_state_description and debug_rpa_step for regression detection. Use when adding verification to RPA steps or debugging flaky automations.
+category: general
+tags: [verification, state, debugging, regression, screenshots]
+priority: 7
+---
+
+# State Verification
+
+## Overview
+
+Every RPA step can include `expectedPreState` and `expectedPostState` — natural language descriptions of what the screen should look like before and after the step runs. The MDS uses LLM-based screenshot analysis to verify these conditions, catching regressions when the target app's UI changes.
+
+## Using `debug_rpa_step`
+
+`debug_rpa_step` runs a script with full diagnostics:
+
+- Takes a **before screenshot**
+- Executes the script
+- Takes an **after screenshot**
+- Returns stdout, stderr, exit code, and both screenshots
+- Optionally verifies against `expectedPreState` / `expectedPostState`
+
+Use during development to validate each step before saving.
+
+## Writing State Descriptions
+
+Use `generate_state_description` to author state descriptions from the current screen. Descriptions should be:
+
+- **Specific enough** to catch real regressions (e.g., "The Patient Search dialog is open with an empty MRN field")
+- **General enough** to not break on minor UI changes (e.g., don't mention exact pixel positions or colors)
+- **Focused on the relevant area** — describe what matters for this step, not the entire screen
+
+## Workflow
+
+1. Navigate to the pre-state → `generate_state_description` → save as `expectedPreState`
+2. Run the automation step
+3. Verify the result → `generate_state_description` → save as `expectedPostState`
+4. Pass both to `create_rpa_flow` when saving the step
+
+## When State Verification Catches Issues
+
+- App updated its UI (new buttons, moved fields, changed labels)
+- Login session expired (expected app screen, got login page)
+- Popup or error dialog appeared unexpectedly
+- Previous step failed silently, leaving the app in wrong state
+
+## Debugging Tools
+
+- `**debug_rpa_step`** — runs script with before/after screenshots + full diagnostics
+- `**vm_reset_state`** — manage windows: focus an app, minimize all, close dialogs
+- `**vm_read_clipboard**` — read clipboard after a copy operation
+- `**vm_screenshot_region**` — crop/zoom a specific screen region
+- `**batch_test_rpa**` — run the workflow with multiple test inputs
+- **Video Recordings** — use `get_full_execution` to see recording references