@dynamicu/chromedebug-mcp 2.7.2 → 2.7.4

package/CLAUDE.md

@@ -66,6 +66,13 @@ npm run update-extension-config # Update Chrome extension config
 # 2. Enable Developer mode
 # 3. Click "Load unpacked"
 # 4. Select chrome-extension/ directory
+
+# Build extension packages
+npm run build:free      # Build FREE version (webpack bundle)
+npm run build:pro       # Build PRO version (webpack bundle)
+npm run build:both      # Build both versions
+npm run package-pro     # Package PRO extension for distribution
+npm run package-webstore # Package for Chrome Web Store submission
 ```
 
 ### VS Code Extension
@@ -121,15 +128,19 @@ npm run compile
 
 - **Element Selection**: Click elements to select for AI manipulation
 - **Screen Recording**: Capture video + console logs for debugging
+- **Workflow Recording**: Record user actions with screenshots for replay
+- **Screenshot Recording**: Click-to-capture mode with countdown (0/3/5 seconds)
 - **Frame Capture**: Optimized frame capture for videos
 - **WebRTC Override**: Redirects webcam to screen capture
 - **Download ZIP Export**: Export recordings as ZIP packages with screenshots and JSON metadata
+- **Tab Filtering**: Filter recordings by type (All/Workflow/Screenshots)
 
 ### Chrome Extension Versions
 
 **FREE Version** (npm package / direct install):
 - 5 recordings per day limit
 - All core recording features
+- Watermarked images (applied at display/export time, not storage)
 - Local storage only
 - No external data transmission
 
@@ -299,6 +310,13 @@ The package name is `chromedebug-mcp` but the project is commonly referred to as
 - Supports restore points for reverting to previous states
 - Stores DOM snapshots, form values, storage, and cookies
 - Enables replay and debugging of complex workflows
+- Two modes: `workflow` (action tracking) and `screenshot` (click-to-capture)
+- Console logs associated with actions using timestamp windowing
+
+### Recording Mode Database Schema
+- `recording_mode` column: 'workflow' or 'screenshot'
+- NULL values treated as 'workflow' for backward compatibility
+- Tab filtering uses SQL: `WHERE (recording_mode = ? OR recording_mode IS NULL)`
 
 ### Testing Framework
 - **Jest-based**: Uses Jest with ES modules support (`NODE_OPTIONS='--experimental-vm-modules'`)

package/README.md

@@ -3,7 +3,15 @@
 [![npm version](https://badge.fury.io/js/%40dynamicu%2Fchromedebug-mcp.svg)](https://www.npmjs.com/package/@dynamicu/chromedebug-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-ChromeDebug MCP is a Model Context Protocol (MCP) server that gives AI assistants like Claude Code full control over a Chrome browser instance. It provides comprehensive browser automation, debugging, and screen recording capabilities optimized for AI-assisted development.
+ChromeDebug MCP is a Model Context Protocol (MCP) server that gives AI assistants like Claude Code full control over a Chrome browser instance. It provides comprehensive browser automation, debugging, and recording capabilities optimized for AI-assisted development.
+
+**Key Features:**
+- **Multiple Recording Modes:** Screen recording, workflow recording, and screenshot recording with countdown
+- **Visual Element Selection:** Click to select elements and modify them via MCP tools
+- **Frame-by-Frame Capture:** High-quality screenshots with synchronized console logs
+- **Video Export (PRO):** Export recordings as MP4 videos with customizable settings
+- **Workflow Replay:** Record and replay user interactions for debugging
+- **100% Local:** All data stored locally - no cloud uploads
 
 ## 🎥 See It In Action
 
@@ -35,6 +43,8 @@ Install the Chrome extension to enable visual element selection and recording fe
 
 - ✅ 5 recordings per day (FREE version)
 - ✅ Visual element selection
+- ✅ Screen, workflow, and screenshot recording
+- ✅ Frame viewer with console logs
 - ✅ Full MCP integration
 - ✅ Automatic updates
 
@@ -50,9 +60,11 @@ npm install
 ## Installing PRO Version
 
 ChromeDebug PRO adds advanced features including:
+- **Unlimited recordings** - No daily recording limits
+- **Export as ZIP/MP4** - Download recordings as image archives or videos
 - **Function call tracking** - Record and replay function execution traces
 - **Advanced debugging** - Enhanced breakpoint and inspection capabilities
-- **Unlimited recordings** - No daily recording limits
+- **Clean exports** - No watermarks on images or videos
 - Priority support and updates
 
 ### 🎥 PRO Installation Video
@@ -65,7 +77,7 @@ Watch the step-by-step installation guide:
 
 ### Installation Steps
 
-After purchasing ChromeDebug PRO from [LemonSqueezy](https://chromedebug.com/buy/996773cb-682b-430f-b9e3-9ce2130bd967):
+After purchasing ChromeDebug PRO from [LemonSqueezy](https://chromedebug.com/checkout/buy/996773cb-682b-430f-b9e3-9ce2130bd967):
 
 1. **Download your PRO extension** from the purchase confirmation email (you'll receive a ZIP file named `chromedebug-extension-pro.zip`)
 2. **Run the installer**:
@@ -275,24 +287,57 @@ Chrome Debug can automatically start an embedded HTTP server for Chrome extensio
 
 When used as an MCP server, Chrome Debug exposes these tools:
 
-- `launch_chrome` - Launch a Chrome browser instance
-- `evaluate_expression` - Evaluate JavaScript expression
-- `get_scopes` - Get scope variables
-- `get_logs` - Get console logs
-- `take_screenshot` - Take a screenshot
-- `get_page_content` - Get page content (text, HTML, and DOM structure)
+**Browser Control:**
+- `launch_chrome` - Start a new Chrome browser instance
+- `connect_to_existing_chrome` - Connect to existing Chrome with debugging enabled
+- `navigate_to` - Navigate to a URL
 - `check_connection` - Check Chrome connection status
 - `force_reset` - Force reset Chrome instance
+
+**Page Inspection:**
+- `take_screenshot` - Capture page screenshot (AI-optimized by default)
+- `get_page_content` - Extract page text, HTML, and DOM structure
+- `evaluate_expression` - Execute JavaScript expression in page context
+- `get_logs` - Retrieve console logs
+
+**Element Selection (via Chrome Extension):**
 - `get_selected_element` - Get info about element selected via extension
 - `apply_css_to_selected` - Apply CSS to the selected element
 - `execute_js_on_selected` - Execute JavaScript on the selected element
 - `clear_selected_element` - Clear the current selection
-- `get_workflow_recording` - Get a workflow recording with actions and logs
+
+**Debugging:**
+- `pause_execution` / `resume_execution` - Debugger control
+- `step_over` - Step over in debugger
+- `set_breakpoint` - Set debugging breakpoints
+- `get_scopes` - Get scope variables from top call frame
+
+**Workflow Recording:**
+- `get_workflow_recording` - Get a workflow recording with actions and logs (can be large)
 - `list_workflow_recordings` - List all workflow recordings
-- `save_restore_point` - Save a restore point for the current browser state
+- `get_workflow_summary` - Get a concise summary of a workflow recording
+- `get_workflow_function_traces` - Get only function execution traces
+- `get_workflow_errors` - Get only error logs and error-related actions
+- `get_workflow_actions_filtered` - Get filtered workflow actions by type with pagination
+- `play_workflow_recording` - Replay a saved workflow recording
+- `play_workflow_by_name` - Replay workflow by recording name
+
+**Restore Points:**
+- `save_restore_point` - Save browser state restore point
 - `restore_from_point` - Restore browser to a saved restore point
 - `list_restore_points` - List restore points for a workflow
 
+**Frame Recording (Screen Capture):**
+- `chromedebug_show_frames` - Display frame recording info
+- `get_frame_session_info` - Get frame capture session info
+- `get_frame` - Get specific frame from recording
+- `get_frame_screenshot` - Get screenshot image data as base64
+- `search_frame_logs` - Search logs across all frames
+- `get_frame_logs_paginated` - Get paginated frame logs
+
+**Extension Integration:**
+- `get_websocket_info` - Get WebSocket server info for extension connection
+
 ## Example
 
 ```bash
