@minicor/mcp-server 3.1.4 → 3.2.0

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