@tontoko/fast-playwright-mcp 0.0.4

package/lib/utils/response-diff-detector.js

@@ -0,0 +1,150 @@
+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/utils/response-diff-detector.ts
+import { createHash } from "node:crypto";
+import diff from "fast-diff";
+import { DiffFormatter } from "./diff-formatter.js";
+
+class ResponseDiffDetector {
+  storage = new Map;
+  formatter = new DiffFormatter;
+  detectDiff(current, toolName, options) {
+    const cacheKey = this.generateCacheKey(toolName);
+    const previous = this.storage.get(cacheKey);
+    if (!previous) {
+      this.storeResponse(current, toolName);
+      return {
+        hasDifference: false,
+        similarity: 1,
+        formattedDiff: "",
+        metadata: {
+          addedLines: 0,
+          removedLines: 0,
+          contextLines: 0,
+          totalLines: current.split(`
+`).length
+        }
+      };
+    }
+    const diffSegments = this.calculateDiff(previous.content, current);
+    const similarity = this.calculateSimilarity(previous.content, current);
+    const hasDifference = similarity < 1 - options.threshold;
+    let formattedDiff = "";
+    const metadata = {
+      addedLines: 0,
+      removedLines: 0,
+      contextLines: 0,
+      totalLines: current.split(`
+`).length
+    };
+    if (hasDifference) {
+      for (const segment of diffSegments) {
+        if (segment.type === "add") {
+          metadata.addedLines += segment.value.split(`
+`).length - 1;
+        } else if (segment.type === "remove") {
+          metadata.removedLines += segment.value.split(`
+`).length - 1;
+        } else {
+          metadata.contextLines += segment.value.split(`
+`).length - 1;
+        }
+      }
+      switch (options.format) {
+        case "split":
+          formattedDiff = this.formatter.formatSplit(diffSegments);
+          break;
+        case "minimal":
+          formattedDiff = this.formatter.formatMinimal(diffSegments);
+          break;
+        default:
+          formattedDiff = this.formatter.formatUnified(diffSegments, options.context);
+          break;
+      }
+      if (formattedDiff.split(`
+`).length > options.maxDiffLines) {
+        const lines = formattedDiff.split(`
+`);
+        formattedDiff = lines.slice(0, options.maxDiffLines).join(`
+`) + `
+... (${lines.length - options.maxDiffLines} more lines truncated)`;
+      }
+    }
+    this.storeResponse(current, toolName);
+    return {
+      hasDifference,
+      similarity,
+      formattedDiff,
+      metadata
+    };
+  }
+  storeResponse(content, toolName) {
+    const cacheKey = this.generateCacheKey(toolName);
+    const hash = createHash("sha256").update(content).digest("hex");
+    this.storage.set(cacheKey, {
+      toolName,
+      timestamp: Date.now(),
+      content,
+      hash
+    });
+  }
+  generateCacheKey(toolName) {
+    return `diff_cache_${toolName}`;
+  }
+  calculateDiff(oldText, newText) {
+    const result = diff(oldText, newText);
+    return result.map(([type, value]) => {
+      let diffType = "equal";
+      if (type === -1) {
+        diffType = "remove";
+      } else if (type === 1) {
+        diffType = "add";
+      }
+      return {
+        type: diffType,
+        value
+      };
+    });
+  }
+  calculateSimilarity(text1, text2) {
+    if (text1 === text2) {
+      return 1;
+    }
+    if (text1.length === 0 && text2.length === 0) {
+      return 1;
+    }
+    if (text1.length === 0 || text2.length === 0) {
+      return 0;
+    }
+    const diffSegments = this.calculateDiff(text1, text2);
+    let equalChars = 0;
+    let totalChars = 0;
+    for (const segment of diffSegments) {
+      totalChars += segment.value.length;
+      if (segment.type === "equal") {
+        equalChars += segment.value.length;
+      }
+    }
+    return totalChars > 0 ? equalChars / totalChars : 0;
+  }
+}
+export {
+  ResponseDiffDetector
+};

package/lib/utils/section-builder.js

