patchright-cli 0.7.0__tar.gz → 0.8.0__tar.gz

{patchright_cli-0.7.0 → patchright_cli-0.8.0}/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Anti-detect browser automation CLI & Skills for AI agents, powered by Patchright",
-    "version": "0.7.0"
+    "version": "0.8.0"
   },
   "plugins": [
     {

patchright_cli-0.7.0/README.md → patchright_cli-0.8.0/PKG-INFO

@@ -1,3 +1,39 @@
+Metadata-Version: 2.5
+Name: patchright-cli
+Version: 0.8.0
+Summary: Anti-detect browser automation CLI using Patchright (undetected Playwright fork)
+Project-URL: Homepage, https://github.com/AhaiMk01/patchright-cli
+Project-URL: Repository, https://github.com/AhaiMk01/patchright-cli
+Project-URL: Issues, https://github.com/AhaiMk01/patchright-cli/issues
+Author: zpahai
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: anti-detect,automation,browser,cli,patchright,playwright,scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: click
+Requires-Dist: patchright
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: fastmcp<5,>=3.0; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: fastmcp<5,>=3.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
 # patchright-cli
 
 [![PyPI version](https://img.shields.io/pypi/v/patchright-cli?color=blue&label=PyPI)](https://pypi.org/project/patchright-cli/)
@@ -339,6 +375,34 @@ patchright-cli install --skills
 
 </details>
 
+### MCP server
+
+MCP support is optional so the base CLI install stays small:
+
+```bash
+pip install 'patchright-cli[mcp]'
+
+# stdio (default)
+patchright-cli mcp
+
+# Streamable HTTP
+patchright-cli mcp --http --host=127.0.0.1 --port=8000
+```
+
+![How a remote MCP call reaches Chrome](docs/mcp-architecture.svg)
+
+The HTTP endpoint is `/mcp`. Set `PATCHRIGHT_CLI_MCP_TOKEN` to require `Authorization: Bearer <token>` on every request, and always set it before binding to `0.0.0.0`.
+
+File paths passed to MCP tools (uploads, state and cookie files, screenshot/PDF/snapshot output, profile directories) must be absolute and beneath the MCP root, so a client cannot reach arbitrary host files. Outputs without a path land in `<root>/output/`, which `browser_delete_output` can clean up. `patchright_eval` and `patchright_run_code` still run arbitrary JavaScript in the page, so protect HTTP deployments regardless.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `PATCHRIGHT_CLI_MCP_TOKEN` | unset (no auth) | Bearer token required by the HTTP transport |
+| `PATCHRIGHT_CLI_MCP_ROOT` | working directory | Root that tool file paths must sit beneath |
+| `PATCHRIGHT_CLI_MCP_UNRESTRICTED_FILESYSTEM` | unset | `1` drops the path check and enables `patchright_install_skills` |
+| `PATCHRIGHT_CLI_MCP_HEADLESS` | unset (headed) | `1` makes `patchright_open` default to headless, for hosts without a display |
+| `PATCHRIGHT_CLI_MCP_DAEMON_PORT` | `9321` | Daemon port the tools talk to |
+
 ### Skill docs
 
 | File | Topic |

patchright_cli-0.7.0/PKG-INFO → patchright_cli-0.8.0/README.md

@@ -1,36 +1,3 @@
-Metadata-Version: 2.5
-Name: patchright-cli
-Version: 0.7.0
-Summary: Anti-detect browser automation CLI using Patchright (undetected Playwright fork)
-Project-URL: Homepage, https://github.com/AhaiMk01/patchright-cli
-Project-URL: Repository, https://github.com/AhaiMk01/patchright-cli
-Project-URL: Issues, https://github.com/AhaiMk01/patchright-cli/issues
-Author: zpahai
-License-Expression: Apache-2.0
-License-File: LICENSE
-Keywords: anti-detect,automation,browser,cli,patchright,playwright,scraping
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
-Classifier: Topic :: Software Development :: Testing
-Requires-Python: >=3.10
-Requires-Dist: aiohttp>=3.9
-Requires-Dist: click
-Requires-Dist: patchright
-Requires-Dist: pyyaml
-Provides-Extra: dev
-Requires-Dist: pre-commit; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Description-Content-Type: text/markdown
-
 # patchright-cli
 
 [![PyPI version](https://img.shields.io/pypi/v/patchright-cli?color=blue&label=PyPI)](https://pypi.org/project/patchright-cli/)
@@ -372,6 +339,34 @@ patchright-cli install --skills
 
 </details>
 
+### MCP server
+
+MCP support is optional so the base CLI install stays small:
+
+```bash
+pip install 'patchright-cli[mcp]'
+
+# stdio (default)
+patchright-cli mcp
+
+# Streamable HTTP
+patchright-cli mcp --http --host=127.0.0.1 --port=8000
+```
+
+![How a remote MCP call reaches Chrome](docs/mcp-architecture.svg)
+
+The HTTP endpoint is `/mcp`. Set `PATCHRIGHT_CLI_MCP_TOKEN` to require `Authorization: Bearer <token>` on every request, and always set it before binding to `0.0.0.0`.
+
+File paths passed to MCP tools (uploads, state and cookie files, screenshot/PDF/snapshot output, profile directories) must be absolute and beneath the MCP root, so a client cannot reach arbitrary host files. Outputs without a path land in `<root>/output/`, which `browser_delete_output` can clean up. `patchright_eval` and `patchright_run_code` still run arbitrary JavaScript in the page, so protect HTTP deployments regardless.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `PATCHRIGHT_CLI_MCP_TOKEN` | unset (no auth) | Bearer token required by the HTTP transport |
+| `PATCHRIGHT_CLI_MCP_ROOT` | working directory | Root that tool file paths must sit beneath |
+| `PATCHRIGHT_CLI_MCP_UNRESTRICTED_FILESYSTEM` | unset | `1` drops the path check and enables `patchright_install_skills` |
+| `PATCHRIGHT_CLI_MCP_HEADLESS` | unset (headed) | `1` makes `patchright_open` default to headless, for hosts without a display |
+| `PATCHRIGHT_CLI_MCP_DAEMON_PORT` | `9321` | Daemon port the tools talk to |
+
 ### Skill docs
 
 | File | Topic |

patchright_cli-0.8.0/docs/mcp-architecture.svg

@@ -0,0 +1,120 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="470" viewBox="0 0 1200 470" role="img" aria-label="A remote MCP client sends tools/call over HTTP across a network boundary guarded by an optional Bearer token to the patchright-cli MCP server on the host. The server spawns one short-lived CLI process per call, which sends length-prefixed JSON over TCP to the long-lived daemon. The daemon drives real Chrome over CDP; headed Chrome draws on an Xvfb display and loads websites over HTTPS. Output files land in the root's output directory on the host.">
+        <style>
+  svg { --bg: #ffffff; --fg: #1b2230; --muted: #5d6778; --line: #c9cfd9; --accent: #c2410c; --host: #eef1f6;
+        color: var(--fg); font-family: -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; }
+  @media (prefers-color-scheme: dark) {
+    svg { --bg: #0d1117; --fg: #e6edf3; --muted: #9aa4b4; --line: #3a4352; --accent: #fb923c; --host: #161b22; }
+  }
+  .bg { fill: var(--bg); }
+  .box { fill: var(--bg); stroke: currentColor; stroke-width: 1.4; }
+  .ghost { fill: var(--bg); stroke: var(--line); stroke-width: 1.2; }
+  .hostbg { fill: var(--host); stroke: var(--line); stroke-width: 1.2; }
+  .t { fill: currentColor; font-size: 14px; font-weight: 600; text-anchor: middle; }
+  .s { fill: var(--muted); font-size: 11.5px; text-anchor: middle; }
+  .m { fill: var(--muted); font-family: ui-monospace, Consolas, monospace; font-size: 11px; text-anchor: middle; }
+  .lbl { fill: currentColor; font-size: 12px; text-anchor: middle; paint-order: stroke; stroke: var(--bg); stroke-width: 5px; stroke-linejoin: round; }
+  .lbl.start { text-anchor: start; }
+  .region { fill: var(--muted); font-family: ui-monospace, Consolas, monospace; font-size: 11px; letter-spacing: 0.05em; text-transform: uppercase; }
+  .edge { stroke: currentColor; stroke-width: 1.4; fill: none; }
+  .edge.dim { stroke: var(--muted); stroke-dasharray: 4 3; }
+  .boundary { stroke: var(--accent); stroke-width: 1.6; stroke-dasharray: 6 5; }
+  .warn { fill: var(--accent); font-size: 12px; font-weight: 600; text-anchor: middle; paint-order: stroke; stroke: var(--bg); stroke-width: 5px; }
+  .head { fill: currentColor; }
+  .head.dim { fill: var(--muted); }
+</style>
+        <rect class="bg" x="0" y="0" width="1200" height="470"/>
+        <defs>
+          <marker id="ah" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+            <path class="head" d="M0,0 L10,5 L0,10 z"/>
+          </marker>
+          <marker id="ahd" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+            <path class="head dim" d="M0,0 L10,5 L0,10 z"/>
+          </marker>
+        </defs>
+
+        <!-- host region -->
+        <rect class="hostbg" x="250" y="30" width="820" height="420" rx="10"/>
+        <text class="region" x="268" y="54">Host · container or server</text>
+        <text class="region" x="20" y="54">Remote machine</text>
+        <text class="region" x="1100" y="54">Internet</text>
+
+        <!-- trust boundary -->
+        <line class="boundary" x1="205" y1="24" x2="205" y2="456"/>
+        <text class="warn" x="205" y="300">trust boundary</text>
+        <text class="warn" x="205" y="317" style="font-weight:400">optional Bearer token</text>
+
+        <!-- client -->
+        <rect class="box" x="20" y="170" width="140" height="80" rx="6"/>
+        <text class="t" x="90" y="205">MCP client</text>
+        <text class="s" x="90" y="225">Claude Code, agents</text>
+
+        <!-- client <-> server -->
+        <line class="edge" x1="160" y1="195" x2="268" y2="195" marker-end="url(#ah)"/>
+        <text class="lbl" x="215" y="187">tools/call</text>
+        <line class="edge" x1="270" y1="228" x2="162" y2="228" marker-end="url(#ah)"/>
+        <text class="lbl" x="215" y="246">text · PNG · YAML</text>
+
+        <!-- MCP server -->
+        <rect class="box" x="270" y="170" width="170" height="80" rx="6"/>
+        <text class="t" x="355" y="198">MCP server</text>
+        <text class="m" x="355" y="217">mcp --http :8000/mcp</text>
+        <text class="s" x="355" y="236">checks session, paths</text>
+
+        <!-- server -> CLI -->
+        <line class="edge" x1="440" y1="210" x2="518" y2="210" marker-end="url(#ah)"/>
+        <text class="lbl" x="479" y="202">spawns</text>
+
+        <!-- CLI process stack -->
+        <rect class="ghost" x="536" y="158" width="160" height="80" rx="6"/>
+        <rect class="ghost" x="528" y="164" width="160" height="80" rx="6"/>
+        <rect class="box" x="520" y="170" width="160" height="80" rx="6"/>
+        <text class="t" x="600" y="198">CLI process</text>
+        <text class="m" x="600" y="217">python -m patchright_cli</text>
+        <text class="s" x="600" y="236">one per call, exits</text>
+
+        <!-- CLI -> daemon -->
+        <line class="edge" x1="696" y1="210" x2="778" y2="210" marker-end="url(#ah)"/>
+        <text class="lbl" x="737" y="202">TCP · JSON</text>
+        <text class="s" x="737" y="229">starts it</text>
+        <text class="s" x="737" y="243">if absent</text>
+
+        <!-- daemon -->
+        <rect class="box" x="780" y="170" width="120" height="80" rx="6"/>
+        <text class="t" x="840" y="198">Daemon</text>
+        <text class="m" x="840" y="217">127.0.0.1:9321</text>
+        <text class="s" x="840" y="236">long-lived</text>
+
+        <!-- daemon -> chrome -->
+        <line class="edge" x1="900" y1="210" x2="948" y2="210" marker-end="url(#ah)"/>
+        <text class="lbl" x="924" y="202">CDP</text>
+
+        <!-- chrome -->
+        <rect class="box" x="950" y="170" width="100" height="80" rx="6"/>
+        <text class="t" x="1000" y="205">Chrome</text>
+        <text class="s" x="1000" y="225">headed or headless</text>
+
+        <!-- xvfb -->
+        <rect class="ghost" x="950" y="72" width="100" height="48" rx="6"/>
+        <text class="t" x="1000" y="96" style="font-weight:500">Xvfb :99</text>
+        <text class="s" x="1000" y="112">headed only</text>
+        <line class="edge dim" x1="1000" y1="120" x2="1000" y2="168" marker-end="url(#ahd)"/>
+        <text class="lbl start" x="1008" y="149" style="fill:var(--muted)">DISPLAY</text>
+
+        <!-- chrome -> web -->
+        <line class="edge" x1="1050" y1="210" x2="1098" y2="210" marker-end="url(#ah)"/>
+        <text class="lbl" x="1075" y="202">HTTPS</text>
+        <rect class="box" x="1100" y="170" width="80" height="80" rx="6"/>
+        <text class="t" x="1140" y="214">Websites</text>
+
+        <!-- output dir -->
+        <rect class="box" x="520" y="350" width="380" height="60" rx="6"/>
+        <text class="m" x="710" y="375" style="fill:currentColor;font-size:12px">&lt;root&gt;/output/</text>
+        <text class="s" x="710" y="395">screenshots · PDFs · snapshots · state files</text>
+
+        <line class="edge" x1="840" y1="250" x2="840" y2="348" marker-end="url(#ah)"/>
+        <text class="lbl start" x="848" y="304">writes files</text>
+        <line class="edge dim" x1="600" y1="252" x2="600" y2="348" marker-end="url(#ahd)"/>
+        <text class="lbl start" x="608" y="304" style="fill:var(--muted)">cwd</text>
+        <polyline class="edge dim" points="355,250 355,380 518,380" marker-end="url(#ahd)"/>
+        <text class="lbl" x="437" y="372" style="fill:var(--muted)">delete_output</text>
+      </svg>

{patchright_cli-0.7.0 → patchright_cli-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "patchright-cli"
-version = "0.7.0"
+version = "0.8.0"
 description = "Anti-detect browser automation CLI using Patchright (undetected Playwright fork)"
 license = "Apache-2.0"
 requires-python = ">=3.10"
@@ -54,16 +54,21 @@ markers = [
 ]
 
 [project.optional-dependencies]
+mcp = [
+    "fastmcp>=3.0,<5",
+]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "pre-commit",
+    "fastmcp>=3.0,<5",
 ]
 
 [dependency-groups]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
+    "fastmcp>=3.0,<5",
 ]
 
 [tool.ruff]

{patchright_cli-0.7.0 → patchright_cli-0.8.0}/src/patchright_cli/__init__.py

@@ -1,3 +1,3 @@
 """patchright-cli — Undetected browser automation CLI using Patchright."""
 
-__version__ = "0.7.0"
+__version__ = "0.8.0"

{patchright_cli-0.7.0 → patchright_cli-0.8.0}/src/patchright_cli/cli.py

@@ -6,6 +6,7 @@ receives the result, and prints it.
 
 from __future__ import annotations
 
+import argparse
 import json
 import os
 import socket
@@ -248,6 +249,36 @@ def _handle_install(args: list) -> None:
     click.echo(f"\npatchright-cli v{__version__} skills installed.")
 
 
+def _handle_mcp(args: list[str]) -> None:
+    """Handle the optional MCP server command."""
+    parser = argparse.ArgumentParser(
+        prog="patchright-cli mcp",
+        description="Run the MCP server. Stdio is the default transport.",
+    )
+    parser.add_argument("--http", action="store_true", help="Use Streamable HTTP instead of stdio.")
+    parser.add_argument("--host", default="127.0.0.1", help="HTTP bind host.")
+    parser.add_argument("--port", type=int, default=8000, help="HTTP bind port.")
+    options = parser.parse_args(args)
+
+    if not 1 <= options.port <= 65535:
+        parser.error("--port must be between 1 and 65535")
+    if not options.http and (options.host != "127.0.0.1" or options.port != 8000):
+        parser.error("--host and --port require --http")
+
+    try:
+        from patchright_cli.mcp_server import run_mcp_server
+    except ImportError as exc:
+        if exc.name not in {"fastmcp", "mcp", "pydantic"}:
+            raise
+        click.echo(
+            "MCP support is not installed. Install it with: pip install 'patchright-cli[mcp]'",
+            err=True,
+        )
+        raise SystemExit(1) from exc
+
+    run_mcp_server(http=options.http, host=options.host, port=options.port)
+
+
 _VERSION_CHECK_INTERVAL = 24 * 60 * 60
 _PYPI_URL = "https://pypi.org/pypi/patchright-cli/json"
 
@@ -510,6 +541,7 @@ COMMANDS_HELP = {
     "codegen-stop": "codegen-stop [file]   Stop recording and save script",
     # Setup
     "install": "install --skills      Install skill files for AI agents",
+    "mcp": "mcp [--http] [--host=HOST] [--port=N]  Start MCP server (stdio by default)",
 }
 
 ALL_COMMANDS = list(COMMANDS_HELP.keys())
@@ -616,7 +648,7 @@ def _print_help():
         ("Profiles", ["profile-list", "profile-delete"]),
         ("Dashboard", ["show"]),
         ("Codegen", ["codegen", "codegen-stop"]),
-        ("Setup", ["install"]),
+        ("Setup", ["install", "mcp"]),
     ]
     for cat_name, cmds in categories:
         click.echo(f"\n  {cat_name}:")
@@ -630,6 +662,13 @@ def main():
     _soften_output_encoding(sys.stdout, sys.stderr)
     argv = sys.argv[1:]
 
+    # MCP is a self-contained subcommand with its own transport options.
+    # Dispatch it before global option parsing so `patchright-cli mcp --help`
+    # shows MCP help rather than the top-level CLI help.
+    if argv and argv[0] == "mcp":
+        _handle_mcp(argv[1:])
+        return
+
     # Parse global options manually (before the command)
     headless = False
     persistent = False
@@ -779,6 +818,10 @@ def main():
         _handle_install(args + [k if v is True else f"{k}={v}" for k, v in extra_opts.items()])
         sys.exit(0)
 
+    if command == "mcp":
+        _handle_mcp(args)
+        sys.exit(0)
+
     _warn_stale_skills()
 
     # Only on `open`: one browser launch already costs seconds, and this keeps