chrometools-mcp 1.0.1 → 1.3.5

package/CHANGELOG.md

@@ -0,0 +1,193 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.3.5] - 2025-01-26
+
+### Added
+- **Request/Response payload and headers now included in getNetworkRequests**
+- `postData` - POST request body (e.g., form data, JSON payload)
+- `requestHeaders` - Request headers
+- `responseHeaders` - Response headers
+
+### Changed
+- `getNetworkRequests` now returns complete request/response details
+- Essential for debugging API calls with payloads
+
+### Example
+```javascript
+getNetworkRequests({ urlPattern: 'send_otp' })
+
+// Now returns:
+{
+  "url": "http://localhost:4200/api/auth/send_otp/",
+  "method": "POST",
+  "postData": "{\"phone\":\"+79001234567\"}",  // ← NEW!
+  "requestHeaders": {                           // ← NEW!
+    "content-type": "application/json",
+    "authorization": "Bearer ..."
+  },
+  "responseHeaders": {                          // ← NEW!
+    "content-type": "application/json"
+  },
+  "status": 200,
+  ...
+}
+```
+
+## [1.3.4] - 2025-01-26
+
+### Fixed
+- **Network monitoring now persists across page navigations** - auto-reinitializes on navigation
+- Network requests are now captured correctly after form submissions, link clicks, and redirects
+- Added WeakSet tracking to prevent duplicate CDP session setup
+- Added 100ms debounce on navigation to ensure stability
+
+### Changed
+- Refactored network monitoring into `setupNetworkMonitoring()` helper function
+- Network monitoring automatically re-enables on framenavigated events
+- Global `networkRequests[]` array preserves history across all navigations
+
+### Technical Details
+- CDP (Chrome DevTools Protocol) session is recreated on each navigation
+- Network.enable is automatically re-sent after navigation completes
+- Request history accumulates across multiple pages in the same session
+- Use `getNetworkRequests({ clear: true })` to reset history when needed
+
+### Example Use Case
+```javascript
+// 1. Open login page
+openBrowser({ url: 'https://app.com/login' })
+// Network monitoring: ✅ active
+
+// 2. Fill form and submit (navigates to /dashboard)
+click({ selector: 'button[type="submit"]' })
+// Network monitoring: ✅ auto-reinitialized
+// Captures POST /api/login, GET /dashboard, etc.
+
+// 3. Check all requests from both pages
+getNetworkRequests({ types: ['XHR', 'Fetch'] })
+// Returns requests from /login AND /dashboard
+```
+
+## [1.3.3] - 2025-01-26
+
+### Added
+- `getNetworkRequests` tool - monitor all network requests (XHR, Fetch, API calls, resources)
+- Network monitoring via Chrome DevTools Protocol (CDP)
+- Automatic capture of all HTTP/HTTPS requests from page load
+- Filter requests by type (XHR, Fetch, Script, Document, etc.)
+- Filter by status (pending, completed, failed)
+- Filter by URL pattern (regex support)
+- Request details include: URL, method, status, headers, timing, cache info, errors
+
+### Changed
+- Network.enable added to CDP session setup in getOrCreatePage
+- Global networkRequests array for request storage
+
+### Examples
+```javascript
+// Get all network requests
+getNetworkRequests()
+
+// Get only XHR and Fetch requests (API calls)
+getNetworkRequests({
+  types: ['XHR', 'Fetch']
+})
+
+// Get failed requests
+getNetworkRequests({
+  status: 'failed'
+})
+
+// Get requests to specific API
+getNetworkRequests({
+  urlPattern: 'api\\.example\\.com'
+})
+
+// Get requests and clear history
+getNetworkRequests({
+  types: ['XHR', 'Fetch'],
+  clear: true
+})
+```
+
+## [1.3.2] - 2025-01-26
+
+### Added
+- `action` parameter for `smartFindElement` - perform actions (click, type, scrollTo, screenshot, hover, setStyles) on the best match immediately
+- `action` parameter for `findElementsByText` - perform actions on the first matching element immediately
+- New helper function `executeElementAction` for unified action execution
+
+### Changed
+- `smartFindElement` can now execute actions on found elements in a single call
+- `findElementsByText` can now execute actions on found elements in a single call
+- Reduces need for separate find + action calls, improving performance
+
+### Examples
+```javascript
+// Find and click in one call
+smartFindElement({
+  description: 'login button',
+  action: { type: 'click' }
+})
+
+// Find and type in one call
+findElementsByText({
+  text: 'Email',
+  action: { type: 'type', text: 'user@example.com' }
+})
+
+// Find, style and screenshot
+smartFindElement({
+  description: 'submit button',
+  action: {
+    type: 'setStyles',
+    styles: [{ name: 'background', value: 'red' }],
+    screenshot: true
+  }
+})
+```
+
+## [1.3.1] - 2025-01-26
+
+### Performance Improvements
+- **BREAKING BEHAVIOR CHANGE**: `click` and `executeScript` commands no longer capture screenshots by default
+  - Screenshots were causing significant performance overhead (2-10x slowdown)
+  - Add `screenshot: true` parameter to explicitly request screenshots when needed
+  - This is backward compatible but changes default behavior for better performance
+
+### Added
+- `screenshot` parameter for `click` command (boolean, default: `false`)
+- `screenshot` parameter for `executeScript` command (boolean, default: `false`)
+- `timeout` parameter for `click` command (number, default: `30000ms`)
+- `timeout` parameter for `executeScript` command (number, default: `30000ms`)
+
+### Changed
+- `click` command now executes 2-10x faster without screenshots
+- `executeScript` command now executes 2-10x faster without screenshots
+- Both commands now have 30-second timeout by default to prevent hanging
+
+### Fixed
+- Commands no longer hang indefinitely if operations fail
+- Reduced memory usage by not capturing unnecessary screenshots
+
+### Migration
+If you relied on automatic screenshots, add `screenshot: true` to your calls:
+```javascript
+// Before (v1.3.0 and earlier)
+await click({ selector: 'button' })  // Always included screenshot
+
+// After (v1.3.1+)
+await click({ selector: 'button', screenshot: true })  // Explicitly request screenshot
+await click({ selector: 'button' })  // Fast mode (no screenshot)
+```
+
+## [1.3.0] - Previous version
+- Scenario recorder with auto-reinjection
+- Smart element finder
+- Page analysis tools
+- Figma integration
+
+## Earlier versions
+See git history for details.

