chrometools-mcp 3.3.8 → 3.4.0

package/index.js

@@ -72,6 +72,12 @@ import {PlaywrightPythonGenerator} from './utils/code-generators/playwright-pyth
 import {SeleniumPythonGenerator} from './utils/code-generators/selenium-python.js';
 import {SeleniumJavaGenerator} from './utils/code-generators/selenium-java.js';
 import {FileAppender} from './utils/code-generators/file-appender.js';
+import {parsePomFile} from './utils/code-generators/pom-integrator.js';
+
+// Import OpenAPI / Swagger tools
+import {OpenAPIParser} from './utils/openapi/parser.js';
+import {ApiModelsTypeScriptGenerator} from './utils/api-generators/api-models-typescript.js';
+import {ApiModelsPythonGenerator} from './utils/api-generators/api-models-python.js';
 // Import Figma tools
 import {
     collectAllText,
@@ -343,6 +349,13 @@ async function executeToolInternal(name, args) {
 
       let hintsText = '\n\n** AI HINTS **';
       hintsText += `\nPage type: ${hints.pageType}`;
+      if (hints.heading) {
+        hintsText += `\nPage heading: "${hints.heading}"`;
+      }
+      if (hints.authRedirect) {
+        hintsText += `\n⚠️ AUTH REDIRECT: Page redirected to login (intended: ${hints.authRedirect.returnUrl || 'unknown'})`;
+        hintsText += `\n  → Session/cookies not established. Login first, then retry navigation.`;
+      }
       if (hints.availableActions.length > 0) {
         hintsText += `\nAvailable actions: ${hints.availableActions.join(', ')}`;
       }
@@ -475,23 +488,74 @@ async function executeToolInternal(name, args) {
         // ALWAYS scroll to element first to ensure it's in viewport
         await element.evaluate(el => el.scrollIntoView({ behavior: 'instant', block: 'center' }));
 
-        // Click with timeout to prevent hanging on navigation
+        // Click with adaptive fallback strategy:
+        //
+        // Pre-check: elementFromPoint() determines if element is the topmost at its center.
+        // This decides the click path — Puppeteer's click() doesn't always throw on interception.
+        //
+        // Path A (element covered by another, e.g. small button under <a routerLink>):
+        //   → JS element.click() — DOM dispatch bypasses coordinate hit-testing
+        //
+        // Path B (element is topmost — normal case):
+        //   Tier 1: Puppeteer native click (trusted CDP events)
+        //   Tier 2: page.mouse.click at coordinates (trusted CDP, no interception check)
+        //   Tier 3: JS element.click() (untrusted, last resort)
+        //   Trusted CDP events (Tier 1 & 2) are critical for Angular/Zone.js apps where
+        //   untrusted .click() triggers change detection mid-dispatch, destroying *ngFor elements.
         const clickWithTimeout = async (timeoutMs = 5000) => {
-          const clickPromise = element.click().catch(() => {
-            // If Puppeteer click fails, fallback to JS click
-            return element.evaluate(el => el.click());
-          });
-          const timeoutPromise = new Promise((_, reject) =>
-            setTimeout(() => reject(new Error('click timeout')), timeoutMs)
-          );
-          return Promise.race([clickPromise, timeoutPromise]).catch(() => {
-            // If click times out, try JS click as last resort
-            return element.evaluate(el => el.click());
+          const withTimeout = (promise) => Promise.race([
+            promise,
+            new Promise((_, reject) => setTimeout(() => reject(new Error('click timeout')), timeoutMs))
+          ]);
+
+          // Pre-check: is another element covering our target at its center coordinates?
+          const intercepted = await element.evaluate(el => {
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 || rect.height === 0) return false;
+            const cx = rect.left + rect.width / 2;
+            const cy = rect.top + rect.height / 2;
+            const topEl = document.elementFromPoint(cx, cy);
+            // topEl is our element or a child of it — not intercepted
+            return topEl !== el && !el.contains(topEl);
           });
+
+          if (intercepted) {
+            // Path A: Element is covered (e.g., small button under <a routerLink>)
+            // Coordinate clicks would hit the covering element — use DOM dispatch
+            await element.evaluate(el => el.click());
+            return;
+          }
+
+          // Path B: Element is topmost — use trusted CDP events
+          // Tier 1: Puppeteer native click
+          try {
+            await withTimeout(element.click());
+            return;
+          } catch (e) { /* fall through to Tier 2 */ }
+
+          // Tier 2: CDP coordinate click — trusted events, bypasses Puppeteer's own checks
+          try {
+            const box = await element.boundingBox();
+            if (box) {
+              await withTimeout(page.mouse.click(box.x + box.width / 2, box.y + box.height / 2));
+              return;
+            }
+          } catch (e) { /* fall through to Tier 3 */ }
+
+          // Tier 3: JS click — untrusted, last resort
+          await element.evaluate(el => el.click());
         };
 
         await clickWithTimeout();
 
+        // Check if element was detached from DOM during click (Angular *ngFor + Zone.js pattern)
+        let elementDetached = false;
+        try {
+          elementDetached = await element.evaluate(el => !el.parentNode);
+        } catch (e) {
+          // Element handle may be invalid if page navigated — not a detachment issue
+        }
+
         // NEW POST-CLICK PATTERN:
         // 1. Run post-click diagnostics (waits for network requests within 200ms, max 10s timeout)
         let diagnostics;
@@ -521,10 +585,48 @@ async function executeToolInternal(name, args) {
 
         // 3. Format output with hints and diagnostics
         let hintsText = '\n\n** AI HINTS **';
-        if (hints.modalOpened) hintsText += '\nModal opened - interact with it or close';
-        if (hints.newElements.length > 0) {
-          hintsText += `\nNew elements appeared: ${hints.newElements.map(e => e.type).join(', ')}`;
+
+        // Modal: show title, body text, and actions
+        if (hints.modalOpened && hints.newElements.some(e => e.type === 'modal')) {
+          const modal = hints.newElements.find(e => e.type === 'modal');
+          let modalText = 'Modal opened';
+          if (modal.title) modalText += `: "${modal.title}"`;
+          if (modal.text) modalText += `\n  ${modal.text}`;
+          if (modal.actions?.length) modalText += `\n  Actions: [${modal.actions.join('] [')}]`;
+          hintsText += '\n' + modalText;
+        } else if (hints.modalOpened) {
+          hintsText += '\nModal opened - interact with it or close';
         }
+
+        // Overlay: show items
+        const overlay = hints.newElements.find(e => e.type === 'dropdown' || e.type === 'menu');
+        if (overlay?.items?.length) {
+          const label = overlay.type === 'menu' ? 'Menu' : 'Dropdown';
+          hintsText += `\n${label} with ${overlay.totalCount} options: ${overlay.items.join(', ')}`;
+        }
+
+        // Other new elements (alerts, etc.)
+        const otherElements = hints.newElements.filter(e => e.type !== 'modal' && e.type !== 'dropdown' && e.type !== 'menu');
+        if (otherElements.length > 0) {
+          hintsText += `\nNew elements appeared: ${otherElements.map(e => e.text ? `${e.type}: ${e.text}` : e.type).join(', ')}`;
+        }
+
+        // Auth redirect after click (session expired, protected route)
+        if (hints.authRedirect) {
+          hintsText += '\n⚠️ AUTH REDIRECT: Landed on login page. Session may have expired.';
+        }
+
+        // Element detached during click (Angular *ngFor + Zone.js)
+        if (elementDetached) {
+          hintsText += '\n⚠️ ELEMENT DETACHED: Element was removed from DOM during click — handler did NOT fire.';
+          hintsText += '\n   Cause: Angular Zone.js triggers change detection mid-click, *ngFor recreates elements.';
+          hintsText += '\n   App fix: add trackBy to *ngFor, or cache array reference instead of returning new one.';
+          hintsText += '\n   Workaround via executeScript:';
+          hintsText += "\n   1. Find component: ng.getComponent(document.querySelector('component-tag'))";
+          hintsText += "\n   2. Explore API: Object.keys(comp).filter(k => k.includes('Event'))";
+          hintsText += '\n   3. Emit: comp.someChangeEvent.emit(selectedOption)';
+        }
+
         if (hints.suggestedNext.length > 0) {
           hintsText += `\nSuggested next: ${hints.suggestedNext.join('; ')}`;
         }
@@ -1245,6 +1347,7 @@ async function executeToolInternal(name, args) {
 
       const distance = validatedArgs.distance || 100;
       const duration = validatedArgs.duration || 500;
+      const mode = validatedArgs.mode || 'native';
 
       // Calculate drag deltas based on direction
       let deltaX = 0;
@@ -1281,62 +1384,166 @@ async function executeToolInternal(name, args) {
           break;
       }
 
-      // Get element center position for drag start
-      const elementInfo = await page.evaluate((selector) => {
-        const element = document.querySelector(selector);
-        if (!element) {
-          return { success: false, error: `Element not found: ${selector}` };
+      if (mode === 'synthetic') {
+        // Synthetic mode: dispatch DOM events for better JS library compatibility
+        const result = await page.evaluate((selector, deltaX, deltaY, duration) => {
+          const element = document.querySelector(selector);
+          if (!element) {
+            return { success: false, error: `Element not found: ${selector}` };
+          }
+
+          const rect = element.getBoundingClientRect();
+          const startX = rect.left + rect.width / 2;
+          const startY = rect.top + rect.height / 2;
+          const endX = startX + deltaX;
+          const endY = startY + deltaY;
+
+          // Helper to create mouse/pointer event
+          const createEvent = (type, clientX, clientY, buttons = 0) => {
+            // Try PointerEvent first (modern browsers)
+            if (typeof PointerEvent !== 'undefined') {
+              return new PointerEvent(type, {
+                bubbles: true,
+                cancelable: true,
+                view: window,
+                clientX,
+                clientY,
+                screenX: clientX,
+                screenY: clientY,
+                buttons,
+                button: 0,
+                pointerId: 1,
+                pointerType: 'mouse',
+                isPrimary: true
+              });
+            }
+            // Fallback to MouseEvent
+            return new MouseEvent(type, {
+              bubbles: true,
+              cancelable: true,
+              view: window,
+              clientX,
+              clientY,
+              screenX: clientX,
+              screenY: clientY,
+              buttons,
+              button: 0
+            });
+          };
+
+          // Dispatch mousedown/pointerdown
+          element.dispatchEvent(createEvent('pointerdown', startX, startY, 1));
+          element.dispatchEvent(createEvent('mousedown', startX, startY, 1));
+
+          // Dispatch intermediate mousemove/pointermove events
+          const steps = Math.max(10, Math.floor(duration / 20));
+          const stepDelay = duration / steps;
+
+          return new Promise((resolve) => {
+            let currentStep = 0;
+
+            const moveInterval = setInterval(() => {
+              currentStep++;
+              const progress = currentStep / steps;
+              const currentX = startX + (deltaX * progress);
+              const currentY = startY + (deltaY * progress);
+
+              element.dispatchEvent(createEvent('pointermove', currentX, currentY, 1));
+              element.dispatchEvent(createEvent('mousemove', currentX, currentY, 1));
+
+              if (currentStep >= steps) {
+                clearInterval(moveInterval);
+
+                // Dispatch mouseup/pointerup
+                element.dispatchEvent(createEvent('pointerup', endX, endY, 0));
+                element.dispatchEvent(createEvent('mouseup', endX, endY, 0));
+                element.dispatchEvent(createEvent('click', endX, endY, 0));
+
+                resolve({
+                  success: true,
+                  startX: Math.round(startX),
+                  startY: Math.round(startY),
+                  endX: Math.round(endX),
+                  endY: Math.round(endY),
+                  mode: 'synthetic'
+                });
+              }
+            }, stepDelay);
+          });
+        }, validatedArgs.selector, deltaX, deltaY, duration);
+
+        if (!result.success) {
+          throw new Error(result.error);
         }
 
-        const rect = element.getBoundingClientRect();
         return {
-          success: true,
-          centerX: rect.left + rect.width / 2,
-          centerY: rect.top + rect.height / 2,
-          width: rect.width,
-          height: rect.height
+          content: [{
+            type: "text",
+            text: `Dragged ${validatedArgs.selector} ${validatedArgs.direction} by ${distance}px (${result.mode} mode):\n` +
+                  `  Start position: (${result.startX}, ${result.startY})\n` +
+                  `  End position: (${result.endX}, ${result.endY})\n` +
+                  `  Delta: (${deltaX}px, ${deltaY}px)\n` +
+                  `  Duration: ${duration}ms\n` +
+                  `  Events: pointerdown → ${Math.floor(duration / 20)} × pointermove → pointerup`
+          }],
         };
-      }, validatedArgs.selector);
+      } else {
+        // Native mode: use Puppeteer mouse API (default, faster)
+        const elementInfo = await page.evaluate((selector) => {
+          const element = document.querySelector(selector);
+          if (!element) {
+            return { success: false, error: `Element not found: ${selector}` };
+          }
 
-      if (!elementInfo.success) {
-        throw new Error(elementInfo.error);
-      }
+          const rect = element.getBoundingClientRect();
+          return {
+            success: true,
+            centerX: rect.left + rect.width / 2,
+            centerY: rect.top + rect.height / 2,
+            width: rect.width,
+            height: rect.height
+          };
+        }, validatedArgs.selector);
+
+        if (!elementInfo.success) {
+          throw new Error(elementInfo.error);
+        }
 
-      // Perform drag: mousedown → mousemove → mouseup
-      const startX = elementInfo.centerX;
-      const startY = elementInfo.centerY;
-      const endX = startX + deltaX;
-      const endY = startY + deltaY;
+        const startX = elementInfo.centerX;
+        const startY = elementInfo.centerY;
+        const endX = startX + deltaX;
+        const endY = startY + deltaY;
 
-      // Move to start position
-      await page.mouse.move(startX, startY);
+        // Move to start position
+        await page.mouse.move(startX, startY);
 
-      // Press mouse button (start drag)
-      await page.mouse.down();
+        // Press mouse button (start drag)
+        await page.mouse.down();
 
-      // Wait a bit to ensure drag is registered
-      await new Promise(resolve => setTimeout(resolve, 50));
+        // Wait a bit to ensure drag is registered
+        await new Promise(resolve => setTimeout(resolve, 50));
 
-      // Move mouse to end position (drag)
-      const steps = Math.max(10, Math.floor(duration / 20)); // Smooth movement
-      await page.mouse.move(endX, endY, { steps });
+        // Move mouse to end position (drag)
+        const steps = Math.max(10, Math.floor(duration / 20)); // Smooth movement
+        await page.mouse.move(endX, endY, { steps });
 
-      // Wait for duration
-      await new Promise(resolve => setTimeout(resolve, Math.max(0, duration - steps * 20)));
+        // Wait for duration
+        await new Promise(resolve => setTimeout(resolve, Math.max(0, duration - steps * 20)));
 
-      // Release mouse button (end drag)
-      await page.mouse.up();
+        // Release mouse button (end drag)
+        await page.mouse.up();
 
-      return {
-        content: [{
-          type: "text",
-          text: `Dragged ${validatedArgs.selector} ${validatedArgs.direction} by ${distance}px:\n` +
-                `  Start position: (${Math.round(startX)}, ${Math.round(startY)})\n` +
-                `  End position: (${Math.round(endX)}, ${Math.round(endY)})\n` +
-                `  Delta: (${deltaX}px, ${deltaY}px)\n` +
-                `  Duration: ${duration}ms`
-        }],
-      };
+        return {
+          content: [{
+            type: "text",
+            text: `Dragged ${validatedArgs.selector} ${validatedArgs.direction} by ${distance}px (native mode):\n` +
+                  `  Start position: (${Math.round(startX)}, ${Math.round(startY)})\n` +
+                  `  End position: (${Math.round(endX)}, ${Math.round(endY)})\n` +
+                  `  Delta: (${deltaX}px, ${deltaY}px)\n` +
+                  `  Duration: ${duration}ms`
+          }],
+        };
+      }
     }
 
     if (name === "scrollHorizontal") {
@@ -1515,6 +1722,13 @@ async function executeToolInternal(name, args) {
 
       let hintsText = '\n\n** AI HINTS **';
       hintsText += `\nPage type: ${hints.pageType}`;
+      if (hints.heading) {
+        hintsText += `\nPage heading: "${hints.heading}"`;
+      }
+      if (hints.authRedirect) {
+        hintsText += `\n⚠️ AUTH REDIRECT: Page redirected to login (intended: ${hints.authRedirect.returnUrl || 'unknown'})`;
+        hintsText += `\n  → Session/cookies not established. Login first, then retry navigation.`;
+      }
       if (hints.availableActions.length > 0) {
         hintsText += `\nAvailable actions: ${hints.availableActions.join(', ')}`;
       }
@@ -2105,9 +2319,12 @@ Start coding now.`;
       const maxResults = validatedArgs.maxResults || 5;
 
       // Execute smart search in page context
-      const results = await page.evaluate((description, maxResults, utilsCode) => {
+      const results = await page.evaluate((description, maxResults, utilsCode, selectorResolverCode) => {
         // Inject utilities into page context
         eval(utilsCode);
+        if (typeof registerElement === 'undefined') {
+          eval(selectorResolverCode);
+        }
 
         // Determine element type from description
         const elementType = determineElementType(description);
@@ -2163,18 +2380,29 @@ Start coding now.`;
         });
 
         // Filter and sort
-        return analyzed
+        const filtered = analyzed
           .filter(r => r.score > 5) // Minimum threshold
           .sort((a, b) => b.score - a.score)
           .slice(0, maxResults);
 
-      }, validatedArgs.description, maxResults, elementFinderUtils);
+        // Register found elements in APOM registry and assign IDs
+        filtered.forEach((result, idx) => {
+          const apomId = `smart_${result.type}_${idx}`;
+          result.id = apomId;
+          if (typeof registerElement === 'function') {
+            registerElement(apomId, result.selector, { source: 'smartFindElement' });
+          }
+        });
+
+        return filtered;
+
+      }, validatedArgs.description, maxResults, elementFinderUtils, selectorResolver);
 
       const hints = {
         totalCandidates: results.length,
         bestMatch: results[0] || null,
         suggestion: results.length > 0
-          ? `Use selector: ${results[0].selector}`
+          ? `Use id: "${results[0].id}" or selector: ${results[0].selector}`
           : 'No good matches found. Try a different description.',
       };
 
@@ -2536,13 +2764,18 @@ Start coding now.`;
       const validatedArgs = schemas.FindElementsByTextSchema.parse(args);
       const page = await getLastOpenPage();
 
-      const elements = await page.evaluate((text, exact, caseSensitive, utilsCode) => {
+      const elements = await page.evaluate((text, exact, caseSensitive, utilsCode, selectorResolverCode) => {
         eval(utilsCode);
+        if (typeof registerElement === 'undefined') {
+          eval(selectorResolverCode);
+        }
 
         const results = [];
+        const MAX_RESULTS = 40; // Collect up to 40 to allow visible/hidden sorting, cap expensive selector generation
         const searchText = caseSensitive ? text : text.toLowerCase();
 
         document.querySelectorAll('*').forEach(el => {
+          if (results.length >= MAX_RESULTS) return; // Stop expensive selector generation after enough results
           // Skip script, style, etc
           if (['SCRIPT', 'STYLE', 'NOSCRIPT', 'BR', 'HR'].includes(el.tagName)) return;
 
@@ -2564,9 +2797,16 @@ Start coding now.`;
             : compareText.includes(searchText);
 
           if (matches) {
+            const selector = getUniqueSelectorInPage(el);
+            const type = el.tagName.toLowerCase();
+            const apomId = `text_${type}_${results.length}`;
+            if (typeof registerElement === 'function') {
+              registerElement(apomId, selector, { source: 'findElementsByText' });
+            }
             results.push({
-              selector: getUniqueSelectorInPage(el),
-              type: el.tagName.toLowerCase(),
+              id: apomId,
+              selector,
+              type,
               text: elementText.substring(0, 100), // Only first 100 chars for preview
               visible: el.offsetParent !== null, // Add visibility check
             });
@@ -2574,7 +2814,7 @@ Start coding now.`;
         });
 
         return results;
-      }, validatedArgs.text, validatedArgs.exact || false, validatedArgs.caseSensitive || false, elementFinderUtils);
+      }, validatedArgs.text, validatedArgs.exact || false, validatedArgs.caseSensitive || false, elementFinderUtils, selectorResolver);
 
       // Prioritize visible elements and limit results to prevent token overflow
       const visibleElements = elements.filter(el => el.visible);
@@ -3089,13 +3329,102 @@ Start coding now.`;
         };
       }
 
+      // Resolve pageObjectMode (backward compat: generatePageObject: true -> 'generate')
+      const pageObjectMode = args.pageObjectMode || (args.generatePageObject ? 'generate' : 'none');
+
       // Select generator based on language
-      let generator;
       const options = {
         cleanSelectors: args.cleanSelectors !== false, // default true
         includeComments: args.includeComments !== false, // default true
       };
 
+      // Resolve POM elements for integrated modes
+      let pomElements = null;
+      let pomClassName = null;
+      let pomImportPath = null;
+      let pageObjectData = null;
+
+      if (pageObjectMode === 'generate-integrated' || pageObjectMode === 'generate') {
+        try {
+          const entryUrl = scenario.metadata?.entryUrl;
+          if (entryUrl) {
+            let page;
+            try {
+              page = await getLastOpenPage();
+              const currentUrl = page.url();
+              if (currentUrl !== entryUrl) {
+                await page.goto(entryUrl, { waitUntil: 'networkidle2' });
+              }
+            } catch (error) {
+              page = await getOrCreatePage(entryUrl);
+            }
+
+            const pageObjectOptions = {
+              className: args.pageObjectClassName || null,
+              framework: args.language,
+              includeComments: args.includeComments !== false,
+              groupElements: true
+            };
+
+            const pageObjectResult = await generatePageObject(page, pageObjectOptions);
+            if (pageObjectResult.success) {
+              const extension = args.language.includes('typescript') ? '.ts' :
+                               args.language.includes('java') ? '.java' : '.py';
+              pageObjectData = {
+                code: pageObjectResult.code,
+                className: pageObjectResult.className,
+                suggestedFileName: `${pageObjectResult.className}${extension}`,
+                elementCount: pageObjectResult.elementCount
+              };
+
+              if (pageObjectMode === 'generate-integrated') {
+                pomElements = pageObjectResult.elements;
+                pomClassName = pageObjectResult.className;
+              }
+            }
+          }
+        } catch (error) {
+          // Page Object generation failed, continue without it
+        }
+      } else if (pageObjectMode === 'use-existing') {
+        if (!args.pageObjectFile) {
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                error: "pageObjectFile is required for 'use-existing' mode"
+              }, null, 2)
+            }],
+            isError: true
+          };
+        }
+
+        try {
+          const pomContent = FileAppender.readFile(args.pageObjectFile);
+          const parsed = parsePomFile(pomContent, args.language);
+          pomElements = parsed.elements;
+          pomClassName = parsed.className;
+        } catch (error) {
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                error: `Failed to parse POM file: ${error.message}`
+              }, null, 2)
+            }],
+            isError: true
+          };
+        }
+      }
+
+      // Add POM options to generator
+      if (pomElements && pomClassName) {
+        options.pomElements = pomElements;
+        options.pomClassName = pomClassName;
+        options.pomImportPath = pomImportPath;
+      }
+
+      let generator;
       switch (args.language) {
         case 'playwright-typescript':
           generator = new PlaywrightTypeScriptGenerator(options);
@@ -3134,59 +3463,21 @@ Start coding now.`;
           referenceTestName: args.referenceTestName
         };
 
-        // Generate Page Object if requested
-        let pageObjectData = null;
-        if (args.generatePageObject) {
-          try {
-            const entryUrl = scenario.metadata?.entryUrl;
-            if (entryUrl) {
-              let page;
-              try {
-                page = await getLastOpenPage();
-                const currentUrl = page.url();
-                if (currentUrl !== entryUrl) {
-                  await page.goto(entryUrl, { waitUntil: 'networkidle2' });
-                }
-              } catch (error) {
-                page = await getOrCreatePage(entryUrl);
-              }
-
-              const pageObjectOptions = {
-                className: args.pageObjectClassName || null,
-                framework: args.language,
-                includeComments: args.includeComments !== false,
-                groupElements: true
-              };
-
-              const pageObjectResult = await generatePageObject(page, pageObjectOptions);
-              if (pageObjectResult.success) {
-                // Suggest filename based on className
-                const extension = args.language.includes('typescript') ? '.ts' :
-                                 args.language.includes('java') ? '.java' : '.py';
-                pageObjectData = {
-                  code: pageObjectResult.code,
-                  className: pageObjectResult.className,
-                  suggestedFileName: `${pageObjectResult.className}${extension}`,
-                  elementCount: pageObjectResult.elementCount
-                };
-              }
-            }
-          } catch (error) {
-            // Page Object generation failed, continue without it
-          }
-        }
-
         // Return JSON with instructions for Claude Code to append the test
         const result = {
           action: 'append_test',
           targetFile: args.targetFile,
-          testCode: testOnly,  // Only test code, no imports
+          testCode: testOnly,
           testName: args.testName || scenario.metadata?.name,
           insertPosition: appendOptions.insertPosition,
           referenceTestName: appendOptions.referenceTestName,
           instruction: `Read file '${args.targetFile}', append the testCode at position '${appendOptions.insertPosition}', then write the file back.`
         };
 
+        if (pomClassName) {
+          result.pomIntegration = { className: pomClassName, mode: pageObjectMode };
+        }
+
         if (pageObjectData) {
           result.pageObject = pageObjectData;
           result.instruction += ` Also create a Page Object file '${pageObjectData.suggestedFileName}' with the provided pageObject.code.`;
@@ -3228,86 +3519,48 @@ Start coding now.`;
         };
       }
 
