@tontoko/fast-playwright-mcp 0.0.4

package/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import './lib/program.js';

package/config.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type * as playwright from 'playwright';
+
+export type ToolCapability =
+  | 'core'
+  | 'core-tabs'
+  | 'core-install'
+  | 'vision'
+  | 'pdf';
+
+export type Config = {
+  /**
+   * The browser to use.
+   */
+  browser?: {
+    /**
+     * The type of browser to use.
+     */
+    browserName?: 'chromium' | 'firefox' | 'webkit';
+
+    /**
+     * Keep the browser profile in memory, do not save it to disk.
+     */
+    isolated?: boolean;
+
+    /**
+     * Path to a user data directory for browser profile persistence.
+     * Temporary directory is created by default.
+     */
+    userDataDir?: string;
+
+    /**
+     * Launch options passed to
+     * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
+     *
+     * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
+     */
+    launchOptions?: playwright.LaunchOptions;
+
+    /**
+     * Context options for the browser context.
+     *
+     * This is useful for settings options like `viewport`.
+     */
+    contextOptions?: playwright.BrowserContextOptions;
+
+    /**
+     * Chrome DevTools Protocol endpoint to connect to an existing browser instance in case of Chromium family browsers.
+     */
+    cdpEndpoint?: string;
+
+    /**
+     * Remote endpoint to connect to an existing Playwright server.
+     */
+    remoteEndpoint?: string;
+  };
+
+  server?: {
+    /**
+     * The port to listen on for SSE or MCP transport.
+     */
+    port?: number;
+
+    /**
+     * The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
+     */
+    host?: string;
+  };
+
+  /**
+   * List of enabled tool capabilities. Possible values:
+   *   - 'core': Core browser automation features.
+   *   - 'pdf': PDF generation and manipulation.
+   *   - 'vision': Coordinate-based interactions.
+   */
+  capabilities?: ToolCapability[];
+
+  /**
+   * Whether to save the Playwright session into the output directory.
+   */
+  saveSession?: boolean;
+
+  /**
+   * Whether to save the Playwright trace of the session into the output directory.
+   */
+  saveTrace?: boolean;
+
+  /**
+   * The directory to save output files.
+   */
+  outputDir?: string;
+
+  network?: {
+    /**
+     * List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     */
+    allowedOrigins?: string[];
+
+    /**
+     * List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     */
+    blockedOrigins?: string[];
+  };
+
+  /**
+   * Whether to send image responses to the client. Can be "allow", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.
+   */
+  imageResponses?: 'allow' | 'omit';
+};

package/index.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Config } from './config.js';
+import type { BrowserContext } from 'playwright';
+
+export declare function createConnection(
+  config?: Config,
+  contextGetter?: () => Promise<BrowserContext>
+): Promise<Server>;

package/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { createConnection } from './lib/index.js';

package/lib/batch/batch-executor.js

@@ -0,0 +1,137 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/batch/batch-executor.ts
+import { Response } from "../response.js";
+import { mergeExpectations } from "../schemas/expectation.js";
+import { getErrorMessage } from "../utils/common-formatters.js";
+
+class BatchExecutor {
+  toolRegistry;
+  context;
+  constructor(context, toolRegistry) {
+    this.context = context;
+    this.toolRegistry = toolRegistry;
+  }
+  validateAllSteps(steps) {
+    for (const [index, step] of steps.entries()) {
+      const tool = this.toolRegistry.get(step.tool);
+      if (!tool) {
+        throw new Error(`Unknown tool: ${step.tool}`);
+      }
+      try {
+        const parseResult = tool.schema.inputSchema.safeParse({
+          ...step.arguments,
+          expectation: step.expectation
+        });
+        if (!parseResult.success) {
+          throw new Error(`Invalid arguments: ${parseResult.error.message}`);
+        }
+      } catch (error) {
+        throw new Error(`Invalid arguments for ${step.tool} at step ${index}: ${getErrorMessage(error)}`);
+      }
+    }
+  }
+  async execute(options) {
+    const results = [];
+    const startTime = Date.now();
+    let stopReason = "completed";
+    this.validateAllSteps(options.steps);
+    const executeSequentially = async (index) => {
+      if (index >= options.steps.length) {
+        return;
+      }
+      const step = options.steps[index];
+      const stepStartTime = Date.now();
+      try {
+        const result = await this.executeStep(step, options.globalExpectation);
+        const stepEndTime = Date.now();
+        results.push({
+          stepIndex: index,
+          toolName: step.tool,
+          success: true,
+          result,
+          executionTimeMs: stepEndTime - stepStartTime
+        });
+        await executeSequentially(index + 1);
+      } catch (error) {
+        const stepEndTime = Date.now();
+        const errorMessage = getErrorMessage(error);
+        results.push({
+          stepIndex: index,
+          toolName: step.tool,
+          success: false,
+          error: errorMessage,
+          executionTimeMs: stepEndTime - stepStartTime
+        });
+        if (!step.continueOnError) {
+          stopReason = "error";
+          return;
+        }
+        await executeSequentially(index + 1);
+      }
+    };
+    await executeSequentially(0);
+    const totalExecutionTime = Date.now() - startTime;
+    const successfulSteps = results.filter((r) => r.success).length;
+    const failedSteps = results.filter((r) => !r.success).length;
+    return {
+      steps: results,
+      totalSteps: options.steps.length,
+      successfulSteps,
+      failedSteps,
+      totalExecutionTimeMs: totalExecutionTime,
+      stopReason
+    };
+  }
+  async executeStep(step, globalExpectation) {
+    const tool = this.toolRegistry.get(step.tool);
+    if (!tool) {
+      throw new Error(`Unknown tool: ${step.tool}`);
+    }
+    const mergedExpectation = this.mergeStepExpectations(step.tool, globalExpectation, step.expectation);
+    const argsWithExpectation = {
+      ...step.arguments,
+      expectation: mergedExpectation
+    };
+    const response = new Response(this.context, step.tool, argsWithExpectation, mergedExpectation);
+    await tool.handle(this.context, argsWithExpectation, response);
+    await response.finish();
+    return response.serialize();
+  }
+  mergeStepExpectations(toolName, globalExpectation, stepExpectation) {
+    let merged = mergeExpectations(toolName);
+    if (globalExpectation) {
+      merged = mergeExpectations(toolName, {
+        ...merged,
+        ...globalExpectation
+      });
+    }
+    if (stepExpectation) {
+      merged = mergeExpectations(toolName, {
+        ...merged,
+        ...stepExpectation
+      });
+    }
+    return merged;
+  }
+}
+export {
+  BatchExecutor
+};

