npm package: @minicor/mcp-server
Description: Desktop and browser RPA automation, workflow management, and AI-powered debugging for the Minicor platform. Formerly Laminar.
Latest version: 3.0.0

# 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.

## Quick Start

### Cursor

Run the setup wizard, then add to your Cursor MCP config (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "minicor": {
      "command": "npx",
      "args": ["-y", "@minicor/mcp-server"]
    }
  }
}
```

If you run `minicor-mcp-setup`, it writes this config automatically.

### Claude Code

```bash
npm install -g @minicor/mcp-server
minicor-mcp-setup
claude mcp add minicor -- minicor-mcp
```

### 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`.

### Update

`npx` users: just restart your editor (fetches latest automatically). Global install: `npm update -g @minicor/mcp-server`.

## How It Works

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

## 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.

## 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"

Use the `get_lds_setup_guide` tool for detailed 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_disconnect`        | Disconnect from VM                                                                         |
| `vm_status`            | Health check for the connected VM                                                          |
| `vm_screenshot`        | Full-screen capture of the VM desktop                                                      |
| `vm_screenshot_region` | Zoom into a specific screen area                                                           |
| `vm_execute_script`    | Run a Python script on the VM                                                              |
| `vm_execution_status`  | Check status of a running script                                                           |
| `vm_execution_control` | Pause, resume, stop, or skip a running script                                              |
| `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 |
| `debug_rpa_step`        | Test a script with before/after screenshots               |
| `vm_reset_state`        | Manage windows: focus app, minimize all, close dialogs    |
| `batch_test_rpa`        | Run a workflow with multiple test inputs                  |
| `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                                       |
| `create_flow` / `update_flow` / `delete_flow`              | Step CRUD                                           |
| `execute_workflow` / `execute_workflow_async`              | Run workflows synchronously or async                |
| `list_executions` / `get_execution` / `get_full_execution` | View execution history and details                  |
| `diagnose_execution`                                       | Analyze failures with RPA-specific pattern matching |
| `get_workflow_overview`                                    | Full snapshot: steps, code, recent executions       |
| `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                                           |

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                 |
| `get_issue`    | Get a specific issue with full description     |
| `create_issue` | Create an issue (supports Markdown)            |
| `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")
- `[Agent:my-bot] Context` — persistent state (URLs, credential rotation dates)
- `[Agent:my-bot] Session 2026-04-09` — run summaries

### Agents

| 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

| 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          |

## Auth

- **Sign in**: `minicor-mcp-setup` (browser) or `minicor-mcp-setup --cli`
- **Token storage**: `~/.minicor/tokens.json`
- **Auto-refresh**: tokens refresh before expiry
- **Regions**: US (default) or Canada

## Development

```bash
npm install
npm run build
npm test
```