@tontoko/fast-playwright-mcp 0.0.5 → 0.0.7

package/lib/batch/batch-executor.js

@@ -18,22 +18,32 @@ var __toESM = (mod, isNodeMode, target) => {
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/batch/batch-executor.ts
+import { randomBytes } from "node:crypto";
+import debug from "debug";
 import { Response } from "../response.js";
 import { mergeExpectations } from "../schemas/expectation.js";
 import { getErrorMessage } from "../utils/common-formatters.js";
+var batchDebug = debug("pw:mcp:batch");
 
 class BatchExecutor {
   toolRegistry;
   context;
+  currentBatchContext;
   constructor(context, toolRegistry) {
     this.context = context;
     this.toolRegistry = toolRegistry;
   }
+  generateBatchId() {
+    const timestamp = Date.now();
+    const random = randomBytes(4).toString("hex");
+    return `batch_${timestamp}_${random}`;
+  }
   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}`);
+        const availableTools = Array.from(this.toolRegistry.keys()).filter((name) => name.startsWith("browser_") && name !== "browser_batch_execute").sort((a, b) => a.localeCompare(b)).join(",");
+        throw new Error(`Unknown tool: "${step.tool}" at step ${index}. Available tools: ${availableTools}`);
       }
       try {
         const parseResult = tool.schema.inputSchema.safeParse({
@@ -52,6 +62,11 @@ class BatchExecutor {
     const results = [];
     const startTime = Date.now();
     let stopReason = "completed";
+    this.currentBatchContext = {
+      batchId: this.generateBatchId(),
+      startTime
+    };
+    batchDebug(`Starting batch execution ${this.currentBatchContext.batchId} with ${options.steps.length} steps`);
     this.validateAllSteps(options.steps);
     const executeSequentially = async (index) => {
       if (index >= options.steps.length) {
@@ -60,7 +75,10 @@ class BatchExecutor {
       const step = options.steps[index];
       const stepStartTime = Date.now();
       try {
-        const result = await this.executeStep(step, options.globalExpectation);
+        if (this.currentBatchContext) {
+          this.currentBatchContext.currentStepIndex = index;
+        }
+        const result = await this.executeStep(step, options.globalExpectation, this.currentBatchContext);
         const stepEndTime = Date.now();
         results.push({
           stepIndex: index,
@@ -100,7 +118,7 @@ class BatchExecutor {
       stopReason
     };
   }
-  async executeStep(step, globalExpectation) {
+  async executeStep(step, globalExpectation, batchContext) {
     const tool = this.toolRegistry.get(step.tool);
     if (!tool) {
       throw new Error(`Unknown tool: ${step.tool}`);
@@ -110,10 +128,18 @@ class BatchExecutor {
       ...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();
+    const previousBatchContext = this.context.batchContext;
+    this.context.batchContext = batchContext;
+    try {
+      const response = new Response(this.context, step.tool, argsWithExpectation, mergedExpectation);
+      batchDebug(`Executing batch step: ${step.tool}`);
+      await tool.handle(this.context, argsWithExpectation, response);
+      await response.finish();
+      batchDebug(`Batch step ${step.tool} completed`);
+      return response.serialize();
+    } finally {
+      this.context.batchContext = previousBatchContext;
+    }
   }
   mergeStepExpectations(toolName, globalExpectation, stepExpectation) {
     let merged = mergeExpectations(toolName);

package/lib/browser-server-backend.js

@@ -79,10 +79,12 @@ class BrowserServerBackend {
       throw new Error(`Tool not found: ${schema.name}`);
     }
     context.setRunningTool(true);
+    backendDebug(`Executing tool: ${schema.name}`);
     try {
       await matchedTool.handle(context, parsedArguments, response);
       await response.finish();
       this._sessionLog?.logResponse(response);
+      backendDebug(`Tool ${schema.name} completed successfully`);
     } catch (error) {
       backendDebug(`Error executing tool ${schema.name}:`, error);
       response.addError(String(error));

package/lib/context.js

@@ -24,6 +24,7 @@ import { outputFile } from "./config.js";
 import { logUnhandledError } from "./log.js";
 import { Tab } from "./tab.js";
 var testDebug = debug("pw:mcp:test");
+var contextDebug = debug("pw:mcp:context");
 
 class Context {
   tools;
@@ -40,6 +41,7 @@ class Context {
   _closeBrowserContextPromise;
   _isRunningTool = false;
   _abortController = new AbortController;
+  batchContext;
   constructor(options) {
     this.tools = options.tools;
     this.config = options.config;
@@ -66,6 +68,7 @@ class Context {
     return this._currentTab;
   }
   async newTab() {
+    contextDebug("Creating new tab");
     const { browserContext } = await this._ensureBrowserContext();
     const page = await browserContext.newPage();
     const tab = this._tabs.find((t) => t.page === page);
@@ -73,6 +76,7 @@ class Context {
       throw new Error("Failed to create tab: tab not found after creation");
     }
     this._currentTab = tab;
+    contextDebug("New tab created successfully");
     return this._currentTab;
   }
   async selectTab(index) {
@@ -121,13 +125,21 @@ class Context {
       this._currentTab = this._tabs[Math.min(index, this._tabs.length - 1)];
     }
     if (!this._tabs.length) {
-      this.closeBrowserContext().catch(() => {});
+      contextDebug("No tabs remaining, closing browser context");
+      this.closeBrowserContext().catch((error) => {
+        contextDebug("Error closing browser context:", error);
+      });
     }
   }
   async closeBrowserContext() {
-    this._closeBrowserContextPromise ??= this._closeBrowserContextImpl().catch(logUnhandledError);
+    contextDebug("Closing browser context");
+    this._closeBrowserContextPromise ??= this._closeBrowserContextImpl().catch((error) => {
+      contextDebug("Failed to close browser context:", error);
+      logUnhandledError(error);
+    });
     await this._closeBrowserContextPromise;
     this._closeBrowserContextPromise = undefined;
+    contextDebug("Browser context closed");
   }
   isRunningTool() {
     return this._isRunningTool;
@@ -175,8 +187,10 @@ class Context {
   }
   _ensureBrowserContext() {
     this._browserContextPromise ??= (() => {
+      contextDebug("Ensuring browser context exists");
       const promise = this._setupBrowserContext();
-      promise.catch(() => {
+      promise.catch((error) => {
+        contextDebug("Failed to setup browser context:", error);
         this._browserContextPromise = undefined;
       });
       return promise;
@@ -187,6 +201,7 @@ class Context {
     if (this._closeBrowserContextPromise) {
       throw new Error("Another browser context is being closed.");
     }
+    contextDebug("Setting up new browser context");
     const result = await this._browserContextFactory.createContext(this._clientInfo, this._abortController.signal);
     const { browserContext } = result;
     await this._setupRequestInterception(browserContext);

package/lib/diagnostics/element-discovery.js

@@ -23,7 +23,6 @@ import { DiagnosticBase } from "./common/diagnostic-base.js";
 import { safeDispose } from "./common/error-enrichment-utils.js";
 import { SmartHandleBatch } from "./smart-handle.js";
 var elementDiscoveryDebug = debug("pw:mcp:element-discovery");
-
 class ElementDiscovery extends DiagnosticBase {
   smartHandleBatch;
   maxBatchSize = 100;
@@ -358,23 +357,134 @@ class ElementDiscovery extends DiagnosticBase {
   }
   async generateSelector(element) {
     return await element.evaluate((el) => {
+      const CLASS_SPLIT_PATTERN = "\\s+";
+      const classSplitRegex = new RegExp(CLASS_SPLIT_PATTERN);
+      const isUnique = (selector) => {
+        return document.querySelectorAll(selector).length === 1;
+      };
+      const getClasses = (elem) => {
+        return elem.className ? `.${elem.className.trim().split(classSplitRegex).join(".")}` : "";
+      };
+      const tryIdSelector = (elem, elemTag) => {
+        if (!elem.id) {
+          return null;
+        }
+        const selector = `${elemTag}#${elem.id}`;
+        return isUnique(selector) ? selector : null;
+      };
+      const tryDataAttributes = (elem, elemTag) => {
+        const dataAttrs = Array.from(elem.attributes).filter((attr) => attr.name.startsWith("data-")).map((attr) => `[${attr.name}="${attr.value}"]`).join("");
+        if (!dataAttrs) {
+          return null;
+        }
+        const selector = `${elemTag}${dataAttrs}`;
+        return isUnique(selector) ? selector : null;
+      };
+      const tryMeaningfulAttributes = (elem, elemTag) => {
+        const attrs = [
+          "name",
+          "type",
+          "aria-label",
+          "placeholder",
+          "value",
+          "role"
+        ];
+        for (const attrName of attrs) {
+          const attrValue = elem.getAttribute(attrName);
+          if (attrValue) {
+            const selector = `${elemTag}[${attrName}="${attrValue}"]`;
+            if (isUnique(selector)) {
+              return selector;
+            }
+          }
+        }
+        return null;
+      };
+      const tryClassSelector = (elem, elemTag) => {
+        const classes = getClasses(elem);
+        if (!classes) {
+          return null;
+        }
+        const selector = `${elemTag}${classes}`;
+        return isUnique(selector) ? selector : null;
+      };
+      const tryParentContext = (elem, elemTag) => {
+        const parent = elem.parentElement;
+        if (!parent) {
+          return null;
+        }
+        const parentSelector = buildParentSelector(parent);
+        const selector = `${parentSelector} ${elemTag}`;
+        return isUnique(selector) ? selector : null;
+      };
+      const buildParentSelector = (parent) => {
+        const tag2 = parent.tagName.toLowerCase();
+        const id = parent.id ? `#${parent.id}` : "";
+        const classes = getClasses(parent);
+        return `${tag2}${id}${classes}`;
+      };
+      const tryNthOfType = (elem, elemTag, siblings, parentSelector, elemClasses) => {
+        const sameTagSiblings = siblings.filter((s) => s.tagName.toLowerCase() === elemTag);
+        if (sameTagSiblings.length > 1) {
+          const tagIndex = sameTagSiblings.indexOf(elem) + 1;
+          const selector = `${parentSelector} > ${elemTag}${elemClasses}:nth-of-type(${tagIndex})`;
+          if (isUnique(selector)) {
+            return selector;
+          }
+        }
+        return null;
+      };
+      const tryGrandparentContext = (parent, parentTag, elemTag, index) => {
+        const grandParent = parent.parentElement;
+        if (!grandParent) {
+          return null;
+        }
+        const gpSelector = buildParentSelector(grandParent);
+        const parentIndex = Array.from(grandParent.children).filter((c) => c.tagName.toLowerCase() === parentTag).indexOf(parent) + 1;
+        const selector = `${gpSelector} ${parentTag}:nth-of-type(${parentIndex}) > ${elemTag}:nth-child(${index})`;
+        return isUnique(selector) ? selector : null;
+      };
+      const tryNthSelectors = (elem, elemTag) => {
+        const parent = elem.parentElement;
+        if (!parent) {
+          return null;
+        }
+        const siblings = Array.from(parent.children);
+        const index = siblings.indexOf(elem) + 1;
+        const parentSelector = buildParentSelector(parent);
+        const elemClasses = getClasses(elem);
+        const nthOfTypeResult = tryNthOfType(elem, elemTag, siblings, parentSelector, elemClasses);
+        if (nthOfTypeResult) {
+          return nthOfTypeResult;
+        }
+        const nthChildSelector = `${parentSelector} > ${elemTag}${elemClasses}:nth-child(${index})`;
+        if (isUnique(nthChildSelector)) {
+          return nthChildSelector;
+        }
+        const parentTag = parent.tagName.toLowerCase();
+        const gpResult = tryGrandparentContext(parent, parentTag, elemTag, index);
+        if (gpResult) {
+          return gpResult;
+        }
+        return nthChildSelector;
+      };
       if (!(el instanceof Element)) {
         return "unknown";
       }
       const tag = el.tagName.toLowerCase();
