@minicor/mcp-server 4.19.2 → 4.19.3

package/dist/tools/vm.js

@@ -1,17 +1,17 @@
+/**
+ * VM provisioning, MDS configuration and installation tools.
+ * Uses the VM service and Azure management APIs; direct desktop access is registered separately.
+ */
 import { z } from "zod";
-import { ok, text, json, DIRECT_VM_TOOLS_DISABLED_HOSTED, } from "../helpers.js";
+import { ok, text, DIRECT_VM_TOOLS_DISABLED_HOSTED } from "../helpers.js";
 import * as lds from "../lds-client.js";
-import { generateInspectScript } from "../inspect-scripts.js";
-import { fetchVmCredentials, fetchVmCredentialsSoft, resolveVmTarget, vmTargetParams, } from "../vm-target.js";
+import { fetchVmCredentials, fetchVmCredentialsSoft } from "../vm-target.js";
+import { register as registerVmDesktop } from "./vm-desktop.js";
 import { registerVmDiscovery } from "./discovery.js";
 const regionParam = z
     .enum(["us", "ca"])
     .optional()
     .describe("Region (us or ca). Auto-detected from workspace if omitted.");
-const targetUserParam = z
-    .string()
-    .optional()
-    .describe("Windows account whose session runs this (broker/multi-session VMs only — REQUIRED there, MDS never picks a user). Omit on standalone VMs. vm_list_sessions shows the registered users.");
 /** A robot-user catalog entry as accepted by the VM service (MDSRegisteredUserInput). */
 const mdsRegisteredUserSchema = z.object({
     username: z.string().describe("Local Windows account name"),
@@ -36,21 +36,9 @@ export function register(deps, directVmTools = true) {
             return text(DIRECT_VM_TOOLS_DISABLED_HOSTED);
         return null;
     }
-    async function requireTarget(args) {
-        const disabled = requireDirect();
-        if (disabled)
-            return { ok: false, res: disabled };
-        const resolved = await resolveVmTarget(deps, args);
-        if (!resolved.ok)
-            return { ok: false, res: text(resolved.message) };
-        return { ok: true, target: resolved.target };
-    }
-    function refreshStoredMode(target, mode) {
-        if (state.ldsConnection?.url === target.url)
-            state.ldsConnection.mode = mode;
-    }
     // ── VM discovery ─────────────────────────────────────────────
     registerVmDiscovery(deps);
+    registerVmDesktop(deps, directVmTools);
     // ── VM deployment ──────────────────────────────────────────
     server.tool("deploy_vm", "Provision a new Windows VM on Azure. Uses smart region selection — pass 'us' or 'canada' " +
         "and the service finds a region with available quota. Deployment is async (~5-10 min). " +
@@ -126,381 +114,6 @@ export function register(deps, directVmTools = true) {
             return text(`VM deployment failed: ${e.message}`);
         }
     });
-    // ── Connection management ─────────────────────────────────
-    server.tool("vm_connect", "Connect to a VM. Provide vmId (from vm_list) to auto-fill credentials, or provide url directly. Discovers the MDS mode from /health: on a multi-session (broker) VM, execute/screenshot calls additionally need targetUser. The connection is remembered only by servers that outlive one call (stdio/embedded) — on the hosted server, pass vmId + workspaceId to each vm_* tool instead.", {
-        vmId: z.number().optional().describe("VM ID from vm_list — auto-fills url, apiKey, serviceId"),
-        workspaceId: z
-            .number()
-            .optional()
-            .describe("Workspace that owns the VM. With vmId, resolves the VM straight from the VM service — no prior vm_list needed."),
-        url: z.string().optional().describe("MDS base URL (Cloudflare Tunnel) — use this OR vmId"),
-        apiKey: z.string().optional().describe("MDS API key (not needed with vmId)"),
-        serviceId: z.string().optional().describe("MDS service ID (not needed with vmId)"),
-        region: regionParam,
-    }, async ({ vmId, workspaceId, url, apiKey, serviceId, region }) => {
-        const disabled = requireDirect();
-        if (disabled)
-            return disabled;
-        let connectUrl = url;
-        let connectApiKey = apiKey;
-        let connectServiceId = serviceId;
-        let vmName;
-        if (vmId) {
-            const vm = state.getCachedVm(vmId);
-            if (vm) {
-                if (!vm.tunnel_url) {
-                    return text(`VM "${vm.vm_name}" has no tunnel URL — it may not be running.`);
-                }
-                connectUrl = vm.tunnel_url;
-                connectApiKey = vm.api_key ?? undefined;
-                connectServiceId = vm.service_id ?? undefined;
-                vmName = vm.vm_name;
-                // Redacted list (newer VM service): resolve the MDS credentials via
-                // the per-VM credentials endpoint instead of failing auth later.
-                if (!connectApiKey && vm.workspace_id) {
-                    const wsId = Number(vm.workspace_id);
-                    const creds = await fetchVmCredentialsSoft(deps, vm.workspace_id, vmId, region ??
-                        (Number.isNaN(wsId) ? undefined : state.getWorkspaceRegion(wsId)));
-                    connectApiKey = creds.apiKey;
-                    connectServiceId = connectServiceId ?? creds.serviceId;
-                }
-            }
-            else if (workspaceId !== undefined) {
-                const wsRegion = region ?? state.getWorkspaceRegion(workspaceId);
-                const resolved = await fetchVmCredentials(deps, workspaceId, vmId, wsRegion);
-                if (!resolved.ok)
-                    return text(resolved.message);
-                if (!resolved.creds.tunnelUrl) {
-                    return text(`VM ${vmId} has no tunnel URL — MDS may not be installed or running. Check vm_list, or get_install_status if an install is in flight.`);
-                }
-                connectUrl = resolved.creds.tunnelUrl;
-                connectApiKey = resolved.creds.apiKey;
-                connectServiceId = resolved.creds.serviceId;
-                vmName = resolved.creds.vmName;
-            }
-            else {
-                return text("VM not found in cache. Run vm_list first to discover available VMs, or pass workspaceId alongside vmId to resolve it directly.");
-            }
-        }
-        if (!connectUrl) {
-            return text("Provide either vmId (from vm_list) or url to connect.");
-        }
-        try {
-            const health = await lds.health(connectUrl);
-            const mode = lds.modeFromHealth(health);
-            state.setLdsConnection({
-                url: connectUrl,
-                apiKey: connectApiKey,
-                serviceId: connectServiceId,
-                vmId,
-                vmName,
-                mode,
-            });
-            const brokerMode = mode === "broker";
-            let registeredUsers;
-            if (brokerMode) {
-                try {
-                    const status = await lds.status(connectUrl, state.ldsAuth());
-                    registeredUsers = status.users.map((u) => u.user);
-                }
-                catch {
-                    /* surface users lazily via vm_list_sessions instead */
-                }
-            }
-            return ok({
-                connected: true,
-                url: connectUrl,
-                vmId,
-                vmName,
-                mode,
-                authenticated: !!(connectApiKey && connectServiceId),
-                service: health,
-                ...(registeredUsers ? { registeredUsers } : {}),
-                next_steps: [
-                    ...(brokerMode
-                        ? [
-                            "This VM is a multi-session broker: EVERY vm_execute_script / vm_screenshot / debug_rpa_step call must include targetUser (MDS never picks a user itself)",
-                            "Use vm_list_sessions to see registered users and their session/agent state, then ask the user which account to target",
-                            "Use vm_start_session / vm_stop_session to manage user sessions",
-                        ]
-                        : [
-                            "Take vm_screenshot to see the current desktop state",
-                            "Use vm_inspect_ui mode 'window_list' to see running apps",
-                            "Use the build-rpa-workflow prompt for guided automation building",
-                            "Run Python scripts via vm_execute_script (CDP for browsers, uiautomation for desktop)",
-                        ]),
-                    ...(vmId !== undefined
-                        ? [
-                            `Pass vmId ${vmId}${workspaceId !== undefined ? ` + workspaceId ${workspaceId}` : " + workspaceId"} on each vm_* call to target this VM without depending on the connection persisting (required on the hosted server)`,
-                        ]
-                        : []),
-                ],
-                automation_approaches: {
-                    browser: "CDP via Python websocket to Chrome on port 9222 → vm_execute_script",
-                    desktop: "uiautomation/pywinauto/pyautogui → vm_execute_script",
-                    api: "Python requests/httpx when APIs are available → vm_execute_script",
-                },
-            });
-        }
-        catch (e) {
-            return text(`Failed to connect to VM at ${connectUrl}: ${e.message}`);
-        }
-    });
-    server.tool("vm_disconnect", "Disconnect from the current VM", {}, async () => {
-        const disabled = requireDirect();
-        if (disabled)
-            return disabled;
-        state.setLdsConnection(null);
-        return text("Disconnected from VM.");
-    });
-    server.tool("vm_status", "Check health/status of a VM, including its MDS mode (standalone or broker)", {
-        ...vmTargetParams,
-        region: regionParam,
-    }, async ({ vmId, workspaceId, region }) => {
-        const t = await requireTarget({ vmId, workspaceId, region: region });
-        if (!t.ok)
-            return t.res;
-        const { target } = t;
-        try {
-            const health = await lds.health(target.url);
-            const mode = lds.modeFromHealth(health);
-            // Keep the stored mode fresh across MDS restarts.
-            refreshStoredMode(target, mode);
-            return ok({
-                connected: true,
-                url: target.url,
-                vmId: target.vmId,
-                vmName: target.vmName,
-                mode,
-                ...health,
-            });
-        }
-        catch (e) {
-            return text(`VM unreachable: ${e.message}`);
-        }
-    });
-    // ── Screenshot ────────────────────────────────────────────
-    server.tool("vm_screenshot", "Take a full-screen screenshot of the VM. Use for verifying actions worked and seeing the current desktop/browser state. For reading small text, prefer vm_screenshot_region. On a broker VM, pass targetUser to capture that user's session desktop.", {
-        targetUser: targetUserParam,
-        ...vmTargetParams,
-        region: regionParam,
-    }, async ({ targetUser, vmId, workspaceId, region }) => {
-        const t = await requireTarget({ vmId, workspaceId, region: region });
-        if (!t.ok)
-            return t.res;
-        const { target } = t;
-        try {
-            const res = await lds.screenshot(target.url, target.auth, targetUser);
-            const { width, height, size_bytes, capture_duration_ms, timestamp } = res.metadata;
-            return {
-                content: [
-                    {
-                        type: "image",
-                        data: res.image,
-                        mimeType: "image/png",
-                    },
-                    {
-                        type: "text",
-                        text: json({
-                            width,
-                            height,
-                            size_bytes,
-                            capture_duration_ms,
-                            timestamp,
-                        }),
-                    },
-                ],
-            };
-        }
-        catch (e) {
-            return text(`Screenshot failed: ${e.message}`);
-        }
-    });
-    server.tool("vm_screenshot_region", "Zoom into a specific screen region. Use for reading small text or verifying specific UI elements with better resolution than full screenshots.", {
-        x: z.number().describe("Left X coordinate"),
-        y: z.number().describe("Top Y coordinate"),
-        width: z.number().describe("Region width in pixels"),
-        height: z.number().describe("Region height in pixels"),
-        targetUser: targetUserParam,
-        ...vmTargetParams,
-        region: z
-            .enum(["us", "ca"])
-            .optional()
-            .describe("Minicor region (us or ca) the workspace lives in — NOT the screen region. Auto-detected from workspace if omitted."),
-    }, async ({ x, y, width, height, targetUser, vmId, workspaceId, region }) => {
-        const t = await requireTarget({ vmId, workspaceId, region: region });
-        if (!t.ok)
-            return t.res;
-        const { target } = t;
-        const x2 = x + width;
-        const y2 = y + height;
-        const script = `
-import json, base64, io
-from PIL import ImageGrab
-
-img = ImageGrab.grab(bbox=(${x}, ${y}, ${x2}, ${y2}))
-buf = io.BytesIO()
-img.save(buf, format="PNG")
-b64 = base64.b64encode(buf.getvalue()).decode("utf-8")
-print(json.dumps({"image": b64, "width": img.width, "height": img.height}))
-`.trim();
-        try {
-            const res = await lds.execute(target.url, script, { targetUser }, target.auth);
-            if (!res.success) {
-                return text(`Region screenshot failed: ${res.stderr || "unknown error"}`);
-            }
-            const parsed = JSON.parse(res.stdout);
-            return {
-                content: [
-                    {
-                        type: "image",
-                        data: parsed.image,
-                        mimeType: "image/png",
-                    },
-                    {
-                        type: "text",
-                        text: json({
-                            width: parsed.width,
-                            height: parsed.height,
-                            region: { x, y, width, height },
-                        }),
-                    },
-                ],
-            };
-        }
-        catch (e) {
-            return text(`Region screenshot failed: ${e.message}`);
-        }
-    });
-    // ── Script execution ──────────────────────────────────────
-    server.tool("vm_execute_script", "Execute a Python script on the VM. This is the primary tool for ALL automation: CDP websocket for browser control, uiautomation/pyautogui for desktop apps, requests/httpx for API calls. Returns stdout, stderr, exit code, and timing. On a broker VM, targetUser is required — MDS routes the script to that user's session.", {
-        script: z.string().describe("Python script to execute"),
-        executionId: z.string().optional().describe("Execution ID for tracking"),
-        flowId: z.string().optional().describe("Flow ID for tracking"),
-        targetUser: targetUserParam,
-        ...vmTargetParams,
-        region: regionParam,
-    }, async ({ script, executionId, flowId, targetUser, vmId, workspaceId, region }) => {
-        const t = await requireTarget({ vmId, workspaceId, region: region });
-        if (!t.ok)
-            return t.res;
-        const { target } = t;
-        try {
-            const res = await lds.execute(target.url, script, { executionId, flowId, targetUser }, target.auth);
-            return ok({
-                success: res.success,
-                exitCode: res.exitCode,
-                stdout: res.stdout,
-                stderr: res.stderr,
-                executionTimeMs: res.executionTimeMs,
-                skipped: res.skipped,
-                stopped: res.stopped,
-                resultData: res.resultData,
-                // Broker attribution (absent on standalone).
-                ...(res.targetUser !== undefined ? { targetUser: res.targetUser } : {}),
-            });
-        }
-        catch (e) {
-            return text(`Execution failed: ${e.message}`);
-        }
-    });
-    // ── Execution status ──────────────────────────────────────
-    // vm_execution_control is gone (MDS removed /execute/control); do not re-add.
-    server.tool("vm_execution_status", "Get current execution status on the VM (active script, progress, queue). On a broker VM the plain call returns the router-wide status for every user; pass targetUser (and optionally executionId) to read one user's live execution progress instead.", {
-        targetUser: targetUserParam,
-        executionId: z
-            .string()
-            .optional()
-            .describe("Look up progress for a specific executionId (with or without targetUser)"),
-        ...vmTargetParams,
-        region: regionParam,
-    }, async ({ targetUser, executionId, vmId, workspaceId, region }) => {
-        const t = await requireTarget({ vmId, workspaceId, region: region });
-        if (!t.ok)
-            return t.res;
-        const { target } = t;
-        try {
-            // A targeted lookup routes to /execute/progress, which brokers
-            // forward to that user's agent; the untargeted call stays on
-            // /execute/status (router-wide on brokers, slots on standalone).
-            if (targetUser || executionId) {
-                const progress = await lds.executionProgress(target.url, target.auth, {
-                    targetUser,
-                    executionId,
-                });
-                return ok(progress);
-            }
-            const status = await lds.executionStatus(target.url, target.auth);
-            return ok(status);
-        }
-        catch (e) {
-            return text(`Failed to get execution status: ${e.message}`);
-        }
-    });
-    // ── User sessions (multi-session / broker VMs) ─────────────
-    server.tool("vm_list_sessions", "List the registered users on a multi-session (broker) VM with their session and agent state (GET /status). Use this to pick a targetUser for vm_execute_script / vm_screenshot, or to show the user which accounts are available. Requires API-key auth (target by vmId + workspaceId, or connect with vmId or apiKey+serviceId).", {
-        ...vmTargetParams,
-        region: regionParam,
-    }, async ({ vmId, workspaceId, region }) => {
-        const t = await requireTarget({ vmId, workspaceId, region: region });
-        if (!t.ok)
-            return t.res;
-        const { target } = t;
-        try {
-            // /status only exists on brokers; probe mode so a standalone 404 reads clearly.
-            const mode = await lds.discoverMode(target.url);
-            refreshStoredMode(target, mode);
-            if (mode !== "broker") {
-                return text(`This VM runs MDS in '${mode}' mode — per-user sessions only exist on multi-session (broker) VMs. Standalone tools work without targetUser.`);
-            }
-            const status = await lds.status(target.url, target.auth);
-            return ok({
-                mode,
-                broker: status.broker,
-                users: status.users,
-                queues: status.queues,
-                hint: "Pass one of these users as targetUser to vm_execute_script / vm_screenshot / debug_rpa_step. State 'active' means a live agent; 'stopped'/'provisioned' users need vm_start_session (or any job) first.",
-            });
-        }
-        catch (e) {
-            return text(`Failed to list sessions: ${e.message}`);
-        }
-    });
-    server.tool("vm_start_session", "Start (or reconnect) a registered user's session on the connected broker VM (POST /sessions/{user}/start). Blocks until the session is up and its agent is registered. Fails with a typed error when the session keeper is disabled (session_start_disabled) or the user is not registered.", {
-        user: z.string().describe("Registered Windows account name (see vm_list_sessions)"),
-        ...vmTargetParams,
-        region: regionParam,
-    }, async ({ user, vmId, workspaceId, region }) => {
-        const t = await requireTarget({ vmId, workspaceId, region: region });
-        if (!t.ok)
-            return t.res;
-        try {
-            const result = await lds.sessionStart(t.target.url, user, t.target.auth);
-            return ok({
-                ...result,
-                hint: `Session for '${user}' is up — target it with targetUser='${user}'.`,
-            });
-        }
-        catch (e) {
-            return text(`Failed to start session for '${user}': ${e.message}`);
-        }
-    });
-    server.tool("vm_stop_session", "Disconnect a registered user's session on the connected broker VM (POST /sessions/{user}/stop). The user STAYS logged in but the session goes dark and stays dark until an explicit start or a new job re-arms it; browser jobs keep working, desktop jobs are refused while dark. The keeper-host user cannot be stopped through MDS.", {
-        user: z.string().describe("Registered Windows account name (see vm_list_sessions)"),
-        ...vmTargetParams,
-        region: regionParam,
-    }, async ({ user, vmId, workspaceId, region }) => {
-        const t = await requireTarget({ vmId, workspaceId, region: region });
-        if (!t.ok)
-            return t.res;
-        try {
-            const result = await lds.sessionStop(t.target.url, user, t.target.auth);
-            return ok(result);
-        }
-        catch (e) {
-            return text(`Failed to stop session for '${user}': ${e.message}`);
-        }
-    });
     // ── MDS configuration & service control (VM service, bearer) ──
     server.tool("vm_get_mds_config", "Read a VM's MDS multi-session configuration and observed state from the VM service: registered robot users (with secretRef), keeper_enabled, session_resolution, live sessions, agent status, and restart/apply tracking. Workspace OWNER/ADMIN only (the service returns 403 otherwise). No VM connection needed — addresses the VM by workspaceId + vmId.", {
         workspaceId: z.number().describe("Workspace ID"),
@@ -633,109 +246,6 @@ print(json.dumps({"image": b64, "width": img.width, "height": img.height}))
             return text(`Service ${action} failed: ${e.message}`);
         }
     });
