# Extended Playwright MCP Server

This MCP server extends the official `@playwright/mcp` server by implementing 22 additional tools to facilitate web automation, direct uploads, element interactions, and advanced scraping workflows for AI agents. All standard Playwright tools remain 1:1 available and fully functional.

## Custom Tools (Features)

### 1. `download_and_convert_images`
* **Description**: Downloads an image from a given URL, converts it to PNG format, and saves it locally.
* **Parameters**:
  * `url` (String, required): The URL of the image to download.
  * `outputDir` (String, optional): The target directory (defaults to a directory named `downloads` inside the current workspace).

### 2. `browser_get_html`
* **Description**: Extracts the raw HTML markup of a specific element (by CSS selector or Snapshot ID) or the entire page.
* **Parameters**:
  * `target` (String, optional): CSS selector or Snapshot ID. If omitted, the HTML of the entire page is returned.

### 3. `browser_scroll_to`
* **Description**: Scrolls the page or a specific element to coordinates or preset positions.
* **Parameters**:
  * `target` (String, optional): CSS selector or Snapshot ID of the element to scroll into view.
  * `x` (Number, optional): Horizontal scroll coordinate.
  * `y` (Number, optional): Vertical scroll coordinate.
  * `position` (Enum `["top", "bottom", "intoView"]`, optional): Scroll position preset.

### 4. `browser_extract_table`
* **Description**: Finds and extracts HTML table data (`<table>` or grid rows) and returns it as a structured JSON array.
* **Parameters**:
  * `target` (String, required): CSS selector or Snapshot ID of the table or grid element.

### 5. `browser_wait_for_network_idle`
* **Description**: Blocks execution until all network requests on the page are completed (no network requests active for at least 500ms). Perfect for modern Single Page Applications (SPAs).
* **Parameters**:
  * `timeout` (Number, optional): Maximum timeout in milliseconds (defaults to 10000ms).

### 6. `browser_get_attributes`
* **Description**: Returns all HTML attributes of an element as a key-value object (e.g. class, style, data-* attributes).
* **Parameters**:
  * `target` (String, required): CSS selector or Snapshot ID of the target element.

### 7. `browser_handle_download`
* **Description**: Clicks an element, intercepts the triggered browser download event, and saves the file to the workspace.
* **Parameters**:
  * `target` (String, required): CSS selector of the download button or link.
  * `filename` (String, optional): Custom filename to save the file as locally.

### 8. `browser_clear_input`
* **Description**: Deterministically clears the text content of any input field or textarea.
* **Parameters**:
  * `target` (String, required): CSS selector or Snapshot ID of the input field.

### 9. `browser_manage_storage`
* **Description**: Allows reading, writing, or clearing data from `localStorage` or `sessionStorage`.
* **Parameters**:
  * `action` (Enum `["get", "set", "clear"]`, required): The storage action to perform.
  * `storageType` (Enum `["local", "session"]`, required): The storage engine type.
  * `key` (String, optional): The key to access or modify (required for `get` and `set`).
  * `value` (String, optional): The value to write (required for `set`).

### 10. `browser_toggle_checkbox`
* **Description**: Checks or unchecks a checkbox or radio button element deterministically.
* **Parameters**:
  * `target` (String, required): CSS selector or Snapshot ID of the target element.
  * `checked` (Boolean, required): Whether the element should be checked (`true`) or unchecked (`false`).

### 11. `browser_mock_route`
* **Description**: Intercepts and blocks network requests (e.g. blocking images/ads to save bandwidth/tokens) or fulfills them with mock HTTP responses.
* **Parameters**:
  * `urlPattern` (String, required): Glob or regex pattern (e.g. `**/*.{png,jpg}` or `**/api/v1/data`).
  * `action` (Enum `["abort", "mock"]`, required): Action to perform.
  * `mockStatus` (Number, optional): HTTP status code for mock responses.
  * `mockBody` (String, optional): Response body for mock responses.

### 12. `browser_upload_file_direct`
* **Description**: Directly uploads files to a file input element (`<input type="file">`) without needing to trigger or wait for a browser file chooser modal.
* **Parameters**:
  * `target` (String, required): CSS selector or Snapshot ID of the file input element.
  * `paths` (Array of Strings, required): List of absolute/relative file paths to assign.

