@minicor/mcp-server 3.1.5 → 3.2.1

package/README.md

@@ -1,12 +1,12 @@
 # Minicor MCP Server
 
-Build, deploy, and debug VM-based browser and desktop automations from **Cursor** or **Claude Code**. The AI agent connects to your Windows VM, writes Python automation scripts, tests them live, and saves them as Minicor workflows.
+Build, deploy, and debug VM-based browser and desktop automations from **Cursor** or **Claude Code**. The AI agent connects to your Windows VM, writes Python automation scripts, tests them through the Minicor executor, and deploys production-ready workflows — with skills accumulated from every build.
 
 ## Quick Start
 
-### Cursor
+### 1. Install
 
-Run the setup wizard, then add to your Cursor MCP config (`~/.cursor/mcp.json`):
+**Cursor** — add to `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -19,60 +19,214 @@ Run the setup wizard, then add to your Cursor MCP config (`~/.cursor/mcp.json`):
 }
 ```
 
-If you run `minicor-mcp-setup`, it writes this config automatically.
-
-### Claude Code
+**Claude Code:**
 
 ```bash
 npm install -g @minicor/mcp-server
-minicor-mcp-setup
 claude mcp add minicor -- minicor-mcp
 ```
 
-### Authenticate
+### 2. Authenticate
 
 ```bash
 npx @minicor/mcp-server-setup
 ```
 
