chrometools-mcp 1.9.1 → 2.3.2

package/README.md

@@ -8,13 +8,13 @@ MCP server for Chrome automation using Puppeteer with persistent browser session
 - [Usage](#usage)
 - [AI Optimization Features](#ai-optimization-features) ⭐ **NEW**
 - [Scenario Recorder](#scenario-recorder) ⭐ **NEW** - Visual UI-based recording with smart optimization
-- [Available Tools](#available-tools) - **39+ Tools Total**
+- [Available Tools](#available-tools) - **40+ Tools Total**
   - [AI-Powered Tools](#ai-powered-tools) ⭐ **NEW** - smartFindElement, analyzePage, getAllInteractiveElements, findElementsByText
   - [Core Tools](#1-core-tools) - ping, openBrowser
   - [Interaction Tools](#2-interaction-tools) - click, type, scrollTo
   - [Inspection Tools](#3-inspection-tools) - getElement, getComputedCss, getBoxModel, screenshot
   - [Advanced Tools](#4-advanced-tools) - executeScript, getConsoleLogs, listNetworkRequests, getNetworkRequest, filterNetworkRequests, hover, setStyles, setViewport, getViewport, navigateTo
-  - [Recorder Tools](#6-recorder-tools) ⭐ **NEW** - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode
+  - [Recorder Tools](#6-recorder-tools) ⭐ **NEW** - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, appendScenarioToFile, generatePageObject
 - [Typical Workflow Example](#typical-workflow-example)
 - [Tool Usage Tips](#tool-usage-tips)
 - [Configuration](#configuration)
@@ -506,56 +506,74 @@ Extract detailed design specifications from Figma including text content, colors
 
 ### 6. Recorder Tools ⭐ NEW
 
-**Directory Management**: All recorder tools support an optional `directory` parameter to specify where scenarios are stored.
+**URL-Based Storage (v2.1+)**: Scenarios are automatically organized by website domain in `~/.config/chrometools-mcp/projects/{domain}/scenarios/`.
 
-**Default Location**: `~/.config/chrometools-mcp` (consistent, predictable location in user's home folder)
+**Automatic Domain Detection**: Project ID is extracted from the URL where recording starts:
+- `https://www.google.com` → `google`
+- `https://dev.example.com:8080` → `example-8080`
+- `http://localhost:3000` → `localhost-3000`
+- `file:///test.html` → `local`
 
-You can override the default by:
-- Passing explicit `directory` parameter to any recorder tool
-- Setting environment variable: `CLAUDE_PROJECT_DIR` or `PROJECT_DIR`
+**Domain Organization Rules**:
+1. Main domain only (subdomains stripped): `mail.google.com` → `google`
+2. Ports included for ALL domains: `example.com:8080` → `example-8080`
+3. Protocol ignored: `http` and `https` both → same project
 
-Once a directory is set (explicitly or via environment), it's remembered for the entire MCP server session.
+**Global Scenario Access**: All tools (`listScenarios`, `searchScenarios`) return scenarios from **all projects**. Agent can filter by:
+- `projectId`: Domain-based identifier (e.g., "google", "localhost-3000")
+- `entryUrl`: URL where recording started
+- `exitUrl`: URL where recording ended
 
 **Example**:
 ```javascript
-// Use default location (recommended)
-enableRecorder()  // Saves to ~/.config/chrometools-mcp
-
-// Or specify explicitly
-enableRecorder({ directory: "/path/to/project" })
-
-// Later calls reuse the same directory automatically
-executeScenario({ name: "test" })  // Uses remembered directory
+// Record scenario on google.com
+enableRecorder()  // Saves to ~/.config/chrometools-mcp/projects/google/scenarios/
+
+// List ALL scenarios from all websites
+listScenarios()
+// Returns: [
+//   { name: "search", projectId: "google", entryUrl: "https://google.com" },
+//   { name: "login", projectId: "localhost-3000", entryUrl: "http://localhost:3000" }
+// ]
+
+// Agent filters by projectId or URL
+scenarios.filter(s => s.projectId === "google")
+scenarios.filter(s => s.entryUrl.includes("localhost"))
+
+// Execute scenario (searches all projects automatically)
+executeScenario({ name: "login" })  // Finds scenario in any project
 ```
 
 ---
 
 #### enableRecorder
-Inject visual recorder UI widget into the current page.
-- **Parameters**:
-  - `directory` (optional): Directory to save scenarios (defaults to `~/.config/chrometools-mcp`)
+Inject visual recorder UI widget into the current page. Scenarios are automatically saved to `~/.config/chrometools-mcp/projects/{domain}/scenarios/` based on the website URL.
+- **Parameters**: None
 - **Use case**: Start recording user interactions visually
-- **Returns**: Success status
+- **Returns**: Success status with storage location
 - **Features**:
   - Floating widget with compact mode (minimize to 50x50px)
   - Visual recording indicator (red pulsing border)
   - Start/Pause/Stop/Stop & Save/Clear controls
   - Real-time action list display
   - Metadata fields (name, description, tags)
+  - Automatic domain-based project detection from URL
 
 #### executeScenario
-Execute a previously recorded scenario by name.
+Execute a previously recorded scenario by name. Searches all projects automatically via global index.
 - **Parameters**:
   - `name` (required): Scenario name
+  - `projectId` (optional): Project ID (domain) to disambiguate when multiple scenarios have the same name. Examples: `"google"`, `"localhost-3000"`
   - `parameters` (optional): Runtime parameters (e.g., { email: "user@test.com" })
   - `executeDependencies` (optional): Execute dependencies before running scenario (default: true)
-  - `directory` (optional): Directory where scenarios are stored (defaults to `~/.config/chrometools-mcp`)
-- **Use case**: Run automated test scenarios
+- **Use case**: Run automated test scenarios across projects
 - **Returns**: Execution result with success/failure status
 - **Features**:
   - Automatic dependency resolution (enabled by default)
+  - Cross-project dependency support
   - Secret parameter injection
   - Fallback selector retry logic
+  - Name collision detection with helpful error messages
 - **Example**:
   ```javascript
   // Execute with dependencies (default)
@@ -563,73 +581,134 @@ Execute a previously recorded scenario by name.
 
   // Execute without dependencies
   executeScenario({ name: "create_post", executeDependencies: false })
+
+  // Disambiguate when multiple scenarios have same name
+  executeScenario({ name: "login", projectId: "google" })
+  executeScenario({ name: "login", projectId: "localhost-3000" })
+  ```
+
+- **Name Collision Handling**:
+  If multiple scenarios with the same name exist across different projects, you'll get an error:
+  ```json
+  {
+    "success": false,
+    "error": "Multiple scenarios named 'login' found. Please specify projectId.",
+    "availableProjectIds": ["google", "localhost-3000"],
+    "hint": "Use: executeScenario({ name: \"login\", projectId: \"one-of-the-above\" })"
+  }
   ```
 
 #### listScenarios
-Get all available scenarios with metadata.
-- **Parameters**:
-  - `directory` (optional): Directory where scenarios are stored (defaults to `~/.config/chrometools-mcp`)
-- **Use case**: Browse recorded scenarios
-- **Returns**: Array of scenarios with names, descriptions, tags, timestamps
+Get all available scenarios with metadata from **all websites**. Agent can filter by `projectId`, `entryUrl`, or `exitUrl`.
+- **Parameters**: None
+- **Use case**: Browse recorded scenarios across all websites
+- **Returns**: Array of scenarios with names, descriptions, tags, timestamps, `projectId`, `entryUrl`, `exitUrl`
+- **Example**:
+  ```javascript
+  // List all scenarios from all websites
+  const scenarios = await listScenarios()
+
+  // Agent filters by projectId
+  const googleScenarios = scenarios.filter(s => s.projectId === "google")
+
+  // Agent filters by URL
+  const localhostScenarios = scenarios.filter(s => s.entryUrl.includes("localhost"))
+  ```
 
 #### searchScenarios
-Search scenarios by text or tags.
+Search scenarios by text or tags across **all websites**. Agent can further filter results by `projectId` or URLs.
 - **Parameters**:
   - `text` (optional): Search in name/description
   - `tags` (optional): Array of tags to filter
-  - `directory` (optional): Directory where scenarios are stored (defaults to `~/.config/chrometools-mcp`)
-- **Use case**: Find specific scenarios
-- **Returns**: Matching scenarios
+- **Use case**: Find specific scenarios across all websites
+- **Returns**: Matching scenarios with `projectId`, `entryUrl`, `exitUrl` metadata
+- **Example**:
+  ```javascript
+  // Search across all websites
+  const results = await searchScenarios({ text: "login" })
+
+  // Search by tags
+  const authScenarios = await searchScenarios({ tags: ["auth"] })
+
+  // Agent filters results by domain
+  const googleLogins = results.filter(s => s.projectId === "google")
+  ```
 
 #### getScenarioInfo
-Get detailed information about a scenario.
+Get detailed information about a scenario. Searches all projects automatically.
 - **Parameters**:
   - `name` (required): Scenario name
   - `includeSecrets` (optional): Include secret values (default: false)
-  - `directory` (optional): Directory where scenarios are stored (defaults to `~/.config/chrometools-mcp`)
 - **Use case**: Inspect scenario actions and dependencies
-- **Returns**: Full scenario details (actions, metadata, dependencies)
+- **Returns**: Full scenario details (actions, metadata, dependencies, project info)
 
 #### deleteScenario
-Delete a scenario and its associated secrets.
+Delete a scenario and its associated secrets. Searches all projects to find the scenario.
 - **Parameters**:
   - `name` (required): Scenario name
-  - `directory` (optional): Directory where scenarios are stored (defaults to `~/.config/chrometools-mcp`)
 - **Use case**: Clean up unused scenarios
 - **Returns**: Success confirmation
 
 #### exportScenarioAsCode ⭐ **NEW**
-Export recorded scenario as executable test code for various frameworks. Automatically cleans unstable selectors (CSS Modules, styled-components, Emotion).
+Export recorded scenario as executable test code for creating a **NEW** test file. Automatically cleans unstable selectors (CSS Modules, styled-components, Emotion). Optionally generates Page Object class. Returns JSON with code and suggested filename - Claude Code will create the file. To add tests to **EXISTING** files, use `appendScenarioToFile` instead.
 
 - **Parameters**:
   - `scenarioName` (required): Name of scenario to export
   - `language` (required): Target framework - `"playwright-typescript"`, `"playwright-python"`, `"selenium-python"`, `"selenium-java"`
   - `cleanSelectors` (optional): Remove unstable CSS classes (default: true)
   - `includeComments` (optional): Include descriptive comments (default: true)
-  - `directory` (optional): Directory where scenarios are stored (defaults to `~/.config/chrometools-mcp`)
+  - `generatePageObject` (optional): Also generate Page Object class for the page (default: false)
+  - `pageObjectClassName` (optional): Custom Page Object class name (auto-generated if not provided)
 
-- **Use case**: Convert recorded scenarios into maintainable test code
+- **Use case**: Create new test files from recorded scenarios with optional Page Objects
 
-- **Returns**: Generated test code as string
+- **Returns**: JSON with:
+  - `action`: `"create_new_file"`
+  - `suggestedFileName`: Suggested test filename
+  - `testCode`: Full test code with imports
+  - `instruction`: Instructions for Claude Code
+  - `pageObject` (if `generatePageObject=true`): Page Object code and metadata
 
-- **Example**:
+- **Example 1 - Test only**:
   ```javascript
-  // Export scenario as Playwright TypeScript
+  // Export scenario as new Playwright TypeScript file
   exportScenarioAsCode({
     scenarioName: "checkout_flow",
+    language: "playwright-typescript"
+  })
+
+  // Returns JSON:
+  {
+    "action": "create_new_file",
+    "suggestedFileName": "checkout_flow.spec.ts",
+    "testCode": "import { test, expect } from '@playwright/test';\n\ntest('checkout_flow', async ({ page }) => {\n  await page.goto('https://example.com');\n  await page.locator('button[data-testid=\"add-to-cart\"]').click();\n  await expect(page).toHaveURL(/checkout/);\n});",
+    "instruction": "Create a new test file 'checkout_flow.spec.ts' with the testCode."
+  }
+  ```
+
+- **Example 2 - Test + Page Object**:
+  ```javascript
+  // Export with Page Object class
+  exportScenarioAsCode({
+    scenarioName: "login_test",
     language: "playwright-typescript",
-    cleanSelectors: true,
-    includeComments: true
+    generatePageObject: true,
+    pageObjectClassName: "LoginPage"
   })
 
-  // Returns clean test code:
-  // import { test, expect } from '@playwright/test';
-  //
-  // test('checkout_flow', async ({ page }) => {
-  //   await page.goto('https://example.com');
-  //   await page.locator('button[data-testid="add-to-cart"]').click();
-  //   await expect(page).toHaveURL(/checkout/);
-  // });
+  // Returns JSON with both files:
+  {
+    "action": "create_new_file",
+    "suggestedFileName": "login_test.spec.ts",
+    "testCode": "import { test } from '@playwright/test';\nimport { LoginPage } from './LoginPage';\n\ntest('login_test', async ({ page }) => {\n  const loginPage = new LoginPage(page);\n  await loginPage.goto();\n  await loginPage.fillEmailInput('user@test.com');\n  await loginPage.clickLoginButton();\n});",
+    "pageObject": {
+      "code": "import { Page, Locator } from '@playwright/test';\n\nexport class LoginPage { ... }",
+      "className": "LoginPage",
+      "suggestedFileName": "LoginPage.ts",
+      "elementCount": 12
+    },
+    "instruction": "Create a new test file 'login_test.spec.ts' with the testCode. Also create a Page Object file 'LoginPage.ts' with the pageObject.code."
+  }
   ```
 
 - **Selector Cleaning**: Automatically removes unstable patterns:
@@ -639,6 +718,153 @@ Export recorded scenario as executable test code for various frameworks. Automat
   - Hash suffixes: `component_a1b2c3d` → removed
   - Prefers stable selectors: `data-testid`, `role`, `aria-label`, semantic attributes
 
+#### appendScenarioToFile ⭐ **NEW v2.3.0**
+Append recorded scenario as test code to an **EXISTING** test file. Automatically cleans unstable selectors (CSS Modules, styled-components, Emotion). Optionally generates Page Object class. Returns JSON with test code (without imports) - Claude Code will read the file, append the test, and write back. To create **NEW** test files, use `exportScenarioAsCode` instead.
+
+- **Parameters**:
+  - `scenarioName` (required): Name of scenario to export
+  - `language` (required): Target framework - `"playwright-typescript"`, `"playwright-python"`, `"selenium-python"`, `"selenium-java"`
+  - `targetFile` (required): Path to existing test file to append to
+  - `testName` (optional): Override test name (default: from scenario name)
+  - `insertPosition` (optional): Where to insert: `'end'` (default), `'before'`, `'after'`
+  - `referenceTestName` (optional): Reference test name for 'before'/'after' insertion
+  - `cleanSelectors` (optional): Remove unstable CSS classes (default: true)
+  - `includeComments` (optional): Include descriptive comments (default: true)
+  - `generatePageObject` (optional): Also generate Page Object class for the page (default: false)
+  - `pageObjectClassName` (optional): Custom Page Object class name (auto-generated if not provided)
+
+- **Use case**: Add tests to existing test files without overwriting current tests
+
+- **Architecture**: MCP server generates only test code (without imports). Claude Code reads the target file, appends the test at the specified position, and writes the file back. This separation ensures MCP doesn't need file system access to test files.
+
+- **Returns**: JSON with:
+  - `action`: `"append_test"`
+  - `targetFile`: Path to file to update
+  - `testCode`: Test code only (without imports/headers)
+  - `testName`: Name of test to append
+  - `insertPosition`: Where to insert test
+  - `referenceTestName`: Reference test for 'before'/'after' positioning
+  - `instruction`: Instructions for Claude Code to read/append/write
+  - `pageObject` (if `generatePageObject=true`): Page Object code and metadata
+
+- **Example 1 - Append to end**:
+  ```javascript
+  // Append test to end of existing file
+  appendScenarioToFile({
+    scenarioName: "new_feature_test",
+    language: "playwright-typescript",
+    targetFile: "./tests/features.spec.ts"
+  })
+
+  // Returns JSON:
+  {
+    "action": "append_test",
+    "targetFile": "./tests/features.spec.ts",
+    "testCode": "test('new_feature_test', async ({ page }) => {\n  // Test implementation\n  await page.click('#submit');\n  await expect(page.locator('.result')).toBeVisible();\n});",
+    "testName": "new_feature_test",
+    "insertPosition": "end",
+    "referenceTestName": null,
+    "instruction": "Read file './tests/features.spec.ts', append the testCode at position 'end', then write the file back."
+  }
+  ```
+
+- **Example 2 - Insert before specific test**:
+  ```javascript
+  // Insert test before specific test
+  appendScenarioToFile({
+    scenarioName: "setup_test",
+    language: "selenium-python",
+    targetFile: "./tests/test_suite.py",
+    insertPosition: "before",
+    referenceTestName: "test_main",
+    testName: "test_setup_data"
+  })
+  ```
+
+- **Example 3 - Append with Page Object**:
+  ```javascript
+  // Append test and generate Page Object
+  appendScenarioToFile({
+    scenarioName: "login_test",
+    language: "playwright-typescript",
+    targetFile: "./tests/auth.spec.ts",
+    generatePageObject: true,
+    pageObjectClassName: "LoginPage"
+  })
+
+  // Returns JSON with both test code and Page Object:
+  {
+    "action": "append_test",
+    "targetFile": "./tests/auth.spec.ts",
+    "testCode": "test('login_test', async ({ page }) => {\n  await page.fill('#username', 'user');\n  await page.fill('#password', 'pass');\n  await page.click('button[type=\"submit\"]');\n});",
+    "testName": "login_test",
+    "insertPosition": "end",
+    "referenceTestName": null,
+    "pageObject": {
+      "code": "export class LoginPage { ... }",
+      "className": "LoginPage",
+      "suggestedFileName": "LoginPage.ts",
+      "elementCount": 8
+    },
+    "instruction": "Read file './tests/auth.spec.ts', append the testCode at position 'end', then write the file back. Also create a Page Object file 'LoginPage.ts' with the provided pageObject.code."
+  }
+  ```
+
+#### generatePageObject ⭐ **NEW**
+Generate Page Object Model (POM) class from current page structure. Analyzes page, extracts interactive elements, and generates framework-specific code with smart naming and helper methods.
+
+- **Parameters**:
+  - `className` (optional): Page Object class name (auto-generated from page title/URL if not provided)
+  - `framework` (optional): Target framework - `"playwright-typescript"` (default), `"playwright-python"`, `"selenium-python"`, `"selenium-java"`
+  - `includeComments` (optional): Include descriptive comments (default: true)
+  - `groupElements` (optional): Group elements by page sections (default: true)
+
+- **Features**:
+  - **Smart Selector Generation**: Prioritizes id > name > data-testid > unique class > CSS path
+  - **Intelligent Naming**: Auto-generates element names from labels, placeholders, text, attributes
+  - **Section Grouping**: Groups elements by semantic sections (header, nav, form, footer, main, etc.)
+  - **Helper Methods**: Auto-generates fill() and click() methods for common actions
+  - **Multi-Framework**: Supports Playwright (TS/Python) and Selenium (Python/Java)
+
+- **Use cases**:
+  - Generate POM classes for test automation
+  - Create maintainable test structure from existing pages
+  - Bootstrap test framework setup quickly
+  - Extract page structure for documentation
+
+- **Returns**: Page Object code with metadata (className, url, title, elementCount, framework)
+
+- **Example**:
+  ```javascript
+  // 1. Navigate to page
+  openBrowser({ url: "https://example.com/login" })
+
+  // 2. Generate Page Object
+  generatePageObject({
+    className: "LoginPage",
+    framework: "playwright-typescript",
+    includeComments: true,
+    groupElements: true
+  })
+
+  // Returns:
+  {
+    "success": true,
+    "className": "LoginPage",
+    "url": "https://example.com/login",
+    "title": "Login - Example Site",
+    "elementCount": 12,
+    "framework": "playwright-typescript",
+    "code": "import { Page, Locator } from '@playwright/test';\n\nexport class LoginPage {\n  readonly page: Page;\n  \n  /** Email input field */\n  readonly emailInput: Locator;\n  /** Password input field */\n  readonly passwordInput: Locator;\n  /** Login button */\n  readonly loginButton: Locator;\n  \n  constructor(page: Page) {\n    this.page = page;\n    this.emailInput = page.locator('#email');\n    this.passwordInput = page.locator('#password');\n    this.loginButton = page.locator('button[type=\"submit\"]');\n  }\n  \n  async goto() {\n    await this.page.goto('https://example.com/login');\n  }\n  \n  async fillEmailInput(text: string) {\n    await this.emailInput.fill(text);\n  }\n  \n  async fillPasswordInput(text: string) {\n    await this.passwordInput.fill(text);\n  }\n  \n  async clickLoginButton() {\n    await this.loginButton.click();\n  }\n}"
+  }
+  ```
+
+- **Supported Frameworks**:
+  - `playwright-typescript`: Playwright with TypeScript (locators, async/await, Page Object pattern)
+  - `playwright-python`: Playwright with Python (sync API, snake_case naming)
+  - `selenium-python`: Selenium with Python (WebDriver, explicit waits, By locators)
+  - `selenium-java`: Selenium with Java (WebDriver, Page Factory compatible)
+
 ---
 
 ## Typical Workflow Example

package/browser/browser-manager.js

@@ -0,0 +1,206 @@
+/**
+ * browser/browser-manager.js
+ *
+ * Browser lifecycle management
+ */
+
+import puppeteer from 'puppeteer';
+import { spawn } from 'child_process';
+import http from 'http';
+import { getChromePath, getTempDir, isWSL, CHROME_DEBUG_PORT } from '../utils/platform-utils.js';
+
+// Global browser instance (persists between requests)
+let browserPromise = null;
+let chromeProcess = null;
+
+/**
+ * Debug log helper (only logs to stderr when DEBUG=1)
+ * @param {...any} args - Arguments to log
+ */
+function debugLog(...args) {
+  if (process.env.DEBUG === '1') {
+    console.error('[browser-manager]', ...args);
+  }
+}
+
+/**
+ * Get WebSocket endpoint from Chrome remote debugging
+ * @param {number} port - Chrome debugging port
+ * @param {number} maxRetries - Maximum retry attempts
+ * @returns {Promise<string>} - WebSocket debugger URL
+ */
+async function getChromeWebSocketEndpoint(port = CHROME_DEBUG_PORT, maxRetries = 10) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const response = await new Promise((resolve, reject) => {
+        const req = http.get(`http://localhost:${port}/json/version`, (res) => {
+          let data = '';
+          res.on('data', chunk => data += chunk);
+          res.on('end', () => resolve(data));
+        });
+        req.on('error', reject);
+        req.setTimeout(1000);
+      });
+
+      const info = JSON.parse(response);
+      if (info.webSocketDebuggerUrl) {
+        return info.webSocketDebuggerUrl;
+      }
+    } catch (err) {
+      // Chrome might not be ready yet, wait and retry
+      await new Promise(resolve => setTimeout(resolve, 500));
+    }
+  }
+  throw new Error('Could not get Chrome WebSocket endpoint after multiple retries');
+}
+
+/**
+ * Initialize browser (singleton)
+ * @returns {Promise<Browser>} - Puppeteer browser instance
+ */
+export async function getBrowser() {
+  // Check if we have a cached browser and if it's still connected
+  if (browserPromise) {
+    try {
+      const cachedBrowser = await browserPromise;
+      if (cachedBrowser && cachedBrowser.isConnected()) {
+        return cachedBrowser;
+      }
+      // Browser disconnected, reset the promise
+      debugLog("Browser disconnected, will reconnect...");
+      browserPromise = null;
+    } catch (error) {
+      debugLog("Error checking cached browser:", error.message);
+      browserPromise = null;
+    }
+  }
+
+  if (!browserPromise) {
+    browserPromise = (async () => {
+      try {
+        let browser;
+        let endpoint;
+
+        // Try to connect to existing Chrome with remote debugging
+        try {
+          endpoint = await getChromeWebSocketEndpoint(CHROME_DEBUG_PORT, 2);
+          browser = await puppeteer.connect({
+            browserWSEndpoint: endpoint,
+            defaultViewport: null,
+          });
+          debugLog("Connected to existing Chrome instance");
+          debugLog("WebSocket endpoint:", endpoint);
+
+          // Set up disconnect handler to reset browserPromise
+          browser.on('disconnected', () => {
+            debugLog("Browser disconnected");
+            browserPromise = null;
+          });
+
+          return browser;
+        } catch (connectError) {
+          debugLog("No existing Chrome found, launching new instance...");
+        }
+
+        // Launch new Chrome with remote debugging enabled
+        const chromePath = getChromePath();
+        const userDataDir = `${getTempDir()}/chrome-mcp-profile`;
+
+        debugLog("Chrome path:", chromePath);
+        debugLog("User data dir:", userDataDir);
+
+        chromeProcess = spawn(chromePath, [
+          `--remote-debugging-port=${CHROME_DEBUG_PORT}`,
+          '--no-first-run',
+          '--no-default-browser-check',
+          `--user-data-dir=${userDataDir}`,
+        ], {
+          detached: true,
+          stdio: 'ignore',
+        });
+
+        chromeProcess.unref(); // Allow Node to exit even if Chrome is running
+
+        debugLog("Chrome launched with remote debugging on port", CHROME_DEBUG_PORT);
+
+        // Wait for Chrome to start and get the endpoint
+        endpoint = await getChromeWebSocketEndpoint(CHROME_DEBUG_PORT, 20);
+
+        // Connect to the Chrome instance
+        browser = await puppeteer.connect({
+          browserWSEndpoint: endpoint,
+          defaultViewport: null,
+        });
+
+        debugLog("Connected to Chrome instance");
+        debugLog("WebSocket endpoint:", endpoint);
+
+        // Set up disconnect handler to reset browserPromise
+        browser.on('disconnected', () => {
+          debugLog("Browser disconnected");
+          browserPromise = null;
+        });
+
+        return browser;
+      } catch (error) {
+        // Check if it's a display-related error in WSL
+        if (isWSL && (
+          error.message.includes('DISPLAY') ||
+          error.message.includes('connect ECONNREFUSED') ||
+          error.message.includes('cannot open display')
+        )) {
+          const helpMessage = `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+❌ WSL X Server Error Detected
+
+You are running in WSL environment with headless:false mode.
+This requires an X server to display the browser GUI.
+
+🔧 Solution:
+   1. Start X server on Windows (e.g., VcXsrv, X410)
+   2. Set DISPLAY in your MCP config:
+
+      {
+        "mcpServers": {
+          "chrometools": {
+            "env": {
+              "DISPLAY": "172.25.96.1:0"
+            }
+          }
+        }
+      }
+
+📚 For detailed setup instructions, see:
+   WSL_SETUP.md in chrometools-mcp package
+
+💡 Alternative: Run in headless mode (modify index.js)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+          console.error(helpMessage);
+          throw new Error(`WSL X Server not available. ${error.message}\n\nSee above for setup instructions.`);
+        }
+
+        // Re-throw other errors as-is
+        throw error;
+      }
+    })();
+  }
+
+  return await browserPromise;
+}
+
+/**
+ * Close browser and cleanup
+ * @returns {Promise<void>}
+ */
+export async function closeBrowser() {
+  if (browserPromise) {
+    try {
+      const browser = await browserPromise;
+      await browser.close();
+    } catch (error) {
+      debugLog("Error closing browser:", error.message);
+    }
+    browserPromise = null;
+  }
+}