@tontoko/fast-playwright-mcp 0.0.4

package/lib/program.js

@@ -0,0 +1,82 @@
+// src/program.ts
+import { Option, program } from "commander";
+import debug from "debug";
+import { startTraceViewerServer } from "playwright-core/lib/server";
+import { contextFactory } from "./browser-context-factory.js";
+import {
+  BrowserServerBackend
+} from "./browser-server-backend.js";
+import {
+  commaSeparatedList,
+  resolveCLIConfig,
+  semicolonSeparatedList
+} from "./config.js";
+import { Context } from "./context.js";
+import {
+  createExtensionContextFactory,
+  runWithExtension
+} from "./extension/main.js";
+import { runLoopTools } from "./loopTools/main.js";
+import { start } from "./mcp/transport.js";
+import { packageJSON } from "./package.js";
+import { logServerStart } from "./utils/request-logger.js";
+var programDebug = debug("pw:mcp:program");
+program.version(`Version ${packageJSON.version}`).name(packageJSON.name).option("--allowed-origins <origins>", "semicolon-separated list of origins to allow the browser to request. Default is to allow all.", semicolonSeparatedList).option("--blocked-origins <origins>", "semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.", semicolonSeparatedList).option("--block-service-workers", "block service workers").option("--browser <browser>", "browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.").option("--caps <caps>", "comma-separated list of additional capabilities to enable, possible values: vision, pdf.", commaSeparatedList).option("--cdp-endpoint <endpoint>", "CDP endpoint to connect to.").option("--config <path>", "path to the configuration file.").option("--device <device>", 'device to emulate, for example: "iPhone 15"').option("--executable-path <path>", "path to the browser executable.").option("--headless", "run browser in headless mode, headed by default").option("--host <host>", "host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.").option("--ignore-https-errors", "ignore https errors").option("--isolated", "keep the browser profile in memory, do not save it to disk.").option("--image-responses <mode>", 'whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow".').option("--no-sandbox", "disable the sandbox for all process types that are normally sandboxed.").option("--output-dir <path>", "path to the directory for output files.").option("--port <port>", "port to listen on for SSE transport.").option("--proxy-bypass <bypass>", 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"').option("--proxy-server <proxy>", 'specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"').option("--save-session", "Whether to save the Playwright MCP session into the output directory.").option("--save-trace", "Whether to save the Playwright Trace of the session into the output directory.").option("--storage-state <path>", "path to the storage state file for isolated sessions.").option("--user-agent <ua string>", "specify user agent string").option("--user-data-dir <path>", "path to the user data directory. If not specified, a temporary directory will be created.").option("--viewport-size <size>", 'specify browser viewport size in pixels, for example "1280, 720"').addOption(new Option("--extension", 'Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.').hideHelp()).addOption(new Option("--connect-tool", "Allow to switch between different browser connection methods.").hideHelp()).addOption(new Option("--loop-tools", "Run loop tools").hideHelp()).addOption(new Option("--vision", "Legacy option, use --caps=vision instead").hideHelp()).action(async (options) => {
+  setupExitWatchdog();
+  if (options.vision) {
+    options.caps = "vision";
+  }
+  try {
+    const config = await resolveCLIConfig(options);
+    if (options.extension) {
+      await runWithExtension(config);
+      return;
+    }
+    if (options.loopTools) {
+      await runLoopTools(config);
+      return;
+    }
+    const browserContextFactory = contextFactory(config);
+    let serverBackendFactory;
+    if (options.connectTool) {
+      const factories = [
+        browserContextFactory,
+        createExtensionContextFactory(config)
+      ];
+      serverBackendFactory = () => new BrowserServerBackend(config, factories);
+    } else {
+      const factories = [browserContextFactory];
+      serverBackendFactory = () => new BrowserServerBackend(config, factories);
+    }
+    logServerStart();
+    await start(serverBackendFactory, config.server);
+    if (config.saveTrace) {
+      const server = await startTraceViewerServer();
+      const urlPrefix = server.urlPrefix("human-readable");
+      const url = urlPrefix + "/trace/index.html?trace=" + config.browser.launchOptions.tracesDir + "/trace.json";
+      programDebug(`Trace viewer available at: ${url}`);
+    }
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(1);
+  }
+});
+function setupExitWatchdog() {
+  let isExiting = false;
+  const handleExit = async () => {
+    if (isExiting) {
+      return;
+    }
+    isExiting = true;
+    setTimeout(() => process.exit(0), 15000);
+    await Context.disposeAll();
+    process.exit(0);
+  };
+  process.stdin.on("close", handleExit);
+  process.on("SIGINT", handleExit);
+  process.on("SIGTERM", handleExit);
+}
+program.parseAsync(process.argv).catch(() => {
+  process.exit(1);
+});

