@diegosouzacdv/jev-browser-mcp 0.7.1 → 0.7.2

package/mcp_servers/jev-browser-npm/src/server.mjs

@@ -1,14 +1,17 @@
 import { spawnSync } from "node:child_process";
 import { readlink } from "node:fs/promises";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { McpServer } from "@modelcontextprotocol/server";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { chromium } from "playwright";
 import * as z from "zod/v4";
 import packageManifest from "../../../package.json" with { type: "json" };
 import { loadSettings, JevBrowserError } from "./config.mjs";
 import { chooseNextAction, collectFlowContractIssues, createMutationAuthorizationStore, describeBrowserActions, executeBrowserFlow } from "./flow.mjs";
+import { createBrowserFlowRunStore } from "./browser-flow-runs.mjs";
+import { executeTestSuite } from "./test-suites.mjs";
+import { cleanupUploadStagingDirectory, prepareUploadStagingDirectory } from "./upload-staging.mjs";
 
 const browserContract = describeBrowserActions();
 const jsonObject = z.record(z.string(), z.unknown());
@@ -21,7 +24,8 @@ const browserOptionsShape = Object.fromEntries(browserContract.options.map((key)
           : key === "console_levels" ? z.array(z.enum(["log", "info", "debug", "warn", "error"]))
             : key === "ready" ? z.union([z.string(), z.record(z.string(), z.unknown()), z.array(z.union([z.string(), z.record(z.string(), z.unknown())]))])
               : ["allow_mutations", "block_trackers", "capture_console_errors", "capture_network_error_bodies", "capture_network_errors", "auto_angular_idle", "block_fonts", "continue_from_current_page", "dry_run", "fast_path", "local_only", "ready_network_idle", "reuse_page", "screenshot_on_failure", "screenshot_on_success", "record_video", "mobile", "snapshot_include_hidden", "include_unnamed_controls", "stop_on_expected", "trace_on_failure", "trace_on_success", "fresh_context", "clear_storage"].includes(key) ? z.boolean()
-                : ["max_flow_steps", "ready_stable_ms", "ready_timeout_seconds", "step_timeout_seconds"].includes(key) ? z.number().positive()
+                : key === "max_flow_steps" ? z.number().int().positive()
+                  : ["ready_stable_ms", "ready_timeout_seconds", "step_timeout_seconds"].includes(key) ? z.number().positive()
                   : ["busy_selectors", "login_text", "login_url_contains"].includes(key) ? z.array(z.string())
                     : ["viewport", "geolocation", "wait_for_http", "fake_media"].includes(key) ? z.union([z.string(), jsonObject])
                       : z.string();
@@ -45,7 +49,7 @@ const expectedOutcomeSchema = z.union([
   }).strict().refine((value) => Boolean(value.text || value.request), "expected_outcome needs text or request"),
 ]);
 
-const browserPools = new Set();
+const browserPools = new Map();
 
 class BrowserPool {
   #settings;
@@ -387,46 +391,66 @@ async function activeProfileOwnerPid(profileDir) {
   }
 }
 
