chrometools-mcp 3.3.6 → 3.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrometools-mcp",
-  "version": "3.3.6",
+  "version": "3.3.9",
   "description": "MCP (Model Context Protocol) server for Chrome automation using Puppeteer. Persistent browser sessions, UI framework detection (MUI, Ant Design, etc.), Page Object support, visual testing, Figma comparison. Works seamlessly in WSL, Linux, macOS, and Windows.",
   "type": "module",
   "main": "index.js",
@@ -48,6 +48,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2",
     "jimp": "^0.22.12",
+    "js-yaml": "^4.1.1",
     "pixelmatch": "^7.1.0",
     "puppeteer": "^24.27.0",
     "ws": "^8.18.0",

package/pom/apom-tree-converter.js

@@ -10,9 +10,10 @@
  * Runs in browser context via page.evaluate()
  *
  * @param {boolean} interactiveOnly - Only include interactive elements and their parents
+ * @param {boolean} viewportOnly - Only include elements visible in current viewport
  * @returns {Object} APOM tree structure
  */
-function buildAPOMTree(interactiveOnly = true) {
+function buildAPOMTree(interactiveOnly = true, viewportOnly = false) {
   const pageId = `page_${btoa(window.location.href).replace(/[^a-zA-Z0-9]/g, '').substring(0, 20)}_${Date.now()}`;
 
   const result = {
@@ -26,7 +27,14 @@ function buildAPOMTree(interactiveOnly = true) {
       interactiveCount: 0,
       formCount: 0,
       modalCount: 0,
-      maxDepth: 0
+      maxDepth: 0,
+      viewportOnly: viewportOnly || undefined,
+      viewport: viewportOnly ? {
+        width: window.innerWidth || document.documentElement.clientWidth,
+        height: window.innerHeight || document.documentElement.clientHeight,
+        scrollX: window.scrollX || window.pageXOffset,
+        scrollY: window.scrollY || window.pageYOffset
+      } : undefined
     }
   };
 
@@ -51,8 +59,122 @@ function buildAPOMTree(interactiveOnly = true) {
   // Collect radio and checkbox groups for easier agent access
   result.groups = collectInputGroups(result.tree);
 
+  // Detect page alerts, warnings, errors, and restrictions
+  result.alerts = detectPageAlerts();
+
   return result;
 
+  /**
+   * Detect page alerts, warnings, errors, toasts, and restrictions
+   * Uses heuristics to find notification elements
+   */
+  function detectPageAlerts() {
+    const alerts = [];
+    const seenTexts = new Set();
+    const MIN_TEXT_LENGTH = 10;  // Ignore very short texts like "19", "OK"
+
+    // Helper to add alert avoiding duplicates and substrings
+    function addAlert(type, text, source) {
+      text = text?.trim();
+      if (!text || text.length < MIN_TEXT_LENGTH || text.length > 300) return;
+
+      // Normalize text
+      const normalizedText = text.substring(0, 200);
+
+      // Skip if already seen or is substring of existing
+      if (seenTexts.has(normalizedText)) return;
+      for (const seen of seenTexts) {
+        if (seen.includes(normalizedText) || normalizedText.includes(seen)) return;
+      }
+
+      seenTexts.add(normalizedText);
+      alerts.push({ type, text: normalizedText, source });
+    }
+
+    // 1. Elements with role="alert" or aria-live (highest priority)
+    document.querySelectorAll('[role="alert"], [aria-live="assertive"]').forEach(el => {
+      const text = el.textContent?.trim();
+      addAlert('alert', text, 'aria');
+    });
+
+    // 2. Classes containing restriction keywords (high priority - affects functionality)
+    const restrictionSelector = '[class*="deactivat"], [class*="disabled"], [class*="blocked"], [class*="restrict"], [class*="suspend"], [class*="inactive"]';
+    document.querySelectorAll(restrictionSelector).forEach(el => {
+      if (!isVisibleForAlert(el)) return;
+      const text = el.textContent?.trim();
+      addAlert('restriction', text, 'class');
+    });
+
+    // 3. Error classes
+    document.querySelectorAll('[class*="error"], [class*="danger"], [class*="invalid"]').forEach(el => {
+      if (!isVisibleForAlert(el)) return;
+      const text = el.textContent?.trim();
+      addAlert('error', text, 'class');
+    });
+
+    // 4. Warning classes
+    document.querySelectorAll('[class*="warning"], [class*="warn"], [class*="caution"]').forEach(el => {
+      if (!isVisibleForAlert(el)) return;
+      const text = el.textContent?.trim();
+      addAlert('warning', text, 'class');
+    });
+
+    // 5. Toast/Snackbar notifications (usually important messages)
+    document.querySelectorAll('[class*="toast"], [class*="snackbar"], [class*="alert-banner"]').forEach(el => {
+      if (!isVisibleForAlert(el)) return;
+      const text = el.textContent?.trim();
+      addAlert('notification', text, 'toast');
+    });
+
+    // 6. SVG icons with warning colors - only for restriction/deactivated contexts
+    const warningColors = ['#FF3B30', '#FAB32F', '#FFCC00', '#FF9500', '#F44336'];
+    document.querySelectorAll('svg').forEach(svg => {
+      const svgHtml = svg.outerHTML.toLowerCase();
+      const hasWarningColor = warningColors.some(c => svgHtml.includes(c.toLowerCase()));
+      if (!hasWarningColor) return;
+
+      // Only consider if parent has restriction-related class or text
+      let parent = svg.parentElement;
+      let attempts = 0;
+      while (parent && attempts < 3) {
+        const className = parent.className?.toLowerCase() || '';
+        const text = parent.textContent?.trim() || '';
+
+        // Check if context suggests restriction/warning
+        const isRestrictionContext =
+          /deactivat|disabled|blocked|restrict|suspend|приостановлен|заблокирован/.test(className + ' ' + text.toLowerCase());
+
+        if (isRestrictionContext && text.length >= MIN_TEXT_LENGTH) {
+          addAlert('restriction', text, 'icon-color');
+          break;
+        }
+        parent = parent.parentElement;
+        attempts++;
+      }
+    });
+
+    // 7. Elements with semantic key/name attributes
+    document.querySelectorAll('[key*="error"], [key*="warning"], [key*="deactivat"], [key*="block"]').forEach(el => {
+      const parent = el.closest('div, span, p');
+      if (parent) {
+        const text = parent.textContent?.trim();
+        addAlert('warning', text, 'semantic-attr');
+      }
+    });
+
+    // Return only if there are meaningful alerts
+    return alerts.length > 0 ? alerts : undefined;
+  }
+
+  /**
+   * Check if element is visible (for alert detection)
+   */
+  function isVisibleForAlert(el) {
+    if (el.offsetWidth === 0 || el.offsetHeight === 0) return false;
+    const style = window.getComputedStyle(el);
+    return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+  }
+
   /**
    * Collect radio and checkbox groups from the tree
    */
@@ -148,6 +270,32 @@ function buildAPOMTree(interactiveOnly = true) {
     return node;
   }
 
+  /**
+   * Filter out null, undefined, and empty string values from object
+   * to reduce JSON output size
+   */
+  function filterNullValues(obj) {
+    if (!obj || typeof obj !== 'object') return obj;
+
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      // Skip null, undefined, and empty strings
+      if (value === null || value === undefined || value === '') continue;
+      // Skip false for boolean fields (keep true)
+      if (value === false) continue;
+      // Recursively filter nested objects (but not arrays)
+      if (typeof value === 'object' && !Array.isArray(value)) {
+        const filtered = filterNullValues(value);
+        if (Object.keys(filtered).length > 0) {
+          result[key] = filtered;
+        }
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  }
+
   /**
    * Check if cursor:pointer is explicitly set (not inherited)
    */
@@ -206,9 +354,9 @@ function buildAPOMTree(interactiveOnly = true) {
         // tabindex (except -1)
         (el.hasAttribute('tabindex') && el.getAttribute('tabindex') !== '-1') ||
         // contenteditable
-        el.getAttribute('contenteditable') === 'true'
-        // Note: We skip event listener check here for performance
-        // as querySelectorAll can return thousands of elements
+        el.getAttribute('contenteditable') === 'true' ||
+        // Click event listeners (Angular, React, Vue) via monkey-patched addEventListener tracker
+        hasExplicitClickBinding(el)
       );
 
       if (isInteractive && isVisible(el)) {
@@ -229,6 +377,23 @@ function buildAPOMTree(interactiveOnly = true) {
     interactiveElements.add(document.body);
   }
 
+  /**
+   * Check if element is in viewport
+   */
+  function isInViewport(el) {
+    const rect = el.getBoundingClientRect();
+    const viewportHeight = window.innerHeight || document.documentElement.clientHeight;
+    const viewportWidth = window.innerWidth || document.documentElement.clientWidth;
+
+    // Element is in viewport if any part of it is visible
+    return (
+      rect.bottom > 0 &&
+      rect.right > 0 &&
+      rect.top < viewportHeight &&
+      rect.left < viewportWidth
+    );
+  }
+
   /**
    * Check if element is visible
    * More reliable check that works with position:fixed elements (Angular Material, etc.)
@@ -248,6 +413,11 @@ function buildAPOMTree(interactiveOnly = true) {
     // For body element, always consider visible if dimensions > 0
     if (el === document.body) return true;
 
+    // Check viewport if viewportOnly mode is enabled
+    if (viewportOnly && !isInViewport(el)) {
+      return false;
+    }
+
     // Additional check: element should be in viewport or have offsetParent
     // This handles elements inside position:fixed containers (Angular Material)
     return el.offsetParent !== null || style.position === 'fixed' || style.position === 'sticky';
@@ -297,19 +467,23 @@ function buildAPOMTree(interactiveOnly = true) {
       node = {
         id,
         tag: element.tagName.toLowerCase(),
-        position,
         type: elementType.type,
         children: []
       };
 
+      // Only include position if not static (position is null for static)
+      if (position) {
+        node.position = position;
+      }
+
       // Add selector only in includeAll mode
       if (!interactiveOnly) {
         node.selector = selector;
       }
 
-      // Add metadata for interactive elements
+      // Add metadata for interactive elements, filtering out null/undefined values
       if (elementType.metadata) {
-        node.metadata = elementType.metadata;
+        node.metadata = filterNullValues(elementType.metadata);
       }
     } else {
       // Containers: compact format "tag_id": [children] when interactiveOnly
@@ -340,8 +514,8 @@ function buildAPOMTree(interactiveOnly = true) {
     if (elementType.type === 'form') {
       result.metadata.formCount++;
     }
-    if (position.type === 'fixed' || position.type === 'absolute') {
-      if (position.zIndex >= 100) {
+    if (position && (position.type === 'fixed' || position.type === 'absolute')) {
+      if (position.zIndex && position.zIndex >= 100) {
         result.metadata.modalCount++;
       }
     }
@@ -365,6 +539,11 @@ function buildAPOMTree(interactiveOnly = true) {
       return compactNode;
     }
 
+    // Remove empty children array to reduce output size
+    if (node.children && node.children.length === 0) {
+      delete node.children;
+    }
+
     return node;
   }
 
@@ -379,37 +558,30 @@ function buildAPOMTree(interactiveOnly = true) {
 
   /**
    * Get positioning information
+   * Returns null for static position (default) to reduce output size
    */
   function getPositionInfo(element) {
     const style = window.getComputedStyle(element);
     const position = style.position;
-    const zIndex = style.zIndex === 'auto' ? 'auto' : parseInt(style.zIndex, 10);
 
-    // Check if creates stacking context
-    const isStacking =
-      position === 'fixed' ||
-      position === 'sticky' ||
-      (position === 'absolute' && zIndex !== 'auto') ||
-      (position === 'relative' && zIndex !== 'auto') ||
-      parseFloat(style.opacity) < 1 ||
-      style.transform !== 'none' ||
-      style.filter !== 'none' ||
-      style.perspective !== 'none' ||
-      style.clipPath !== 'none' ||
-      style.mask !== 'none' ||
-      style.mixBlendMode !== 'normal' ||
-      style.isolation === 'isolate';
+    // Skip static position (default) - no need to include
+    if (position === 'static') {
+      return null;
+    }
 
-    return {
-      type: position,
-      zIndex: zIndex,
-      isStacking: isStacking,
-      // Additional positioning properties for modals/overlays detection
-      hasBackdrop: style.backgroundColor !== 'rgba(0, 0, 0, 0)' &&
-                   (position === 'fixed' || position === 'absolute'),
-      isFullscreen: element.offsetWidth >= window.innerWidth * 0.9 &&
-                    element.offsetHeight >= window.innerHeight * 0.9
+    const zIndex = style.zIndex === 'auto' ? 'auto' : parseInt(style.zIndex, 10);
+
+    // Only include non-default values
+    const result = {
+      type: position
     };
+
+    // Only include zIndex if it's not 'auto'
+    if (zIndex !== 'auto') {
+      result.zIndex = zIndex;
+    }
+
+    return result;
   }
 
   /**
@@ -426,24 +598,80 @@ function buildAPOMTree(interactiveOnly = true) {
   }
 
   /**
-   * Check if element has click event listeners
+   * Check if tag is a custom element (Web Component / Framework component)
+   */
+  function isCustomElement(tag) {
+    // Custom elements must contain a hyphen
+    return tag.includes('-');
+  }
+
+  /**
+   * Check if element has explicit click binding (framework attributes or addEventListener)
+   * Uses monkey-patched addEventListener tracker for framework detection (Angular, React, Vue)
    */
-  function hasClickListener(element) {
-    try {
-      // Check for getEventListeners (available in Chrome DevTools context)
-      if (typeof getEventListeners === 'function') {
-        const listeners = getEventListeners(element);
-        return listeners && listeners.click && listeners.click.length > 0;
+  function hasExplicitClickBinding(element) {
+    // Check for framework-specific click bindings (attributes)
+    const attrs = element.attributes;
+    for (let i = 0; i < attrs.length; i++) {
+      const name = attrs[i].name.toLowerCase();
+      // Angular: (click), Angular.js: ng-click
+      // Vue: @click, v-on:click
+      // React: onClick (but this is a property, not attribute)
+      if (name === '(click)' || name === 'ng-click' ||
+          name === '@click' || name === 'v-on:click' ||
+          name.startsWith('on') && name.includes('click')) {
+        return true;
       }
+    }
+    // Check onclick property
+    if (element.onclick) return true;
+    // Check onclick attribute
+    if (element.hasAttribute('onclick')) return true;
+
+    // Check for click listeners added via addEventListener (framework detection)
+    // This is injected by page-manager.js via evaluateOnNewDocument
+    if (typeof window.__hasClickListener === 'function' && window.__hasClickListener(element)) {
+      return true;
+    }
 
-      // Fallback: check for common event listener markers
-      // Note: This is not 100% reliable but catches common cases
-      return element._events?.click ||
-             element.__listeners?.click ||
-             element.__eventListeners?.click;
-    } catch (e) {
-      return false;
+    return false;
+  }
+
+  /**
+   * Find click handler for interactive elements (bubbling search)
+   * Searches UP from element to find ancestor with explicit click binding
+   * Returns "tag:id" format like "div:container_19" or null if not found
+   */
+  function findClickHandler(element) {
+    const tag = element.tagName.toLowerCase();
+
+    // Check self first - native interactive elements handle their own clicks
+    if (hasExplicitClickBinding(element) ||
+        ['button', 'a', 'input', 'select'].includes(tag) ||
+        element.getAttribute('role') === 'button') {
+      return null;  // element handles its own click, no need for clickTarget
+    }
+
+    // Search UP (like event bubbling) - find ancestor with explicit click handler
+    let parent = element.parentElement;
+    let depth = 0;
+    const maxDepth = 5;  // limit to prevent hanging
+
+    while (parent && depth < maxDepth) {
+      if (hasExplicitClickBinding(parent)) {
+        // Found real click handler
+        const parentId = elementIds.get(parent);
+        if (parentId) {
+          const parentTag = parent.tagName.toLowerCase();
+          return `${parentTag}:${parentId}`;
+        }
+      }
+      parent = parent.parentElement;
+      depth++;
     }
+
+    // No click handler found - return null (no fallback!)
+    return null;
   }
 
   /**
@@ -483,8 +711,8 @@ function buildAPOMTree(interactiveOnly = true) {
       return { isInteractive: true, reason: 'cursor-pointer' };
     }
 
-    // 6. Elements with click event listeners
-    if (hasClickListener(element)) {
+    // 6. Elements with click event listeners (framework handlers: Angular, React, Vue)
+    if (hasExplicitClickBinding(element)) {
       return { isInteractive: true, reason: 'event-listener' };
     }
 
@@ -680,12 +908,20 @@ function buildAPOMTree(interactiveOnly = true) {
 
     // Generic container - check for JavaScript interactivity
     const interactivityCheck = checkInteractivity(element);
+
+    // For ALL interactive elements, search for click handler (bubbling)
+    // Returns "tag:id" format or null if not found
+    const clickTarget = interactivityCheck.isInteractive
+      ? findClickHandler(element)
+      : null;
+
     return {
       type: 'container',
       isInteractive: interactivityCheck.isInteractive,
       metadata: interactivityCheck.isInteractive ? {
         text: element.textContent?.trim().substring(0, 100) || '',
-        interactivityReason: interactivityCheck.reason
+        interactivityReason: interactivityCheck.reason,
+        clickTarget: clickTarget || undefined
       } : null
     };
   }

package/recorder/page-object-generator.js

@@ -33,6 +33,19 @@ export async function generatePageObject(page, options = {}) {
   // Generate code based on framework
   const code = await generateCode(finalClassName, elementGroups, pageAnalysis, framework, includeComments);
 
+  // Build structured elements metadata for POM integration
+  const allElements = Object.values(elementGroups).flat();
+  const uniqueElements = deduplicateElements(allElements);
+  const lang = framework.includes('python') ? 'python' : framework.includes('java') ? 'java' : 'typescript';
+  const elements = uniqueElements.map(el => ({
+    name: sanitizeIdentifier(el.name, lang),
+    selector: el.selector,
+    tag: el.tag,
+    type: el.type,
+    methodName: generateMethodName(el, framework),
+    methodType: getMethodType(el)
+  }));
+
   return {
     success: true,
     className: finalClassName,
@@ -41,7 +54,8 @@ export async function generatePageObject(page, options = {}) {
     elementCount: pageAnalysis.elements.length,
     groups: Object.keys(elementGroups),
     framework,
-    code
+    code,
+    elements
   };
 }
 
@@ -728,6 +742,36 @@ function generateSeleniumJavaActionMethods(lines, elements) {
   });
 }
 
+/**
+ * Helper: Determine method type for element
+ * @param {Object} el - Element info
+ * @returns {string} - "fill" | "click" | "select"
+ */
+function getMethodType(el) {
+  if (el.tag === 'select') return 'select';
+  if (el.tag === 'input' || el.tag === 'textarea') return 'fill';
+  return 'click';
+}
+
+/**
+ * Helper: Generate method name for element based on framework
+ * @param {Object} el - Element info
+ * @param {string} framework - Target framework
+ * @returns {string} - Method name (e.g., "fillUsername", "clickSubmit", "fill_username")
+ */
+function generateMethodName(el, framework) {
+  const methodType = getMethodType(el);
+  const isPython = framework.includes('python');
+  const lang = isPython ? 'python' : framework.includes('java') ? 'java' : 'typescript';
+  const name = sanitizeIdentifier(el.name, lang);
+
+  if (isPython) {
+    return `${methodType}_${name}`;
+  }
+  // TypeScript/Java: camelCase
+  return `${methodType}${capitalize(name)}`;
+}
+
 /**
  * Helper: Capitalize first letter
  */

package/server/tool-definitions.js

@@ -238,7 +238,7 @@ export const toolDefinitions = [
       },
       {
         name: "drag",
-        description: "Drag element in any direction. For maps, charts, SVG, canvas, sliders. Use scrollHorizontal for scrollbars.",
+        description: "Drag element in any direction. For maps, charts, SVG, canvas, sliders. Use mode='synthetic' for JS libraries (frappe-gantt, jQuery UI). Use scrollHorizontal for scrollbars.",
         inputSchema: {
           type: "object",
           properties: {
@@ -246,6 +246,7 @@ export const toolDefinitions = [
             direction: { type: "string", enum: ["up", "down", "left", "right", "up-left", "up-right", "down-left", "down-right"], description: "Drag direction" },
             distance: { type: "number", description: "Distance in pixels (default: 100)" },
             duration: { type: "number", description: "Drag duration in ms (default: 500)" },
+            mode: { type: "string", enum: ["native", "synthetic"], description: "Drag mode: 'native' (default, faster) or 'synthetic' (better for JS libraries)" },
           },
           required: ["selector", "direction"],
         },
@@ -477,7 +478,7 @@ export const toolDefinitions = [
       },
       {
         name: "analyzePage",
-        description: "PRIMARY tool for reading page state. Returns APOM tree: {tree, metadata, groups}. Compact format (default): containers as \"tag_id\":[children] keys, interactive elements as {id, tag, type, position, metadata} without selectors. Use element IDs (e.g., button_45, input_20) with click/type tools. Selectors registered internally for resolution. Use refresh:true after clicks. Efficient: 8-10k tokens vs screenshot 15-25k.",
+        description: "PRIMARY tool for reading page state. Returns APOM tree: {tree, metadata, groups}. Compact format (default): containers as \"tag_id\":[children] keys, interactive elements as {id, tag, type, position, metadata} without selectors. Use element IDs (e.g., button_45, input_20) with click/type tools. Selectors registered internally for resolution. Use refresh:true after clicks. Efficient: 8-10k tokens vs screenshot 15-25k. Legend: clickTarget format is \"tag:id\" (e.g., \"kp-chats-list-item:container_58\") - use the id part for clicking. No clickTarget = element handles its own click.",
         inputSchema: {
           type: "object",
           properties: {
@@ -486,6 +487,8 @@ export const toolDefinitions = [
             useLegacyFormat: { type: "boolean", description: "Return legacy format instead of APOM (default: false - APOM is now default)" },
             registerElements: { type: "boolean", description: "Auto-register elements in selector resolver (default: true)" },
             groupBy: { type: "string", description: "Group elements: 'type' or 'flat' (default: 'type')", enum: ["type", "flat"] },
+            viewportOnly: { type: "boolean", description: "Only analyze elements in current viewport (default: false). Reduces output for long pages." },
+            diff: { type: "boolean", description: "Return only changes since last analysis: {added, removed, changed} (default: false)." },
           },
         },
       },
@@ -683,7 +686,7 @@ export const toolDefinitions = [
       },
       {
         name: "exportScenarioAsCode",
-        description: "Export scenario as test code for NEW file. Cleans unstable selectors, optionally generates Page Object. Use appendScenarioToFile for existing files.",
+        description: "Export scenario as test code for NEW file. Supports Page Object integration: 'generate-integrated' generates POM + test using it, 'use-existing' generates test using existing POM file. Use appendScenarioToFile for existing files.",
         inputSchema: {
           type: "object",
           properties: {
@@ -706,19 +709,28 @@ export const toolDefinitions = [
             },
             generatePageObject: {
               type: "boolean",
-              description: "Also generate Page Object class for the page (default: false)"
+              description: "Also generate Page Object class for the page (default: false). Legacy - use pageObjectMode instead."
             },
             pageObjectClassName: {
               type: "string",
               description: "Page Object class name (optional, auto-generated if not provided)"
             },
+            pageObjectMode: {
+              type: "string",
+              enum: ["none", "generate", "generate-integrated", "use-existing"],
+              description: "POM integration: 'none' (default), 'generate' (separate POM), 'generate-integrated' (POM + test using it), 'use-existing' (test uses existing POM file)"
+            },
+            pageObjectFile: {
+              type: "string",
+              description: "Path to existing POM file (required for 'use-existing' mode)"
+            },
           },
           required: ["scenarioName", "language"],
         },
       },
       {
         name: "appendScenarioToFile",
-        description: "Append scenario as test code to EXISTING file. Cleans unstable selectors, optionally generates Page Object. Use exportScenarioAsCode for new files.",
+        description: "Append scenario as test code to EXISTING file. Supports Page Object integration: 'generate-integrated' generates POM + test using it, 'use-existing' generates test using existing POM file. Use exportScenarioAsCode for new files.",
         inputSchema: {
           type: "object",
           properties: {
@@ -758,7 +770,16 @@ export const toolDefinitions = [
             },
             generatePageObject: {
               type: "boolean",
-              description: "Also generate Page Object class for the page (default: false)"
+              description: "Also generate Page Object class for the page (default: false). Legacy - use pageObjectMode instead."
+            },
+            pageObjectMode: {
+              type: "string",
+              enum: ["none", "generate", "generate-integrated", "use-existing"],
+              description: "POM integration: 'none' (default), 'generate' (separate POM), 'generate-integrated' (POM + test using it), 'use-existing' (test uses existing POM file)"
+            },
+            pageObjectFile: {
+              type: "string",
+              description: "Path to existing POM file (required for 'use-existing' mode)"
             },
             pageObjectClassName: {
               type: "string",
@@ -819,4 +840,34 @@ export const toolDefinitions = [
           required: ["tab"],
         },
       },
+      {
+        name: "loadSwagger",
+        description: "Load and parse OpenAPI/Swagger spec from URL or local file. Returns structured summary: endpoints, schemas, auth types, base URL. Supports both OpenAPI 2.0 (Swagger) and 3.x, JSON and YAML formats. Use this first to understand an API before generating models or client code.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            source: { type: "string", description: "URL (http/https) or local file path to swagger.json / openapi.yaml" },
+            format: { type: "string", enum: ["auto", "json", "yaml"], description: "Spec format. 'auto' (default) detects from extension/content" },
+          },
+          required: ["source"],
+        },
+      },
+      {
+        name: "generateApiModels",
+        description: "Generate typed data models from OpenAPI/Swagger spec. Creates TypeScript interfaces/types or Python dataclasses/pydantic/TypedDict from API schemas. Handles $ref resolution, enums, allOf/oneOf, nested objects. Use after loadSwagger to generate model files.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            source: { type: "string", description: "URL or file path to OpenAPI spec" },
+            language: { type: "string", enum: ["typescript", "python"], description: "Target language for models" },
+            format: { type: "string", enum: ["auto", "json", "yaml"], description: "Spec format (default: auto)" },
+            style: { type: "string", enum: ["interface", "type"], description: "TypeScript only: 'interface' (default) or 'type' aliases" },
+            pythonStyle: { type: "string", enum: ["dataclass", "pydantic", "typeddict"], description: "Python only: 'dataclass' (default), 'pydantic', or 'typeddict'" },
+            includeEnums: { type: "boolean", description: "Generate enum types (default: true)" },
+            includeValidation: { type: "boolean", description: "Include validation constraints as comments (default: false)" },
+            schemas: { type: "array", items: { type: "string" }, description: "Generate only these schemas (default: all)" },
+          },
+          required: ["source", "language"],
+        },
+      },
 ];