-Opens a browser to sign in or create an account. Tokens are stored at `~/.minicor/tokens.json` and auto-refresh. For headless environments: `npx @minicor/mcp-server-setup --cli`.
+Opens a browser to sign in. Tokens stored at `~/.minicor/tokens.json` with auto-refresh. For headless: `npx @minicor/mcp-server-setup --cli`.
+
+### 3. Bootstrap Workspace (optional)
+
+After cloning a workspace, generate harness-specific config files:
+
+```bash
+# For Claude Code — creates CLAUDE.md + .claude/settings.local.json
+npx @minicor/mcp-server minicor-bootstrap claude-code --dir ./my-workspace
+
+# For Cursor — creates .cursor/rules/workspace.mdc
+npx @minicor/mcp-server minicor-bootstrap cursor --dir ./my-workspace
+
+# All harnesses at once
+npx @minicor/mcp-server minicor-bootstrap all --dir ./my-workspace
+```
+
+### 4. Update
+
+`npx` users: restart your editor (auto-fetches latest). Global: `npm update -g @minicor/mcp-server`.
+
+## Session Lifecycle
+
+The MCP server sends **instructions** to every client on connect, telling agents to call `session_start` first when in a workspace clone. This works across all harnesses — Claude Code, Cursor, Bedrock, etc.
+
+### Session Tools
+
+| Tool | What it does |
+| --- | --- |
+| `session_start` | Load workspace context (AGENTS.md, VMs, skills, issues, prior session). Call FIRST in a workspace clone. |
+| `session_checkpoint` | Save progress mid-session. Writes `.minicor/session.json` + syncs `[Workspace:Session]` issue. |
+| `session_end` | Persist final state, sync to platform, optionally update context.md. Call before ending work. |
+| `set_workspaces_root` | Set default root directory for cloning workspaces (saved to `~/.minicor/config.json`). |
+
+### Auto-Save on Disconnect
+
+If the agent crashes or the user closes the IDE, the server auto-checkpoints with `status: "interrupted"` so no session state is lost. The next agent resumes from that checkpoint.
+
+### Multi-Agent Handoff
+
+Sessions are synced to `[Workspace:Session]` issues on the platform, so agents on other machines (or scheduled Bedrock agents) can resume where the last agent left off.
+
+## The RPA Lifecycle
+
+This is the complete flow from zero to production automation. The agent handles each phase using MCP tools and skills.
+
+### Phase 1: Workspace Setup
+
+```
+"Create a workspace for Acme Corp and set up a VM"
+```
+
+- `create_workspace` / `list_workspaces` / `get_workspace` — create or find a workspace
+- `vm_list` — discover available VMs
+- `deploy_vm` — provision a new Windows VM if needed
+- `install_mds_on_vm` / `start_mds_on_vm` — install the Minicor Desktop Service
+- `vm_connect` — connect to the VM via Cloudflare tunnel
+
+### Phase 2: Clone Workspace
+
+```
+"Clone workspace 257 to my local folder"
+```
+
+- `clone_workspace` — pulls everything to a local folder:
+  - `minicor.json` — workspace manifest
+  - `workflows/` — all workflow steps as files (git-native)
+  - `.minicor/skills/general/` — bundled RPA skills
+  - `.minicor/skills/workspace/` — workspace-specific learned skills
+  - `.minicor/issues/` — agent-persisted context from previous runs
+  - `.minicor/skill-index.json` — compact skill summary
+  - `.minicor/workspace.json` — workspace metadata
+
+The folder is git-ready. Push to GitHub for version control, diffs, and CI/CD.
+
+### Phase 3: Scope & Research
+
+```
+"I want to automate patient lookup in Centricity"
+```
+
+The agent:
+
+- Takes screenshots, inspects UI elements, identifies the app framework
+- Loads relevant skills: `get_skill("cdp-browser-automation")` or `get_skill("desktop-uiautomation")`
+- Checks `list_skills()` for customer-specific skills (e.g., "centricity-quirks")
+- Studies existing workflows via `get_workflow_overview`
+- Determines strategy: CDP browser, desktop uiautomation, or hybrid
+
+### Phase 4: Build (Iterative)
+
+For each automation step:
+
+1. **Observe** — `vm_screenshot` + `vm_inspect_ui` to map the UI
+2. **Write** — Python script using patterns from loaded skills
+3. **Prototype** — `vm_execute_script` to test on the VM directly
+4. **Save** — `create_rpa_flow` to persist as a Minicor workflow step
+5. **Test through Minicor** — `execute_workflow_async` with `start_from_step`/`end_at_step` to verify the step works through the real executor (config variables, data passing, JS wrapper)
+
+The testing step is critical — `vm_execute_script` doesn't resolve `{{config.*}}` variables or `data.input` interpolation. The agent loads `get_skill("rpa-testing-workflow")` for exact tool call sequences.
+
+### Phase 5: Test End-to-End
+
+After all steps pass individually:
+
+- `execute_workflow_async` with real inputs + `configurationId` — full workflow, no step isolation
+- Poll `get_execution_status` + `vm_screenshot` to monitor
+- `diagnose_execution` on failure, fix with `update_flow`, re-run
+- Workflow is NOT done until it passes end-to-end through the Minicor executor
+
+### Phase 6: Production Hardening
+
+For production workflows (not POCs):
+
+- Load `get_skill("state-verification")` — add `expectedPreState`/`expectedPostState` to each step
+- Run the workflow twice to verify idempotency
+- `create_agent` with `mode: "monitor"` + `watchWorkflowId` for failure monitoring
+- `create_agent` with `mode: "scheduled"` + cron for recurring runs
+- Persist context: `create_issue` with `[Agent:<name>] Rules` for cross-run learning
+
+### Phase 7: Extract & Share Knowledge
+
+After a successful build:
+
+- `generate_skill` — gathers workflow code, execution history, and agent issues
+- The agent analyzes patterns and calls `save_skill` to persist them
+- Skills are stored per-workspace and available to future builds
+- Customer-specific quirks become reusable knowledge
+
+## Skills System
+
+Skills are reusable RPA patterns that accumulate as you build automations. The MCP ships with 6 bundled general skills:
+
+
+| Skill                        | Purpose                                                                           |
+| ---------------------------- | --------------------------------------------------------------------------------- |
+| `rpa-testing-workflow`       | **Mandatory.** Exact tool call sequences for testing through the Minicor executor |
+| `cdp-browser-automation`     | CDP starter template, React-safe setters, parallel execution                      |
+| `desktop-uiautomation`       | Framework selection, element selectors, wait/retry patterns                       |
+| `data-extraction-strategies` | Priority-ordered methods for reading data from screen                             |
+| `data-passing-between-steps` | JS-layer interpolation, config variables, step outputs                            |
+| `state-verification`         | LLM-based UI verification for production workflows                                |
+
+
+### Using Skills
+
+```
+list_skills()                         → see all available skills
+get_skill("cdp-browser-automation")   → load full patterns + code templates
+save_skill(...)                       → persist a new skill from a successful build
+generate_skill(workflowId)            → extract patterns from an existing workflow
+```
+
+### Skills Service
 
