@diegosouzacdv/jev-browser-mcp 0.1.0

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

@@ -0,0 +1,206 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+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, executeBrowserFlow } from "./flow.mjs";
+
+const browserPools = new Set();
+
+class BrowserPool {
+  #settings;
+  #contextPromise;
+  #context;
+  #browser;
+  #page;
+  #startedAt;
+  #flowQueue = Promise.resolve();
+
+  constructor(settings) {
+    this.#settings = settings;
+  }
+
+  async runFlow(work) {
+    const previous = this.#flowQueue;
+    let release;
+    this.#flowQueue = new Promise((resolve) => { release = resolve; });
+    await previous;
+    try {
+      return await work();
+    } finally {
+      release();
+    }
+  }
+
+  async getPage() {
+    if (this.#page?.isClosed() && this.#context) {
+      this.#page = this.#context.pages()[0] || await this.#context.newPage();
+    }
+    const isOpening = !this.#contextPromise;
+    if (isOpening) {
+      this.#startedAt = performance.now();
+      this.#contextPromise = this.#open();
+    }
+    await this.#contextPromise;
+    return { page: this.#page, sessionMs: isOpening ? performance.now() - this.#startedAt : 0 };
+  }
+
+  async #open() {
+    const { mode, channel, profileDir } = this.#settings.browser;
+    try {
+      if (mode === "computer") {
+        this.#context = await chromium.launchPersistentContext(profileDir, {
+          channel,
+          headless: false,
+        });
+        this.#page = this.#context.pages()[0] || await this.#context.newPage();
+      } else {
+        this.#browser = await chromium.launch({ channel, headless: true });
+        this.#page = await this.#browser.newPage();
+        this.#context = this.#page.context();
+      }
+    } catch (error) {
+      this.#contextPromise = undefined;
+      throw new JevBrowserError(
+        `Could not start the configured ${channel} browser (${error?.name || "BrowserError"}); install it with jev-browser-mcp --install-browser`,
+      );
+    }
+  }
+
+  async close() {
+    try {
+      if (this.#context) await this.#context.close();
+      else if (this.#browser) await this.#browser.close();
+    } catch {
+      // The host may already have closed the process during shutdown.
+    }
+    this.#context = undefined;
+    this.#browser = undefined;
+    this.#page = undefined;
+    this.#contextPromise = undefined;
+  }
+}
+
+function toolError(error) {
+  const message = error instanceof JevBrowserError ? error.message : `Jev browser flow failed (${error?.name || "Error"})`;
+  return { isError: true, content: [{ type: "text", text: message }] };
+}
+
+function toolText(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+
+export function createJevBrowserServer({ env = process.env, configPath, fetchImpl = fetch } = {}) {
+  const settings = loadSettings({ env, ...(configPath ? { configPath } : {}) });
+  const browserPool = new BrowserPool(settings);
+  browserPools.add(browserPool);
+  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.registerTool(
+    "choose_next_action",
+    {
+      description: "Ask Jev to select one candidate browser action from the current UI snapshot and full flow. Returns the selected ID; the harness executes it through separately authorized calls.",
+      inputSchema: {
+        flow: z.string(),
+        page_snapshot: z.string(),
+        actions: z.record(z.string(), z.string()),
+        completed_steps: z.array(z.string()).optional(),
+      },
+    },
+    async ({ flow, page_snapshot: pageSnapshot, actions, completed_steps: completedSteps }) => {
+      try {
+        return toolText(await chooseNextAction({ flow, pageSnapshot, actions, completedSteps, settings, fetchImpl }));
+      } catch (error) {
+        return toolError(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "run_browser_flow",
+    {
+      description: "Run a bounded screen flow in one warm Playwright browser session. Jev chooses one supplied plan once, the MCP executes accessible-name actions and verifies the requested outcome.",
+      inputSchema: {
+        flow: z.string(),
+        initial_url: z.string(),
+        expected_outcome: z.string(),
+        candidate_plans: z.record(z.string(), z.unknown()),
+      },
+    },
+    async ({ flow, initial_url: initialUrl, expected_outcome: expectedOutcome, candidate_plans: candidatePlans }) => {
+      try {
+        return toolText(await browserPool.runFlow(() => executeBrowserFlow({
+          flow,
+          initialUrl,
+          expectedOutcome,
+          candidatePlans,
+          settings,
+          browserPool,
+          fetchImpl,
+        })));
+      } catch (error) {
+        return toolError(error);
+      }
+    },
+  );
+
+  return server;
+}
+
+export async function closeBrowserSessions() {
+  await Promise.all([...browserPools].map((pool) => pool.close()));
+  browserPools.clear();
+}
+
+export function installConfiguredBrowser({ env = process.env } = {}) {
+  const settings = loadSettings({ env });
+  if (settings.browser.mode === "computer") {
+    process.stderr.write("Computer mode uses the installed Chrome or Edge; no browser download is needed.\n");
+    return 0;
+  }
+  const entryPath = fileURLToPath(import.meta.resolve("playwright"));
+  const cliPath = path.join(path.dirname(entryPath), "cli.js");
+  const install = spawnSync(process.execPath, [cliPath, "install", settings.browser.channel], { stdio: "inherit" });
+  return install.status ?? 1;
+}
+
+export function runStdioServer() {
+  const handle = serveStdio(() => createJevBrowserServer());
+  const removeSignalHandlers = () => {
+    process.removeListener("SIGINT", onInterrupt);
+    process.removeListener("SIGTERM", onTerminate);
+  };
+  const shutdown = async () => {
+    removeSignalHandlers();
+    await handle.close();
+    await closeBrowserSessions();
+  };
+  const onInterrupt = () => { void shutdown(); };
+  const onTerminate = () => { void shutdown(); };
+  const onInputClosed = () => {
+    removeSignalHandlers();
+    void closeBrowserSessions();
+  };
+  process.once("SIGINT", onInterrupt);
+  process.once("SIGTERM", onTerminate);
+  process.stdin.once("end", onInputClosed);
+  process.stdin.once("close", onInputClosed);
+  return handle;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@diegosouzacdv/jev-browser-mcp",
+  "version": "0.1.0",
+  "description": "Portable MCP server for bounded Playwright screen flows selected by Jev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diegosouzacdv/orquestrador.git"
+  },
+  "homepage": "https://github.com/diegosouzacdv/orquestrador/tree/main/docs/jev-browser-mcp.md",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "jev-browser-mcp": "mcp_servers/jev-browser-npm/bin/jev-browser-mcp.cjs"
+  },
+  "exports": {
+    "./server": "./mcp_servers/jev-browser-npm/src/server.mjs"
+  },
+  "files": [
+    "config/ui-testing.json",
+    "docs/jev-browser-mcp.md",
+    "mcp_servers/jev-browser-npm/bin/**",
+    "mcp_servers/jev-browser-npm/src/**"
+  ],
+  "scripts": {
+    "test:jev-browser-mcp": "node --test mcp_servers/jev-browser-npm/tests/*.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.1.0",
+    "playwright": "1.63.0",
+    "zod": "4.6.5"
+  }
+}