StealthyBrowserAgent MCP Endpoint

This specialized Model Context Protocol (MCP) server wraps the Patchright Node.js Software Development Kit (SDK) to deliver clandestine web automation capabilities directly to sophisticated artificial intelligence models. This optimized, minimal server implementation concentrates solely on core operational necessities, simplifying accessibility for less complex AI architectures.

Understanding Patchright

Patchright functions as an obfuscated derivative of the Playwright testing and automation framework. It is engineered to serve as a direct, concealed substitution for standard Playwright installations, incorporating superior anti-detection mechanisms to bypass contemporary bot mitigation systems. Patchright systematically neutralizes common detection vectors, specifically targeting:

• Leakage via Runtime.enable calls
• Obfuscation of Console.enable usage
• Concealment of known command-line flags
• General fingerprinting telemetry points
• Manipulation of interactions involving closed Shadow Roots

This server leverages the capabilities of the Node.js Patchright environment, exposing its functionality via a straightforward, uniform protocol interface for AI consumption.

Key Capabilities

• Streamlined API: Features only 4 fundamental, high-utility operations.
• Evasion-Oriented Automation: Leverages Patchright's specialized stealth mode to evade automated system scrutiny.
• MCP Compliance: Fully adheres to the Model Context Protocol standard for straightforward AI integration.
• Inter-Process Communication: Utilizes standard input/output (stdio) streams for simple, direct connectivity.

Prerequisites for Deployment

• Node.js environment (version 18 or newer)
• Package manager: npm or yarn

Setup Guide

1. Obtain the source code repository: bash git clone https://github.com/yourusername/patchright-lite-mcp-server.git cd patchright-lite-mcp-server

2. Install necessary dependencies: bash npm install

3. Compile the TypeScript source code: bash npm run build

4. Acquire the required browser driver for Patchright: bash npx patchright install chromium

Execution Instructions

Initiate the agent service using:

bash npm start

This command launches the server employing the stdio transport method, rendering it immediately available for orchestration by MCP-compatible AI entities.

Integration Methods for AI Frameworks

Claude Desktop Integration

Integrate the following configuration into your claude-desktop-config.json file:

{ "mcpServers": { "patchright": { "command": "node", "args": ["path/to/patchright-lite-mcp-server/dist/index.js"] } } }

VS Code / GitHub Copilot Integration

Utilize the VS Code Command Line Interface (CLI) to register the MCP endpoint:

bash code --add-mcp '{"name":"patchright","command":"node","args":["path/to/patchright-lite-mcp-server/dist/index.js"]}'

Exposed Toolset

The service exposes a quartet of essential operational interfaces:

1. NavigateAndCapture (browse)

Initializes a browser instance, navigates to a specified Uniform Resource Locator (URL), and captures page artifacts.

Tool: browse Parameters: { "url": "https://example.com", "headless": true, "waitFor": 1000 }

Output Delivers: - The document's designated title - A preliminary textual summary of visible elements - A unique identifier for the browser instance - A unique identifier for the active page tab - Path to the captured screen image

2. ElementOperation (interact)

Executes a targeted manipulation on an element within the active browsing context.