@@ -339,7 +384,7 @@ Install the FREE version directly from the Chrome Web Store:
 
 For unlimited recordings and advanced features, purchase the PRO version:
 
-💎 **[Get PRO Version](https://chromedebug.com/buy/996773cb-682b-430f-b9e3-9ce2130bd967)**
+💎 **[Get PRO Version](https://chromedebug.com/checkout/buy/996773cb-682b-430f-b9e3-9ce2130bd967)**
 
 - ✅ Unlimited recordings
 - ✅ Advanced function tracing
@@ -359,12 +404,35 @@ For unlimited recordings and advanced features, purchase the PRO version:
      - `execute_js_on_selected` - Execute JavaScript on the element
      - `clear_selected_element` - Clear the selection
 
-2. **Workflow Recording**
+2. **Screen Recording**
+   - Capture video of the current tab with synchronized console logs
+   - All user interactions (clicks, inputs, scrolling) are tracked
+   - Recordings stored locally in SQLite database
+
+3. **Workflow Recording**
    - Click "Start Workflow Recording" to record user interactions
-   - All clicks, inputs, and drags are captured
-   - Console logs can be included in the recording
+   - All clicks, inputs, and drags are captured with screenshots
+   - Console logs included and associated with each action
    - Workflows can be replayed later for debugging
 
+4. **Screenshot Recording** (NEW)
+   - Click-to-capture mode with configurable countdown (0/3/5 seconds)
+   - Captures the RESULT of a click, not the moment of clicking
+   - Perfect for documenting dropdown menus, modals, and form responses
+   - Filter recordings by type using the tab system
+
+5. **Frame Editor** (PRO)
+   - Browse all frames with visual timeline
+   - Delete unwanted frames
+   - Export as ZIP or MP4 video
+   - Full console log synchronization
+
+6. **Video Player** (PRO)
+   - Play recordings at various speeds (0.25x - 4x)
+   - Seek to any frame
+   - Synchronized log panel
+   - Export to MP4 format
+
 ### Managing License Activations
 
 Chrome Debug uses a license activation system to prevent activation limit exhaustion when reinstalling the extension.
@@ -519,4 +587,146 @@ Screen recordings now automatically capture all user interactions:
 - `get_recording` - Retrieve a recording by ID to analyze video and logs
 - `chromedebug_show_frames` - Display frame-by-frame recording with interactions and logs
 - `get_frame` - Get specific frame with its interactions and console logs
-- `get_screen_interactions` - Query specific interaction data from recordings
+- `get_screen_interactions` - Query specific interaction data from recordings
+
+## Screenshot Recording (Click-to-Capture)
+
+Screenshot Recording is a dedicated mode for capturing high-quality screenshots with an optional countdown timer. Unlike Workflow Recording which captures actions immediately, Screenshot Recording waits for the page to respond to your click before capturing.
+
+### How It Works
+
+1. **Start Screenshot Recording** from the extension popup
+2. **Click anywhere on the page** to trigger a capture
+3. **Countdown timer** (0/3/5 seconds) gives the page time to respond
+4. **Screenshot captured** after the countdown
+
+### Use Cases
+
+- **Capture dropdown menus:** Click to open, countdown lets menu animate, screenshot captures open state
+- **Document form submissions:** Click submit, countdown waits for response, screenshot shows result
+- **Record modal dialogs:** Click trigger, countdown waits for animation, screenshot shows modal
+- **Step-by-step documentation:** Each click captures the result, not the moment of clicking
+
+### Settings
+
+- **Countdown Timer:** 0 seconds (instant), 3 seconds (default), or 5 seconds
+- **Hide Cursor:** Option to hide the mouse cursor during capture
+
+## Frame Editor (PRO)
+
+The Frame Editor is a powerful PRO feature for reviewing, editing, and exporting your recordings.
+
+### Features
+
+- **Timeline Navigation:** Browse all frames in your recording with a visual timeline
+- **Frame Thumbnails:** Quick preview strip at the bottom for easy navigation
+- **Frame Information:** View timestamp, dimensions, and capture metadata
+- **Console Logs:** See console output associated with each frame
+- **Delete Frames:** Remove unwanted frames from your recording
+
+### Export Options
+
+- **Download as ZIP:** Export all frames as individual images with metadata JSON
+- **Export as MP4:** Create a video from your frame recording with customizable settings:
+  - Frame rate selection (1-30 fps)
+  - Quality settings (1080p, 720p, 480p)
+  - Playback speed control
+
+## Video Player (PRO)
+
+The Video Player provides a complete playback experience for your frame recordings.
+
+### Playback Controls
+
+- **Play/Pause:** Control video playback
+- **Seek Bar:** Jump to any point in the recording
+- **Speed Control:** 0.25x, 0.5x, 1x, 2x, 4x playback speeds
+- **Frame Counter:** Shows current frame and total frame count
+- **Time Display:** Current time and total duration
+
+### Viewing Options
+
+- **Loop Playback:** Continuously replay the recording
+- **Auto-scroll Logs:** Keep console logs synced with current frame
+- **Log Panel Position:** Right side, bottom, or overlay
+- **Show/Hide Logs:** Toggle console log panel visibility
+
+### Console Log Panel
+
+- **Synchronized with Playback:** Logs highlight as video plays
+- **Color-coded Levels:** Different colors for log, info, warn, error, debug
+- **Timestamp Display:** See exact timing for each log entry
+- **Searchable:** Find specific log entries
+
+## Tab Filtering for Recordings
+
+Manage your recordings with built-in filtering:
+
+- **All:** View all workflow and screenshot recordings
+- **Workflow:** Filter to show only workflow recordings (action tracking)
+- **Screenshots:** Filter to show only screenshot recordings (click-to-capture)
+
+Each recording displays a visual badge indicating its type for easy identification.
+
+## FREE vs PRO Comparison
+
+| Feature | FREE | PRO |
+|---------|------|-----|
+| **Recording Modes** | | |
+| Screen Recording | ✅ | ✅ |
+| Workflow Recording | ✅ | ✅ |
+| Screenshot Recording | ✅ | ✅ |
+| **Daily Limits** | | |
+| Recordings per Day | 5 | Unlimited |
+| **Export Features** | | |
+| View Recordings | ✅ | ✅ |
+| Frame Editor | Watermarked | ✅ Full Access |
+| Download ZIP | ❌ | ✅ |
+| Export as MP4 | ❌ | ✅ |
+| **Advanced Features** | | |
+| Function Tracing | ❌ | ✅ |
+| Enhanced Debugging | ❌ | ✅ |
+| Video Player | Watermarked | ✅ Full Access |
+| **Support** | | |
+| Community Support | ✅ | ✅ |
+| Priority Support | ❌ | ✅ |
+
+### Upgrade to PRO
+
+Ready for unlimited recordings and full export capabilities?
+
+💎 **[Get ChromeDebug PRO](https://chromedebug.com/checkout/buy/996773cb-682b-430f-b9e3-9ce2130bd967)**
+
+## Privacy & Data
+
+ChromeDebug respects your privacy:
+
+- **100% Local:** All recordings are stored locally on your machine
+- **No Cloud Upload:** Your data never leaves your computer
+- **No Analytics:** No usage tracking or telemetry
+- **No Account Required:** Use the FREE version without any sign-up
+- **License Only:** PRO version requires a license key, but no account or login
+
+## Troubleshooting
+
+### Common Issues
+
+**Extension not connecting to server:**
+- Ensure ChromeDebug MCP server is running
+- Check that the port matches (default: 3001)
+- Look for "Connected" status in the extension popup
+
+**Recording not starting:**
+- Grant screen capture permission when prompted
+- Ensure you're not on a restricted page (chrome://, Chrome Web Store)
+
+**Frames not capturing:**
+- Check console for errors
+- Ensure sufficient storage space
+- Try reducing capture quality in settings
+
+### Getting Help
+
+- 📚 [Documentation](https://www.npmjs.com/package/@dynamicu/chromedebug-mcp)
+- 🐛 [Report Issues](https://github.com/dynamicupgrade/ChromeDebug/issues)
+- 💬 [Discussions](https://github.com/dynamicupgrade/ChromeDebug/discussions)