@diegosouzacdv/jev-browser-mcp 0.6.1 → 0.7.0

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

@@ -7,21 +7,101 @@ 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, createMutationAuthorizationStore, executeBrowserFlow } from "./flow.mjs";
-
-const browserPools = new Set();
+import { loadSettings, JevBrowserError } from "./config.mjs";
+import { chooseNextAction, createMutationAuthorizationStore, describeBrowserActions, executeBrowserFlow } from "./flow.mjs";
+
+const browserContract = describeBrowserActions();
+const actionNames = Object.keys(browserContract.actions);
+const jsonObject = z.record(z.string(), z.unknown());
+function browserStepFieldSchema(field) {
+  if (["mutating", "screenshot", "expect_download", "expect_popup", "blur", "sensitive", "full_page"].includes(field)) return z.boolean();
+  if (["timeout_ms", "timeout_seconds"].includes(field)) return z.number().positive();
+  if (["index", "context_index", "ms", "duration_ms", "status", "close_code"].includes(field)) return z.number().int();
+  if (field === "file_paths") return z.union([z.string(), z.array(z.string())]);
+  if (["near", "within", "if_visible", "json"].includes(field)) return jsonObject;
+  if (field === "name_match") return z.enum(["exact", "contains", "regex"]);
+  if (field === "condition") return z.enum(["network_idle", "angular_idle", "url", "hidden"]);
+  if (field === "standard") return z.enum(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa", "section508"]);
+  return z.string();
+}
+function browserStepVariant(action, contract, aliases = []) {
+  const required = new Set(contract.required);
+  const optional = new Set([...contract.optional, "timeout_ms", "mutating", "screenshot", ...aliases]);
+  if (action === "wait") { required.delete("ms"); optional.add("ms"); }
+  if (action === "wait_for_text") { required.delete("text"); optional.add("text"); }
+  if (action === "assert_text" || action === "assert_value") { required.delete("expected"); optional.add("expected"); }
+  if (action === "upload_file") { required.delete("file_paths"); optional.add("file_paths"); }
+  if (action === "wait") optional.add("duration_ms");
+  if (action === "wait_for_text" || action === "assert_text" || action === "assert_value") optional.add("value");
+  if (action === "upload_file") optional.add("file_path");
+  if (action === "confirm_modal") {
+    required.delete("button");
+    optional.add("button");
+    optional.add("trigger");
+    optional.add("confirm");
+  }
+  const shape = { action: z.literal(action) };
+  for (const key of new Set([...required, ...optional])) {
+    const field = browserStepFieldSchema(key);
+    shape[key] = required.has(key) ? field : field.optional();
+  }
+  return z.object(shape).strict();
+}
+const browserStepVariants = Object.entries(browserContract.actions).map(([action, contract]) => browserStepVariant(action, contract));
+browserStepVariants.push(
+  browserStepVariant("fill", browserContract.actions.type, ["value"]),
+  browserStepVariant("press_key", browserContract.actions.press),
+);
+const browserStepSchema = z.discriminatedUnion("action", browserStepVariants);
+const candidatePlanSchema = z.object({
+  description: z.string(),
+  steps: z.array(browserStepSchema).min(1),
+  comment: z.string().optional(),
+  when: z.object({ visible: z.string() }).strict().optional(),
+}).strict();
+const browserOptionsShape = Object.fromEntries(browserContract.options.map((key) => {
+  const value = key === "return_snapshot" ? z.enum(["diff", "full", "none"])
+    : key === "reuse_page_match" ? z.enum(["url", "path"])
+      : key === "color_scheme" ? z.enum(["light", "dark", "no-preference"])
+        : key === "permissions" ? z.array(z.enum(["microphone", "geolocation"]))
+          : 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()
+                  : ["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();
+  return [key, value.optional()];
+}));
+const browserOptionsSchema = z.object(browserOptionsShape).passthrough();
+const expectedOutcomeSchema = z.union([
+  z.string(),
+  z.object({
+    text: z.string().optional(),
+    request: z.string().optional(),
+    method: z.string().optional(),
+    status: z.number().int().min(100).max(599).optional(),
+    message_contains: z.string().optional(),
+  }).strict().refine((value) => Boolean(value.text || value.request), "expected_outcome needs text or request"),
+]);
+
+const browserPools = new Set();
 
 class BrowserPool {
   #settings;
   #contextPromise;
   #context;
-  #browser;
+  #browser;
+  #extraContexts = new Set();
+  #extraBrowsers = new Set();
+  #contextBrowsers = new Map();
   #page;
   #startedAt;
   #everStarted = false;
   #navigationError;
-  #flowQueue = Promise.resolve();
+  #flowQueue = Promise.resolve();
+  #configurationKey;
+  #lastConfiguration = {};
 
   constructor(settings) {
     this.#settings = settings;
@@ -47,12 +127,17 @@ class BrowserPool {
     }
   }
 
-  async getPage() {
-    let isOpening = !this.#contextPromise;
-    if (isOpening) {
-      this.#everStarted = true;
-      this.#startedAt = performance.now();
-      this.#contextPromise = this.#open();
+  async getPage(configuration) {
+    if (configuration === undefined) configuration = this.#lastConfiguration;
+    else this.#lastConfiguration = configuration;
+    const configurationKey = JSON.stringify(configuration);
+    if (this.#contextPromise && this.#configurationKey !== configurationKey) await this.close();
+    let isOpening = !this.#contextPromise;
+    if (isOpening) {
+      this.#everStarted = true;
+      this.#startedAt = performance.now();
+      this.#configurationKey = configurationKey;
+      this.#contextPromise = this.#open(configuration);
     }
     try {
       await this.#contextPromise;
@@ -64,7 +149,8 @@ class BrowserPool {
       if (!isOpening) {
         isOpening = true;
         this.#startedAt = performance.now();
-        this.#contextPromise = this.#open();
+        this.#configurationKey = configurationKey;
+        this.#contextPromise = this.#open(configuration);
         await this.#contextPromise;
       } else {
         throw error;
@@ -93,18 +179,61 @@ class BrowserPool {
     }
   }
 
-  async restart() {
+  async restart() {
     await this.close();
     this.#everStarted = true;
     this.#startedAt = performance.now();
-    this.#contextPromise = this.#open();
+    this.#contextPromise = this.#open(this.#lastConfiguration);
     try {
       await this.#contextPromise;
       return { status: "connected", connected: true, recovered: true, restarted: true, current_url: this.#page.url() };
     } catch (error) {
       return { status: "disconnected", connected: false, restarted: true, reason: error?.message || error?.name || "browser unavailable" };
     }
-  }
+  }
+
+  async replaceClosedPage(page) {
+    if (this.#page !== page || !this.#context) return;
+    this.#page = this.#context.pages()[0] || await this.#context.newPage();
+  }
+
+  async createIsolatedContext(contextOptions = {}, launchArgs = []) {
+    let browser = this.#browser;
+    let ownsBrowser = false;
+    if (!browser) {
+      browser = await chromium.launch({
+        channel: this.#settings.browser.channel,
+        headless: this.#settings.browser.mode !== "computer",
+        args: launchArgs,
+      });
+      ownsBrowser = true;
+    }
+    try {
+      const context = await browser.newContext(contextOptions);
+      this.#extraContexts.add(context);
+      this.#contextBrowsers.set(context, { browser, ownsBrowser });
+      context.once("close", () => this.#extraContexts.delete(context));
+      if (ownsBrowser) {
+        this.#extraBrowsers.add(browser);
+        browser.once("disconnected", () => this.#extraBrowsers.delete(browser));
+      }
+      return context;
+    } catch (error) {
+      if (ownsBrowser) await browser.close().catch(() => {});
+      throw error;
+    }
+  }
+
+  async releaseContext(context) {
+    const ownership = this.#contextBrowsers.get(context);
+    await context?.close().catch(() => {});
+    this.#extraContexts.delete(context);
+    this.#contextBrowsers.delete(context);
+    if (ownership?.ownsBrowser) {
+      await ownership.browser.close().catch(() => {});
+      this.#extraBrowsers.delete(ownership.browser);
+    }
+  }
 
   #watchContext(context, browser) {
     context.once("close", () => {
@@ -115,19 +244,22 @@ class BrowserPool {
     });
   }
 
-  async #open() {
-    const { mode, channel, profileDir } = this.#settings.browser;
+  async #open({ contextOptions = {}, launchArgs = [], profileDir: configuredProfileDir } = {}) {
+    const { mode, channel } = this.#settings.browser;
+    const profileDir = configuredProfileDir || this.#settings.browser.profileDir;
     try {
       if (mode === "computer") {
-        this.#context = await chromium.launchPersistentContext(profileDir, {
-          channel,
-          headless: false,
-        });
+        this.#context = await chromium.launchPersistentContext(profileDir, {
+          channel,
+          headless: false,
+          args: launchArgs,
+          ...contextOptions,
+        });
         this.#watchContext(this.#context);
         this.#page = this.#context.pages()[0] || await this.#context.newPage();
       } else {
-        this.#browser = await chromium.launch({ channel, headless: true });
-        this.#context = await this.#browser.newContext();
+        this.#browser = await chromium.launch({ channel, headless: true, args: launchArgs });
+        this.#context = await this.#browser.newContext(contextOptions);
         this.#watchContext(this.#context, this.#browser);
         this.#page = await this.#context.newPage();
       }
@@ -144,14 +276,20 @@ class BrowserPool {
     }
   }
 
-  async close() {
+  async close() {
+    await Promise.all([...this.#extraContexts].map((context) => this.releaseContext(context)));
+    await Promise.all([...this.#extraBrowsers].map((browser) => browser.close().catch(() => {})));
+    this.#extraContexts.clear();
+    this.#extraBrowsers.clear();
+    this.#contextBrowsers.clear();
     if (this.#context) await this.#context.close().catch(() => {});
     if (this.#browser) await this.#browser.close().catch(() => {});
     this.#context = undefined;
     this.#browser = undefined;
     this.#page = undefined;
-    this.#contextPromise = undefined;
-    this.#navigationError = undefined;
+    this.#contextPromise = undefined;
+    this.#navigationError = undefined;
+    this.#configurationKey = undefined;
   }
 }
 
@@ -164,11 +302,46 @@ function toolError(error, settings) {
   return { isError: true, content: [{ type: "text", text: `[jev-browser ${packageManifest.version}] ${message}` }] };
 }
 
-function toolText(value) {
-  const versioned = value && typeof value === "object" && !Array.isArray(value)
-    ? { ...value, server_version: packageManifest.version }
-    : { result: value, server_version: packageManifest.version };
-  return { content: [{ type: "text", text: JSON.stringify(versioned) }] };
+export function fitToolResponse(value, maxBytes) {
+  const clone = structuredClone(value && typeof value === "object" ? value : { result: value });
+  const measure = () => Buffer.byteLength(JSON.stringify(clone), "utf8");
+  if (measure() <= maxBytes) return clone;
+  clone.output_truncated = true;
+  delete clone.unnamed_controls;
+  if (typeof clone.final_snapshot === "string") clone.final_snapshot = "[snapshot omitted to fit the configured MCP response limit]";
+  for (const key of ["unnamed_controls_initial", "unnamed_controls_final"]) {
+    if (Array.isArray(clone[key])) clone[key] = clone[key].map(({ role, index, nearest_label }) => ({ role, index, nearest_label }));
+  }
+  for (const key of ["console_errors", "network_failures", "warnings"]) {
+    if (Array.isArray(clone[key])) clone[key] = clone[key].slice(-10);
+  }
+  for (const step of clone.steps || []) {
+    delete step.html;
+    if (typeof step.error === "string") step.error = step.error.slice(0, 300);
+  }
+  while (measure() > maxBytes) {
+    if (Array.isArray(clone.steps) && clone.steps.length > 4) clone.steps.splice(1, clone.steps.length - 4);
+    else if (Array.isArray(clone.network_failures) && clone.network_failures.length) clone.network_failures.shift();
+    else if (Array.isArray(clone.console_errors) && clone.console_errors.length) clone.console_errors.shift();
+    else if (Array.isArray(clone.warnings) && clone.warnings.length) clone.warnings.shift();
+    else break;
+  }
+  if (measure() <= maxBytes) return clone;
+  return {
+    ...(clone.server_version ? { server_version: clone.server_version } : {}),
+    status: clone.status || "failed",
+    output_truncated: true,
+    ...(clone.reason ? { reason: String(clone.reason).slice(0, 300) } : {}),
+    ...(Number.isSafeInteger(clone.steps_executed) ? { steps_executed: clone.steps_executed } : {}),
+  };
+}
+
+function toolText(value, maxBytes) {
+  const versioned = value && typeof value === "object" && !Array.isArray(value)
+    ? { ...value, server_version: packageManifest.version }
+    : { result: value, server_version: packageManifest.version };
+  const bounded = maxBytes ? fitToolResponse(versioned, maxBytes) : versioned;
+  return { content: [{ type: "text", text: JSON.stringify(bounded) }] };
 }
 
 export function profileOwnerPidFromProcessList(processes, profileDir, platform = process.platform) {
@@ -242,8 +415,33 @@ export function createJevBrowserServer({ env = process.env, configPath, fetchImp
       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 } = {}) => toolText(restart ? await browserPool.restart() : await browserPool.health()),
-  );
+    async ({ restart = false } = {}) => {
+      const health = restart ? await browserPool.restart() : await browserPool.health();
+      return toolText({
+        ...health,
+        server_version: packageManifest.version,
+        browser_mode: settings.browser.mode,
+        session_id: settings.browser.sessionId,
+        capabilities: {
+          actions: Object.keys(describeBrowserActions().actions),
+          options: describeBrowserActions().options,
+          media_permissions: ["microphone", "geolocation"],
+          fake_media: "WAV audio input",
+          storage_state: "named account snapshots",
+          contexts: ["current", "new isolated context"],
+        },
+      }, settings.browser.maxToolResponseBytes);
+    },
+  );
+
+  server.registerTool(
+    "describe_actions",
+    {
+      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),
+  );
 
   server.registerTool(
     "choose_next_action",
@@ -259,29 +457,32 @@ export function createJevBrowserServer({ env = process.env, configPath, fetchImp
     },
     async ({ flow, page_snapshot: pageSnapshot, actions, completed_steps: completedSteps, local_only: localOnly }) => {
       try {
-        return toolText(await chooseNextAction({ flow, pageSnapshot, actions, completedSteps, localOnly, settings, fetchImpl }));
+        return toolText(
+          await chooseNextAction({ flow, pageSnapshot, actions, completedSteps, localOnly, settings, fetchImpl }),
+          settings.browser.maxToolResponseBytes,
+        );
       } catch (error) {
         return toolError(error, settings);
       }
     },
   );
 
-  server.registerTool(
-    "run_browser_flow",
-    {
-      description: "Run a bounded screen flow in a warm Playwright session. Continues the current same-origin page by default without repeating navigation. Supports role and label locators, exact row scopes, guarded dialog confirmation, network assertions, variables and extraction, AngularJS idle waits, field-value/enabled waits, dry runs before mutating steps, per-step timing and screenshots, Markdown/JUnit reports, uploads, downloads, accessibility audits, and clear navigation diagnostics. Jev chooses among supplied plans; one plan skips the decision call when fast_path is enabled.",
-      inputSchema: {
-        flow: z.string(),
-        initial_url: z.string(),
-        expected_outcome: z.string(),
-        candidate_plans: z.record(z.string(), z.unknown()),
-        params: z.record(z.string(), z.unknown()).optional(),
-        options: z.record(z.string(), z.unknown()).optional(),
-      },
+  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.",
+      inputSchema: {
+        flow: z.string(),
+        initial_url: z.string().optional(),
+        expected_outcome: expectedOutcomeSchema.optional(),
+        candidate_plans: z.record(z.string(), candidatePlanSchema),
+        params: z.record(z.string(), z.unknown()).optional(),
+        options: browserOptionsSchema.optional(),
+      },
     },
     async ({ flow, initial_url: initialUrl, expected_outcome: expectedOutcome, candidate_plans: candidatePlans, params, options }) => {
       try {
-        return toolText(await browserPool.runFlow(async () => {
+        return toolText(await browserPool.runFlow(async () => {
           const args = {
           flow,
           initialUrl,
@@ -302,7 +503,7 @@ export function createJevBrowserServer({ env = process.env, configPath, fetchImp
           if (!recovery.connected) return { ...first, browser_restart: recovery, retry_count: 0 };
           const retry = await executeBrowserFlow({ ...args, options: { ...options, reuse_page: false } });
           return { ...retry, browser_restart: recovery, retry_count: 1 };
-        }));
+        }), settings.browser.maxToolResponseBytes);
       } catch (error) {
         return toolError(error, settings);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegosouzacdv/jev-browser-mcp",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Portable MCP server for bounded Playwright screen flows selected by Jev",
   "license": "MIT",
   "repository": {