@@ -0,0 +1,62 @@
+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/utils/section-builder.ts
+function buildDiagnosticSection(sections, title, content, level = 2) {
+  sections.push("");
+  sections.push(`${"#".repeat(level)} ${title}`);
+  if (typeof content === "function") {
+    content();
+  } else {
+    sections.push(...content);
+  }
+}
+function addKeyValuePairs(sections, pairs) {
+  for (const [key, value] of Object.entries(pairs)) {
+    sections.push(`- **${key}:** ${value}`);
+  }
+}
+function addListItems(sections, items, prefix = "-") {
+  for (const item of items) {
+    sections.push(`${prefix} ${item}`);
+  }
+}
+function addIfNotEmpty(sections, items, formatter) {
+  if (items.length > 0) {
+    for (const item of items) {
+      sections.push(formatter(item));
+    }
+  }
+}
+function buildPerformanceSection(sections, metrics) {
+  if (metrics.executionTime !== undefined) {
+    const icon = metrics.threshold && metrics.executionTime > metrics.threshold ? "⚠️" : "✅";
+    sections.push(`${icon} Execution time: ${metrics.executionTime}ms`);
+    if (metrics.threshold && metrics.executionTime > metrics.threshold) {
+      sections.push(`⚠️ Exceeded threshold (${metrics.threshold}ms)`);
+    }
+  }
+}
+export {
+  buildPerformanceSection,
+  buildDiagnosticSection,
+  addListItems,
+  addKeyValuePairs,
+  addIfNotEmpty
+};

package/lib/utils/tool-patterns.js

@@ -0,0 +1,153 @@
+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/utils/tool-patterns.ts
+import { BaseElementToolHandler } from "../tools/base-tool-handler.js";
+import { getErrorMessage } from "./common-formatters.js";
+var resolveElementLocator = async (tab, params) => {
+
+  class TempHandler extends BaseElementToolHandler {
+    constructor() {
+      super("temp");
+    }
+    executeToolLogic() {
+      return Promise.resolve();
+    }
+    resolveLocator(tabInstance, locatorParams) {
+      return this.resolveElementLocator(tabInstance, locatorParams);
+    }
+  }
+  return await new TempHandler().resolveLocator(tab, params);
+};
+var validateElementParams = (params) => {
+
+  class TempHandler extends BaseElementToolHandler {
+    constructor() {
+      super("temp");
+    }
+    executeToolLogic() {
+      return Promise.resolve();
+    }
+    validateParams(validationParams) {
+      this.validateElementParams(validationParams);
+    }
+  }
+  new TempHandler().validateParams(params);
+};
+function addToolErrorContext(response, error, toolName, params) {
+  const errorMessage = getErrorMessage(error);
+  response.addError(`Error in ${toolName}: ${errorMessage}`);
+  if (params?.element) {
+    response.addResult(`Element context: ${params.element}`);
+  }
+  if (params?.ref) {
+    response.addResult(`Reference: ${params.ref}`);
+  }
+}
+function applyCommonExpectations(response, expectation) {
+  if (expectation?.includeSnapshot !== false) {
+    response.setIncludeSnapshot();
+  }
+}
+async function waitForToolCompletion(tab, operation, toolName, operationName) {
+  try {
+    await tab.waitForCompletion(operation);
+  } catch (error) {
+    const opName = operationName ?? "operation";
+    throw new Error(`${toolName} ${opName} failed: ${getErrorMessage(error)}`);
+  }
+}
+function addOperationComment(response, operation, context) {
+  const comment = context ? `// ${operation} - ${context}` : `// ${operation}`;
+  response.addCode(comment);
+}
+function addMouseOperationComment(response, operation, params) {
+  if (params.element) {
+    addOperationComment(response, operation, `on ${params.element}`);
+  } else {
+    addOperationComment(response, operation, `at (${params.x}, ${params.y})`);
+  }
+}
+function addNavigationComment(response, operation, url) {
+  if (url) {
+    addOperationComment(response, operation, `to ${url}`);
+  } else {
+    addOperationComment(response, operation);
+  }
+}
+async function executeToolOperation(operation, toolName, response, params) {
+  try {
+    return await operation();
+  } catch (error) {
+    addToolErrorContext(response, error, toolName, params);
+    throw error;
+  }
+}
+function setupToolResponse(response, params) {
+  applyCommonExpectations(response, params.expectation);
+}
+async function validateAndResolveElement(tab, params) {
+  validateElementParams(params);
+  return await resolveElementLocator(tab, params);
+}
+var ToolPatterns = {
+  Mouse: {
+    addComment: addMouseOperationComment,
+    validate: (params) => {
+      if (params.x < 0 || params.y < 0) {
+        throw new Error("Mouse coordinates must be non-negative");
+      }
+    }
+  },
+  Navigation: {
+    addComment: addNavigationComment,
+    validateUrl: (url) => {
+      try {
+        new URL(url);
+      } catch {
+        throw new Error(`Invalid URL: ${url}`);
+      }
+    }
+  },
+  Element: {
+    validateAndResolve: validateAndResolveElement,
+    addErrorContext: (response, error, toolName, element) => {
+      const errorMsg = getErrorMessage(error);
+      response.addResult(`${toolName} failed: ${errorMsg}`);
+      if (element) {
+        response.addResult(`Target element: ${element}`);
+        response.addResult("Suggestion: Verify element is visible and interactable");
+      }
+    }
+  }
+};
+export {
+  waitForToolCompletion,
+  validateElementParams,
+  validateAndResolveElement,
+  setupToolResponse,
+  resolveElementLocator,
+  executeToolOperation,
+  applyCommonExpectations,
+  addToolErrorContext,
+  addOperationComment,
+  addNavigationComment,
+  addMouseOperationComment,
+  ToolPatterns
+};

