chrome-devtools-mcp-canpoint 0.1.0__tar.gz

chrome_devtools_mcp_canpoint-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: chrome-devtools-mcp-canpoint
+Version: 0.1.0
+Summary: Session-local Chrome launcher for Chrome DevTools MCP workflows.
+Author: whqp
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/whqp/chrome-devtools-mcp-canpoint
+Project-URL: Issues, https://github.com/whqp/chrome-devtools-mcp-canpoint/issues
+Keywords: mcp,chrome,devtools,browser,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+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 :: Software Development :: Debuggers
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# chrome-devtools-mcp-canpoint
+
+Session-local Chrome launcher for Chrome DevTools MCP workflows.
+
+This wrapper starts one dedicated Chrome process per MCP server process. Each
+session gets its own random remote debugging port and a generated user data
+directory under the current working directory, so multiple agent sessions do not
+fight over port `9222` or a shared Chrome profile.
+
+## Usage
+
+Run it directly with `uvx`:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint -- <downstream-mcp-command>
+```
+
+Example:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}
+```
+
+If Chrome is not installed in the default Windows location, pass it explicitly:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint --chrome-path "D:\Apps\Chrome\chrome.exe" -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}
+```
+
+## Codex MCP Config
+
+After publishing to PyPI, configure Codex like this:
+
+```toml
+[mcp_servers.chrome-devtools]
+command = "uvx"
+args = [
+  "chrome-devtools-mcp-canpoint",
+  "--",
+  "npx",
+  "-y",
+  "chrome-devtools-mcp@latest",
+  "--browser-url={browser_url}",
+  "--no-usage-statistics"
+]
+startup_timeout_sec = 60
+```
+
+## Session Profile Directory
+
+By default, generated Chrome profiles are created under:
+
+```text
+<current-working-directory>/.chrome-mcp-sessions/<uuid>
+```
+
+Override the parent directory with `--session-root`:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint --session-root .\.chrome-mcp-sessions -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}
+```
+
+Use `--user-data-dir` only when you want an exact profile directory instead of a
+generated per-session subdirectory.
+
+## Environment Passed to the Downstream MCP
+
+The downstream command receives these variables:
+
+- `CHROME_DEVTOOLS_URL`: `http://127.0.0.1:<random-port>`
+- `BROWSER_URL`: same value as `CHROME_DEVTOOLS_URL`
+- `CHROME_REMOTE_DEBUGGING_PORT`: selected port
+- `CHROME_USER_DATA_DIR`: session profile path
+
+Configure the real Chrome MCP package to use one of these values as its browser
+endpoint. This wrapper also expands placeholders in downstream command
+arguments:
+
+- `{browser_url}` or `{devtools_url}`: `http://127.0.0.1:<random-port>`
+- `{port}`: selected port
+- `{user_data_dir}`: generated profile path
+
+## Cleanup
+
+When the downstream MCP exits, this wrapper terminates only the Chrome process it
+started. Temporary profiles are deleted by default.
+
+Use `--keep-profile` when debugging:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint --keep-profile -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}
+```
+
+## Options
+
+```powershell
+uvx chrome-devtools-mcp-canpoint --help
+```
+
+Useful options:
+
+- `--chrome-path`: path to `chrome.exe`
+- `--session-root`: parent directory for generated project-local profiles
+- `--user-data-dir`: explicit profile directory instead of a generated one
+- `--keep-profile`: leave the temporary profile on disk
+- `--headless`: start Chrome with `--headless=new`
+- `--chrome-arg`: pass extra arguments to Chrome, repeatable
+- `--devtools-timeout`: seconds to wait for `/json/version`
+
+## Development
+
+Use the project virtual environment for local development:
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install -e .
+.\.venv\Scripts\python.exe -m unittest discover -v
+.\.venv\Scripts\chrome-devtools-mcp-canpoint.exe --help
+```
+
+Build distributions:
+
+```powershell
+.\.venv\Scripts\python.exe -m build
+```

chrome_devtools_mcp_canpoint-0.1.0/README.md

