@minicor/mcp-server 3.1.4 → 3.2.0

package/skills/general/data-hydration-patterns.md

@@ -0,0 +1,167 @@
+---
+name: data-hydration-patterns
+description: Patterns for building standard CRUD data workflows (Get Practitioners, Patients, Appointments, Encounter Notes). API-first vs RPA approaches, data output conventions, pagination, orchestration order, pass-through return steps. Use when building data extraction or synchronization workflows for healthcare/enterprise apps.
+category: general
+tags: [data, hydration, crud, practitioners, patients, appointments, notes, api, scraping]
+priority: 8
+---
+
+# Data Hydration Patterns
+
+Most Minicor workspaces follow a standard set of data workflows. This skill documents the patterns across production deployments.
+
+## The Standard Workflow Set
+
+Every EHR/EMR integration workspace typically needs:
+
+1. **Get Practitioners** — list of doctors/providers
+2. **Get Patients** — patient roster (all or by search)
+3. **Get Patient By ID** — single patient detail
+4. **Get Appointments** — schedule for a date range
+5. **Get Encounter Notes** — clinical notes for a patient
+6. **Create Encounter Note** — write back a note
+7. **Verify Patient** — confirm a patient exists by name/DOB
+
+## Two Approaches
+
+### API-First (Preferred)
+
+If the app has accessible internal APIs (discovered via CDP network interception or documentation):
+
+```python
+import json, urllib.request
+
+url = f'{base_url}/api/patients?page={page}&size=100'
+req = urllib.request.Request(url, headers={'Authorization': f'Bearer {token}'})
+resp = urllib.request.urlopen(req)
+data = json.loads(resp.read())
+```
+
+**Pros**: Fast, reliable, handles pagination natively, returns structured data.
+**Examples**: HSMC (Insta HMS API), Novelle SQL queries.
+
+### RPA Scraping (Fallback)
+
+When no API is available, scrape data from the UI via CDP or uiautomation:
+
+```python
+# CDP: Execute JS to extract table data
+table_data = cdp_eval(ws, """
+(function() {
+    var rows = document.querySelectorAll('table tbody tr');
+    var data = [];
+    rows.forEach(function(row) {
+        var cells = row.querySelectorAll('td');
+        data.push({
+            name: cells[0]?.textContent?.trim(),
+            id: cells[1]?.textContent?.trim(),
+            dob: cells[2]?.textContent?.trim()
+        });
+    });
+    return JSON.stringify(data);
+})();
+""")
+```
+
+**Pros**: Works when no API exists.
+**Cons**: Fragile, slow, pagination via scrolling.
+**Examples**: Hillside (PracticeFusion CDP scraping).
+
+## Data Output Convention
+
+All data workflows should return structured JSON:
+
+```json
+{
+  "count": 42,
+  "data": [
+    {"id": "P001", "name": "John Doe", "dob": "1990-01-15"},
+    {"id": "P002", "name": "Jane Smith", "dob": "1985-07-22"}
+  ]
+}
+```
+
+For single-record queries (Get Patient By ID):
+
+```json
+{
+  "patient_id": "P001",
+  "name": "John Doe",
+  "dob": "1990-01-15",
+  "phone": "555-1234"
+}
+```
+
+## The Pass-Through Return Step
+
+The workflow engine returns whatever the LAST step produces. If your last step is RPA (cleanup/navigation), the data gets lost.
+
+**Pattern**: Add a final GENERAL_FUNCTION step that passes through the data:
+
+```javascript
+(data) => {
+  return data.step_3?.data || data.step_3?.response;
+}
+```
+
+This ensures the formatted data from step 3 becomes the workflow output.
+
+## Pagination
+
+### API Pagination
+
+```python
+all_records = []
+page = 1
+while True:
+    data = fetch_page(page, page_size=100)
+    all_records.extend(data['records'])
+    if len(data['records']) < 100:
+        break
+    page += 1
+```
+
+### CDP Scroll Pagination
+
+```python
+previous_count = 0
+while True:
+    # Scroll to bottom
+    cdp_eval(ws, 'window.scrollTo(0, document.body.scrollHeight)')
+    time.sleep(2)
+    
+    # Count rows
+    count = int(cdp_eval(ws, 'document.querySelectorAll("table tbody tr").length'))
+    if count == previous_count:
+        break  # No new rows loaded
+    previous_count = count
+```
+
+## Hydration Orchestration
+
+When running multiple data workflows to populate a cache:
+
+1. **Practitioners first** — no dependencies
+2. **Appointments** — optionally filtered by practitioner IDs from step 1
+3. **Patients from appointments** — derived from appointment data (step 2)
+4. **Encounter notes** — for patients from step 3
+
+This is the pattern used by HSMC (WFs 753-756) — each workflow is standalone but designed to chain.
+
+## Workflow Step Structure
+
+A typical data workflow has 3-4 steps:
+
+1. **Navigate/Setup** (RPA) — navigate to the right page or prepare the API call
+2. **Extract/Scrape** (RPA) — get the raw data via API or scraping
+3. **Format** (GENERAL_FUNCTION) — transform raw data into the standard JSON format
+4. **Return** (GENERAL_FUNCTION) — pass-through step that ensures data is the workflow output
+
+## Config Store Properties
+
+Standard properties for data workflows:
+- `{{config.username}}` / `{{config.password}}` — credentials
+- `{{config.url}}` or `{{config.base_url}}` — app URL
+- `{{config.channelId}}` — RPA channel for desktop dispatch
+- `{{config.sullyOrganizationId}}` — customer ID for middleware routing
+- `{{config.BASE_API_URL}}` — middleware/API base URL