-### Update
+Skills are automatically persisted through the Minicor platform API. When authenticated, `save_skill` and `generate_skill` store skills server-side so they persist across sessions and are available to other agents in the same workspace.
 
-`npx` users: just restart your editor (fetches latest automatically). Global install: `npm update -g @minicor/mcp-server`.
+Skill tiers:
 
-## How It Works
+- **Global** — general RPA knowledge (read-only, bundled with the MCP)
+- **Per-workspace** — learned from agent sessions, persisted across runs
+- **Customer-specific** — app quirks, environment patterns
 
-1. **Connect to a VM** — The agent connects to your Windows VM running the Laminar Desktop Service (LDS) via a Cloudflare tunnel
-2. **Build automations** — The agent takes screenshots, inspects UI elements, writes Python scripts, and tests them on the VM in real time
-3. **Deploy as workflows** — Validated scripts are saved as step-based Minicor workflows with credentials stored in config stores
-4. **Debug failures** — Before/after screenshots, video recordings of each step, execution diagnosis, and replay on live VMs
+Without authentication, skills fall back to the bundled `.md` files in the package.
 
 ## What You Can Automate
 
-- **Web portals** — Chrome on the VM controlled via CDP (Chrome DevTools Protocol). Works on React/Angular SPAs, anti-bot protected sites, payor portals, EHR web apps.
-- **Desktop applications** — Native Windows apps driven via uiautomation, pywinauto, or pyautogui. EMR clients, billing software, legacy systems.
-- **APIs** — Direct HTTP calls when the agent discovers usable REST endpoints behind a web portal.
-- **Hybrid workflows** — Mix browser, desktop, and API steps in a single workflow.
+- **Web portals** — Chrome via CDP. React/Angular SPAs, anti-bot sites, payor portals, EHR web apps.
+- **Desktop applications** — Windows apps via uiautomation, pywinauto, pyautogui. EMR clients, billing software, legacy systems.
+- **APIs** — Direct HTTP when the agent discovers usable endpoints behind a portal.
+- **Hybrid workflows** — Mix browser, desktop, and API steps in one workflow.
 
 ## VM Setup
 
-1. Install LDS on a Windows 10/11 or Server VM with Python 3.11+
-2. Start LDS on port 1016
-3. Expose via Cloudflare Tunnel: `cloudflared tunnel --url http://localhost:1016`
-4. For browser automation: start Chrome with `--remote-debugging-port=9222`
-5. In your editor, tell the agent: "Connect to my VM at https://your-tunnel-url.com"
+The easiest path is to let the agent handle everything:
+
+```
+"Deploy a VM and set it up for automation"
+```
+
+The agent runs: `deploy_vm` → `install_mds_on_vm` → `start_mds_on_vm` → `vm_connect`
 
-Use the `get_lds_setup_guide` tool for detailed step-by-step instructions.
+Once the VM is provisioned, a secure tunnel is automatically created. The agent connects via the tunnel URL and is ready to build automations. Chrome instances for browser automation are managed automatically by the MDS — no manual setup needed.
+
+For manual setup, use `get_lds_setup_guide` for step-by-step instructions.
 
 ## Tools
 
 ### VM Tools
 
+
 | Tool                   | What it does                                                                               |
 | ---------------------- | ------------------------------------------------------------------------------------------ |
 | `vm_list`              | Discover available VMs (returns ID, name, status, tunnel URL)                              |
-| `vm_connect`           | Connect to VM via LDS Cloudflare tunnel URL or VM ID                                      |
+| `vm_connect`           | Connect to VM via LDS Cloudflare tunnel URL or VM ID                                       |
 | `vm_disconnect`        | Disconnect from VM                                                                         |
 | `vm_status`            | Health check for the connected VM                                                          |
 | `vm_screenshot`        | Full-screen capture of the VM desktop                                                      |
