@dynamicu/chromedebug-mcp 2.2.0

package/CLAUDE.md

@@ -0,0 +1,344 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Chrome Debug is an MCP (Model Context Protocol) server that gives AI full control over a Chrome browser instance. It consists of:
+- An MCP server for AI integration
+- An HTTP API server for browser control
+- A Chrome extension for visual element selection and screen recording
+- A VS Code extension for IDE integration
+
+## Key Commands
+
+### Development
+```bash
+npm install          # Install dependencies
+npm start           # Start MCP server (cleans up processes first)
+npm run go          # Start in development mode with NODE_ENV=development
+npm run dev         # Start with --watch flag for development
+npm run start-http  # Start HTTP server directly (port 3000-4000)
+npm run server      # Run standalone server
+npm run single-server # Run with --single-server flag
+npm run cleanup     # Clean up stale Chrome processes
+npm run cleanup-force # Force cleanup of all Chrome processes
+```
+
+### Testing
+```bash
+# Run all tests
+npm test            # Run all Jest tests
+npm run test:watch  # Run tests in watch mode
+npm run test:coverage # Run tests with coverage report
+
+# Run specific test suites
+npm run test:unit   # Run unit tests only (excludes integration tests)
+npm run test:integration # Run integration tests only
+npm run test:chrome # Test ChromeController functionality
+npm run test:http   # Test HTTP server
+npm run test:db     # Test database functionality
+npm run test:mcp    # Test MCP server functionality
+
+# Recording system tests
+npm run test:recording # Test comprehensive recording system
+npm run test:extension # Test Chrome extension recording
+npm run test:migration # Test dual ID migration
+npm run test:regression # Test recording regression
+npm run test:recording-all # Run all recording-related tests
+```
+
+### Configuration Management
+```bash
+npm run config              # Manage configuration
+npm run config-show         # Show current configuration
+npm run config-ports        # List configured ports
+npm run update-extension-config # Update Chrome extension config
+```
+
+### Chrome Extension
+```bash
+# Load extension in Chrome:
+# 1. Open chrome://extensions/
+# 2. Enable Developer mode
+# 3. Click "Load unpacked"
+# 4. Select chrome-extension/ directory
+```
+
+### VS Code Extension
+```bash
+cd vscode-chrome-pilot
+npm install
+npm run compile
+# Press F5 in VS Code to test
+```
+
+## Architecture
+
+### Core Components
+
+1. **MCP Server** (`src/index.js`)
+   - Entry point for AI integration via Model Context Protocol
+   - Exposes Chrome control tools to AI assistants
+   - Uses StdioServerTransport for communication
+
+2. **Chrome Controller** (`src/chrome-controller.js`)
+   - Central class managing Chrome browser instances
+   - Uses Puppeteer for browser automation
+   - Handles debugging protocol connections
+   - Manages element selection and screenshots
+   - Stores recordings in SQLite database
+
+3. **HTTP Server** (`src/http-server.js`)
+   - REST API on ports 3000-4000 (auto-finds available)
+   - WebSocket support for real-time element selection
+   - Handles screen recording uploads and workflow recording
+   - CORS-enabled for cross-origin requests
+
+4. **Database** (`src/database.js`)
+   - SQLite database for persistent storage
+   - Stores screen recordings and workflow data
+   - Located at `data/chrome-pilot.db`
+
+5. **Capture System** (`src/capture/`)
+   - Modular frame capture architecture
+   - Memory management for large video recordings
+   - TypeScript-style interfaces defined in `interfaces.js`
+   - Optimized for AI analysis and debugging workflows
+
+### Key Design Patterns
+
+- **Single Chrome Instance**: Each server (MCP or HTTP) maintains one ChromeController instance
+- **Per-Instance Chrome**: Each Chrome launch creates a unique user data directory
+- **Automatic Cleanup**: Stale Chrome profiles are cleaned up on startup
+- **Port Management**: Automatically finds available ports for debugging and HTTP server
+- **Timeout Protection**: All async operations have configurable timeouts
+
+### Chrome Extension Features
+
+- **Element Selection**: Click elements to select for AI manipulation
+- **Screen Recording**: Capture video + console logs for debugging
+- **Frame Capture**: Optimized frame capture for videos
+- **WebRTC Override**: Redirects webcam to screen capture
+
+### MCP Tools Available
+
+- `launch_chrome` - Start new Chrome instance
+- `connect_to_existing_chrome` - Connect to existing Chrome with debugging enabled
+- `navigate_to` - Navigate to URL
+- `take_screenshot` - Capture page screenshot (AI-optimized by default)
+- `get_page_content` - Extract page text, HTML, and DOM structure
+- `evaluate_expression` - Execute JavaScript
+- `get_selected_element` - Get currently selected element
+- `apply_css_to_selected` - Apply CSS to selected element
+- `execute_js_on_selected` - Run JS on selected element
+- `clear_selected_element` - Clear current element selection
+- `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
+- `get_logs` - Retrieve console logs
+- `check_connection` - Check Chrome connection status
+- `force_reset` - Force reset Chrome instance
+- `get_websocket_info` - Get WebSocket server info for extension
+- `get_workflow_recording` - Retrieve workflow recording with actions/logs (WARNING: Can be very large)
+- `list_workflow_recordings` - List all workflow recordings
+- `get_workflow_function_traces` - Get only function execution traces from a workflow
+- `get_workflow_errors` - Get only error logs and error-related actions
+- `get_workflow_summary` - Get a concise summary of a workflow recording
+- `get_workflow_actions_filtered` - Get filtered workflow actions by type with pagination
+- `save_restore_point` - Save browser state restore point
+- `restore_from_point` - Restore browser to saved point
+- `list_restore_points` - List restore points for workflow
+- `chrome_pilot_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 for a specific frame as base64
+- `search_frame_logs` - Search logs across all frames
+- `get_frame_logs_paginated` - Get paginated frame logs
+- `play_workflow_recording` - Replay a saved workflow recording
+- `play_workflow_by_name` - Replay workflow by recording name
+
+## Important Files and Locations
+
+- Chrome user data: Temporary directories in OS temp folder
+- Database: `data/chrome-pilot.db` (SQLite)
+- Chrome extension: `chrome-extension/` directory
+- VS Code extension: `vscode-chrome-pilot/` directory
+- HTTP server logs: `http-server.log`
+- Configuration: `config/chrome-pilot-config.json`
+- Test files: `test-*.js` in root directory
+
+## Screenshot Retrieval Feature
+
+### New MCP Tool: `get_frame_screenshot`
+The `get_frame_screenshot` tool enables viewing of actual screenshots captured during frame recordings:
+
+```javascript
+// Get screenshot for frame 0 with metadata
+{
+  "name": "get_frame_screenshot",
+  "arguments": {
+    "sessionId": "frame_1756936437368_tsvn4ehi0",
+    "frameIndex": 0,
+    "includeMetadata": true
+  }
+}
+```
+
+Returns base64-encoded JPEG image data that can be displayed or saved:
+- `imageData`: Base64 string of the screenshot
+- `imageFormat`: Format (always 'jpeg' for Chrome Debug)
+- `metadata`: Optional size, encoding, and capture time info
+- Full error handling for invalid sessions/frames
+
+### Usage Examples
+- **View specific moments**: Get screenshots from any frame in a recording
+- **Debug visual issues**: See exactly what was displayed when an error occurred
+- **Extract UI snapshots**: Save screenshots for documentation or analysis
+- **Verify user interactions**: Visual confirmation of what users clicked
+
+## Common Workflows
+
+### Adding New MCP Tools
+1. Add tool definition to `tools` array in `src/index.js`
+2. Implement handler in the `CallToolRequestSchema` handler
+3. Add corresponding method in `ChromeController` class
+
+### Adding New HTTP Endpoints
+1. Add route in `src/http-server.js`
+2. Implement logic using `chromeController` instance
+3. Update README.md with endpoint documentation
+
+### Modifying Chrome Extension
+1. Edit files in `chrome-extension/` directory
+2. Reload extension in Chrome (chrome://extensions/)
+3. Test functionality before packaging
+
+## Error Handling
+
+- All async operations use `withTimeout()` wrapper
+- Chrome processes are tracked and killed on cleanup
+- WebSocket connections are managed in a Set for cleanup
+- Database operations use transactions for consistency
+
+## Security Considerations
+
+- CORS enabled for cross-origin requests
+- Request size limits: 50MB for JSON/URL-encoded
+- Chrome runs with separate user data directories
+- No persistent cookies between sessions
+
+## CLI Usage
+
+Chrome Debug provides a CLI tool that can be used directly:
+```bash
+chromedebug-mcp  # Runs the MCP server (equivalent to npm start)
+npx chromedebug-mcp  # Run without global installation
+```
+
+The package name is `chromedebug-mcp` but the project is commonly referred to as Chrome Debug.
+
+## Additional Architecture Notes
+
+### Port Discovery
+- Server automatically finds available port from configured list (default: 3001, 3000, 3002, 3028)
+- Port selection stored in `config/chrome-pilot-config.json`
+- Extension automatically updated with current port via `npm run update-extension-config`
+
+### Frame Recording System
+- Captures screenshots and console logs during browser sessions
+- Stores frame data in SQLite with session IDs
+- Supports searching logs across frames
+- Optimized for AI analysis with low-res JPEG capture
+- **NEW**: Screenshots can be retrieved as base64 data for viewing with `get_frame_screenshot`
+
+### Workflow Recording
+- Records user actions and browser state
+- Supports restore points for reverting to previous states
+- Stores DOM snapshots, form values, storage, and cookies
+- Enables replay and debugging of complex workflows
+
+### Testing Framework
+- **Jest-based**: Uses Jest with ES modules support (`NODE_OPTIONS='--experimental-vm-modules'`)
+- **Test Structure**: Tests located in `tests/` directory
+- **Coverage**: Excludes legacy code and CLI from coverage reports
+- **Specialized Test Suites**: Recording system, extension integration, database migration
+- **Timeouts**: 30-second timeout for tests involving browser automation
+- **Setup**: Custom test setup in `tests/setup.js`
+
+## Development Guidelines
+
+### Code Review Process
+- **ALWAYS** run all plans by the second-opinion-analyst agent before implementation
+- This applies to significant changes including:
+  - Architectural changes (adding/removing systems, modifying core patterns)
+  - Bug fixes that affect multiple components
+  - Performance optimizations that alter timing or execution flow
+  - State management changes (especially lease system, session management)
+  - Race condition fixes
+  - Error handling modifications
+
+### Why Second Opinion Matters
+The second-opinion-analyst helps prevent:
+- **Symptom fixes**: Addressing surface issues without fixing root causes
+- **Cascade effects**: Changes that solve one problem but create others
+- **Technical debt**: Quick fixes that make future maintenance harder
+- **Defensive over-engineering**: Adding unnecessary complexity "just in case"
+
+### When to Skip Second Opinion
+- Simple documentation updates
+- Test additions (without changing behavior)
+- Formatting/linting fixes
+- Variable/function renaming
+
+### Example Process
+1. Identify the problem and proposed solution
+2. Use the second-opinion-analyst agent to review the approach
+3. Adjust based on feedback (addressing root causes, not symptoms)
+4. Implement the approved solution
+5. Test thoroughly to verify the fix
+
+---
+
+## Standard Operating Procedure for All Changes
+
+### Team-Based Development Process
+
+**All significant changes MUST follow this workflow:**
+
+1. **Strategic Planning Phase**
+   - Work with the Strategic Project Manager agent to plan implementation
+   - Present plan to user for approval
+   - If plan changes during implementation, alert user before proceeding
+
+2. **Second Opinion Review**
+   - Second Opinion Agent MUST approve all plans and changes
+   - Review for unintended consequences and system-wide impacts
+   - Ensure root causes are addressed, not symptoms
+
+3. **TrustButVerify Integration**
+   - **Before Starting:** Use `trustbutverify.impact_predict` to identify affected areas
+   - **During Development:** After each major function, use `trustbutverify.microtest_generate_and_run`
+   - **After Completion:** Run `trustbutverify.verify_fix` with `includeReplay: true`
+   - **Quality Gate:** Only mark complete and proceed if risk score is below 0.3
+
+4. **Specialized Agent Assignment**
+   - Chrome Debug Agent: Handles all Chrome Debug codebase changes
+   - Use domain-specific agents for specialized work:
+     - Firebase Implementation Expert for Firebase changes
+     - React Optimization Expert for React/UI changes
+     - Android Platform Expert for Android work
+     - etc.
+
+5. **No TODO Lists for New Projects**
+   - Build functionality directly, don't create TODO items
+   - Complete implementation in single workflow
+   - Use TrustButVerify for validation instead of tracking
+
+### Quality Standards
+
+- Risk score must be below 0.3 before proceeding
+- All changes must pass microtest validation
+- Impact prediction required before starting
+- Replay verification required for completion

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dynamicupgrade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# ChromeDebug MCP
+
+[![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.
+
+## Quick Start
+
+### Installation from npm
+
+```bash
+# Install globally
+npm install -g @dynamicu/chromedebug-mcp
+
+# Or install locally in your project
+npm install @dynamicu/chromedebug-mcp
+```
+
+### Development Installation
+
+```bash
+# Clone and install from source
+git clone https://github.com/dynamicupgrade/ChromePilot.git
+cd ChromePilot
+npm install
+```
+
+## Usage
+
+### As MCP Server
+
+To add Chrome Debug to your Claude desktop app:
+
+```bash
+claude mcp add chromepilot -s user -- chrome-pilot
+```
+
+### Embedded HTTP Server
+
+Chrome Debug automatically starts an embedded HTTP server for Chrome extension communication. The server uses ports configured in `config/chrome-pilot-config.json` (default: 3001, 3000, 3002, 3028). The server provides these REST API endpoints:
+
+| Endpoint | Method | Description | Body |
+|----------|--------|-------------|------|
+| `/chrome-pilot/pause` | POST | Pause execution | - |
+| `/chrome-pilot/resume` | POST | Resume execution | - |
+| `/chrome-pilot/step-over` | POST | Step over | - |
+| `/chrome-pilot/evaluate` | POST | Evaluate expression | `{ "expression": "window.user" }` |
+| `/chrome-pilot/scopes` | GET | Get scope variables | - |
+| `/chrome-pilot/set-breakpoint` | POST | Set breakpoint | `{ "url": "file.js", "lineNumber": 10 }` |
+| `/chrome-pilot/logs` | GET | Get recent console logs | - |
+| `/chrome-pilot/screenshot` | POST | Take screenshot | `{ "type": "jpeg", "fullPage": true, "path": "/path/to/save.jpg" }` |
+| `/chrome-pilot/dom-intent` | POST | Process natural language DOM commands | `{ "selector": "#element", "instruction": "make it blue" }` |
+| `/chrome-pilot/status` | GET | Check server and Chrome connection status | - |
+| `/chrome-pilot/recording` | POST | Upload screen recording with logs | FormData with video file, logs JSON, and duration |
+| `/chrome-pilot/recording/:id` | GET | Retrieve a recording by ID | - |
+| `/chrome-pilot/workflow-recording` | POST | Save workflow recording | `{ "sessionId": "...", "actions": [...], "logs": [...] }` |
+| `/chrome-pilot/workflow-recording/:id` | GET | Get workflow recording | - |
+| `/chrome-pilot/restore-point` | POST | Save restore point | `{ "workflowId": "...", "domSnapshot": {...}, ... }` |
+| `/chrome-pilot/restore-point/:id` | GET/DELETE | Get or delete restore point | - |
+| `/chrome-pilot/restore-points/:workflowId` | GET | List restore points for workflow | - |
+
+### MCP Tools
+
+When used as an MCP server, Chrome Debug exposes these tools:
+
+- `launch_chrome` - Launch a Chrome browser instance
+- `pause_execution` - Pause Chrome execution
+- `resume_execution` - Resume Chrome execution
+- `step_over` - Step over in debugger
+- `evaluate_expression` - Evaluate JavaScript expression
+- `get_scopes` - Get scope variables
+- `set_breakpoint` - Set a breakpoint
+- `get_logs` - Get console logs
+- `take_screenshot` - Take a screenshot
+- `get_page_content` - Get page content (text, HTML, and DOM structure)
+- `check_connection` - Check Chrome connection status
+- `force_reset` - Force reset Chrome instance
+- `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
+- `list_workflow_recordings` - List all workflow recordings
+- `save_restore_point` - Save a restore point for the current browser state
+- `restore_from_point` - Restore browser to a saved restore point
+- `list_restore_points` - List restore points for a workflow
+
+## Example
+
+```bash
+# Start the server (automatically kills existing processes and finds available port)
+npm start
+
+# The server will display the port it's running on:
+# 🚀 Starting Chrome Debug Server on port 3000...
+# 📍 Extension should connect to: http://localhost:3000
+# 🔧 MCP tools will use this port for API calls
+
+# In another terminal, test the API (use the port shown in startup)
+curl -X POST http://localhost:3000/chrome-pilot/pause
+curl -X POST http://localhost:3000/chrome-pilot/evaluate \
+  -H "Content-Type: application/json" \
+  -d '{"expression": "document.title"}'
+```
+
+## Chrome Extension - Visual Element Selection
+
+Chrome Debug includes a Chrome extension that enables visual element selection for MCP control:
+
+### Installing the Extension
+
+1. Open Chrome and navigate to `chrome://extensions/`
+2. Enable "Developer mode" 
+3. Click "Load unpacked" and select the `chrome-extension` directory
+
+### Using the Extension
+
+1. **Element Selection**
+   - Click on any element on a webpage
+   - The element is sent to Chrome Debug and highlighted in pink
+   - Use Claude MCP tools to modify the selected element:
+     - `get_selected_element` - View the currently selected element
+     - `apply_css_to_selected` - Apply CSS styles to the element
+     - `execute_js_on_selected` - Execute JavaScript on the element
+     - `clear_selected_element` - Clear the selection
+
+2. **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
+   - Workflows can be replayed later for debugging
+
+3. **Restore Points** (NEW)
+   - During workflow recording, click "📍 Save Restore Point" to capture browser state
+   - Captures DOM, form values, storage, cookies, and scroll position
+   - Restore to any saved point to retry workflows from that state
+   - Perfect for debugging multi-step forms or complex interactions
+   - See [RESTORE_POINTS.md](RESTORE_POINTS.md) for details
+
+## Development
+
+```bash
+npm run dev  # Run with --watch flag
+```
+
+## Example Prompts for Claude
+
+Once Chrome Debug is installed as an MCP server, you can use these prompts with Claude:
+
+### Basic Browser Control
+- "Launch Chrome and navigate to https://example.com"
+- "Evaluate document.title in the browser"
+- "Get all the links on the current page"
+- "Take a screenshot of the current page"
+
+### Debugging JavaScript
+- "Set a breakpoint on line 42 of app.js and tell me what variables are in scope when it hits"
+- "Pause execution and show me the current call stack"
+- "Step through the code and watch how the 'counter' variable changes"
+- "Evaluate localStorage.getItem('user') in the browser console"
+
+### Web Scraping & Automation
+- "Navigate to https://news.ycombinator.com and get the titles of the top 5 stories"
+- "Fill out the search form with 'JavaScript' and submit it"
+- "Click the login button and enter username 'test' and password 'demo'"
+- "Monitor the network requests and show me all API calls"
+
+### Debugging Web Apps
+- "Show me all console errors on this page"
+- "Watch for any uncaught exceptions and report them"
+- "Profile the page load performance"
+- "Check if there are any memory leaks by monitoring heap usage"
+
+### Advanced Debugging
+- "Set conditional breakpoints when userId === 5"
+- "Trace the execution flow of the checkout() function"
+- "Show me all event listeners attached to the submit button"
+- "Evaluate the current state of the Redux store"
+
+### Visual Element Modification
+After selecting an element with the Chrome extension:
+- "Show me what element is currently selected"
+- "Make the selected element blue with rounded corners"
+- "Apply CSS: background-color: #2196F3 !important; padding: 20px !important"
+- "Hide the selected element"
+- "Execute JavaScript to get the element's text content"
+- "Click the selected element"
+- "Clear the selected element"
+
+## Screen Recording Feature
+
+Chrome Debug includes a powerful screen recording feature that captures video of the current tab along with synchronized console logs. This helps users explain issues more effectively by providing visual context with technical details.
+
+### How to Use Recording
+
+1. **Start Recording:**
+   - Click the Chrome Debug extension icon
+   - Click "Start Recording" button
+   - The browser will prompt for permission to capture the tab
+   - Recording starts immediately after permission is granted
+
+2. **During Recording:**
+   - The button changes to "Stop Recording" and pulses red
+   - A timer shows the recording duration
+   - All console logs (log, warn, error, info) are captured with timestamps
+   - Continue using the browser normally - all interactions are recorded
+
+3. **Stop Recording:**
+   - Click "Stop Recording" button
+   - The video and logs are automatically uploaded to the Chrome Debug server
+   - You'll receive a recording ID (e.g., `rec_1234567890_abc123`)
+
+4. **Share with Claude:**
+   - Tell Claude: "Get recording rec_1234567890_abc123"
+   - Claude will retrieve the video and synchronized console logs
+   - The logs show precise timing relative to the video
+
+### Recording Details
+
+- **Video Format:** WebM with VP9 codec for efficient compression
+- **Resolution:** Up to 1920x1080 (adapts to tab size)
+- **Console Logs:** Captured with millisecond precision timestamps
+- **User Interactions:** Mouse clicks, keyboard input, scrolling automatically captured
+- **Storage:** Recordings are stored temporarily (last 10 recordings kept)
+- **No Audio:** Audio is not captured to focus on visual debugging
+
+### Captured Interactions
+
+Screen recordings now automatically capture all user interactions:
+
+- **Clicks:** Position, element selector, XPath, and clicked text
+- **Input:** Text entered into forms with field selectors
+- **Keypresses:** Special keys like Enter, Escape, Tab
+- **Scrolling:** Scroll positions throughout the recording
+
+### Example Use Cases
+
+- **Bug Reports:** Record the exact steps to reproduce an issue
+- **UI Problems:** Show visual glitches or unexpected behavior
+- **Performance Issues:** Capture slow interactions with console timing
+- **Complex Workflows:** Document multi-step processes that are hard to explain
+- **User Testing:** Review exactly how users interact with your interface
+
+### MCP Tools for Recording
+
+- `get_recording` - Retrieve a recording by ID to analyze video and logs
+- `chrome_pilot_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

package/chrome-extension/README.md

@@ -0,0 +1,41 @@
+# Chrome Debug Assistant Extension
+
+This Chrome extension enables visual element selection for the Chrome Debug MCP server.
+
+## Installation
+
+1. Open Chrome and navigate to `chrome://extensions/`
+2. Enable "Developer mode" (toggle in the top right)
+3. Click "Load unpacked"
+4. Select the `chrome-extension` directory
+
+## Usage
+
+1. Ensure the Chrome Debug MCP server is running (`npm start`)
+2. Navigate to any webpage
+3. Click on any element to select it
+4. The element will be:
+   - Highlighted with a pink outline
+   - Sent to Chrome Debug server
+   - Available for modification via Claude MCP tools
+
+## How it Works
+
+1. Click any element on the page
+2. The extension sends the element's selector to Chrome Debug
+3. Use Claude in your terminal to modify the selected element:
+   ```
+   "Show me what element is currently selected"
+   "Make the selected element blue"
+   "Apply CSS: padding: 20px !important; border-radius: 8px !important"
+   "Execute JavaScript to get the element's text content"
+   "Clear the selected element"
+   ```
+
+## Features
+
+- Visual element selection with hover highlighting
+- Automatic server detection (scans ports 3000-3025)
+- Pink outline shows currently selected element
+- Server connection status indicator
+- One-click element selection