package/lib/browser-context-factory.js

@@ -0,0 +1,252 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/browser-context-factory.ts
+import { promises as fsPromises } from "node:fs";
+import { createServer } from "node:net";
+import { join as pathJoin } from "node:path";
+import debug from "debug";
+import {
+  chromium,
+  firefox,
+  webkit
+} from "playwright";
+import { registryDirectory } from "playwright-core/lib/server/registry/index";
+import { outputFile } from "./config.js";
+import { logUnhandledError, testDebug } from "./log.js";
+import { createHash } from "./utils.js";
+var browserDebug = debug("pw:mcp:browser");
+function getBrowserType(browserName) {
+  switch (browserName) {
+    case "chromium":
+      return chromium;
+    case "firefox":
+      return firefox;
+    case "webkit":
+      return webkit;
+    default:
+      throw new Error(`Unsupported browser: ${browserName}`);
+  }
+}
+function contextFactory(config) {
+  if (config.browser.remoteEndpoint) {
+    return new RemoteContextFactory(config);
+  }
+  if (config.browser.cdpEndpoint) {
+    return new CdpContextFactory(config);
+  }
+  if (config.browser.isolated) {
+    return new IsolatedContextFactory(config);
+  }
+  return new PersistentContextFactory(config);
+}
+
+class BaseContextFactory {
+  name;
+  description;
+  config;
+  _browserPromise;
+  _tracesDir;
+  constructor(name, description, config) {
+    this.name = name;
+    this.description = description;
+    this.config = config;
+  }
+  _obtainBrowser() {
+    if (this._browserPromise) {
+      return this._browserPromise;
+    }
+    testDebug(`obtain browser (${this.name})`);
+    this._browserPromise = this._doObtainBrowser();
+    this._browserPromise.then((browser) => {
+      browser.on("disconnected", () => {
+        this._browserPromise = undefined;
+      });
+    }).catch((error) => {
+      browserDebug("Browser connection failed:", error);
+      this._browserPromise = undefined;
+    });
+    return this._browserPromise;
+  }
+  _doObtainBrowser() {
+    throw new Error("Not implemented");
+  }
+  async createContext(clientInfo) {
+    if (this.config.saveTrace) {
+      this._tracesDir = await outputFile(this.config, clientInfo.rootPath, `traces-${Date.now()}`);
+    }
+    testDebug(`create browser context (${this.name})`);
+    const browser = await this._obtainBrowser();
+    const browserContext = await this._doCreateContext(browser);
+    return {
+      browserContext,
+      close: () => this._closeBrowserContext(browserContext, browser)
+    };
+  }
+  _doCreateContext(_browser) {
+    throw new Error("Not implemented");
+  }
+  async _closeBrowserContext(browserContext, browser) {
+    testDebug(`close browser context (${this.name})`);
+    if (browser.contexts().length === 1) {
+      this._browserPromise = undefined;
+    }
+    await browserContext.close().catch(logUnhandledError);
+    if (browser.contexts().length === 0) {
+      testDebug(`close browser (${this.name})`);
+      await browser.close().catch(logUnhandledError);
+    }
+  }
+}
+
+class IsolatedContextFactory extends BaseContextFactory {
+  constructor(config) {
+    super("isolated", "Create a new isolated browser context", config);
+  }
+  async _doObtainBrowser() {
+    await injectCdpPort(this.config.browser);
+    const browserType = getBrowserType(this.config.browser.browserName);
+    return browserType.launch({
+      tracesDir: this._tracesDir,
+      ...this.config.browser.launchOptions,
+      handleSIGINT: false,
+      handleSIGTERM: false
+    }).catch((error) => {
+      if (error.message.includes("Executable doesn't exist")) {
+        throw new Error("Browser specified in your config is not installed. Either install it (likely) or change the config.");
+      }
+      throw error;
+    });
+  }
+  _doCreateContext(browser) {
+    return browser.newContext(this.config.browser.contextOptions);
+  }
+}
+
+class CdpContextFactory extends BaseContextFactory {
+  constructor(config) {
+    super("cdp", "Connect to a browser over CDP", config);
+  }
+  _doObtainBrowser() {
+    return chromium.connectOverCDP(this.config.browser.cdpEndpoint);
+  }
+  async _doCreateContext(browser) {
+    return this.config.browser.isolated ? await browser.newContext() : browser.contexts()[0];
+  }
+}
+
+class RemoteContextFactory extends BaseContextFactory {
+  constructor(config) {
+    super("remote", "Connect to a browser using a remote endpoint", config);
+  }
+  _doObtainBrowser() {
+    const url = new URL(this.config.browser.remoteEndpoint);
+    url.searchParams.set("browser", this.config.browser.browserName);
+    if (this.config.browser.launchOptions) {
+      url.searchParams.set("launch-options", JSON.stringify(this.config.browser.launchOptions));
+    }
+    return getBrowserType(this.config.browser.browserName).connect(String(url));
+  }
+  _doCreateContext(browser) {
+    return browser.newContext();
+  }
+}
+
+class PersistentContextFactory {
+  config;
+  name = "persistent";
+  description = "Create a new persistent browser context";
+  _userDataDirs = new Set;
+  constructor(config) {
+    this.config = config;
+  }
+  async createContext(clientInfo) {
+    await injectCdpPort(this.config.browser);
+    testDebug("create browser context (persistent)");
+    const userDataDir = this.config.browser.userDataDir ?? await this._createUserDataDir(clientInfo.rootPath);
+    let tracesDir;
+    if (this.config.saveTrace) {
+      tracesDir = await outputFile(this.config, clientInfo.rootPath, `traces-${Date.now()}`);
+    }
+    this._userDataDirs.add(userDataDir);
+    testDebug("lock user data dir", userDataDir);
+    const browserType = getBrowserType(this.config.browser.browserName);
+    const launchWithRetry = async (attempt) => {
+      if (attempt >= 5) {
+        throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
+      }
+      try {
+        const browserContext = await browserType.launchPersistentContext(userDataDir, {
+          tracesDir,
+          ...this.config.browser.launchOptions,
+          ...this.config.browser.contextOptions,
+          handleSIGINT: false,
+          handleSIGTERM: false
+        });
+        const close = () => this._closeBrowserContext(browserContext, userDataDir);
+        return { browserContext, close };
+      } catch (error) {
+        if (error instanceof Error && error.message.includes("Executable doesn't exist")) {
+          throw new Error("Browser specified in your config is not installed. Either install it (likely) or change the config.");
+        }
+        if (error instanceof Error && (error.message.includes("ProcessSingleton") || error.message.includes("Invalid URL"))) {
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+          return launchWithRetry(attempt + 1);
+        }
+        throw error;
+      }
+    };
+    return launchWithRetry(0);
+  }
+  async _closeBrowserContext(browserContext, userDataDir) {
+    testDebug("close browser context (persistent)");
+    testDebug("release user data dir", userDataDir);
+    await browserContext.close().catch((error) => {
+      browserDebug("Failed to close browser context:", error);
+    });
+    this._userDataDirs.delete(userDataDir);
+    testDebug("close browser context complete (persistent)");
+  }
+  async _createUserDataDir(rootPath) {
+    const dir = process.env.PWMCP_PROFILES_DIR_FOR_TEST ?? registryDirectory;
+    const browserToken = this.config.browser.launchOptions?.channel ?? this.config.browser?.browserName;
+    const rootPathToken = rootPath ? `-${createHash(rootPath)}` : "";
+    const result = pathJoin(dir, `mcp-${browserToken}${rootPathToken}`);
+    await fsPromises.mkdir(result, { recursive: true });
+    return result;
+  }
+}
+async function injectCdpPort(browserConfig) {
+  if (browserConfig.browserName === "chromium") {
+    browserConfig.launchOptions.cdpPort = await findFreePort();
+  }
+}
+function findFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(0, () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+    server.on("error", reject);
+  });
+}
+export {
+  contextFactory
+};