@@ -83,8 +237,10 @@ Use the `get_lds_setup_guide` tool for detailed step-by-step instructions.
 | `vm_inspect_ui`        | Inspect Windows UI elements (window list, element tree, element at point, focused element) |
 | `vm_read_clipboard`    | Read VM clipboard contents                                                                 |
 
+
 ### Automation Building
 
+
 | Tool                    | What it does                                              |
 | ----------------------- | --------------------------------------------------------- |
 | `create_rpa_flow`       | Save a validated Python script as a Minicor workflow step |
@@ -94,8 +250,10 @@ Use the `get_lds_setup_guide` tool for detailed step-by-step instructions.
 | `replay_execution_step` | Re-run a step from a failed execution on the VM           |
 | `get_lds_setup_guide`   | LDS installation walkthrough                              |
 
+
 ### Workflows and Executions
 
+
 | Tool                                                       | What it does                                        |
 | ---------------------------------------------------------- | --------------------------------------------------- |
 | `create_workflow` / `update_workflow` / `delete_workflow`  | Workflow CRUD                                       |
@@ -107,40 +265,46 @@ Use the `get_lds_setup_guide` tool for detailed step-by-step instructions.
 | `test_workflow_step`                                       | Run a single step in isolation                      |
 | `preview_flow_changes` / `compare_flow_versions`           | Diff code before deploying                          |
 
+
 ### 2FA / OTP
 