package/README.md

@@ -6,11 +6,15 @@ MCP server for Chrome automation using Puppeteer with persistent browser session
 
 - [Installation](#installation)
 - [Usage](#usage)
-- [Available Tools](#available-tools) - **16 Tools Total**
+- [AI Optimization Features](#ai-optimization-features) ⭐ **NEW**
+- [Scenario Recorder](#scenario-recorder) ⭐ **NEW** - Visual UI-based recording with smart optimization
+- [Available Tools](#available-tools) - **26+ 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, hover, setStyles, setViewport, getViewport, navigateTo
+  - [Advanced Tools](#4-advanced-tools) - executeScript, getConsoleLogs, getNetworkRequests, hover, setStyles, setViewport, getViewport, navigateTo
+  - [Recorder Tools](#5-recorder-tools) ⭐ **NEW** - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario
 - [Typical Workflow Example](#typical-workflow-example)
 - [Tool Usage Tips](#tool-usage-tips)
 - [Configuration](#configuration)
@@ -40,8 +44,119 @@ Add to your MCP client configuration (e.g., Claude Desktop):
 }
 ```
 
+## AI Optimization Features
+
+⭐ **NEW**: Dramatically reduce AI agent request cycles with intelligent element finding and page analysis.
+
+### Why This Matters
+
+Traditional browser automation with AI requires many trial-and-error cycles:
+```
+AI: "Find login button"
+→ Try selector #1: Not found
+→ Try selector #2: Not found
+→ Try selector #3: Found! (3 requests, 15-30 seconds)
+```
+
+**With AI optimization:**
+```
+AI: smartFindElement("login button")
+→ Returns ranked candidates with confidence scores (1 request, 2 seconds)
+```
+
+### Key Features
+
+1. **`smartFindElement`** - Natural language element search with multilingual support
+2. **`analyzePage`** - Complete page structure in one request (cached)
+3. **AI Hints** - Automatic context in all tools (page type, available actions, suggestions)
+4. **Batch helpers** - `getAllInteractiveElements`, `findElementsByText`
+
+**Performance:** 3-5x faster, 5-10x fewer requests
+
+📚 [Full AI Optimization Guide](AI_OPTIMIZATION.md)
+
+## Scenario Recorder
+
+⭐ **NEW**: Visual UI-based recorder for creating reusable test scenarios with automatic secret detection.
+
+### Features
+
+- **Visual Widget** - Floating recorder UI with compact mode (50x50px minimize button)
+- **Auto-Reinjection** - Recorder persists across page reloads/navigation automatically with duplicate prevention ⭐ **IMPROVED**
+- **Smart Click Detection** - Finds actual clickable parent elements with event listeners ⭐ **NEW**
+- **Smart Waiters** - 2s minimum + animation/network/DOM change detection after clicks ⭐ **NEW**
+- **Detailed Error Reports** - Comprehensive failure analysis with context and suggestions ⭐ **NEW**
+- **Smart Recording** - Captures clicks, typing, navigation with intelligent optimization
+- **Secret Detection** - Auto-detects passwords/emails and stores them securely
+- **Action Optimization** - Combines sequential actions, removes duplicates
+- **Scenario Management** - Save, load, execute, search, and delete scenarios
+- **Dependencies** - Chain scenarios together with dependency resolution
+- **Multi-Instance Protection** - Prevents multiple recorder instances from interfering ⭐ **NEW**
+
+### Quick Start
+
+```javascript
+// 1. Enable recorder UI
+enableRecorder()
+
+// 2. Click "Start" in widget, perform actions, click "Stop & Save"
+// 3. Execute saved scenario
+executeScenario({ name: "login_flow", parameters: { email: "user@test.com" } })
+```
+
+📚 [Full Recorder Guide](RECORDER_QUICKSTART.md) | [Recorder Spec](RECORDER_SPEC.md)
+
 ## Available Tools
 
+### AI-Powered Tools
+
+#### smartFindElement ⭐
+Find elements using natural language descriptions instead of CSS selectors.
+- **Parameters**:
+  - `description` (required): Natural language (e.g., "login button", "email field")
+  - `maxResults` (optional): Max candidates to return (default: 5)
+- **Use case**: When you don't know the exact selector
+- **Returns**: Ranked candidates with confidence scores, selectors, and reasoning
+- **Example**:
+  ```json
+  {
+    "description": "submit button",
+    "maxResults": 3
+  }
+  ```
+  Returns:
+  ```json
+  {
+    "candidates": [
+      { "selector": "button.login-btn", "confidence": 0.95, "text": "Login", "reason": "type=submit, in form, matching keyword" },
+      { "selector": "#submit", "confidence": 0.7, "text": "Send", "reason": "submit class" }
+    ],
+    "hints": { "suggestion": "Use selector: button.login-btn" }
+  }
+  ```
+
+#### analyzePage ⭐
+Get complete page structure in one request. Results are cached per URL.
+- **Parameters**:
+  - `refresh` (optional): Force refresh cache (default: false)
+- **Use case**: Understanding page structure before planning actions
+- **Returns**: Complete map of forms, inputs, buttons, links, navigation with selectors
+- **Example**: Returns structured data for all interactive elements on the page
+
+#### getAllInteractiveElements
+Get all clickable/fillable elements with their selectors.
+- **Parameters**:
+  - `includeHidden` (optional): Include hidden elements (default: false)
+- **Returns**: Array of all interactive elements with selectors and metadata
+
+#### findElementsByText
+Find elements by their visible text content.
+- **Parameters**:
+  - `text` (required): Text to search for
+  - `exact` (optional): Exact match only (default: false)
+  - `caseSensitive` (optional): Case sensitive search (default: false)
+- **Returns**: Elements containing the text with their selectors
+
 ### 1. Core Tools
 
 #### ping
@@ -59,12 +174,15 @@ Opens browser and navigates to URL. Browser stays open for further interactions.
 ### 2. Interaction Tools
 
 #### click
-Click an element and capture result screenshot.
+Click an element with optional result screenshot.
 - **Parameters**:
   - `selector` (required): CSS selector
   - `waitAfter` (optional): Wait time in ms (default: 1500)
+  - `screenshot` (optional): Capture screenshot (default: false for performance) ⚡
+  - `timeout` (optional): Max operation time in ms (default: 30000)
 - **Use case**: Buttons, links, form submissions
-- **Returns**: Confirmation text + screenshot
+- **Returns**: Confirmation text + optional screenshot
+- **Performance**: 2-10x faster without screenshot
 
 #### type
 Type text into input fields with optional clearing and typing delay.
@@ -105,22 +223,45 @@ Get precise dimensions, positioning, margins, padding, and borders.
 - **Returns**: Box model data + metrics
 
 #### screenshot
-Capture PNG screenshot of specific element.
+Capture optimized screenshot of specific element with smart compression.
 - **Parameters**:
   - `selector` (required)
-  - `padding` (optional): Padding in pixels
+  - `padding` (optional): Padding in pixels (default: 0)
+  - `maxWidth` (optional): Max width for auto-scaling (default: 1024, null for original size)
+  - `maxHeight` (optional): Max height for auto-scaling (default: 8000, null for original size)
+  - `quality` (optional): JPEG quality 1-100 (default: 80)
+  - `format` (optional): 'png', 'jpeg', or 'auto' (default: 'auto')
 - **Use case**: Visual documentation, bug reports
-- **Returns**: Base64 PNG image
+- **Returns**: Optimized image with metadata
+- **Default behavior**: Auto-scales to 1024px width and 8000px height (API limit) and uses smart compression to reduce AI token usage
+- **For original quality**: Set `maxWidth: null`, `maxHeight: null` and `format: 'png'`
+
+#### saveScreenshot
+Save optimized screenshot to filesystem without returning in context.
+- **Parameters**:
+  - `selector` (required)
+  - `filePath` (required): Absolute path to save file
+  - `padding` (optional): Padding in pixels (default: 0)
+  - `maxWidth` (optional): Max width for auto-scaling (default: 1024, null for original)
+  - `maxHeight` (optional): Max height for auto-scaling (default: 8000, null for original)
+  - `quality` (optional): JPEG quality 1-100 (default: 80)
+  - `format` (optional): 'png', 'jpeg', or 'auto' (default: 'auto')
+- **Use case**: Baseline screenshots, file storage
+- **Returns**: File path and metadata (not image data)
+- **Default behavior**: Auto-scales and compresses to save disk space
 
 ### 4. Advanced Tools
 
 #### executeScript
-Execute arbitrary JavaScript in page context.
+Execute arbitrary JavaScript in page context with optional screenshot.
 - **Parameters**:
   - `script` (required): JavaScript code
   - `waitAfter` (optional): Wait time in ms (default: 500)
+  - `screenshot` (optional): Capture screenshot (default: false for performance) ⚡
+  - `timeout` (optional): Max operation time in ms (default: 30000)
 - **Use case**: Complex interactions, custom manipulations
-- **Returns**: Execution result + screenshot
+- **Returns**: Execution result + optional screenshot
+- **Performance**: 2-10x faster without screenshot
 
 #### getConsoleLogs
 Retrieve browser console logs (log, warn, error, etc.).
@@ -130,6 +271,22 @@ Retrieve browser console logs (log, warn, error, etc.).
 - **Use case**: Debugging JavaScript errors, tracking behavior
 - **Returns**: Array of log entries with timestamps
 
+#### getNetworkRequests
+Retrieve all network requests (XHR, Fetch, API calls, resources). **Auto-captures across page navigations**.
+- **Parameters**:
+  - `types` (optional): Array of request types (XHR, Fetch, Script, Document, Image, etc.)
+  - `status` (optional): Filter by status (pending, completed, failed, all)
+  - `urlPattern` (optional): Filter by URL using regex
+  - `clear` (optional): Clear requests after reading (default: false)
+- **Use case**: Debugging API calls, monitoring backend requests, tracking failed requests
+- **Returns**: Array of requests with URL, method, status, headers, timing, errors
+- **Auto-reinitialization**: Monitoring continues automatically after form submissions, redirects, and navigation
+- **Examples**:
+  - `getNetworkRequests({ types: ['XHR', 'Fetch'] })` - API calls only
+  - `getNetworkRequests({ status: 'failed' })` - failed requests
+  - `getNetworkRequests({ urlPattern: 'api\\.' })` - requests to API endpoints
+  - `getNetworkRequests({ clear: true })` - get requests and clear history
+
 #### hover
 Simulate mouse hover over element.
 - **Parameters**: `selector` (required)
@@ -167,6 +324,69 @@ Navigate to different URL while keeping browser instance.
 - **Use case**: Moving between pages in workflow
 - **Returns**: New page title
 
+### 5. Recorder Tools ⭐ NEW
+
+#### enableRecorder
+Inject visual recorder UI widget into the current page.
+- **Parameters**: None
+- **Use case**: Start recording user interactions visually
+- **Returns**: Success status
+- **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)
+
+#### executeScenario
+Execute a previously recorded scenario by name.
+- **Parameters**:
+  - `name` (required): Scenario name
+  - `parameters` (optional): Runtime parameters (e.g., { email: "user@test.com" })
+  - `executeDependencies` (optional): Execute dependencies before running scenario (default: true)
+- **Use case**: Run automated test scenarios
+- **Returns**: Execution result with success/failure status
+- **Features**:
+  - Automatic dependency resolution (enabled by default)
+  - Secret parameter injection
+  - Fallback selector retry logic
+- **Example**:
+  ```javascript
+  // Execute with dependencies (default)
+  executeScenario({ name: "create_post" })
+
+  // Execute without dependencies
+  executeScenario({ name: "create_post", executeDependencies: false })
+  ```
+
+#### listScenarios
+Get all available scenarios with metadata.
+- **Parameters**: None
+- **Use case**: Browse recorded scenarios
+- **Returns**: Array of scenarios with names, descriptions, tags, timestamps
+
+#### searchScenarios
+Search scenarios by text or tags.
+- **Parameters**:
+  - `text` (optional): Search in name/description
+  - `tags` (optional): Array of tags to filter
+- **Use case**: Find specific scenarios
+- **Returns**: Matching scenarios
+
+#### getScenarioInfo
+Get detailed information about a scenario.
+- **Parameters**:
+  - `name` (required): Scenario name
+  - `includeSecrets` (optional): Include secret values (default: false)
+- **Use case**: Inspect scenario actions and dependencies
+- **Returns**: Full scenario details (actions, metadata, dependencies)
+
+#### deleteScenario
+Delete a scenario and its associated secrets.
+- **Parameters**: `name` (required)
+- **Use case**: Clean up unused scenarios
+- **Returns**: Success confirmation
+
 ---
 
 ## Typical Workflow Example
@@ -307,12 +527,16 @@ npx @modelcontextprotocol/inspector node index.js
 
 ## Features
 
-- **16 Powerful Tools**: Complete toolkit for browser automation
+- **27+ Powerful Tools**: Complete toolkit for browser automation
   - Core: ping, openBrowser
   - Interaction: click, type, scrollTo
   - Inspection: getElement, getComputedCss, getBoxModel, screenshot
-  - Advanced: executeScript, getConsoleLogs, hover, setStyles, setViewport, getViewport, navigateTo
+  - Advanced: executeScript, getConsoleLogs, getNetworkRequests, hover, setStyles, setViewport, getViewport, navigateTo
+  - AI-Powered: smartFindElement, analyzePage, getAllInteractiveElements, findElementsByText
+  - Recorder: enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario
+  - Figma: getFigmaFrame, compareFigmaToElement, getFigmaSpecs
 - **Console Log Capture**: Automatic JavaScript console monitoring
+- **Network Request Monitoring**: Track all HTTP/API requests (XHR, Fetch, etc.)
 - **Persistent Browser Sessions**: Browser tabs remain open between requests
 - **Visual Browser (GUI Mode)**: See automation in real-time
 - **Cross-platform**: Works on Windows/WSL, Linux, macOS