-      // Select generator based on language
-      let generator;
+      // Resolve pageObjectMode (backward compat: generatePageObject: true -> 'generate')
+      const pageObjectMode = args.pageObjectMode || (args.generatePageObject ? 'generate' : 'none');
+
       const options = {
         cleanSelectors: args.cleanSelectors !== false, // default true
         includeComments: args.includeComments !== false, // default true
       };
 
-      switch (args.language) {
-        case 'playwright-typescript':
-          generator = new PlaywrightTypeScriptGenerator(options);
-          break;
-        case 'playwright-python':
-          generator = new PlaywrightPythonGenerator(options);
-          break;
-        case 'selenium-python':
-          generator = new SeleniumPythonGenerator(options);
-          break;
-        case 'selenium-java':
-          generator = new SeleniumJavaGenerator(options);
-          break;
-        default:
+      // Resolve POM elements for integrated modes
+      let pomElements = null;
+      let pomClassName = null;
+      let pageObjectData = null;
+      const entryUrl = scenario.metadata?.entryUrl;
+
+      if (pageObjectMode === 'generate-integrated' || pageObjectMode === 'generate') {
+        if (!entryUrl) {
           return {
             content: [{
               type: 'text',
               text: JSON.stringify({
-                error: `Unknown language: ${args.language}. Supported: playwright-typescript, playwright-python, selenium-python, selenium-java`
+                error: 'Cannot generate Page Object: scenario has no entryUrl in metadata'
               }, null, 2)
             }],
             isError: true
           };
-      }
-
-      // Generate test code with full imports
-      const testCode = generator.generate(scenario, options);
-
-      // Generate suggested filename
-      const testName = scenario.metadata?.name || 'test';
-      const extension = args.language.includes('typescript') ? '.spec.ts' :
-                       args.language.includes('java') ? 'Test.java' :
-                       args.language.includes('python') ? '_test.py' : '.test.js';
-      const suggestedFileName = args.language.includes('java')
-        ? testName.charAt(0).toUpperCase() + testName.slice(1) + 'Test.java'
-        : testName.replace(/\s+/g, '_').toLowerCase() + extension;
+        }
 
-      // If generatePageObject is requested, also generate Page Object class
-      if (args.generatePageObject) {
         try {
-          // Get page - need to open at scenario's entry URL
           let page;
-          const entryUrl = scenario.metadata?.entryUrl;
-
-          if (!entryUrl) {
-            return {
-              content: [{
-                type: 'text',
-                text: JSON.stringify({
-                  error: 'Cannot generate Page Object: scenario has no entryUrl in metadata'
-                }, null, 2)
-              }],
-              isError: true
-            };
-          }
-
-          // Try to get existing page or open new one
           try {
             page = await getLastOpenPage();
-            // Navigate to entry URL if current page is different
             const currentUrl = page.url();
             if (currentUrl !== entryUrl) {
               await page.goto(entryUrl, { waitUntil: 'networkidle2' });
             }
           } catch (error) {
-            // No page open, create new one
             page = await getOrCreatePage(entryUrl);
           }
 
-          // Generate Page Object
           const pageObjectOptions = {
             className: args.pageObjectClassName || null,
-            framework: args.language, // Use same framework as test
+            framework: args.language,
             includeComments: args.includeComments !== false,
             groupElements: true
           };
@@ -3315,71 +3568,119 @@ Start coding now.`;
           const pageObjectResult = await generatePageObject(page, pageObjectOptions);
 
           if (pageObjectResult.success) {
-            // Suggest Page Object filename
             const poExtension = args.language.includes('typescript') ? '.ts' :
                                args.language.includes('java') ? '.java' : '.py';
-            const pageObjectFileName = `${pageObjectResult.className}${poExtension}`;
-
-            // Return both test code and Page Object code
-            return {
-              content: [{
-                type: 'text',
-                text: JSON.stringify({
-                  action: 'create_new_file',
-                  suggestedFileName: suggestedFileName,
-                  testCode: testCode,
-                  pageObject: {
-                    code: pageObjectResult.code,
-                    className: pageObjectResult.className,
-                    suggestedFileName: pageObjectFileName,
-                    elementCount: pageObjectResult.elementCount
-                  },
-                  instruction: `Create a new test file '${suggestedFileName}' with the testCode. Also create a Page Object file '${pageObjectFileName}' with the pageObject.code.`
-                }, null, 2)
-              }]
-            };
-          } else {
-            // Page Object generation failed, return test code only with warning
-            return {
-              content: [{
-                type: 'text',
-                text: JSON.stringify({
-                  action: 'create_new_file',
-                  suggestedFileName: suggestedFileName,
-                  testCode: testCode,
-                  warning: 'Page Object generation failed: ' + (pageObjectResult.error || 'Unknown error'),
-                  instruction: `Create a new test file '${suggestedFileName}' with the testCode.`
-                }, null, 2)
-              }]
+            pageObjectData = {
+              code: pageObjectResult.code,
+              className: pageObjectResult.className,
+              suggestedFileName: `${pageObjectResult.className}${poExtension}`,
+              elementCount: pageObjectResult.elementCount
             };
+
+            if (pageObjectMode === 'generate-integrated') {
+              pomElements = pageObjectResult.elements;
+              pomClassName = pageObjectResult.className;
+            }
           }
         } catch (error) {
-          // Page Object generation failed, return test code only with error
+          // Page Object generation failed, continue without it
+        }
+      } else if (pageObjectMode === 'use-existing') {
+        if (!args.pageObjectFile) {
           return {
             content: [{
               type: 'text',
               text: JSON.stringify({
-                action: 'create_new_file',
-                suggestedFileName: suggestedFileName,
-                testCode: testCode,
-                warning: 'Page Object generation error: ' + error.message,
-                instruction: `Create a new test file '${suggestedFileName}' with the testCode.`
+                error: "pageObjectFile is required for 'use-existing' mode"
               }, null, 2)
-            }]
+            }],
+            isError: true
+          };
+        }
+
+        try {
+          const pomContent = FileAppender.readFile(args.pageObjectFile);
+          const parsed = parsePomFile(pomContent, args.language);
+          pomElements = parsed.elements;
+          pomClassName = parsed.className;
+        } catch (error) {
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                error: `Failed to parse POM file: ${error.message}`
+              }, null, 2)
+            }],
+            isError: true
           };
         }
       }
 
-      // Default: return test code only
+      // Add POM options to generator
+      if (pomElements && pomClassName) {
+        options.pomElements = pomElements;
+        options.pomClassName = pomClassName;
+      }
+
+      let generator;
+      switch (args.language) {
+        case 'playwright-typescript':
+          generator = new PlaywrightTypeScriptGenerator(options);
+          break;
+        case 'playwright-python':
+          generator = new PlaywrightPythonGenerator(options);
+          break;
+        case 'selenium-python':
+          generator = new SeleniumPythonGenerator(options);
+          break;
+        case 'selenium-java':
+          generator = new SeleniumJavaGenerator(options);
+          break;
+        default:
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                error: `Unknown language: ${args.language}. Supported: playwright-typescript, playwright-python, selenium-python, selenium-java`
+              }, null, 2)
+            }],
+            isError: true
+          };
+      }
+
+      // Generate test code with full imports
+      const testCode = generator.generate(scenario, options);
+
+      // Generate suggested filename
+      const testName = scenario.metadata?.name || 'test';
+      const extension = args.language.includes('typescript') ? '.spec.ts' :
+                       args.language.includes('java') ? 'Test.java' :
+                       args.language.includes('python') ? '_test.py' : '.test.js';
+      const suggestedFileName = args.language.includes('java')
+        ? testName.charAt(0).toUpperCase() + testName.slice(1) + 'Test.java'
+        : testName.replace(/\s+/g, '_').toLowerCase() + extension;
+
+      // Build result
+      const result = {
+        action: 'create_new_file',
+        suggestedFileName: suggestedFileName,
+        testCode: testCode,
+        instruction: `Create a new test file '${suggestedFileName}' with the testCode.`
+      };
+
+      if (pomClassName) {
+        result.pomIntegration = { className: pomClassName, mode: pageObjectMode };
+      }
+
+      if (pageObjectData) {
+        result.pageObject = pageObjectData;
+        result.instruction = `Create a new test file '${suggestedFileName}' with the testCode. Also create a Page Object file '${pageObjectData.suggestedFileName}' with the pageObject.code.`;
+      }
+
       return {
         content: [{
           type: 'text',
-          text: JSON.stringify({
-            action: 'create_new_file',
-            suggestedFileName: suggestedFileName,
-            testCode: testCode,
-            instruction: `Create a new test file '${suggestedFileName}' with the testCode.`
-          }, null, 2)
+          text: JSON.stringify(result, null, 2)
         }]
       };
     }
@@ -3541,6 +3842,87 @@ Start coding now.`;
       };
     }
 
+    // ========== API / Swagger Tools ==========
+
+    if (name === "loadSwagger") {
+      const validatedArgs = schemas.LoadSwaggerSchema.parse(args);
+      const parser = await OpenAPIParser.load(validatedArgs.source, validatedArgs.format || 'auto');
+      const summary = parser.getSummary();
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            success: true,
+            ...summary,
+            instruction: 'Use generateApiModels to generate typed models from these schemas.'
+          }, null, 2)
+        }]
+      };
+    }
+
+    if (name === "generateApiModels") {
+      const validatedArgs = schemas.GenerateApiModelsSchema.parse(args);
+      const parser = await OpenAPIParser.load(validatedArgs.source, validatedArgs.format || 'auto');
+      let schemasObj = parser.getSchemas();
+
+      // Filter schemas if specified
+      if (validatedArgs.schemas && validatedArgs.schemas.length > 0) {
+        const filtered = {};
+        for (const schemaName of validatedArgs.schemas) {
+          if (schemasObj[schemaName]) filtered[schemaName] = schemasObj[schemaName];
+        }
+        schemasObj = filtered;
+      }
+
+      const metadata = {
+        title: parser.spec.info?.title || '',
+        source: validatedArgs.source,
+        version: parser.version
+      };
+
+      let code, suggestedFileName;
+
+      if (validatedArgs.language === 'typescript') {
+        const generator = new ApiModelsTypeScriptGenerator(schemasObj, {
+          style: validatedArgs.style || 'interface',
+          includeEnums: validatedArgs.includeEnums !== false,
+          includeValidation: validatedArgs.includeValidation || false,
+        });
+        code = generator.generate(metadata);
+        const titleSlug = (metadata.title || 'api').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+        suggestedFileName = `${titleSlug}.models.ts`;
+      } else {
+        const generator = new ApiModelsPythonGenerator(schemasObj, {
+          style: validatedArgs.pythonStyle || 'dataclass',
+          includeEnums: validatedArgs.includeEnums !== false,
+          includeValidation: validatedArgs.includeValidation || false,
+        });
+        code = generator.generate(metadata);
+        const titleSlug = (metadata.title || 'api').toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '');
+        suggestedFileName = `${titleSlug}_models.py`;
+      }
+
+      const schemaCount = Object.keys(schemasObj).length;
+      const enumCount = Object.values(schemasObj).filter(s => s.enum && s.type === 'string').length;
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            action: 'create_new_file',
+            suggestedFileName,
+            code,
+            schemaCount,
+            enumCount,
+            language: validatedArgs.language,
+            source: validatedArgs.source,
+            instruction: `Create file '${suggestedFileName}' with the generated code.`
+          }, null, 2)
+        }]
+      };
+    }
+
     return {
       content: [
         {