@@ -0,0 +1,124 @@
+# chrome-devtools-mcp-canpoint
+
+Session-local Chrome launcher for Chrome DevTools MCP workflows.
+
+This wrapper starts one dedicated Chrome process per MCP server process. Each
+session gets its own random remote debugging port and a generated user data
+directory under the current working directory, so multiple agent sessions do not
+fight over port `9222` or a shared Chrome profile.
+
+## Usage
+
+Run it directly with `uvx`:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint -- <downstream-mcp-command>
+```
+
+Example:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}
+```
+
+If Chrome is not installed in the default Windows location, pass it explicitly:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint --chrome-path "D:\Apps\Chrome\chrome.exe" -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}
+```
+
+## Codex MCP Config
+
+After publishing to PyPI, configure Codex like this:
+
+```toml
+[mcp_servers.chrome-devtools]
+command = "uvx"
+args = [
+  "chrome-devtools-mcp-canpoint",
+  "--",
+  "npx",
+  "-y",
+  "chrome-devtools-mcp@latest",
+  "--browser-url={browser_url}",
+  "--no-usage-statistics"
+]
+startup_timeout_sec = 60
+```
+
+## Session Profile Directory
+
+By default, generated Chrome profiles are created under:
+
+```text
+<current-working-directory>/.chrome-mcp-sessions/<uuid>
+```
+
+Override the parent directory with `--session-root`:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint --session-root .\.chrome-mcp-sessions -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}
+```
+
+Use `--user-data-dir` only when you want an exact profile directory instead of a
+generated per-session subdirectory.
+
+## Environment Passed to the Downstream MCP
+
+The downstream command receives these variables:
+
+- `CHROME_DEVTOOLS_URL`: `http://127.0.0.1:<random-port>`
+- `BROWSER_URL`: same value as `CHROME_DEVTOOLS_URL`
+- `CHROME_REMOTE_DEBUGGING_PORT`: selected port
+- `CHROME_USER_DATA_DIR`: session profile path
+
+Configure the real Chrome MCP package to use one of these values as its browser
+endpoint. This wrapper also expands placeholders in downstream command
+arguments:
+
+- `{browser_url}` or `{devtools_url}`: `http://127.0.0.1:<random-port>`
+- `{port}`: selected port
+- `{user_data_dir}`: generated profile path
+
+## Cleanup
+
+When the downstream MCP exits, this wrapper terminates only the Chrome process it
+started. Temporary profiles are deleted by default.
+
+Use `--keep-profile` when debugging:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint --keep-profile -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}
+```
+
+## Options
+
+```powershell
+uvx chrome-devtools-mcp-canpoint --help
+```
+
+Useful options:
+
+- `--chrome-path`: path to `chrome.exe`
+- `--session-root`: parent directory for generated project-local profiles
+- `--user-data-dir`: explicit profile directory instead of a generated one
+- `--keep-profile`: leave the temporary profile on disk
+- `--headless`: start Chrome with `--headless=new`
+- `--chrome-arg`: pass extra arguments to Chrome, repeatable
+- `--devtools-timeout`: seconds to wait for `/json/version`
+
+## Development
+
+Use the project virtual environment for local development:
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install -e .
+.\.venv\Scripts\python.exe -m unittest discover -v
+.\.venv\Scripts\chrome-devtools-mcp-canpoint.exe --help
+```
+
+Build distributions:
+
+```powershell
+.\.venv\Scripts\python.exe -m build
+```