### 13. `browser_take_screenshot_element`
* **Description**: Captures a PNG/JPEG screenshot of a specific element and saves it to the workspace.
* **Parameters**:
  * `target` (String, required): CSS selector or Snapshot ID of the target element.
  * `filename` (String, optional): Custom filename to save the screenshot.
  * `type` (Enum `["png", "jpeg"]`, optional): Output image format (defaults to `png`).

### 14. `browser_get_page_info`
* **Description**: Retrieves frame tree, URL, page title, user agent, tab count, and viewport information.
* **Parameters**: None.

### 15. `browser_set_geolocation`
* **Description**: Emulates a specific geographic location for testing region-restricted content.
* **Parameters**:
  * `latitude` (Number, required): Latitude between -90 and 90.
  * `longitude` (Number, required): Longitude between -180 and 180.
  * `accuracy` (Number, optional): Geolocation accuracy value.

### 16. `browser_emulate_media`
* **Description**: Emulates dark/light color scheme theme settings and media type queries (screen vs. print).
* **Parameters**:
  * `colorScheme` (Enum `["light", "dark", "no-preference"]`, optional): Emulated color scheme.
  * `media` (Enum `["screen", "print", "null"]`, optional): Emulated media type.

### 17. `browser_focus_element`
* **Description**: Directs DOM focus onto the target element.
* **Parameters**:
  * `target` (String, required): CSS selector or Snapshot ID of the element to focus.

### 18. `browser_dispatch_event`
* **Description**: Dispatches a custom event (e.g. click, change, input) with optional custom initialization parameters on a target element.
* **Parameters**:
  * `target` (String, required): CSS selector or Snapshot ID of the target element.
  * `type` (String, required): Event type string (e.g. `'change'`).
  * `eventInit` (Object, optional): Custom event initialization parameters.

### 19. `browser_get_element_state`
* **Description**: Checks current states of an element: whether it is visible, enabled, editable, or checked.
* **Parameters**:
  * `target` (String, required): CSS selector or Snapshot ID of the element.

### 20. `browser_key_down_up`
* **Description**: Separately fires keydown and keyup events for modifier controls or custom key holding.
* **Parameters**:
  * `key` (String, required): Name of the key (e.g., 'Shift', 'Control', 'a', 'ArrowUp').
  * `action` (Enum `["down", "up"]`, required): Press down or release key.

### 21. `browser_get_links`
* **Description**: Extracts and lists all internal and external link URLs from the current page.
* **Parameters**: None.

### 22. `browser_mouse_move_click`
* **Description**: Performs absolute mouse movement and click actions on coordinate pixels.
* **Parameters**:
  * `x` (Number, required): X coordinate in pixels.
  * `y` (Number, required): Y coordinate in pixels.
  * `click` (Boolean, optional): Set to true to click at the coordinates.
  * `button` (Enum `["left", "right", "middle"]`, optional): Mouse click button.

---

## Integration

You can bind this local MCP server to your preferred MCP client (such as Claude Desktop or Cursor). Since it runs locally, you execute it using `node` and the path to the compiled JavaScript bundle.

### 1. Claude Desktop (Configuration)

Add the server to your Claude Desktop configuration file (e.g. at `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": [
        "C:/Users/danev/Downloads/extend-playwright-mcp/dist/index.js",
        "--extension"
      ],
      "env": {
        "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "PYefeTc_P7a5Ej8TmHCIshkWvtIPnlQ90H04ItZ66Aw"
      }
    }
  }
}
```

> **Note**: Replace `C:/Users/danev/Downloads/extend-playwright-mcp` with your actual directory path if the project folder is moved. Ensure you use forward slashes (`/`) instead of backslashes (`\`) in the JSON paths.

### 2. Cursor (Configuration)

Add a new MCP server in Cursor:
* **Name**: `playwright`
* **Type**: `command`
* **Command**:
  ```bash
  node "C:/Users/danev/Downloads/extend-playwright-mcp/dist/index.js" --extension
  ```
* **Environment Variables**:
  * Name: `PLAYWRIGHT_MCP_EXTENSION_TOKEN`
  * Value: `PYefeTc_P7a5Ej8TmHCIshkWvtIPnlQ90H04ItZ66Aw`

---

## Development and Compilation

If you modify the TypeScript code, compile the project again using:

```bash
# Install dependencies
npm install

# Compile the project (outputs to the dist/ folder)
npm run build
```