-    // ── UI inspection ─────────────────────────────────────────
-    server.tool("vm_inspect_ui", "X-ray the VM screen: list windows, get element trees with coordinates and properties, find elements at a point, or get the focused element. Use element_tree to map all interactive elements before writing desktop automation scripts.", {
-        mode: z
-            .enum([
-            "window_list",
-            "screen_info",
-            "element_at_point",
-            "element_tree",
-            "focused_element",
-        ])
-            .describe("Inspection mode"),
-        x: z.number().optional().describe("X coordinate (for element_at_point)"),
-        y: z.number().optional().describe("Y coordinate (for element_at_point)"),
-        windowTitle: z
-            .string()
-            .optional()
-            .describe("Window title filter (for element_tree)"),
-        framework: z
-            .enum(["auto", "uiautomation", "pywinauto", "jab"])
-            .optional()
-            .describe("Automation framework (default: auto → uiautomation)"),
-        depth: z
-            .number()
-            .optional()
-            .describe("Max tree depth (for element_tree, default 3)"),
-        targetUser: targetUserParam,
-        ...vmTargetParams,
-        region: regionParam,
-    }, async ({ mode, x, y, windowTitle, framework, depth, targetUser, vmId, workspaceId, region }) => {
-        const t = await requireTarget({ vmId, workspaceId, region: region });
-        if (!t.ok)
-            return t.res;
-        const { target } = t;
-        const script = generateInspectScript({
-            mode,
-            x,
-            y,
-            windowTitle,
-            framework,
-            depth,
-        });
-        try {
-            const res = await lds.execute(target.url, script, { targetUser }, target.auth);
-            if (!res.success) {
-                return text(`UI inspection failed (exit ${res.exitCode}): ${res.stderr || res.stdout}`);
-            }
-            try {
-                return ok(JSON.parse(res.stdout));
-            }
-            catch {
-                return text(res.stdout);
-            }
-        }
-        catch (e) {
-            return text(`UI inspection failed: ${e.message}`);
-        }
-    });
-    // ── Clipboard ─────────────────────────────────────────────
-    server.tool("vm_read_clipboard", "Read the current clipboard contents from the VM", {
-        targetUser: targetUserParam,
-        ...vmTargetParams,
-        region: regionParam,
-    }, async ({ targetUser, vmId, workspaceId, region }) => {
-        const t = await requireTarget({ vmId, workspaceId, region: region });
-        if (!t.ok)
-            return t.res;
-        const { target } = t;
-        const script = `
-import json
-
-clipboard_text = ""
-try:
-    import win32clipboard
-    win32clipboard.OpenClipboard()
-    try:
-        clipboard_text = win32clipboard.GetClipboardData()
-    except TypeError:
-        clipboard_text = ""
-    finally:
-        win32clipboard.CloseClipboard()
-except ImportError:
-    import subprocess
-    result = subprocess.run(["powershell", "-command", "Get-Clipboard"], capture_output=True, text=True)
-    clipboard_text = result.stdout.strip()
-
-print(json.dumps({"clipboard": clipboard_text}))
-`.trim();
-        try {
-            const res = await lds.execute(target.url, script, { targetUser }, target.auth);
-            if (!res.success) {
-                return text(`Clipboard read failed: ${res.stderr || "unknown error"}`);
-            }
-            try {
-                return ok(JSON.parse(res.stdout));
-            }
-            catch {
-                return text(res.stdout);
-            }
-        }
-        catch (e) {
-            return text(`Clipboard read failed: ${e.message}`);
-        }
-    });
     // ── MDS Installation ───────────────────────────────────────
     /**
      * Refuse legacy standalone management actions on broker VMs (live /health