package/lib/utils.js

@@ -0,0 +1,46 @@
+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/utils.ts
+import { createHash as cryptoCreateHash } from "node:crypto";
+function createHash(data) {
+  return cryptoCreateHash("sha256").update(data).digest("hex").slice(0, 7);
+}
+var UNSAFE_FILENAME_CHARS = /[<>:"/\\|?*]+/g;
+function removeControlCharacters(str) {
+  return str.split("").map((char) => {
+    const code = char.charCodeAt(0);
+    return code >= 0 && code <= 31 || code === 127 ? "-" : char;
+  }).join("");
+}
+function sanitizeForFilePath(input) {
+  const sanitize = (str) => {
+    const cleanStr = removeControlCharacters(str);
+    return cleanStr.replace(UNSAFE_FILENAME_CHARS, "-");
+  };
+  const separator = input.lastIndexOf(".");
+  if (separator === -1) {
+    return sanitize(input);
+  }
+  return sanitize(input.substring(0, separator)) + "." + sanitize(input.substring(separator + 1));
+}
+export {
+  sanitizeForFilePath,
+  createHash
+};

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@tontoko/fast-playwright-mcp",
+  "version": "0.0.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Fast Playwright Tools for MCP",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tontoko/fast-playwright-mcp"
+  },
+  "homepage": "https://playwright.dev",
+  "engines": {
+    "node": ">=18"
+  },
+  "author": {
+    "name": "Microsoft Corporation"
+  },
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "bun build ./src/**/**/*.ts ./src/**/*.ts ./src/*.ts --outdir ./lib --root ./src --target node --format esm --external '*'",
+    "build:publish": "bun build ./src/**/**/*.ts ./src/**/*.ts ./src/*.ts --outdir ./lib --root ./src --target node --format esm --external '*'",
+    "benchmark": "bun benchmark/src/index.ts",
+    "benchmark:verbose": "bun benchmark/src/index.ts --verbose",
+    "benchmark:quiet": "bun benchmark/src/index.ts --quiet",
+    "lint": "ultracite lint",
+    "lint-fix": "ultracite format",
+    "update-readme": "bun utils/update-readme.js",
+    "watch": "tsc --watch",
+    "test": "playwright test",
+    "ctest": "playwright test --project=chrome",
+    "ftest": "playwright test --project=firefox",
+    "wtest": "playwright test --project=webkit",
+    "run-server": "bun lib/browserServer.js",
+    "clean": "rm -rf lib benchmark/lib",
+    "npm-publish": "npm run clean && npm run build:publish && npm run test && npm publish"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.16.0",
+    "@types/sharp": "^0.31.1",
+    "commander": "^13.1.0",
+    "debug": "^4.4.1",
+    "dotenv": "^17.2.0",
+    "fast-diff": "^1.3.0",
+    "mime": "^4.0.7",
+    "playwright": "1.55.0-alpha-2025-08-07",
+    "playwright-core": "1.55.0-alpha-2025-08-07",
+    "sharp": "^0.34.3",
+    "ws": "^8.18.1",
+    "zod": "^3.24.1",
+    "zod-to-json-schema": "^3.24.4"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.57.0",
+    "@biomejs/biome": "2.1.2",
+    "@playwright/test": "1.55.0-alpha-2025-08-07",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^22.13.10",
+    "@types/ws": "^8.18.1",
+    "@typescript/native-preview": "^7.0.0-dev.20250808.1",
+    "esbuild": "^0.20.1",
+    "lefthook": "^1.12.2",
+    "openai": "^5.10.2",
+    "ultracite": "5.1.2"
+  },
+  "bin": {
+    "mcp-server-playwright": "cli.js"
+  }
+}