package/skills/general/data-passing-between-steps.md

@@ -0,0 +1,46 @@
+---
+name: data-passing-between-steps
+description: How to pass data between workflow steps in Minicor RPA workflows. JS-layer interpolation from data.input and data.step_N, config variables via {{config.xxx}}, common pitfalls with Python template vars. Use when building multi-step workflows that need to share data.
+category: general
+tags: [data-passing, workflow, steps, interpolation, config]
+priority: 9
+---
+
+# Data Passing Between Steps
+
+Workflow input is available as `data.input` in the **JS wrapper**, NOT in Python directly. Dynamic values must be interpolated in the JS layer, then embedded into the Python template literal.
+
+## CORRECT — JS-Layer Interpolation
+
+```javascript
+(data) => {
+  const mrn = data?.input?.mrn || "DEFAULT";
+  const pythonScript = `
+    mrn = "${mrn}"
+    # ... rest of Python script uses mrn variable
+  `;
+  return { "lam.httpRequest": { body: { script: pythonScript } } };
+}
+```
+
+## WRONG — Python Template Vars
+
+```python
+mrn = "{{input.mrn}}"   # WRONG — this is not a config variable
+mrn = data.input.mrn     # WRONG — data object doesn't exist in Python
+```
+
+## Config Variables
+
+`{{config.username}}` and `{{config.password}}` ARE resolved by the workflow engine and work in both JS and Python layers. Use these for credentials and environment URLs via config stores. **NEVER** hardcode credentials.
+
+## Previous Step Outputs
+
+- `data.step_N.response` — for HTTP/RPA steps
+- `data.step_N.data` — for GENERAL_FUNCTION steps
+
+## Important Notes
+
+- `create_rpa_flow` generates the JS wrapper automatically, but if the script needs dynamic input from `data.input` or `data.step_N`, you must construct the JS wrapper yourself or update the flow after creation to add JS-layer const declarations
+- The **last step** is the workflow output. If you need structured data returned, the last step must output it. Don't put meaningful data in step N and cleanup in step N+1. Combine cleanup + data return in the last step, or add a GENERAL_FUNCTION step after RPA that formats the final result.
+

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)