package/lib/response.js

@@ -0,0 +1,493 @@
+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/response.ts
+import debug from "debug";
+import { TIMEOUTS } from "./config/constants.js";
+import { mergeExpectations } from "./schemas/expectation.js";
+import { renderModalStates } from "./tab.js";
+import { filterConsoleMessages } from "./utils/console-filter.js";
+import { processImage } from "./utils/image-processor.js";
+import { TextReportBuilder } from "./utils/report-builder.js";
+import { ResponseDiffDetector } from "./utils/response-diff-detector.js";
+var responseDebug = debug("pw:mcp:response");
+
+class Response {
+  _result = [];
+  _code = [];
+  _images = [];
+  _context;
+  _includeSnapshot = false;
+  _includeTabs = false;
+  _tabSnapshot;
+  _expectation;
+  _diffResult;
+  toolName;
+  toolArgs;
+  _isError;
+  static diffDetector = new ResponseDiffDetector;
+  constructor(context, toolName, toolArgs, expectation) {
+    this._context = context;
+    this.toolName = toolName;
+    this.toolArgs = toolArgs;
+    const actualExpectation = expectation || toolArgs.expectation;
+    this._expectation = mergeExpectations(toolName, actualExpectation);
+  }
+  addResult(result) {
+    this._result.push(result);
+  }
+  addError(error) {
+    this._result.push(error);
+    this._isError = true;
+  }
+  isError() {
+    return this._isError;
+  }
+  result() {
+    return this._result.join(`
+`);
+  }
+  addCode(code) {
+    this._code.push(code);
+  }
+  code() {
+    return this._code.join(`
+`);
+  }
+  addImage(image) {
+    this._images.push(image);
+  }
+  images() {
+    return this._images;
+  }
+  setIncludeSnapshot() {
+    this._includeSnapshot = true;
+  }
+  setIncludeTabs() {
+    this._includeTabs = true;
+  }
+  setTabSnapshot(snapshot) {
+    this._tabSnapshot = snapshot;
+  }
+  async finish() {
+    const shouldIncludeSnapshot = this._expectation.includeSnapshot || this._includeSnapshot;
+    if (shouldIncludeSnapshot && this._context.currentTab() && !this._tabSnapshot) {
+      await this._captureSnapshotWithNavigationHandling();
+    }
+    await Promise.all(this._context.tabs().map((tab) => tab.updateTitle()));
+    if (this._expectation.imageOptions && this._images.length > 0) {
+      const processedImages = await Promise.all(this._images.map(async (image) => {
+        try {
+          const processedResult = await processImage(image.data, image.contentType, this._expectation.imageOptions);
+          return {
+            contentType: processedResult.contentType,
+            data: processedResult.data
+          };
+        } catch (error) {
+          responseDebug("Image processing failed:", error);
+          return image;
+        }
+      }));
+      this._images.length = 0;
+      this._images.push(...processedImages);
+    }
+    if (this._expectation.diffOptions?.enabled) {
+      try {
+        const currentContent = this.buildContentForDiff();
+        const diffOptions = {
+          enabled: this._expectation.diffOptions.enabled,
+          threshold: this._expectation.diffOptions.threshold ?? 0.1,
+          format: this._expectation.diffOptions.format ?? "unified",
+          maxDiffLines: this._expectation.diffOptions.maxDiffLines ?? 50,
+          ignoreWhitespace: this._expectation.diffOptions.ignoreWhitespace ?? true,
+          context: this._expectation.diffOptions.context ?? 3
+        };
+        this._diffResult = Response.diffDetector.detectDiff(currentContent, this.toolName, diffOptions);
+      } catch (error) {
+        responseDebug("Diff detection failed:", error);
+        this._diffResult = undefined;
+      }
+    }
+  }
+  tabSnapshot() {
+    return this._tabSnapshot;
+  }
+  serialize() {
+    const response = [];
+    this._addDiffSectionToResponse(response);
+    this._addResultSectionToResponse(response);
+    this._addCodeSectionToResponse(response);
+    const { shouldIncludeTabs, shouldIncludeSnapshot } = this._getInclusionFlags();
+    if (shouldIncludeTabs) {
+      response.push(...renderTabsMarkdown(this._context.tabs(), true));
+    }
+    this._addSnapshotSectionToResponse(response, shouldIncludeSnapshot);
+    const content = [
+      { type: "text", text: response.join(`
+`) }
+    ];
+    if (this._context.config.imageResponses !== "omit") {
+      for (const image of this._images) {
+        content.push({
+          type: "image",
+          data: image.data.toString("base64"),
+          mimeType: image.contentType
+        });
+      }
+    }
+    return { content, isError: this._isError };
+  }
+  renderFilteredTabSnapshot(tabSnapshot) {
+    const sections = [
+      this.buildConsoleSection(tabSnapshot),
+      this.buildDownloadsSection(tabSnapshot),
+      this.buildPageStateSection(tabSnapshot)
+    ].filter(Boolean);
+    return sections.join(`
+`);
+  }
+  buildConsoleSection(tabSnapshot) {
+    if (!(this._expectation.includeConsole && tabSnapshot.consoleMessages.length)) {
+      return null;
+    }
+    const filteredMessages = filterConsoleMessages(tabSnapshot.consoleMessages, this._expectation.consoleOptions);
+    if (!filteredMessages.length) {
+      return null;
+    }
+    return this.buildSection("New console messages", (b) => {
+      for (const message of filteredMessages) {
+        b.addListItem(trim(message.toString(), 100));
+      }
+    }, 3);
+  }
+  buildDownloadsSection(tabSnapshot) {
+    if (!(this._expectation.includeDownloads && tabSnapshot.downloads.length)) {
+      return null;
+    }
+    return this.buildSection("Downloads", (b) => {
+      for (const entry of tabSnapshot.downloads) {
+        const filename = entry.download.suggestedFilename();
+        const status = entry.finished ? `Downloaded file ${filename} to ${entry.outputFile}` : `Downloading file ${filename} ...`;
+        b.addListItem(status);
+      }
+    }, 3);
+  }
+  buildPageStateSection(tabSnapshot) {
+    return this.buildSection("Page state", (b) => {
+      b.addKeyValue("Page URL", tabSnapshot.url);
+      b.addKeyValue("Page Title", tabSnapshot.title);
+      if (this._expectation.includeSnapshot) {
+        b.addLine("- Page Snapshot:");
+        b.addCodeBlock(tabSnapshot.ariaSnapshot, "yaml");
+      }
+    }, 3);
+  }
+  buildSection(title, contentFn, level = 2) {
+    const builder = new TextReportBuilder;
+    builder.addSection(title, contentFn, level);
+    return builder.getSections().join(`
+`);
+  }
+  _addDiffSectionToResponse(response) {
+    if (!(this._diffResult?.hasDifference && this._diffResult.formattedDiff)) {
+      return;
+    }
+    response.push("### Changes from previous response", `Similarity: ${(this._diffResult.similarity * 100).toFixed(1)}%`, `Changes: ${this._diffResult.metadata.addedLines} additions, ${this._diffResult.metadata.removedLines} deletions`, "", "```diff", this._diffResult.formattedDiff, "```", "");
+  }
+  _addResultSectionToResponse(response) {
+    if (this._result.length) {
+      response.push("### Result", this._result.join(`
+`), "");
+    }
+  }
+  _addCodeSectionToResponse(response) {
+    if (this._code.length && this._expectation.includeCode) {
+      response.push(`### Ran Playwright code
+\`\`\`js
+${this._code.join(`
+`)}
+\`\`\``, "");
+    }
+  }
+  _getInclusionFlags() {
+    return {
+      shouldIncludeTabs: this._expectation.includeTabs || this._includeTabs,
+      shouldIncludeSnapshot: this._expectation.includeSnapshot || this._includeSnapshot
+    };
+  }
+  _addSnapshotSectionToResponse(response, shouldIncludeSnapshot) {
+    if (!(shouldIncludeSnapshot && this._tabSnapshot)) {
+      return;
+    }
+    if (this._tabSnapshot.modalStates.length) {
+      response.push(...renderModalStates(this._context, this._tabSnapshot.modalStates), "");
+    } else {
+      response.push(this.renderFilteredTabSnapshot(this._tabSnapshot), "");
+    }
+  }
+  buildContentForDiff() {
+    const sections = [
+      this.buildResultDiffSection(),
+      this.buildCodeDiffSection(),
+      this.buildSnapshotDiffSection(),
+      this.buildConsoleMessagesDiffSection()
+    ].filter(Boolean);
+    return sections.join(`
+`);
+  }
+  buildResultDiffSection() {
+    return this._result.length ? ["### Result", this._result.join(`
+`)].join(`
+`) : null;
+  }
+  buildCodeDiffSection() {
+    return this._code.length ? ["### Code", this._code.join(`
+`)].join(`
+`) : null;
+  }
+  buildSnapshotDiffSection() {
+    if (!(this._tabSnapshot && this._expectation.includeSnapshot)) {
+      return null;
+    }
+    return [
+      "### Page State",
+      `URL: ${this._tabSnapshot.url}`,
+      `Title: ${this._tabSnapshot.title}`,
+      "Snapshot:",
+      this._tabSnapshot.ariaSnapshot
+    ].join(`
+`);
+  }
+  buildConsoleMessagesDiffSection() {
+    if (!(this._tabSnapshot?.consoleMessages.length && this._expectation.includeConsole)) {
+      return null;
+    }
+    const filteredMessages = filterConsoleMessages(this._tabSnapshot.consoleMessages, this._expectation.consoleOptions);
+    if (!filteredMessages.length) {
+      return null;
+    }
+    const messageLines = filteredMessages.map((msg) => `- ${msg.toString()}`);
+    return ["### Console Messages", ...messageLines].join(`
+`);
+  }
+  _getNavigationRetryConfig() {
+    return {
+      maxRetries: 3,
+      retryDelay: TIMEOUTS.RETRY_DELAY,
+      stabilityTimeout: TIMEOUTS.STABILITY_TIMEOUT,
+      evaluationTimeout: 200
+    };
+  }
+  async _captureSnapshotWithNavigationHandling() {
+    const currentTab = this._context.currentTabOrDie();
+    const { maxRetries } = this._getNavigationRetryConfig();
+    await this._executeWithRetry(() => this._performSnapshotCapture(currentTab), maxRetries);
+  }
+  async _executeWithRetry(operation, maxRetries) {
+    await this._executeWithRetryRecursive(operation, 1, maxRetries);
+  }
+  async _executeWithRetryRecursive(operation, attempt, maxRetries) {
+    if (attempt > maxRetries) {
+      return;
+    }
+    try {
+      await operation();
+      return;
+    } catch (error) {
+      const shouldRetry = await this._handleSnapshotError(error, attempt, maxRetries, this._getNavigationRetryConfig().retryDelay, this._context.currentTabOrDie());
+      if (!shouldRetry) {
+        return;
+      }
+      await this._executeWithRetryRecursive(operation, attempt + 1, maxRetries);
+    }
+  }
+  async _performSnapshotCapture(tab) {
+    await this._handleNavigationIfNeeded(tab);
+    await this._attemptSnapshotCapture(tab);
+  }
+  async _handleNavigationIfNeeded(tab) {
+    if (await this._isPageNavigating(tab)) {
+      await this._waitForNavigationStability(tab);
+    }
+  }
+  async _attemptSnapshotCapture(tab) {
+    const options = this._expectation.snapshotOptions;
+    if (options?.selector || options?.maxLength) {
+      this._tabSnapshot = await tab.capturePartialSnapshot(options.selector, options.maxLength);
+    } else {
+      this._tabSnapshot = await tab.captureSnapshot();
+    }
+  }
+  async _handleSnapshotError(error, attempt, maxRetries, retryDelay, tab) {
+    const errorMessage = error?.message ?? "";
+    if (this._isRecoverableError(errorMessage) && attempt < maxRetries) {
+      await this._delayRetry(retryDelay, attempt);
+      return true;
+    }
+    if (attempt === maxRetries) {
+      await this._handleFinalFailure(tab);
+    }
+    return false;
+  }
+  _isRecoverableError(errorMessage) {
+    const recoverableErrors = [
+      "Execution context was destroyed",
+      "Target closed",
+      "Session closed"
+    ];
+    return recoverableErrors.some((err) => errorMessage.includes(err));
+  }
+  async _delayRetry(retryDelay, attempt) {
+    await new Promise((resolve) => setTimeout(resolve, retryDelay * attempt));
+  }
+  async _handleFinalFailure(tab) {
+    try {
+      this._tabSnapshot = await this._captureBasicSnapshot(tab);
+    } catch (error) {
+      responseDebug("Failed to capture basic snapshot:", error);
+      this._tabSnapshot = undefined;
+    }
+  }
+  async _isPageNavigating(tab) {
+    try {
+      if (this._hasInternalNavigationState(tab)) {
+        return tab.isNavigating();
+      }
+      const navigationState = await this._evaluateNavigationState(tab);
+      return this._isNavigationInProgress(navigationState);
+    } catch (error) {
+      responseDebug("Navigation check failed (assuming in progress):", error);
+      return true;
+    }
+  }
+  _hasInternalNavigationState(tab) {
+    return "isNavigating" in tab && typeof tab.isNavigating === "function";
+  }
+  async _evaluateNavigationState(tab) {
+    return await Promise.race([
+      tab.page.evaluate(() => [
+        document.readyState,
+        window.performance?.timing?.loadEventEnd === 0
+      ]).catch(() => [null, null]),
+      new Promise((resolve) => setTimeout(() => resolve([null, null]), this._getNavigationRetryConfig().evaluationTimeout))
+    ]);
+  }
+  _isNavigationInProgress(state) {
+    const [readyState, isLoading] = state;
+    return readyState === "loading" || isLoading === true;
+  }
+  async _waitForNavigationStability(tab) {
+    if (await this._tryBuiltInNavigationCompletion(tab)) {
+      return;
+    }
+    await this._performManualStabilityCheck(tab);
+  }
+  async _tryBuiltInNavigationCompletion(tab) {
+    if (!this._hasNavigationCompletionMethod(tab)) {
+      return false;
+    }
+    try {
+      await tab.waitForNavigationComplete();
+      return true;
+    } catch (error) {
+      responseDebug("Tab navigation completion failed:", error);
+      return false;
+    }
+  }
+  _hasNavigationCompletionMethod(tab) {
+    return "waitForNavigationComplete" in tab && typeof tab.waitForNavigationComplete === "function";
+  }
+  async _performManualStabilityCheck(tab) {
+    const { stabilityTimeout } = this._getNavigationRetryConfig();
+    const startTime = Date.now();
+    await this._performStabilityCheckRecursive(tab, startTime, stabilityTimeout);
+  }
+  async _performStabilityCheckRecursive(tab, startTime, stabilityTimeout) {
+    if (Date.now() - startTime >= stabilityTimeout) {
+      return;
+    }
+    if (await this._checkPageStability(tab)) {
+      await new Promise((resolve) => setTimeout(resolve, 200));
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    await this._performStabilityCheckRecursive(tab, startTime, stabilityTimeout);
+  }
+  async _checkPageStability(tab) {
+    try {
+      await tab.page.waitForLoadState("load", {
+        timeout: TIMEOUTS.MEDIUM_DELAY
+      });
+      await tab.page.waitForLoadState("networkidle", { timeout: TIMEOUTS.SHORT_DELAY }).catch(() => {});
+      return await tab.page.evaluate(() => document.readyState === "complete").catch(() => false);
+    } catch (error) {
+      responseDebug("Page stability check failed (retrying):", error);
+      return false;
+    }
+  }
+  async _captureBasicSnapshot(tab) {
+    try {
+      return await tab.captureSnapshot();
+    } catch (error) {
+      responseDebug("Basic snapshot capture failed, creating minimal snapshot:", error);
+      return await this._createMinimalSnapshot(tab);
+    }
+  }
+  async _createMinimalSnapshot(tab) {
+    const url = tab.page.url();
+    const title = await tab.page.title().catch(() => "");
+    return {
+      url,
+      title,
+      ariaSnapshot: "// Snapshot unavailable due to navigation context issues",
+      modalStates: [],
+      consoleMessages: [],
+      downloads: []
+    };
+  }
+}
+function renderTabsMarkdown(tabs, force = false) {
+  if (tabs.length === 1 && !force) {
+    return [];
+  }
+  if (!tabs.length) {
+    return [
+      "### Open tabs",
+      'No open tabs. Use the "browser_navigate" tool to navigate to a page first.',
+      ""
+    ];
+  }
+  const lines = ["### Open tabs"];
+  for (let i = 0;i < tabs.length; i++) {
+    const tab = tabs[i];
+    const current = tab.isCurrentTab() ? " (current)" : "";
+    lines.push(`- ${i}:${current} [${tab.lastTitle()}] (${tab.page.url()})`);
+  }
+  lines.push("");
+  return lines;
+}
+function trim(text, maxLength) {
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, maxLength)}...`;
+}
+export {
+  Response
+};