-      const id = el.id ? `#${el.id}` : "";
-      const classes = el.className ? `.${el.className.split(" ").join(".")}` : "";
-      if (id) {
-        return `${tag}${id}`;
-      }
-      if (classes) {
-        return `${tag}${classes}`;
-      }
-      const parent = el.parentElement;
-      if (parent) {
-        const siblings = Array.from(parent.children);
-        const index = siblings.indexOf(el) + 1;
-        return `${parent.tagName.toLowerCase()} > ${tag}:nth-child(${index})`;
+      const strategies = [
+        () => tryIdSelector(el, tag),
+        () => tryDataAttributes(el, tag),
+        () => tryMeaningfulAttributes(el, tag),
+        () => tryClassSelector(el, tag),
+        () => tryParentContext(el, tag),
+        () => tryNthSelectors(el, tag)
+      ];
+      for (const strategy of strategies) {
+        const result = strategy();
+        if (result) {
+          return result;
+        }
       }
       return tag;
     });

package/lib/diagnostics/resource-manager.js

@@ -87,7 +87,9 @@ class ResourceManager {
   }
   startCleanupTimer() {
     this.cleanupInterval = setInterval(() => {
-      this.cleanupExpiredResources().catch(() => {});
+      this.cleanupExpiredResources().catch((error) => {
+        resourceDebug("Resource cleanup error (handled internally):", error);
+      });
     }, this.disposeTimeout / 2);
   }
   async cleanupExpiredResources() {

package/lib/response.js

@@ -434,7 +434,9 @@ ${this._code.join(`
       await tab.page.waitForLoadState("load", {
         timeout: TIMEOUTS.MEDIUM_DELAY
       });
-      await tab.page.waitForLoadState("networkidle", { timeout: TIMEOUTS.SHORT_DELAY }).catch(() => {});
+      await tab.page.waitForLoadState("networkidle", { timeout: TIMEOUTS.SHORT_DELAY }).catch((error) => {
+        responseDebug("networkidle timeout ignored during stability check:", error);
+      });
       return await tab.page.evaluate(() => document.readyState === "complete").catch(() => false);
     } catch (error) {
       responseDebug("Page stability check failed (retrying):", error);

package/lib/tab.js

@@ -29,6 +29,7 @@ var TabEvents = {
   modalState: "modalState"
 };
 var snapshotDebug = debug("pw:mcp:snapshot");
+var tabDebug = debug("pw:mcp:tab");
 
 class Tab extends EventEmitter {
   context;
@@ -40,6 +41,8 @@ class Tab extends EventEmitter {
   _onPageClose;
   _modalStates = [];
   _downloads = [];
+  _customRefMappings = new Map;
+  _customRefCounter = 0;
   _navigationState = {
     isNavigating: false,
     lastNavigationStart: 0
@@ -63,7 +66,9 @@ class Tab extends EventEmitter {
     });
     page.on("dialog", (dialog) => this._dialogShown(dialog));
     page.on("download", (download) => {
-      this._downloadStarted(download).catch(() => {});
+      this._downloadStarted(download).catch((error) => {
+        tabDebug("Download error ignored:", error);
+      });
     });
     page.on("framenavigated", (frame) => {
       if (frame === page.mainFrame()) {
@@ -138,7 +143,11 @@ class Tab extends EventEmitter {
     return this === this.context.currentTab();
   }
   async waitForLoadState(state, options) {
-    await callOnPageNoTrace(this.page, (page) => page.waitForLoadState(state, options).catch(logUnhandledError));
+    tabDebug(`Waiting for load state: ${state}`);
+    await callOnPageNoTrace(this.page, (page) => page.waitForLoadState(state, options).catch((error) => {
+      tabDebug(`Failed to wait for load state ${state}:`, error);
+      logUnhandledError(error);
+    }));
   }
   _handleNavigationStart() {
     this._navigationState.isNavigating = true;
@@ -178,6 +187,7 @@ class Tab extends EventEmitter {
     }
   }
   async navigate(url) {
+    tabDebug(`Navigating to: ${url}`);
     this._clearCollectedArtifacts();
     const downloadEvent = callOnPageNoTrace(this.page, (page) => page.waitForEvent("download").catch(logUnhandledError));
     try {
@@ -344,12 +354,34 @@ class Tab extends EventEmitter {
   async waitForCompletion(callback) {
     await this._raceAgainstModalStates(() => waitForCompletion(this, callback));
   }
+  registerCustomRef(ref, selector) {
+    this._customRefMappings.set(ref, selector);
+  }
+  unregisterCustomRef(ref) {
+    this._customRefMappings.delete(ref);
+  }
+  clearCustomRefs() {
+    this._customRefMappings.clear();
+  }
+  getNextCustomRefId(options) {
+    this._customRefCounter++;
+    if (options?.batchId && options.batchId.length > 0) {
+      return `batch_${options.batchId}_element_${this._customRefCounter}`;
+    }
+    return `element_${this._customRefCounter}`;
+  }
   async refLocator(params) {
     return (await this.refLocators([params]))[0];
   }
   async refLocators(params) {
     const snapshot = await this.page._snapshotForAI();
     return params.map((param) => {
+      if (this._customRefMappings.has(param.ref)) {
+        const selector = this._customRefMappings.get(param.ref);
+        if (selector) {
+          return this.page.locator(selector).describe(param.element);
+        }
+      }
       if (!snapshot.includes(`[ref=${param.ref}]`)) {
         const availableRefs = this._getAvailableRefs(snapshot);
         throw new Error(`Ref ${param.ref} not found. Available refs: [${availableRefs.join(", ")}]. Element: ${param.element}. Consider capturing a new snapshot if the page has changed.`);

package/lib/tools/batch-execute.js

@@ -26,7 +26,7 @@ var batchExecuteTool = defineTool({
   schema: {
     name: "browser_batch_execute",
     title: "Batch Execute Browser Actions",
-    description: `Execute multiple browser actions in sequence with optimized response handling.RECOMMENDED:Use this tool instead of individual actions when performing multiple operations to significantly reduce token usage and improve performance.BY DEFAULT use for:form filling(multiple type→click),multi-step navigation,any workflow with 2+ known steps.Saves 90% tokens vs individual calls.globalExpectation:{includeSnapshot:false,snapshotOptions:{selector:"#app"},diffOptions:{enabled:true}}.Per-step override:steps[].expectation.Example:[{tool:"browser_navigate",arguments:{url:"https://example.com"}},{tool:"browser_type",arguments:{element:"username",ref:"#user",text:"john"}},{tool:"browser_click",arguments:{element:"submit",ref:"#btn"}}].`,
+    description: `Execute multiple browser actions in sequence with optimized response handling.RECOMMENDED:Use this tool instead of individual actions when performing multiple operations to significantly reduce token usage and improve performance.BY DEFAULT use for:form filling(multiple type→click),multi-step navigation,any workflow with 2+ known steps.Saves 90% tokens vs individual calls.globalExpectation:{includeSnapshot:false,snapshotOptions:{selector:"#app"},diffOptions:{enabled:true}}.Per-step override:steps[].expectation.Example:[{tool:"browser_navigate",arguments:{url:"https://example.com"}},{tool:"browser_type",arguments:{element:"username",ref:"#user",text:"john"}},{tool:"browser_click",arguments:{element:"submit",ref:"#btn"}}].Tool names must match exactly(e.g.browser_navigate,browser_click,browser_type).`,
     inputSchema: batchExecuteSchema,
     type: "destructive"
   },

package/lib/tools/find-elements.js

@@ -62,6 +62,24 @@ var browserFindElements = defineTabTool({
         response.addResult("No elements found matching the specified criteria.");
         return;
       }
+      const batchId = tab.context.batchContext?.batchId;
+      const usesBatchRefs = Boolean(batchId);
+      if (usesBatchRefs) {
+        for (const alt of alternatives) {
+          const customRef = tab.getNextCustomRefId({ batchId });
+          tab.registerCustomRef(customRef, alt.selector);
+          alt.ref = customRef;
+        }
+      } else {
+        for (let i = 1;i <= 100; i++) {
+          tab.unregisterCustomRef(`found_${i}`);
+        }
+        for (const [index, alt] of alternatives.entries()) {
+          const customRef = `found_${index + 1}`;
+          tab.registerCustomRef(customRef, alt.selector);
+          alt.ref = customRef;
+        }
+      }
       const resultsText = formatElementResults(alternatives);
       await addDiagnosticInfoIfRequested(tab, context, resultsText);
       addPerformanceInfoIfAvailable(context, resultsText);
@@ -215,7 +233,8 @@ function formatElementResults(alternatives) {
   builder.addLine(`Found ${alternatives.length} elements matching the criteria:`);
   builder.addEmptyLine();
   for (const [index, alt] of alternatives.entries()) {
-    builder.addLine(`${index + 1}. Selector: ${alt.selector}`);
+    builder.addLine(`${index + 1}. Ref: ${alt.ref}`);
+    builder.addLine(`   Selector: ${alt.selector}`);
     builder.addLine(`   Confidence: ${formatConfidencePercentage(alt.confidence)}`);
     builder.addLine(`   Reason: ${alt.reason ?? "No reason provided"}`);
     if (index < alternatives.length - 1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tontoko/fast-playwright-mcp",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "publishConfig": {
     "access": "public"
   },