-| Tool                  | What it does                                                         |
-| --------------------- | -------------------------------------------------------------------- |
-| `tfa_provision_phone` | Buy a Twilio phone number for the workspace (SMS webhook auto-configured) |
-| `tfa_provision_email` | Generate a Mailgun email address for OTP capture                     |
-| `tfa_list_channels`   | List all provisioned phone numbers and email addresses               |
-| `tfa_delete_channel`  | Remove a channel (releases Twilio number if phone)                   |
-| `tfa_register_secret` | Store a TOTP secret (base32 or otpauth:// URI), encrypted at rest    |
-| `tfa_list_secrets`    | List stored TOTP secrets for the workspace                           |
-| `tfa_delete_secret`   | Remove a stored TOTP secret                                         |
-| `tfa_generate_totp`   | Get the current 6-digit TOTP code + seconds until expiry             |
-| `tfa_verify_totp`     | Verify a TOTP code against a stored secret                           |
-| `tfa_parse_qr`        | Parse a QR code image to extract TOTP parameters                     |
-| `tfa_request_sms_otp` | Wait for an SMS OTP (blocks until SMS arrives or timeout)            |
-| `tfa_request_email_otp` | Wait for an email OTP (blocks until email arrives or timeout)      |
-| `tfa_get_challenge`   | Check the status of a pending challenge                              |
-| `tfa_resolve_challenge` | Manually resolve a challenge (for captchas or Slack-provided codes)|
-| `tfa_cancel_challenge`| Cancel a pending challenge                                           |
+
+| Tool                    | What it does                                                              |
+| ----------------------- | ------------------------------------------------------------------------- |
+| `tfa_provision_phone`   | Buy a Twilio phone number for the workspace (SMS webhook auto-configured) |
+| `tfa_provision_email`   | Generate a Mailgun email address for OTP capture                          |
+| `tfa_list_channels`     | List all provisioned phone numbers and email addresses                    |
+| `tfa_delete_channel`    | Remove a channel (releases Twilio number if phone)                        |
+| `tfa_register_secret`   | Store a TOTP secret (base32 or otpauth:// URI), encrypted at rest         |
+| `tfa_list_secrets`      | List stored TOTP secrets for the workspace                                |
+| `tfa_delete_secret`     | Remove a stored TOTP secret                                               |
+| `tfa_generate_totp`     | Get the current 6-digit TOTP code + seconds until expiry                  |
+| `tfa_verify_totp`       | Verify a TOTP code against a stored secret                                |
+| `tfa_parse_qr`          | Parse a QR code image to extract TOTP parameters                          |
+| `tfa_request_sms_otp`   | Wait for an SMS OTP (blocks until SMS arrives or timeout)                 |
+| `tfa_request_email_otp` | Wait for an email OTP (blocks until email arrives or timeout)             |
+| `tfa_get_challenge`     | Check the status of a pending challenge                                   |
+| `tfa_resolve_challenge` | Manually resolve a challenge (for captchas or Slack-provided codes)       |
+| `tfa_cancel_challenge`  | Cancel a pending challenge                                                |
+
 
 Workflows that encounter 2FA prompts use these tools to auto-resolve OTP challenges. Provision channels once per workspace, store the IDs in config stores, and reference them with `{{config.sms_channel_id}}` or `{{config.totp_secret_id}}` at runtime.
 
 ### Config Stores
 
+
 | Tool                                                | What it does                                        |
 | --------------------------------------------------- | --------------------------------------------------- |
 | `create_config_store`                               | Create a credential store with key-value properties |
 | `list_config_stores` / `get_config_store`           | Browse stores                                       |
 | `update_config_property` / `remove_config_property` | Manage individual properties                        |
 
+
 Scripts reference credentials as `{{config.propertyKey}}` — resolved at runtime by the workflow engine.
 
 ### Issues
 
+
 | Tool           | What it does                                   |
 | -------------- | ---------------------------------------------- |
 | `list_issues`  | List all issues in a workspace                 |
@@ -149,6 +313,7 @@ Scripts reference credentials as `{{config.propertyKey}}` — resolved at runtim
 | `update_issue` | Update title, description, status, or assignee |
 | `delete_issue` | Delete an issue                                |
 
+
 Agents use Issues to persist context across runs with the `[Agent:<name>]` title convention:
 
 - `[Agent:my-bot] Rules` — learned behaviors (e.g., "login page takes 15s to load")
@@ -157,31 +322,75 @@ Agents use Issues to persist context across runs with the `[Agent:<name>]` title
 
 ### Agents
 
-| Tool           | What it does                                                    |
-| -------------- | --------------------------------------------------------------- |
-| `list_agents`  | List agents in a workspace                                      |
-| `get_agent`    | Get agent details (task, mode, VM, run stats)                   |
+
+| Tool           | What it does                                                     |
+| -------------- | ---------------------------------------------------------------- |
+| `list_agents`  | List agents in a workspace                                       |
+| `get_agent`    | Get agent details (task, mode, VM, run stats)                    |
 | `create_agent` | Create an agent (on-demand, scheduled, or workflow monitor mode) |
 
+
 Agents are autonomous runners that execute tasks on VMs using MCP tools. After building a workflow, the `build-rpa-workflow` prompt offers to create a monitoring agent that watches for failures and auto-recovers.
 
-### Workflow Sync
+### Skills
+
+
+| Tool             | What it does                                                          |
+| ---------------- | --------------------------------------------------------------------- |
+| `list_skills`    | List available skills (filterable by category, tags, workspace)       |
+| `get_skill`      | Load full skill content by name                                       |
+| `save_skill`     | Save a skill to the skills service and/or local workspace clone       |
+| `generate_skill` | Gather workflow context for skill extraction (agent writes the skill) |
+
+
+### Workspace Sync
+
+
+| Tool                              | What it does                                                                   |
+| --------------------------------- | ------------------------------------------------------------------------------ |
+| `clone_workspace`                 | Full workspace clone: workflows + skills + issues + metadata. Defaults to configured workspaces root if outputDir omitted. |
+| `init_project`                    | Scaffold a git-ready project from a workspace (workflows only)                 |
+| `pull_workflow` / `push_workflow` | Sync individual workflows                                                      |
+| `pull_all` / `push_changed`       | Bulk sync                                                                      |
+| `sync_status`                     | Diff local vs deployed                                                         |
+| `set_workspaces_root`             | Set default root directory for cloning workspaces (`~/.minicor/config.json`)   |
+
+
+### Session Lifecycle
+
+
+| Tool                  | What it does                                                                                  |
+| --------------------- | --------------------------------------------------------------------------------------------- |
+| `session_start`       | Load full workspace context + begin session tracking. Call FIRST in a workspace clone.        |
+| `session_checkpoint`  | Save progress: writes `.minicor/session.json` + syncs `[Workspace:Session]` issue.            |
+| `session_end`         | End session: persist final state, sync to platform, optionally update context.md.             |
 
-| Tool                              | What it does                                  |
-| --------------------------------- | --------------------------------------------- |
-| `init_project`                    | Scaffold a git-ready project from a workspace |
-| `pull_workflow` / `push_workflow` | Sync individual workflows                     |
-| `pull_all` / `push_changed`       | Bulk sync                                     |
-| `sync_status`                     | Diff local vs deployed                        |
 
 ## Prompts
 
-| Prompt                     | What it does                                                                                      |
-| -------------------------- | ------------------------------------------------------------------------------------------------- |
-| `build-rpa-workflow`       | Guided automation building: strategy selection, iterative build loop, per-step Minicor testing, idempotency, context persistence, and agent setup |
-| `debug-workflow-execution` | Analyze a failed execution with VM-aware debugging and replay                                     |
-| `minicor-workflow-guide`   | Full workflow specification: step types, data access, keywords, libraries                         |
-| `2fa-workflow-guide`       | Handling 2FA in workflows: provisioning channels, TOTP secrets, auto-resolving OTP codes          |
+
+| Prompt                       | What it does                                                                                                                           |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `build-rpa-workflow`         | Guided automation building with POC/production mode. Loads skills, iterative build loop, per-step Minicor testing, optional hardening. |
+| `debug-workflow-execution`   | Analyze a failed execution with VM-aware debugging and replay                                                                          |
+| `minicor-workflow-guide`     | Full workflow specification: step types, data access, keywords, libraries                                                              |
+| `2fa-workflow-guide`         | Handling 2FA in workflows: provisioning channels, TOTP secrets, auto-resolving OTP codes                                               |
+| `workspace-session-guide`    | Returns AGENTS.md rules and session state for any workspace clone                                                                      |
+
+
+The `build-rpa-workflow` prompt accepts a `mode` parameter:
+
+- `**poc**` — Quick prototype. Streamlined testing, no state verification or monitoring.
+- `**production**` — Full hardening. State verification, idempotency testing, monitoring agent, context persistence.
+- **Omitted** — The agent asks the user which mode to use.
+
+## Environment Variables
+
+
+| Variable             | Purpose                | Default            |
+| -------------------- | ---------------------- | ------------------ |
+| `VM_MANAGER_API_URL` | VM Manager service URL | Cloud Run instance |
+
 
 ## Auth
 
@@ -197,3 +406,29 @@ npm install
 npm run build
 npm test
 ```
+
+### Project Structure
+
+```
+src/
+  index.ts              — CLI MCP entry (stdio transport, token management, disconnect hooks)
+  lib.ts                — Embeddable server factory (in-process, no side effects)
+  bootstrap.ts          — CLI to generate harness configs (CLAUDE.md, .cursor/rules, etc.)
+  config.ts             — User config (~/.minicor/config.json) — workspacesRoot, etc.
+  state.ts              — Shared mutable state (VM connections, active session tracking)
+  skills.ts             — Skill loader, parser, index builder
+  tools/
+    session.ts          — session_start, session_checkpoint, session_end, auto-checkpoint
+    skills.ts           — list_skills, get_skill, save_skill, generate_skill
+    sync-tools.ts       — clone_workspace, init_project, pull/push, set_workspaces_root
+    vm.ts, vm-rpa.ts    — VM and RPA tools
+    core.ts             — Workflows, flows, executions
+    ...
+  prompts/
+    workspace-session.ts — Workspace session guide prompt
+    build-rpa.ts        — Guided RPA building (POC/production modes)
+    ...
+skills/
+  general/              — Bundled skill files (shipped with npm package)
+```
+

package/dist/bootstrap.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Bootstrap CLI — generates harness-specific config files for a Minicor workspace clone.
+ *
+ * Usage:
+ *   minicor-bootstrap claude-code [--dir <workspace-dir>]
+ *   minicor-bootstrap cursor      [--dir <workspace-dir>]
+ *   minicor-bootstrap generic     [--dir <workspace-dir>]
+ *   minicor-bootstrap all         [--dir <workspace-dir>]
+ */
+export {};
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":";AAEA;;;;;;;;GAQG"}