chrome_devtools_mcp_canpoint-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chrome-devtools-mcp-canpoint"
+version = "0.1.0"
+description = "Session-local Chrome launcher for Chrome DevTools MCP workflows."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "whqp" }
+]
+keywords = ["mcp", "chrome", "devtools", "browser", "automation"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: Microsoft :: Windows",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Debuggers",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/whqp/chrome-devtools-mcp-canpoint"
+Issues = "https://github.com/whqp/chrome-devtools-mcp-canpoint/issues"
+
+[project.scripts]
+chrome-devtools-mcp-canpoint = "chrome_devtools_mcp_canpoint.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

chrome_devtools_mcp_canpoint-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chrome_devtools_mcp_canpoint-0.1.0/src/chrome_devtools_mcp_canpoint/__init__.py

@@ -0,0 +1,3 @@
+"""Session-local Chrome launcher for Chrome DevTools MCP workflows."""
+
+__version__ = "0.1.0"

chrome_devtools_mcp_canpoint-0.1.0/src/chrome_devtools_mcp_canpoint/cli.py

@@ -0,0 +1,372 @@
+from __future__ import annotations
+
+import argparse
+import atexit
+import os
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import threading
+import time
+import uuid
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping, Sequence
+
+
+DEFAULT_CHROME_PATHS = (
+    Path(r"C:\Program Files\Google\Chrome\Application\chrome.exe"),
+    Path(r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe"),
+)
+DEFAULT_SESSION_ROOT_NAME = ".chrome-mcp-sessions"
+
+
+@dataclass(frozen=True)
+class ChromeSessionConfig:
+    chrome_path: Path
+    port: int
+    user_data_dir: Path
+    headless: bool
+    extra_args: tuple[str, ...]
+
+
+def find_free_port(host: str = "127.0.0.1") -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind((host, 0))
+        return int(sock.getsockname()[1])
+
+
+def devtools_url(port: int) -> str:
+    return f"http://127.0.0.1:{port}"
+
+
+def build_chrome_args(config: ChromeSessionConfig) -> list[str]:
+    args = [
+        str(config.chrome_path),
+        f"--remote-debugging-port={config.port}",
+        f"--user-data-dir={config.user_data_dir}",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--disable-background-networking",
+        "--disable-sync",
+    ]
+    if config.headless:
+        args.append("--headless=new")
+    args.extend(config.extra_args)
+    return args
+
+
+def downstream_env(base_env: Mapping[str, str], port: int, user_data_dir: Path) -> dict[str, str]:
+    env = dict(base_env)
+    url = devtools_url(port)
+    env.update(
+        {
+            "CHROME_DEVTOOLS_URL": url,
+            "CHROME_REMOTE_DEBUGGING_PORT": str(port),
+            "CHROME_USER_DATA_DIR": str(user_data_dir),
+            "BROWSER_URL": url,
+        }
+    )
+    return env
+
+
+def expand_downstream_command(
+    command: Sequence[str], port: int, user_data_dir: Path
+) -> list[str]:
+    replacements = {
+        "browser_url": devtools_url(port),
+        "devtools_url": devtools_url(port),
+        "port": str(port),
+        "user_data_dir": str(user_data_dir),
+    }
+    return [arg.format(**replacements) for arg in command]
+
+
+def resolve_session_root(value: str | None) -> Path:
+    if value:
+        return Path(value).resolve()
+    return (Path.cwd() / DEFAULT_SESSION_ROOT_NAME).resolve()
+
+
+def resolve_chrome_path(value: str | None) -> Path:
+    candidates: list[Path] = []
+    if value:
+        candidates.append(Path(value))
+    if os.environ.get("CHROME_PATH"):
+        candidates.append(Path(os.environ["CHROME_PATH"]))
+    candidates.extend(DEFAULT_CHROME_PATHS)
+
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+
+    raise FileNotFoundError(
+        "Chrome executable not found. Pass --chrome-path or set CHROME_PATH."
+    )
+
+
+def wait_for_devtools(port: int, timeout_seconds: float) -> None:
+    deadline = time.monotonic() + timeout_seconds
+    endpoint = f"{devtools_url(port)}/json/version"
+    last_error: Exception | None = None
+
+    while time.monotonic() < deadline:
+        try:
+            with urllib.request.urlopen(endpoint, timeout=1) as response:
+                if response.status == 200:
+                    return
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            last_error = exc
+        time.sleep(0.1)
+
+    message = f"Timed out waiting for Chrome DevTools at {endpoint}"
+    if last_error:
+        message = f"{message}: {last_error}"
+    raise TimeoutError(message)
+
+
+def bridge_stream(source, target) -> None:
+    source_fd = source.fileno()
+    target_fd = target.fileno()
+    try:
+        while True:
+            chunk = os.read(source_fd, 64 * 1024)
+            if not chunk:
+                break
+            os.write(target_fd, chunk)
+    finally:
+        try:
+            target.close()
+        except OSError:
+            pass
+
+
+def terminate_process(process: subprocess.Popen[bytes], timeout_seconds: float = 5) -> None:
+    if process.poll() is not None:
+        return
+    if os.name == "nt":
+        subprocess.run(
+            ["taskkill", "/PID", str(process.pid), "/T", "/F"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
+        try:
+            process.wait(timeout=timeout_seconds)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait(timeout=timeout_seconds)
+        return
+    process.terminate()
+    try:
+        process.wait(timeout=timeout_seconds)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.wait(timeout=timeout_seconds)
+
+
+def terminate_chrome_profile_processes(user_data_dir: Path) -> None:
+    if os.name != "nt":
+        return
+    powershell_path = (
+        Path(os.environ.get("SystemRoot", r"C:\Windows"))
+        / "System32"
+        / "WindowsPowerShell"
+        / "v1.0"
+        / "powershell.exe"
+    )
+    if not powershell_path.exists():
+        return
+    profile_marker = str(user_data_dir)
+    command = (
+        "Get-CimInstance Win32_Process -Filter \"name = 'chrome.exe'\" | "
+        "Where-Object { $_.CommandLine -like ('*' + $env:CHROME_MCP_PROFILE_MARKER + '*') } | "
+        "ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }"
+    )
+    env = dict(os.environ)
+    env["CHROME_MCP_PROFILE_MARKER"] = profile_marker
+    subprocess.run(
+        [str(powershell_path), "-NoProfile", "-Command", command],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        env=env,
+        check=False,
+    )
+
+
+def remove_directory_with_retries(path: Path, attempts: int = 20, delay_seconds: float = 0.25) -> None:
+    for attempt in range(attempts):
+        shutil.rmtree(path, ignore_errors=True)
+        if not path.exists():
+            return
+        if attempt < attempts - 1:
+            time.sleep(delay_seconds)
+
+
+def run_downstream(command: Sequence[str], env: Mapping[str, str]) -> int:
+    downstream = subprocess.Popen(
+        list(command),
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=None,
+        env=dict(env),
+    )
+
+    stdin_thread = threading.Thread(
+        target=bridge_stream,
+        args=(sys.stdin.buffer, downstream.stdin),
+        daemon=True,
+    )
+    stdout_thread = threading.Thread(
+        target=bridge_stream,
+        args=(downstream.stdout, sys.stdout.buffer),
+        daemon=True,
+    )
+
+    def stop_downstream_when_input_closes() -> None:
+        stdin_thread.join()
+        if downstream.poll() is None:
+            time.sleep(0.5)
+        if downstream.poll() is None:
+            terminate_process(downstream)
+
+    stdin_thread.start()
+    stdout_thread.start()
+    input_watcher = threading.Thread(target=stop_downstream_when_input_closes, daemon=True)
+    input_watcher.start()
+
+    try:
+        return downstream.wait()
+    except KeyboardInterrupt:
+        terminate_process(downstream)
+        return 130
+    finally:
+        stdout_thread.join(timeout=1)
+
+
+def create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Start a session-local Chrome instance and run a downstream MCP command."
+    )
+    parser.add_argument(
+        "--chrome-path",
+        help="Path to chrome.exe. Defaults to CHROME_PATH or common Windows install paths.",
+    )
+    parser.add_argument(
+        "--user-data-dir",
+        help="Exact profile directory to use. Overrides --session-root.",
+    )
+    parser.add_argument(
+        "--session-root",
+        default=None,
+        help="Directory for generated session profiles. Defaults to .chrome-mcp-sessions in the current working directory.",
+    )
+    parser.add_argument(
+        "--keep-profile",
+        action="store_true",
+        help="Do not delete the session profile after the downstream command exits.",
+    )
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        help="Start Chrome in headless mode.",
+    )
+    parser.add_argument(
+        "--devtools-timeout",
+        type=float,
+        default=15.0,
+        help="Seconds to wait for Chrome DevTools to become ready.",
+    )
+    parser.add_argument(
+        "--chrome-arg",
+        action="append",
+        default=[],
+        help="Extra argument passed to Chrome. Repeat for multiple values.",
+    )
+    parser.add_argument(
+        "command",
+        nargs=argparse.REMAINDER,
+        help="Downstream MCP command. Prefix it with --, for example: -- npx chrome-devtools-mcp",
+    )
+    return parser
+
+
+def normalize_command(command: Sequence[str]) -> list[str]:
+    normalized = list(command)
+    if normalized and normalized[0] == "--":
+        normalized = normalized[1:]
+    if not normalized:
+        raise ValueError("Missing downstream MCP command after --.")
+    return normalized
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        command = normalize_command(args.command)
+        chrome_path = resolve_chrome_path(args.chrome_path)
+    except (FileNotFoundError, ValueError) as exc:
+        parser.error(str(exc))
+
+    port = find_free_port()
+    generated_session_dir = args.user_data_dir is None
+    user_data_dir = (
+        Path(args.user_data_dir)
+        if args.user_data_dir
+        else resolve_session_root(args.session_root) / uuid.uuid4().hex
+    )
+    user_data_dir.mkdir(parents=True, exist_ok=True)
+
+    config = ChromeSessionConfig(
+        chrome_path=chrome_path,
+        port=port,
+        user_data_dir=user_data_dir,
+        headless=args.headless,
+        extra_args=tuple(args.chrome_arg),
+    )
+
+    chrome = subprocess.Popen(
+        build_chrome_args(config),
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+
+    def cleanup() -> None:
+        terminate_process(chrome)
+        terminate_chrome_profile_processes(user_data_dir)
+        if generated_session_dir and not args.keep_profile:
+            remove_directory_with_retries(user_data_dir)
+
+    atexit.register(cleanup)
+
+    previous_sigterm = signal.getsignal(signal.SIGTERM)
+
+    def handle_sigterm(signum, frame) -> None:
+        cleanup()
+        if callable(previous_sigterm):
+            previous_sigterm(signum, frame)
+        raise SystemExit(143)
+
+    signal.signal(signal.SIGTERM, handle_sigterm)
+
+    try:
+        wait_for_devtools(port, args.devtools_timeout)
+        env = downstream_env(os.environ, port, user_data_dir)
+        expanded_command = expand_downstream_command(command, port, user_data_dir)
+        return run_downstream(expanded_command, env)
+    except KeyboardInterrupt:
+        return 130
+    finally:
+        cleanup()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

chrome_devtools_mcp_canpoint-0.1.0/src/chrome_devtools_mcp_canpoint.egg-info/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: chrome-devtools-mcp-canpoint
+Version: 0.1.0
+Summary: Session-local Chrome launcher for Chrome DevTools MCP workflows.
+Author: whqp
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/whqp/chrome-devtools-mcp-canpoint
+Project-URL: Issues, https://github.com/whqp/chrome-devtools-mcp-canpoint/issues
+Keywords: mcp,chrome,devtools,browser,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+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 :: Software Development :: Debuggers
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# chrome-devtools-mcp-canpoint
+
+Session-local Chrome launcher for Chrome DevTools MCP workflows.
+
+This wrapper starts one dedicated Chrome process per MCP server process. Each
+session gets its own random remote debugging port and a generated user data
+directory under the current working directory, so multiple agent sessions do not
+fight over port `9222` or a shared Chrome profile.
+
+## Usage
+
+Run it directly with `uvx`:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint -- <downstream-mcp-command>
+```
+
+Example:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}
+```
+
+If Chrome is not installed in the default Windows location, pass it explicitly:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint --chrome-path "D:\Apps\Chrome\chrome.exe" -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}
+```
+
+## Codex MCP Config
+
+After publishing to PyPI, configure Codex like this:
+
+```toml
+[mcp_servers.chrome-devtools]
+command = "uvx"
+args = [
+  "chrome-devtools-mcp-canpoint",
+  "--",
+  "npx",
+  "-y",
+  "chrome-devtools-mcp@latest",
+  "--browser-url={browser_url}",
+  "--no-usage-statistics"
+]
+startup_timeout_sec = 60
+```
+
+## Session Profile Directory
+
+By default, generated Chrome profiles are created under:
+
+```text
+<current-working-directory>/.chrome-mcp-sessions/<uuid>
+```
+
+Override the parent directory with `--session-root`:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint --session-root .\.chrome-mcp-sessions -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}
+```
+
+Use `--user-data-dir` only when you want an exact profile directory instead of a
+generated per-session subdirectory.
+
+## Environment Passed to the Downstream MCP
+
+The downstream command receives these variables:
+
+- `CHROME_DEVTOOLS_URL`: `http://127.0.0.1:<random-port>`
+- `BROWSER_URL`: same value as `CHROME_DEVTOOLS_URL`
+- `CHROME_REMOTE_DEBUGGING_PORT`: selected port
+- `CHROME_USER_DATA_DIR`: session profile path
+
+Configure the real Chrome MCP package to use one of these values as its browser
+endpoint. This wrapper also expands placeholders in downstream command
+arguments:
+
+- `{browser_url}` or `{devtools_url}`: `http://127.0.0.1:<random-port>`
+- `{port}`: selected port
+- `{user_data_dir}`: generated profile path
+
+## Cleanup
+
+When the downstream MCP exits, this wrapper terminates only the Chrome process it
+started. Temporary profiles are deleted by default.
+
+Use `--keep-profile` when debugging:
+
+```powershell
+uvx chrome-devtools-mcp-canpoint --keep-profile -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}
+```
+
+## Options
+
+```powershell
+uvx chrome-devtools-mcp-canpoint --help
+```
+
+Useful options:
+
+- `--chrome-path`: path to `chrome.exe`
+- `--session-root`: parent directory for generated project-local profiles
+- `--user-data-dir`: explicit profile directory instead of a generated one
+- `--keep-profile`: leave the temporary profile on disk
+- `--headless`: start Chrome with `--headless=new`
+- `--chrome-arg`: pass extra arguments to Chrome, repeatable
+- `--devtools-timeout`: seconds to wait for `/json/version`
+
+## Development
+
+Use the project virtual environment for local development:
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install -e .
+.\.venv\Scripts\python.exe -m unittest discover -v
+.\.venv\Scripts\chrome-devtools-mcp-canpoint.exe --help
+```
+
+Build distributions:
+
+```powershell
+.\.venv\Scripts\python.exe -m build
+```

chrome_devtools_mcp_canpoint-0.1.0/src/chrome_devtools_mcp_canpoint.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/chrome_devtools_mcp_canpoint/__init__.py
+src/chrome_devtools_mcp_canpoint/cli.py
+src/chrome_devtools_mcp_canpoint.egg-info/PKG-INFO
+src/chrome_devtools_mcp_canpoint.egg-info/SOURCES.txt
+src/chrome_devtools_mcp_canpoint.egg-info/dependency_links.txt
+src/chrome_devtools_mcp_canpoint.egg-info/entry_points.txt
+src/chrome_devtools_mcp_canpoint.egg-info/top_level.txt
+tests/test_main.py

chrome_devtools_mcp_canpoint-0.1.0/src/chrome_devtools_mcp_canpoint.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chrome_devtools_mcp_canpoint-0.1.0/src/chrome_devtools_mcp_canpoint.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chrome-devtools-mcp-canpoint = chrome_devtools_mcp_canpoint.cli:main

chrome_devtools_mcp_canpoint-0.1.0/src/chrome_devtools_mcp_canpoint.egg-info/top_level.txt

@@ -0,0 +1 @@
+chrome_devtools_mcp_canpoint

chrome_devtools_mcp_canpoint-0.1.0/tests/test_main.py

@@ -0,0 +1,147 @@
+import os
+import sys
+import threading
+import unittest
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from chrome_devtools_mcp_canpoint import cli as main
+
+
+class WrapperHelpersTest(unittest.TestCase):
+    def test_devtools_url_uses_loopback_and_port(self):
+        self.assertEqual(main.devtools_url(45678), "http://127.0.0.1:45678")
+
+    def test_downstream_env_injects_session_values(self):
+        env = main.downstream_env({"EXISTING": "1"}, 45678, Path(r"C:\Temp\profile"))
+
+        self.assertEqual(env["EXISTING"], "1")
+        self.assertEqual(env["CHROME_DEVTOOLS_URL"], "http://127.0.0.1:45678")
+        self.assertEqual(env["BROWSER_URL"], "http://127.0.0.1:45678")
+        self.assertEqual(env["CHROME_REMOTE_DEBUGGING_PORT"], "45678")
+        self.assertEqual(env["CHROME_USER_DATA_DIR"], r"C:\Temp\profile")
+
+    def test_build_chrome_args_includes_isolated_session_flags(self):
+        config = main.ChromeSessionConfig(
+            chrome_path=Path(r"C:\Chrome\chrome.exe"),
+            port=45678,
+            user_data_dir=Path(r"C:\Temp\profile"),
+            headless=True,
+            extra_args=("--window-size=1200,900",),
+        )
+
+        args = main.build_chrome_args(config)
+
+        self.assertEqual(args[0], r"C:\Chrome\chrome.exe")
+        self.assertIn("--remote-debugging-port=45678", args)
+        self.assertIn(r"--user-data-dir=C:\Temp\profile", args)
+        self.assertIn("--no-first-run", args)
+        self.assertIn("--no-default-browser-check", args)
+        self.assertIn("--headless=new", args)
+        self.assertIn("--window-size=1200,900", args)
+
+    def test_normalize_command_strips_separator(self):
+        self.assertEqual(
+            main.normalize_command(["--", "npx", "chrome-devtools-mcp"]),
+            ["npx", "chrome-devtools-mcp"],
+        )
+
+    def test_normalize_command_rejects_empty_command(self):
+        with self.assertRaises(ValueError):
+            main.normalize_command(["--"])
+
+    def test_expand_downstream_command_replaces_session_placeholders(self):
+        command = [
+            "npx",
+            "chrome-devtools-mcp",
+            "--browser-url={browser_url}",
+            "--profile={user_data_dir}",
+            "--port={port}",
+        ]
+
+        expanded = main.expand_downstream_command(command, 45678, Path(r"C:\Temp\profile"))
+
+        self.assertEqual(
+            expanded,
+            [
+                "npx",
+                "chrome-devtools-mcp",
+                "--browser-url=http://127.0.0.1:45678",
+                r"--profile=C:\Temp\profile",
+                "--port=45678",
+            ],
+        )
+
+    def test_resolve_chrome_path_uses_explicit_existing_path(self):
+        path = Path(os.environ["SystemRoot"]) / "System32" / "cmd.exe"
+
+        self.assertEqual(main.resolve_chrome_path(str(path)), path)
+
+    def test_resolve_session_root_defaults_to_current_working_directory(self):
+        self.assertEqual(
+            main.resolve_session_root(None),
+            (Path.cwd() / ".chrome-mcp-sessions").resolve(),
+        )
+
+    @unittest.skipUnless(os.name == "nt", "Windows-specific process tree cleanup")
+    def test_terminate_process_uses_taskkill_process_tree_on_windows(self):
+        process = mock.Mock()
+        process.poll.return_value = None
+        process.pid = 1234
+
+        with mock.patch.object(main.subprocess, "run") as run:
+            main.terminate_process(process)
+
+        run.assert_called_once_with(
+            ["taskkill", "/PID", "1234", "/T", "/F"],
+            stdout=main.subprocess.DEVNULL,
+            stderr=main.subprocess.DEVNULL,
+            check=False,
+        )
+        process.wait.assert_called_once()
+
+    def test_remove_directory_with_retries_stops_after_directory_is_gone(self):
+        path = mock.Mock()
+        path.exists.side_effect = [True, False]
+
+        with mock.patch.object(main.shutil, "rmtree") as rmtree, mock.patch.object(
+            main.time, "sleep"
+        ) as sleep:
+            main.remove_directory_with_retries(path, attempts=3, delay_seconds=0.01)
+
+        self.assertEqual(rmtree.call_count, 2)
+        sleep.assert_called_once_with(0.01)
+
+    def test_bridge_stream_forwards_small_message_before_eof(self):
+        source_read, source_write = os.pipe()
+        target_read, target_write = os.pipe()
+        with os.fdopen(source_read, "rb", buffering=0) as source, os.fdopen(
+            target_write, "wb", buffering=0
+        ) as target:
+            thread = threading.Thread(target=main.bridge_stream, args=(source, target))
+            thread.start()
+            message = b"Content-Length: 2\r\n\r\n{}"
+            os.write(source_write, message)
+            forwarded = os.read(target_read, len(message))
+            os.close(source_write)
+            thread.join(timeout=2)
+            os.close(target_read)
+
+        self.assertEqual(forwarded, message)
+
+    @unittest.skipUnless(os.name == "nt", "Windows-specific Chrome cleanup")
+    def test_terminate_chrome_profile_processes_filters_by_profile_path(self):
+        with mock.patch.object(main.subprocess, "run") as run:
+            main.terminate_chrome_profile_processes(Path(r"C:\Temp\profile"))
+
+        args, kwargs = run.call_args
+        self.assertTrue(args[0][0].lower().endswith(r"powershell.exe"))
+        self.assertEqual(args[0][1:3], ["-NoProfile", "-Command"])
+        self.assertEqual(kwargs["env"]["CHROME_MCP_PROFILE_MARKER"], r"C:\Temp\profile")
+        self.assertFalse(kwargs["check"])
+
+
+if __name__ == "__main__":
+    unittest.main()