chrometools-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, chrometools-mcp contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,329 @@
+# chrometools-mcp
+
+MCP server for Chrome automation using Puppeteer with persistent browser sessions.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Available Tools](#available-tools) - **16 Tools Total**
+  - [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
+- [Typical Workflow Example](#typical-workflow-example)
+- [Tool Usage Tips](#tool-usage-tips)
+- [Configuration](#configuration)
+- [WSL Setup Guide](#wsl-setup-guide) → [Full WSL Guide](WSL_SETUP.md)
+- [Development](#development)
+- [Features](#features)
+- [Architecture](#architecture)
+
+## Installation
+
+```bash
+npx -y chrometools-mcp
+```
+
+## Usage
+
+Add to your MCP client configuration (e.g., Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "chrometools": {
+      "command": "npx",
+      "args": ["-y", "chrometools-mcp"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### 1. Core Tools
+
+#### ping
+Test MCP connection with a simple ping-pong response.
+- **Parameters**: `message` (optional)
+- **Example**: `{ "name": "ping", "arguments": { "message": "hello" } }`
+- **Returns**: `pong: hello`
+
+#### openBrowser
+Opens browser and navigates to URL. Browser stays open for further interactions.
+- **Parameters**: `url` (required)
+- **Use case**: First step before other tools
+- **Returns**: Page title + confirmation
+
+### 2. Interaction Tools
+
+#### click
+Click an element and capture result screenshot.
+- **Parameters**:
+  - `selector` (required): CSS selector
+  - `waitAfter` (optional): Wait time in ms (default: 1500)
+- **Use case**: Buttons, links, form submissions
+- **Returns**: Confirmation text + screenshot
+
+#### type
+Type text into input fields with optional clearing and typing delay.
+- **Parameters**:
+  - `selector` (required): CSS selector
+  - `text` (required): Text to type
+  - `delay` (optional): Delay between keystrokes in ms
+  - `clearFirst` (optional): Clear field first (default: true)
+- **Use case**: Filling forms, search boxes, text inputs
+- **Returns**: Confirmation text
+
+#### scrollTo
+Scroll page to bring element into view.
+- **Parameters**:
+  - `selector` (required): CSS selector
+  - `behavior` (optional): "auto" or "smooth"
+- **Use case**: Lazy loading, sticky elements, visibility checks
+- **Returns**: Final scroll position
+
+### 3. Inspection Tools
+
+#### getElement
+Get HTML markup of element (defaults to body if no selector).
+- **Parameters**: `selector` (optional)
+- **Use case**: Inspecting structure, debugging markup
+- **Returns**: Complete outerHTML
+
+#### getComputedCss
+Get all computed CSS styles for an element.
+- **Parameters**: `selector` (optional)
+- **Use case**: Debugging layout, verifying styles
+- **Returns**: JSON object with CSS properties
+
+#### getBoxModel
+Get precise dimensions, positioning, margins, padding, and borders.
+- **Parameters**: `selector` (required)
+- **Use case**: Pixel-perfect measurements, layout analysis
+- **Returns**: Box model data + metrics
+
+#### screenshot
+Capture PNG screenshot of specific element.
+- **Parameters**:
+  - `selector` (required)
+  - `padding` (optional): Padding in pixels
+- **Use case**: Visual documentation, bug reports
+- **Returns**: Base64 PNG image
+
+### 4. Advanced Tools
+
+#### executeScript
+Execute arbitrary JavaScript in page context.
+- **Parameters**:
+  - `script` (required): JavaScript code
+  - `waitAfter` (optional): Wait time in ms (default: 500)
+- **Use case**: Complex interactions, custom manipulations
+- **Returns**: Execution result + screenshot
+
+#### getConsoleLogs
+Retrieve browser console logs (log, warn, error, etc.).
+- **Parameters**:
+  - `types` (optional): Array of log types to filter
+  - `clear` (optional): Clear logs after reading (default: false)
+- **Use case**: Debugging JavaScript errors, tracking behavior
+- **Returns**: Array of log entries with timestamps
+
+#### hover
+Simulate mouse hover over element.
+- **Parameters**: `selector` (required)
+- **Use case**: Testing hover effects, tooltips, dropdown menus
+- **Returns**: Confirmation text
+
+#### setStyles
+Apply inline CSS styles to element for live editing.
+- **Parameters**:
+  - `selector` (required)
+  - `styles` (required): Array of {name, value} pairs
+- **Use case**: Testing design changes, rapid prototyping
+- **Returns**: Applied styles confirmation
+
+#### setViewport
+Change viewport dimensions for responsive testing.
+- **Parameters**:
+  - `width` (required): 320-4000px
+  - `height` (required): 200-3000px
+  - `deviceScaleFactor` (optional): 0.5-3 (default: 1)
+- **Use case**: Testing mobile, tablet, desktop layouts
+- **Returns**: Actual viewport dimensions
+
+#### getViewport
+Get current viewport size and device pixel ratio.
+- **Parameters**: None
+- **Use case**: Checking current screen dimensions
+- **Returns**: Viewport metrics (width, height, DPR)
+
+#### navigateTo
+Navigate to different URL while keeping browser instance.
+- **Parameters**:
+  - `url` (required)
+  - `waitUntil` (optional): load event type
+- **Use case**: Moving between pages in workflow
+- **Returns**: New page title
+
+---
+
+## Typical Workflow Example
+
+```javascript
+// 1. Open page
+openBrowser({ url: "https://example.com/form" })
+
+// 2. Fill form
+type({ selector: "input[name='email']", text: "user@example.com" })
+type({ selector: "input[name='password']", text: "secret123" })
+
+// 3. Submit
+click({ selector: "button[type='submit']" })
+
+// 4. Verify
+getElement({ selector: ".success-message" })
+screenshot({ selector: ".dashboard", padding: 20 })
+```
+
+---
+
+## Tool Usage Tips
+
+**Persistent Browser:**
+- Browser windows remain open after each command
+- Manual interaction possible between AI requests
+- All tools work with currently open page
+
+**Best Practices:**
+- Start with `openBrowser` to establish context
+- Use `screenshot` to verify visual results
+- Combine tools for complex workflows
+- Tools use CDP (Chrome DevTools Protocol) for precision
+
+## Configuration
+
+### Basic Configuration (Linux, macOS, Windows)
+
+Add the MCP server to your MCP client configuration file:
+
+**Claude Desktop** (`~/.claude/mcp_config.json` or `~/AppData/Roaming/Claude/mcp_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "chrometools": {
+      "command": "npx",
+      "args": ["-y", "chrometools-mcp"]
+    }
+  }
+}
+```
+
+**Claude Code** (`~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "chrometools": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "chrometools-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+### GUI Mode vs Headless Mode
+
+The MCP server runs Chrome with `headless: false` by default, which means:
+- ✅ Browser windows are visible on your screen
+- ✅ You can interact with pages between AI requests
+- ✅ You can see what the automation is doing in real-time
+
+**Requirements for GUI Mode:**
+- **Linux/macOS**: X server (usually available by default)
+- **WSL (Windows Subsystem for Linux)**: Requires X server setup (see WSL Setup Guide below)
+- **Windows**: No additional setup needed
+
+**Alternative: Headless Mode with Virtual Display (xvfb)**
+
+If you don't need to see the browser window, you can use xvfb (virtual X server):
+
+```json
+{
+  "mcpServers": {
+    "chrometools": {
+      "type": "stdio",
+      "command": "xvfb-run",
+      "args": ["-a", "npx", "-y", "chrometools-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+This runs Chrome in GUI mode but on a virtual display (window is not visible).
+
+---
+
+## WSL Setup Guide
+
+If you're using **Windows Subsystem for Linux (WSL)**, special configuration is required to display Chrome GUI windows.
+
+📖 **See the complete WSL Setup Guide:** [WSL_SETUP.md](WSL_SETUP.md)
+
+The guide includes:
+- Step-by-step VcXsrv installation and configuration
+- MCP server configuration for WSL (3 different options)
+- Testing and troubleshooting procedures
+- Solutions for common issues
+- All reference links and resources
+
+**Quick Summary for WSL Users:**
+1. Install VcXsrv on Windows ([Download](https://sourceforge.net/projects/vcxsrv/))
+2. Enable "Disable access control" in VcXsrv settings ⚠️ (Critical!)
+3. Configure MCP server with `DISPLAY=<your-windows-ip>:0` environment variable
+4. Fully restart your MCP client
+
+For detailed instructions, see [WSL_SETUP.md](WSL_SETUP.md).
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run locally
+npm start
+
+# Test with MCP inspector
+npx @modelcontextprotocol/inspector node index.js
+```
+
+## Features
+
+- **16 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
+- **Console Log Capture**: Automatic JavaScript console monitoring
+- **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
+- **Simple Installation**: One command with npx
+- **CDP Integration**: Uses Chrome DevTools Protocol for precision
+- **AI-Friendly**: Detailed descriptions optimized for AI agents
+- **Responsive Testing**: Built-in viewport control for mobile/tablet/desktop
+
+## Architecture
+
+- Uses Puppeteer for Chrome automation
+- MCP Server SDK for protocol implementation
+- Zod for schema validation
+- Stdio transport for communication

package/WSL_SETUP.md

@@ -0,0 +1,270 @@
+# WSL Setup Guide for chrometools-mcp
+
+If you're using **Windows Subsystem for Linux (WSL)**, follow these steps to enable visible Chrome GUI windows.
+
+> **Note:** This setup is based on the solution from [Puppeteer Issue #8148](https://github.com/puppeteer/puppeteer/issues/8148#issuecomment-1195390456):
+>
+> _"I was able to partially resolve this issue using VcXsrv Windows X Server, and with the help of this guide [...] now when I enter `google-chrome` into my WSL Ubuntu terminal, it launches and works just fine."_
+> — Solution tested on Ubuntu WSL2 on Windows 11
+
+## Table of Contents
+
+- [Why WSL Needs Special Setup?](#why-wsl-needs-special-setup)
+- [Step 1: Install VcXsrv Windows X Server](#step-1-install-vcxsrv-windows-x-server)
+- [Step 2: Configure VcXsrv (First Time Setup)](#step-2-configure-vcxsrv-first-time-setup)
+- [Step 3: Configure MCP Server for WSL](#step-3-configure-mcp-server-for-wsl)
+- [Step 4: Test the Setup](#step-4-test-the-setup)
+- [Step 5: Restart MCP Client](#step-5-restart-mcp-client)
+- [Troubleshooting WSL](#troubleshooting-wsl)
+- [References](#references-for-wsl-setup)
+
+---
+
+## Why WSL Needs Special Setup?
+
+WSL runs Linux in a separate environment from Windows. To display GUI applications (like Chrome), you need an X server running on Windows that WSL can connect to.
+
+## Step 1: Install VcXsrv Windows X Server
+
+VcXsrv is a free X server for Windows that allows WSL Linux applications to display GUI windows.
+
+**Download and Install:**
+1. Download VcXsrv: [https://sourceforge.net/projects/vcxsrv/](https://sourceforge.net/projects/vcxsrv/)
+2. Run the installer (default settings are fine)
+3. Launch **XLaunch** from Start Menu or Desktop
+
+## Step 2: Configure VcXsrv (First Time Setup)
+
+When you launch XLaunch for the first time, configure it as follows:
+
+**Screen 1: Display settings**
+- ✅ Select **"Multiple windows"** (recommended for WSL)
+- Display number: `0` (leave default)
+- Click "Next"
+
+**Screen 2: Client startup**
+- ✅ Select **"Start no client"** (recommended)
+- Click "Next"
+
+**Screen 3: Extra settings** ⚠️ **IMPORTANT**
+- ☑️ **"Clipboard"** (optional, convenient for copy-paste)
+- ☑️ **"Disable access control"** ✅ **MUST BE ENABLED!**
+  - This allows WSL to connect to the X server
+  - Without this, you'll get "Connection refused" errors
+- Click "Next"
+
+**Screen 4: Finish**
+- Optionally save configuration as `.xlaunch` file for quick restart
+- Place saved file in Windows Startup folder for automatic launch
+- Click "Finish"
+
+**Verify VcXsrv is Running:**
+- Check for VcXsrv icon in Windows system tray (bottom-right)
+- If you see the icon, VcXsrv is running
+
+## Step 3: Configure MCP Server for WSL
+
+**Find your Windows host IP address:**
+
+In WSL terminal, run:
+```bash
+ip route show | grep -i default | awk '{print $3}'
+```
+
+You should see an IP like `172.x.x.1` (commonly `172.25.96.1` or similar).
+
+### Option A: Using Environment Variable (Recommended)
+
+Configure the MCP server with `DISPLAY` pointing to your Windows host:
+
+```json
+{
+  "mcpServers": {
+    "chrometools": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "chrometools-mcp"],
+      "env": {
+        "DISPLAY": "172.25.96.1:0"
+      }
+    }
+  }
+}
+```
+
+⚠️ **Replace `172.25.96.1` with your actual Windows host IP!**
+
+### Option B: Using Direct Node Path (For Claude Code)
+
+If you're using Claude Code, use the full path to node:
+
+```json
+{
+  "mcpServers": {
+    "chrometools": {
+      "type": "stdio",
+      "command": "/home/user/.nvm/versions/node/v22.20.0/bin/node",
+      "args": ["/path/to/chrometools-mcp/index.js"],
+      "env": {
+        "DISPLAY": "172.25.96.1:0"
+      }
+    }
+  }
+}
+```
+
+### Option C: Using xvfb (No VcXsrv Required)
+
+If you don't want to install VcXsrv, you can use xvfb (virtual display):
+
+```bash
+# Install xvfb in WSL
+sudo apt-get update
+sudo apt-get install -y xvfb
+```
+
+Then configure:
+
+```json
+{
+  "mcpServers": {
+    "chrometools": {
+      "type": "stdio",
+      "command": "xvfb-run",
+      "args": ["-a", "npx", "-y", "chrometools-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+**Note:** With xvfb, the browser runs but windows are **not visible**. This is useful for automation without GUI.
+
+## Step 4: Test the Setup
+
+### Test VcXsrv Connection (if using GUI mode)
+
+In WSL terminal:
+```bash
+# Set DISPLAY variable (use your Windows host IP)
+export DISPLAY=172.25.96.1:0
+
+# Test X server connection
+timeout 3 nc -zv 172.25.96.1 6000
+```
+
+Expected output: `Connection to 172.25.96.1 6000 port [tcp/x11] succeeded!`
+
+If you get "Connection refused", check:
+- VcXsrv is running (icon in system tray)
+- "Disable access control" is enabled in XLaunch settings
+- Windows Firewall is not blocking port 6000
+
+### Test Chrome GUI
+
+```bash
+# Test with a simple command
+DISPLAY=172.25.96.1:0 google-chrome https://example.com
+```
+
+You should see a Chrome window appear on your screen with example.com loaded!
+
+## Step 5: Restart MCP Client
+
+After configuring, **fully restart your MCP client** (Claude Desktop or Claude Code):
+- Close the application completely
+- Relaunch it
+- The MCP server will now use the new configuration
+
+## Troubleshooting WSL
+
+### Problem: "Missing X server" error
+
+```
+Error: Missing X server to start the headful browser.
+```
+
+**Solutions:**
+1. Make sure VcXsrv is running (check system tray)
+2. Verify "Disable access control" is enabled in VcXsrv
+3. Check DISPLAY variable is set correctly in MCP config
+4. Test X server connection: `nc -zv 172.25.96.1 6000`
+5. Fully restart MCP client after config changes
+
+### Problem: Browser opens but window is not visible
+
+**Cause:** MCP server is using xvfb (virtual display) instead of VcXsrv.
+
+**Solution:**
+1. Check your config has `"env": { "DISPLAY": "172.25.96.1:0" }`
+2. Make sure you're **not** using `xvfb-run` in the command
+3. Fully restart MCP client (close and reopen)
+4. Check process: `ps aux | grep chrometools` - should NOT show `xvfb-run`
+
+### Problem: Windows Firewall blocking connection
+
+If `nc -zv 172.25.96.1 6000` fails, Windows Firewall might be blocking the connection.
+
+**Solution:**
+1. Open Windows Defender Firewall
+2. Click "Allow an app or feature through Windows Defender Firewall"
+3. Find "VcXsrv windows xserver" and enable it for Private networks
+4. If not listed, click "Allow another app" and add `vcxsrv.exe`
+
+### Problem: IP address changes after Windows restart
+
+WSL assigns a new IP to Windows host after each restart.
+
+**Solution:** Create a startup script to get current IP:
+
+```bash
+# In WSL ~/.bashrc or ~/.zshrc
+export DISPLAY=$(ip route show | grep -i default | awk '{print $3}'):0
+```
+
+Or use a helper script:
+```bash
+#!/bin/bash
+# ~/.local/bin/win-ip.sh
+ip route show | grep -i default | awk '{print $3}'
+```
+
+## References for WSL Setup
+
+These resources were instrumental in solving the WSL + Puppeteer GUI setup:
+
+- **VcXsrv Windows X Server** (Free X server for Windows)
+  [https://sourceforge.net/projects/vcxsrv/](https://sourceforge.net/projects/vcxsrv/)
+
+- **ChromeDriver in WSL2** by Greg Brisebois (Comprehensive setup guide)
+  [https://www.gregbrisebois.com/posts/chromedriver-in-wsl2/](https://www.gregbrisebois.com/posts/chromedriver-in-wsl2/)
+
+- **Puppeteer Issue #8148** (Missing X server or $DISPLAY)
+  - Main issue thread: [https://github.com/puppeteer/puppeteer/issues/8148](https://github.com/puppeteer/puppeteer/issues/8148)
+  - Solution comment: [https://github.com/puppeteer/puppeteer/issues/8148#issuecomment-1195390456](https://github.com/puppeteer/puppeteer/issues/8148#issuecomment-1195390456)
+
+- **Stack Overflow: WSL2 X Server Setup**
+  [https://stackoverflow.com/a/66398613](https://stackoverflow.com/a/66398613)
+
+**Additional Resources:**
+- [WSL GUI Apps Official Documentation](https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps) (Microsoft)
+- [Puppeteer Troubleshooting Guide](https://pptr.dev/troubleshooting) (Official Docs)
+
+---
+
+## Quick Summary
+
+**For visible Chrome windows in WSL:**
+1. Install and run VcXsrv on Windows
+2. Enable "Disable access control" in VcXsrv settings
+3. Get Windows host IP: `ip route show | grep -i default | awk '{print $3}'`
+4. Configure MCP server with `DISPLAY=<your-ip>:0` in env
+5. Fully restart MCP client
+6. Test: `DISPLAY=172.25.96.1:0 google-chrome https://example.com`
+
+**For headless automation (no visible windows):**
+1. Install xvfb: `sudo apt-get install xvfb`
+2. Configure MCP server with `xvfb-run` command
+3. Restart MCP client
+
+[← Back to README](README.md)