Tool: interact Parameters: { "browserId": "browser-id-from-browse", "pageId": "page-id-from-browse", "action": "click", // Options: "click", "fill", or "select" "selector": "#submit-button", "value": "Hello World" // Required only for 'fill' and 'select' actions }

Output Delivers: - Status report on the performed action - The current navigated URL - Path to a post-action screenshot

3. DataHarvest (extract)

Retrieves explicitly defined data from the current viewport.

Tool: extract Parameters: { "browserId": "browser-id-from-browse", "pageId": "page-id-from-browse", "type": "text" // Options: "text", "html", or "screenshot" }

Output Delivers: - The retrieved dataset, formatted according to the specified type

4. TerminateSession (close)

Safely shuts down a running browser instance to reclaim system resources.

Tool: close Parameters: { "browserId": "browser-id-from-browse" }

Illustrative Workflow Sequence

1. Establish a browser context and load a target location:

Tool: browse Parameters: { "url": "https://example.com/login", "headless": false }

1. Input user credentials into the appropriate field:

Tool: interact Parameters: { "browserId": "browser-id-from-step-1", "pageId": "page-id-from-step-1", "action": "fill", "selector": "#username", "value": "user@example.com" }

1. Input the secret key/password:

Tool: interact Parameters: { "browserId": "browser-id-from-step-1", "pageId": "page-id-from-step-1", "action": "fill", "selector": "#password", "value": "password123" }

1. Initiate the form submission:

Tool: interact Parameters: { "browserId": "browser-id-from-step-1", "pageId": "page-id-from-step-1", "action": "click", "selector": "#login-button" }

1. Parse the resultant page content to confirm successful authentication:

Tool: extract Parameters: { "browserId": "browser-id-from-step-1", "pageId": "page-id-from-step-1", "type": "text" }

1. Conclude the session and dispose of the browser process:

Tool: close Parameters: { "browserId": "browser-id-from-step-1" }

Ethical and Safety Protocols

• This service grants substantial control over web environments; deployment must adhere strictly to ethical guidelines.
• Refrain from automating actions that contravene the service agreements or terms of use of target websites.
• Implement throttling mechanisms to prevent excessive request rates that could constitute service disruption.

Licensing Information

This software is distributed under the permissive MIT License (refer to the LICENSE file for specifics).

Credits and Recognition

• Acknowledgement to Kaliiiiiiiiii-Vinyzu for the Patchright-nodejs implementation.
• Acknowledgement to modelcontextprotocol for defining the Model Context Protocol specification.

Containerized Deployment (Docker)

Run this specialized agent using a pre-built Docker image:

bash docker run -it --rm dylangroos/patchright-mcp

Local Image Construction

Generate the Docker artifact locally:

bash docker build -t patchright-mcp .

Execute the local container:

bash docker run -it --rm patchright-mcp

Docker Hub Registry

The official image is automatically published to Docker Hub upon main branch merges. The latest artifact is accessible here: dylangroos/patchright-mcp

WIKIPEDIA CONTEXTUAL NOTE: A 'headless browser' operates without a visible graphical user interface. These tools provide programmatic governance over web content, simulating standard browser functions via command-line or network protocols. They are invaluable for web integrity validation because they interpret layout, styling (color, fonts), and execute scripting (JavaScript/Ajax) accurately, unlike simpler testing methods. Modern browser engines (Chrome 59+, Firefox 56+) incorporate native remote control APIs, rendering older solutions like PhantomJS largely obsolete.

== Primary Applications == The core utility of headless browsers centers on:

• Validation testing for contemporary web applications (Web Testing).
• Automated acquisition of visual page snapshots.
• Execution harnesses for JavaScript library verification suites.
• Programmatic control and interaction with web page elements.

=== Secondary Functions === Headless modes are also beneficial for web data aggregation (scraping). Google recognized their utility in 2009 for indexing content reliant on Ajax rendering. Conversely, misuse cases have been documented, including:

• Orchestration of Distributed Denial of Service (DDoS) attacks.
• Artificially inflating advertisement view counts.
• Unsanctioned automated interaction, such as credential stuffing.

However, 2018 traffic analysis indicated that malicious actors show no distinct bias towards headless over standard browser traffic for illicit activities like SQL injection or cross-site scripting.

== Automation Frameworks Leveraging Headless Mode == Since major rendering engines now natively expose headless modes via APIs, several unified interface solutions facilitate browser automation:

• Selenium WebDriver (W3C compliant implementation of WebDriver)
• Playwright (Node.js interface for Chromium, Firefox, and WebKit)
• Puppeteer (Node.js interface specifically for Chrome or Firefox)

=== Integration within Testing Suites === Numerous quality assurance frameworks incorporate headless browsing capabilities into their operational apparatus:

• Capybara (utilizes WebKit or Headless Chrome for user behavior simulation).
• Jasmine (defaults to Selenium but supports WebKit/Headless Chrome for environment testing).
• Cypress (a dedicated frontend verification framework).
• QF-Test (a tool for GUI-based automated validation).

=== Non-Rendering API Alternatives === An alternative methodology involves utilizing software that supplies browser-like APIs without full rendering capability. Examples include Deno's built-in browser APIs or jsdom for Node.js environments. While these often support parsing, cookie handling, and XHR requests, they lack DOM rendering and have limited event support, typically resulting in faster execution speeds than full rendering engines.