-export function createJevBrowserServer({ env = process.env, configPath, fetchImpl = fetch } = {}) {
-  const settings = loadSettings({ env, ...(configPath ? { configPath } : {}) });
-  const browserPool = new BrowserPool(settings);
-  const mutationAuthorizationStore = createMutationAuthorizationStore();
-  browserPools.add(browserPool);
+export function createJevBrowserServer({ env = process.env, configPath, fetchImpl = fetch } = {}) {
+  const settings = loadSettings({ env, ...(configPath ? { configPath } : {}) });
+  const browserPool = new BrowserPool(settings);
+  const mutationAuthorizationStore = createMutationAuthorizationStore();
+  const flowRunStore = createBrowserFlowRunStore({
+    maxEntries: settings.browser.maxBackgroundFlowRuns,
+    retentionMs: settings.browser.backgroundFlowResultTtlMs,
+  });
+  browserPools.set(browserPool, settings);
   const server = new McpServer({
     name: "jev-browser",
     version: packageManifest.version,
     description: "Bounded Playwright screen flows selected by Jev through the OpenRouter Decisions API.",
   });
   const closeServer = server.close.bind(server);
-  server.close = async () => {
-    try {
-      await closeServer();
-    } finally {
-      await browserPool.close();
-      browserPools.delete(browserPool);
-    }
-  };
+  server.close = async () => {
+    try {
+      await closeServer();
+    } finally {
+      try {
+        await browserPool.close();
+      } finally {
+        browserPools.delete(browserPool);
+        await cleanupUploadStagingDirectory(settings);
+      }
+    }
+  };
 
   server.registerTool(
     "browser_health",
     {
       description: "Check the managed browser connection; set restart=true to close and restart only the browser session owned by this MCP process.",
       inputSchema: { restart: z.boolean().optional() },
-    },
+    },
     async ({ restart = false } = {}) => {
       const health = restart ? await browserPool.restart() : await browserPool.health();
+      const uploadStagingDirectory = settings.browser.managedUploadStaging
+        ? await prepareUploadStagingDirectory(settings)
+        : undefined;
       return toolText({
         ...health,
         server_version: packageManifest.version,
         browser_mode: settings.browser.mode,
         session_id: settings.browser.sessionId,
+        ...(uploadStagingDirectory ? { upload_staging_directory: uploadStagingDirectory } : {}),
         capabilities: {
           actions: Object.keys(describeBrowserActions().actions),
           options: describeBrowserActions().options,
+          limits: describeBrowserActions(settings).limits,
+          environment_profiles: Object.keys(settings.browser.environmentProfiles.profiles),
+          profile_environments: Object.fromEntries(Object.entries(settings.browser.environmentProfiles.profiles).map(([name, profile]) => [name, profile.environment])),
+          test_suite_directory: ".jev-browser/suites",
+          suite_report_format: "Markdown",
+          database_engines: ["postgresql", "oracle"],
+          remote_file_protocols: ["ftp", "ftps", "sftp"],
           media_permissions: ["microphone", "geolocation"],
           fake_media: "WAV audio input",
           storage_state: "named account snapshots",
           contexts: ["current", "new isolated context"],
+          file_upload_staging: settings.browser.managedUploadStaging ? "private project-local fixtures and uploads; managed files are cleaned after flows and suites" : "managed project-local staging unavailable",
         },
       }, settings.browser.maxToolResponseBytes);
     },
@@ -438,7 +462,7 @@ export function createJevBrowserServer({ env = process.env, configPath, fetchImp
       description: "Return the live JSON contract for every supported Jev Browser MCP action, option, alias, timeout and placeholder rule.",
       inputSchema: {},
     },
-    async () => toolText({ server_version: packageManifest.version, ...describeBrowserActions() }, settings.browser.maxToolResponseBytes),
+    async () => toolText({ server_version: packageManifest.version, ...describeBrowserActions(settings) }, settings.browser.maxToolResponseBytes),
   );
 
   server.registerTool(
@@ -468,7 +492,7 @@ export function createJevBrowserServer({ env = process.env, configPath, fetchImp
   server.registerTool(
     "run_browser_flow",
     {
-      description: "Run a bounded screen flow in an isolated per-server browser profile. Continues the current SPA page by default. Supports media fakes, tabs and contexts, read-only page inspection, conditional plans, HTTP/network/WebSocket assertions, named storage state, guarded mutation confirmation, per-step timeouts and evidence. expected_outcome accepts descriptive text or structured text/request assertions. Use describe_actions for required and optional fields and the exact options contract. Jev chooses among eligible supplied plans; a single plan skips the decision call when fast_path is enabled.",
+      description: "Run a bounded screen flow in an isolated per-server browser profile. Set background=true to return a run_id immediately and poll get_browser_flow_result instead of holding a long MCP call open. Continues the current SPA page by default. Supports media fakes, tabs and contexts, read-only page inspection, conditional plans, HTTP/network/WebSocket assertions, named storage state, guarded mutation confirmation, per-step timeouts and evidence. expected_outcome accepts descriptive text or structured text/request assertions. Use describe_actions for required and optional fields and the exact options contract. Jev chooses among eligible supplied plans; a single plan skips the decision call when fast_path is enabled.",
       inputSchema: {
         flow: z.string().optional(),
         initial_url: z.string().optional(),
@@ -476,13 +500,14 @@ export function createJevBrowserServer({ env = process.env, configPath, fetchImp
         candidate_plans: z.record(z.string(), candidatePlanSchema).optional(),
         params: z.record(z.string(), z.unknown()).optional(),
         options: browserOptionsSchema.optional(),
+        background: z.boolean().optional(),
       },
     },
-    async ({ flow, initial_url: initialUrl, expected_outcome: expectedOutcome, candidate_plans: candidatePlans, params, options }) => {
+    async ({ flow, initial_url: initialUrl, expected_outcome: expectedOutcome, candidate_plans: candidatePlans, params, options, background = false }) => {
       try {
         const contractIssues = collectFlowContractIssues({ flow, candidatePlans });
         if (contractIssues.length) throw new JevBrowserError(`flow contract validation failed:\n- ${contractIssues.join("\n- ")}`);
-        return toolText(await browserPool.runFlow(async () => {
+        const execute = () => browserPool.runFlow(async () => {
           const args = {
             flow,
             initialUrl,
@@ -557,20 +582,96 @@ export function createJevBrowserServer({ env = process.env, configPath, fetchImp
           if (first.status !== "environment_error" || !disconnected
             || first.steps_executed > 0 || first.mutating_steps?.length || options?.confirmation_token) return first;
           return retryAfterRestart(first);
-        }), settings.browser.maxToolResponseBytes);
-      } catch (error) {
-        return toolError(error, settings);
-      }
-    },
-  );
-
-  return server;
-}
+        });
+        if (background) {
+          const started = flowRunStore.start(async () => {
+            try {
+              return fitToolResponse(await execute(), Math.floor(settings.browser.maxToolResponseBytes * 0.8));
+            } catch (error) {
+              throw new Error(safeErrorMessage(error, settings));
+            }
+          });
+          return toolText(started, settings.browser.maxToolResponseBytes);
+        }
+        return toolText(await execute(), settings.browser.maxToolResponseBytes);
+      } catch (error) {
+        return toolError(error, settings);
+      }
+    },
+  );
+
+  server.registerTool(
+    "run_test_suite",
+    {
+      description: "Run a validated JSON suite from .jev-browser/suites/<suite_name>.json sequentially, retaining the browser and integration session across setup, acceptance criteria and always-attempted teardown. Produces a Markdown evidence report and cleans project-local fixtures after teardown. Set background=true to poll the long run with get_browser_flow_result.",
+      inputSchema: {
+        suite_name: z.string().min(1).max(80),
+        params: z.record(z.string(), z.unknown()).optional(),
+        environment_profile: z.string().min(1).max(48).optional(),
+        report_path: z.string().min(1).max(2048).optional(),
+        background: z.boolean().optional(),
+      },
+    },
+    async ({ suite_name: suiteName, params, environment_profile: environmentProfile, report_path: reportPath, background = false }) => {
+      try {
+        const execute = () => browserPool.runFlow(() => executeTestSuite({
+          suiteName,
+          params,
+          environmentProfile,
+          reportPath,
+          settings,
+          browserPool,
+          fetchImpl,
+          serverVersion: packageManifest.version,
+          mutationAuthorizationStore,
+          executeFlow: executeBrowserFlow,
+        }));
+        if (background) {
+          const started = flowRunStore.start(async () => {
+            try { return fitToolResponse(await execute(), Math.floor(settings.browser.maxToolResponseBytes * 0.8)); }
+            catch (error) { throw new Error(safeErrorMessage(error, settings)); }
+          });
+          return toolText(started, settings.browser.maxToolResponseBytes);
+        }
+        return toolText(await execute(), settings.browser.maxToolResponseBytes);
+      } catch (error) {
+        return toolError(error, settings);
+      }
+    },
+  );
+
+  server.registerTool(
+    "get_browser_flow_result",
+    {
+      description: "Poll a background run_browser_flow call. Set wait_ms up to 30000 to long-poll; completed results are retained for 30 minutes in this MCP process.",
+      inputSchema: {
+        run_id: z.string().min(1),
+        wait_ms: z.number().int().min(0).max(30000).optional(),
+      },
+    },
+    async ({ run_id: runId, wait_ms: waitMs = 0 }) => {
+      const result = await flowRunStore.get(runId, waitMs);
+      if (!result) return toolError(new JevBrowserError("background flow run was not found or its result expired"), settings);
+      return toolText(result, settings.browser.maxToolResponseBytes);
+    },
+  );
+
+  return server;
+}
 
-export async function closeBrowserSessions() {
-  await Promise.all([...browserPools].map((pool) => pool.close()));
-  browserPools.clear();
-}
+export async function closeBrowserSessions() {
+  try {
+    await Promise.all([...browserPools].map(async ([pool, settings]) => {
+      try {
+        await pool.close();
+      } finally {
+        await cleanupUploadStagingDirectory(settings);
+      }
+    }));
+  } finally {
+    browserPools.clear();
+  }
+}
 
 export function installConfiguredBrowser({ env = process.env } = {}) {
   const settings = loadSettings({ env });