clearcote-mcp 0.1.0__tar.gz

clearcote_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: clearcote-mcp
+Version: 0.1.0
+Summary: MCP server for Clearcote — drive the open-source stealth Chromium from Claude Desktop, Cursor, Cline, and any MCP client.
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/clearcotelabs/clearcote-browser
+Project-URL: Source, https://github.com/clearcotelabs/clearcote-browser/tree/main/mcp
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: clearcote>=0.13
+Requires-Dist: mcp[cli]>=1.2
+Requires-Dist: markdownify>=0.11
+
+# Clearcote MCP server
+
+Drive the open-source **Clearcote stealth Chromium** from any MCP client — Claude Desktop, Cursor,
+Cline, Continue, or your own agent. One shared, coherent stealth browser; ~20 tools to navigate,
+read, extract, click, fill, screenshot, and persist sessions — plus `get_cdp_endpoint`, which hands
+the **same** stealth browser to any Playwright / Puppeteer / browser-use / Crawl4AI client.
+
+The fingerprint is corrected in Chromium's **C++**, so you do **not** add `puppeteer-stealth` /
+`undetected-chromedriver` / any JS patching — those self-reveal and undo it. Driving over CDP adds
+no automation flags, so `navigator.webdriver` stays `false` and the persona is intact end to end.
+
+---
+
+## Run it
+
+**Node (no install):**
+```bash
+npx clearcote-mcp
+```
+
+**Python:**
+```bash
+pip install clearcote-mcp
+clearcote-mcp            # stdio server
+```
+
+Both auto-download + SHA-256-verify the right Clearcote binary per OS on first use (native Windows
+x64 + Linux x64).
+
+## Add it to a client
+
+Claude Desktop / Cursor / Cline `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "clearcote": {
+      "command": "npx",
+      "args": ["-y", "clearcote-mcp"],
+      "env": {
+        "CLEARCOTE_FINGERPRINT": "acct-1",
+        "CLEARCOTE_PLATFORM": "windows",
+        "CLEARCOTE_PROXY": "http://user:pass@host:port",
+        "CLEARCOTE_GEOIP": "1"
+      }
+    }
+  }
+}
+```
+
+The **persona lives in the environment**, so the tool surface stays clean:
+
+| env var | meaning |
+|---|---|
+| `CLEARCOTE_FINGERPRINT` | seed → one stable, coherent identity (same seed = same machine across runs) |
+| `CLEARCOTE_PLATFORM` | `windows` \| `linux` \| `macos` \| `android` |
+| `CLEARCOTE_BRAND` | `Chrome` \| `Edge` \| `Opera` \| `Vivaldi` |
+| `CLEARCOTE_PROXY` | `http://user:pass@host:port` (routes all traffic) |
+| `CLEARCOTE_GEOIP` | `1` → derive timezone/locale/WebRTC IP from the proxy exit IP |
+| `CLEARCOTE_TIMEZONE` / `CLEARCOTE_ACCEPT_LANGUAGE` | explicit overrides |
+| `CLEARCOTE_HEADLESS` | `0` for a visible window (default headless) |
+| `CLEARCOTE_BINARY` | path to a specific Clearcote binary (optional) |
+
+Hardening knobs: `CLEARCOTE_MCP_TOOL_TIMEOUT` (s), `CLEARCOTE_MCP_WRITE_DIR` (sandbox for file
+writes), `CLEARCOTE_MCP_ALLOW_ANY_PATH=1`, `CLEARCOTE_ALLOW_PRIVATE_EGRESS=1` (allow localhost /
+private targets), `CLEARCOTE_MCP_PREWARM=0`, `CLEARCOTE_SERVE_PORT`.
+
+## Tools
+
+**Read** · `read_page` (text + Markdown) · `get_page_html` · `page_elements` (interactive elements +
+selectors) · `evaluate_js` · `wait_for` · `current_page` · `get_cookies` · `list_tabs`
+**Act** · `navigate` · `click` (selector or visible text) · `fill_field` (selector/label/placeholder/name)
+· `press_key` · `new_tab` · `close_tab`
+**Capture** · `screenshot_page` · `save_page_pdf`
+**Session** · `save_profile` / `load_profile` (cookies + storage)
+**Stealth / infra** · `get_egress_info` (public IP + active persona) · **`get_cdp_endpoint`** (attach any
+other CDP client to the same stealth browser)
+
+## Guardrails (built in)
+
+- Every tool has a wall-clock timeout and returns a **structured error** instead of crashing the server.
+- URL args are **SSRF-checked** — localhost / private / cloud-metadata are refused unless you opt in.
+- File writes are **confined** to a sandbox dir (no path traversal).
+- Oversized text is **capped** so a response never floods the agent's context.
+- The shared browser is **rebuilt** automatically if it dies.
+
+## Just want the raw endpoint?
+
+If you don't need the tools, run the browser as a standing CDP endpoint and attach your existing code:
+
+```bash
+clearcote-serve --port 9222 --fingerprint acct-1 --platform windows
+# → prints http://127.0.0.1:9222 ; then:  connect_over_cdp / puppeteer.connect({browserURL})
+```
+
+See [USAGE.md](USAGE.md) for per-client examples. Part of
+[clearcote-browser](https://github.com/clearcotelabs/clearcote-browser) (BSD-3).

clearcote_mcp-0.1.0/README.md

@@ -0,0 +1,97 @@
+# Clearcote MCP server
+
+Drive the open-source **Clearcote stealth Chromium** from any MCP client — Claude Desktop, Cursor,
+Cline, Continue, or your own agent. One shared, coherent stealth browser; ~20 tools to navigate,
+read, extract, click, fill, screenshot, and persist sessions — plus `get_cdp_endpoint`, which hands
+the **same** stealth browser to any Playwright / Puppeteer / browser-use / Crawl4AI client.
+
+The fingerprint is corrected in Chromium's **C++**, so you do **not** add `puppeteer-stealth` /
+`undetected-chromedriver` / any JS patching — those self-reveal and undo it. Driving over CDP adds
+no automation flags, so `navigator.webdriver` stays `false` and the persona is intact end to end.
+
+---
+
+## Run it
+
+**Node (no install):**
+```bash
+npx clearcote-mcp
+```
+
+**Python:**
+```bash
+pip install clearcote-mcp
+clearcote-mcp            # stdio server
+```
+
+Both auto-download + SHA-256-verify the right Clearcote binary per OS on first use (native Windows
+x64 + Linux x64).
+
+## Add it to a client
+
+Claude Desktop / Cursor / Cline `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "clearcote": {
+      "command": "npx",
+      "args": ["-y", "clearcote-mcp"],
+      "env": {
+        "CLEARCOTE_FINGERPRINT": "acct-1",
+        "CLEARCOTE_PLATFORM": "windows",
+        "CLEARCOTE_PROXY": "http://user:pass@host:port",
+        "CLEARCOTE_GEOIP": "1"
+      }
+    }
+  }
+}
+```
+
+The **persona lives in the environment**, so the tool surface stays clean:
+
+| env var | meaning |
+|---|---|
+| `CLEARCOTE_FINGERPRINT` | seed → one stable, coherent identity (same seed = same machine across runs) |
+| `CLEARCOTE_PLATFORM` | `windows` \| `linux` \| `macos` \| `android` |
+| `CLEARCOTE_BRAND` | `Chrome` \| `Edge` \| `Opera` \| `Vivaldi` |
+| `CLEARCOTE_PROXY` | `http://user:pass@host:port` (routes all traffic) |
+| `CLEARCOTE_GEOIP` | `1` → derive timezone/locale/WebRTC IP from the proxy exit IP |
+| `CLEARCOTE_TIMEZONE` / `CLEARCOTE_ACCEPT_LANGUAGE` | explicit overrides |
+| `CLEARCOTE_HEADLESS` | `0` for a visible window (default headless) |
+| `CLEARCOTE_BINARY` | path to a specific Clearcote binary (optional) |
+
+Hardening knobs: `CLEARCOTE_MCP_TOOL_TIMEOUT` (s), `CLEARCOTE_MCP_WRITE_DIR` (sandbox for file
+writes), `CLEARCOTE_MCP_ALLOW_ANY_PATH=1`, `CLEARCOTE_ALLOW_PRIVATE_EGRESS=1` (allow localhost /
+private targets), `CLEARCOTE_MCP_PREWARM=0`, `CLEARCOTE_SERVE_PORT`.
+
+## Tools
+
+**Read** · `read_page` (text + Markdown) · `get_page_html` · `page_elements` (interactive elements +
+selectors) · `evaluate_js` · `wait_for` · `current_page` · `get_cookies` · `list_tabs`
+**Act** · `navigate` · `click` (selector or visible text) · `fill_field` (selector/label/placeholder/name)
+· `press_key` · `new_tab` · `close_tab`
+**Capture** · `screenshot_page` · `save_page_pdf`
+**Session** · `save_profile` / `load_profile` (cookies + storage)
+**Stealth / infra** · `get_egress_info` (public IP + active persona) · **`get_cdp_endpoint`** (attach any
+other CDP client to the same stealth browser)
+
+## Guardrails (built in)
+
+- Every tool has a wall-clock timeout and returns a **structured error** instead of crashing the server.
+- URL args are **SSRF-checked** — localhost / private / cloud-metadata are refused unless you opt in.
+- File writes are **confined** to a sandbox dir (no path traversal).
+- Oversized text is **capped** so a response never floods the agent's context.
+- The shared browser is **rebuilt** automatically if it dies.
+
+## Just want the raw endpoint?
+
+If you don't need the tools, run the browser as a standing CDP endpoint and attach your existing code:
+
+```bash
+clearcote-serve --port 9222 --fingerprint acct-1 --platform windows
+# → prints http://127.0.0.1:9222 ; then:  connect_over_cdp / puppeteer.connect({browserURL})
+```
+
+See [USAGE.md](USAGE.md) for per-client examples. Part of
+[clearcote-browser](https://github.com/clearcotelabs/clearcote-browser) (BSD-3).

clearcote_mcp-0.1.0/clearcote_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Clearcote MCP server — drive the open-source stealth Chromium from any MCP client."""
+from .server import main, mcp
+
+__all__ = ["main", "mcp"]
+__version__ = "0.1.0"

clearcote_mcp-0.1.0/clearcote_mcp/__main__.py

@@ -0,0 +1,4 @@
+from .server import main
+
+if __name__ == "__main__":
+    main()

clearcote_mcp-0.1.0/clearcote_mcp/_facade.py

@@ -0,0 +1,247 @@
+"""Async browser facade the MCP tools drive.
+
+It launches ONE clearcote stealth browser via ``clearcote.serve()`` (a raw CDP endpoint) and
+attaches to it with Playwright's async ``connect_over_cdp`` — so the exact same browser the tools
+drive is ALSO the endpoint any other client can attach to (``get_cdp_endpoint``). Attaching over
+CDP adds no launch flags, so the served persona (``navigator.webdriver=false``, Windows UA, etc.)
+is preserved end to end.
+
+The facade owns a "current page" (the active tab) so an agent can call tools without repeating a
+URL; pass ``url`` to any read/act tool to navigate first.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+
+
+def _md(html: str) -> str:
+    """HTML -> Markdown, best-effort. Uses markdownify if present, else falls back to a light strip."""
+    try:
+        from markdownify import markdownify
+        return markdownify(html, heading_style="ATX", strip=["script", "style", "noscript"])
+    except Exception:
+        import re
+        text = re.sub(r"(?is)<(script|style|noscript)[^>]*>.*?</\1>", " ", html)
+        text = re.sub(r"(?s)<[^>]+>", " ", text)
+        return re.sub(r"[ \t\r\f\v]+\n", "\n", re.sub(r"[ \t]{2,}", " ", text)).strip()
+
+
+# In-page collector for interactive elements (links, buttons, inputs) with a stable-ish selector.
+_ELEMENTS_JS = r"""() => {
+  const out = [];
+  const sel = (el) => {
+    if (el.id) return '#' + CSS.escape(el.id);
+    const nm = el.getAttribute('name'); if (nm) return el.tagName.toLowerCase() + '[name="' + nm + '"]';
+    const aria = el.getAttribute('aria-label'); if (aria) return el.tagName.toLowerCase() + '[aria-label="' + aria + '"]';
+    return null;
+  };
+  const seen = new Set();
+  for (const el of document.querySelectorAll('a[href], button, input, textarea, select, [role=button], [onclick]')) {
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) continue;                 // skip hidden
+    const txt = (el.innerText || el.value || el.getAttribute('aria-label') || el.getAttribute('placeholder') || '').trim().slice(0, 120);
+    const item = { tag: el.tagName.toLowerCase(), text: txt,
+                   type: el.getAttribute('type') || null,
+                   href: el.getAttribute('href') || null, selector: sel(el) };
+    const key = JSON.stringify(item);
+    if (seen.has(key)) continue; seen.add(key);
+    out.push(item);
+    if (out.length >= 200) break;
+  }
+  return out;
+}"""
+
+
+class ClearcoteBrowser:
+    """One shared, stealth clearcote browser + its Playwright attachment."""
+
+    def __init__(self, persona: dict | None = None):
+        self._persona = persona or {}
+        self._srv = None          # clearcote._serve.Server
+        self._pw = None           # playwright async context manager
+        self._browser = None      # playwright Browser (over CDP)
+        self._ctx = None          # BrowserContext
+        self._page = None         # current page
+
+    # ── lifecycle ────────────────────────────────────────────────────────────
+    async def start(self):
+        import clearcote
+        from playwright.async_api import async_playwright
+        loop = asyncio.get_running_loop()
+        # serve() is a blocking subprocess launch — off the event loop.
+        self._srv = await loop.run_in_executor(None, lambda: clearcote.serve(quiet=True, **self._persona))
+        self._pw = await async_playwright().start()
+        self._browser = await self._pw.chromium.connect_over_cdp(self._srv.cdp_url)
+        self._ctx = self._browser.contexts[0] if self._browser.contexts else await self._browser.new_context()
+        self._page = self._ctx.pages[0] if self._ctx.pages else await self._ctx.new_page()
+
+    def is_healthy(self) -> bool:
+        try:
+            return bool(self._srv and self._srv.is_alive() and self._browser and self._browser.is_connected())
+        except Exception:
+            return False
+
+    async def close(self):
+        for step in (
+            lambda: self._browser.close() if self._browser else None,
+            lambda: self._pw.stop() if self._pw else None,
+        ):
+            try:
+                r = step()
+                if asyncio.iscoroutine(r):
+                    await r
+            except Exception:
+                pass
+        try:
+            if self._srv:
+                self._srv.close()
+        except Exception:
+            pass
+        self._srv = self._pw = self._browser = self._ctx = self._page = None
+
+    @property
+    def cdp_url(self) -> str:
+        return self._srv.cdp_url if self._srv else ""
+
+    async def _pg(self, url: str | None):
+        if url:
+            await self._page.goto(url, wait_until="domcontentloaded", timeout=45000)
+        return self._page
+
+    # ── read ─────────────────────────────────────────────────────────────────
+    async def navigate(self, url: str) -> dict:
+        pg = await self._pg(url)
+        return {"status": "ok", "url": pg.url, "title": await pg.title()}
+
+    async def read_page(self, url: str | None = None) -> dict:
+        pg = await self._pg(url)
+        html = await pg.content()
+        return {"status": "ok", "url": pg.url, "title": await pg.title(),
+                "text": (await pg.inner_text("body"))[:200000], "markdown": _md(html)[:200000]}
+
+    async def get_html(self, url: str | None = None) -> dict:
+        pg = await self._pg(url)
+        return {"status": "ok", "url": pg.url, "html": await pg.content()}
+
+    async def page_elements(self, url: str | None = None) -> dict:
+        pg = await self._pg(url)
+        return {"status": "ok", "url": pg.url, "elements": await pg.evaluate(_ELEMENTS_JS)}
+
+    async def evaluate(self, expression: str, url: str | None = None) -> dict:
+        pg = await self._pg(url)
+        return {"status": "ok", "url": pg.url, "result": await pg.evaluate(expression)}
+
+    async def wait_for(self, selector: str, url: str | None = None, timeout_ms: int = 10000) -> dict:
+        pg = await self._pg(url)
+        await pg.wait_for_selector(selector, timeout=timeout_ms)
+        return {"status": "ok", "url": pg.url, "found": selector}
+
+    async def current_page(self) -> dict:
+        pg = self._page
+        return {"status": "ok", "url": pg.url, "title": await pg.title()}
+
+    # ── act ──────────────────────────────────────────────────────────────────
+    async def click(self, target: str, url: str | None = None) -> dict:
+        pg = await self._pg(url)
+        # try as a CSS selector first, then fall back to visible text
+        try:
+            await pg.click(target, timeout=6000)
+        except Exception:
+            await pg.get_by_text(target, exact=False).first.click(timeout=6000)
+        await pg.wait_for_load_state("domcontentloaded")
+        return {"status": "ok", "url": pg.url, "clicked": target}
+
+    async def fill(self, field: str, value: str, url: str | None = None) -> dict:
+        pg = await self._pg(url)
+        loc = None
+        for attempt in (
+            lambda: pg.locator(field),
+            lambda: pg.get_by_label(field),
+            lambda: pg.get_by_placeholder(field),
+            lambda: pg.locator("[name='%s']" % field),
+        ):
+            try:
+                cand = attempt()
+                await cand.first.fill(value, timeout=4000)
+                loc = field
+                break
+            except Exception:
+                continue
+        if loc is None:
+            raise ValueError("no fillable field matched %r" % field)
+        return {"status": "ok", "url": pg.url, "filled": field}
+
+    async def press(self, key: str) -> dict:
+        await self._page.keyboard.press(key)
+        return {"status": "ok", "pressed": key}
+
+    # ── capture ──────────────────────────────────────────────────────────────
+    async def screenshot(self, path: str, url: str | None = None, full_page: bool = True) -> dict:
+        pg = await self._pg(url)
+        await pg.screenshot(path=path, full_page=full_page)
+        return {"status": "ok", "url": pg.url, "path": path}
+
+    async def save_pdf(self, path: str, url: str | None = None) -> dict:
+        pg = await self._pg(url)
+        await pg.pdf(path=path)  # headless only
+        return {"status": "ok", "url": pg.url, "path": path}
+
+    # ── state ────────────────────────────────────────────────────────────────
+    async def cookies(self, url: str | None = None) -> dict:
+        c = await self._ctx.cookies(url) if url else await self._ctx.cookies()
+        return {"status": "ok", "cookies": c}
+
+    async def list_tabs(self) -> dict:
+        tabs = []
+        for i, p in enumerate(self._ctx.pages):
+            tabs.append({"index": i, "url": p.url, "title": await p.title(), "current": p is self._page})
+        return {"status": "ok", "tabs": tabs}
+
+    async def new_tab(self, url: str | None = None) -> dict:
+        self._page = await self._ctx.new_page()
+        if url:
+            await self._page.goto(url, wait_until="domcontentloaded", timeout=45000)
+        return {"status": "ok", "url": self._page.url, "index": len(self._ctx.pages) - 1}
+
+    async def close_tab(self, index: int) -> dict:
+        pages = self._ctx.pages
+        if not (0 <= index < len(pages)):
+            raise ValueError("tab index %d out of range (0..%d)" % (index, len(pages) - 1))
+        target = pages[index]
+        await target.close()
+        if target is self._page:
+            self._page = self._ctx.pages[-1] if self._ctx.pages else await self._ctx.new_page()
+        return {"status": "ok", "closed": index}
+
+    async def save_profile(self, path: str) -> dict:
+        state = await self._ctx.storage_state()
+        with open(path, "w", encoding="utf-8") as fh:
+            json.dump(state, fh)
+        return {"status": "ok", "path": path,
+                "cookies": len(state.get("cookies", [])), "origins": len(state.get("origins", []))}
+
+    async def load_profile(self, path: str) -> dict:
+        with open(path, encoding="utf-8") as fh:
+            state = json.load(fh)
+        if state.get("cookies"):
+            await self._ctx.add_cookies(state["cookies"])
+        return {"status": "ok", "path": path, "cookies": len(state.get("cookies", []))}
+
+    async def egress_info(self) -> dict:
+        pg = self._page
+        prev = pg.url
+        try:
+            info = await pg.evaluate(
+                "async () => { const r = await fetch('https://api.ipify.org?format=json',{cache:'no-store'});"
+                " return await r.json(); }")
+        except Exception as exc:
+            info = {"error": str(exc)}
+        try:
+            if prev and prev != "about:blank":
+                await pg.goto(prev, wait_until="domcontentloaded", timeout=15000)
+        except Exception:
+            pass
+        return {"status": "ok", "public_ip": info.get("ip") if isinstance(info, dict) else None,
+                "persona": {k: self._persona.get(k) for k in ("fingerprint", "platform", "brand", "proxy") if self._persona.get(k)}}

clearcote_mcp-0.1.0/clearcote_mcp/server.py

@@ -0,0 +1,366 @@
+"""Clearcote MCP server — drive the open-source stealth Chromium from any MCP client
+(Claude Desktop, Cursor, Cline, ...).
+
+One shared stealth browser, launched via ``clearcote.serve()`` (a raw CDP endpoint the tools
+attach to over Playwright, and that ``get_cdp_endpoint`` hands to any other client). The persona
+(seed / platform / proxy / geoip) is read from the environment so the tool surface stays clean.
+
+Hardening (ported from the Fortress MCP design): every tool has a wall-clock timeout and returns a
+STRUCTURED error instead of crashing the server; URL args are SSRF-checked (no localhost / private /
+cloud-metadata unless opted in); file writes are confined to a sandbox dir; oversized text fields
+are capped so a response never floods the agent's context; the shared browser is guarded by an
+asyncio lock and rebuilt if it dies.
+"""
+from __future__ import annotations
+
+import asyncio
+import functools
+import os
+import sys
+from contextlib import asynccontextmanager
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+from ._facade import ClearcoteBrowser
+
+# ── tool annotations ─────────────────────────────────────────────────────────
+_READ = ToolAnnotations(readOnlyHint=True, openWorldHint=True)
+_LOCAL = ToolAnnotations(readOnlyHint=True, openWorldHint=False)
+_WRITE = ToolAnnotations(readOnlyHint=False, openWorldHint=True)
+
+_TOOL_TIMEOUT = float(os.environ.get("CLEARCOTE_MCP_TOOL_TIMEOUT", "90"))
+
+
+def _env(name: str, default: str | None = None) -> str | None:
+    v = os.environ.get("CLEARCOTE_" + name)
+    return v if v is not None else default
+
+
+# ── error boundary ───────────────────────────────────────────────────────────
+def _safe(fn):
+    """Per-tool wall-clock timeout + structured error, so a bad/slow call never wedges the server."""
+    @functools.wraps(fn)
+    async def wrap(*args, **kwargs):
+        try:
+            return await asyncio.wait_for(fn(*args, **kwargs), timeout=_TOOL_TIMEOUT)
+        except asyncio.TimeoutError:
+            return {"status": "error",
+                    "error": f"tool timed out after {_TOOL_TIMEOUT:.0f}s "
+                             f"(raise CLEARCOTE_MCP_TOOL_TIMEOUT for slow pages)"}
+        except Exception as exc:  # noqa: BLE001 — deliberate catch-all at the tool boundary
+            return {"status": "error", "error": f"{type(exc).__name__}: {exc}"}
+    return wrap
+
+
+# ── SSRF guard ───────────────────────────────────────────────────────────────
+def _ip_blocked(ip_str: str) -> bool:
+    import ipaddress
+    try:
+        ip = ipaddress.ip_address(ip_str)
+    except ValueError:
+        return False
+    if getattr(ip, "ipv4_mapped", None) is not None:
+        ip = ip.ipv4_mapped
+    return (ip.is_private or ip.is_loopback or ip.is_link_local
+            or ip.is_reserved or ip.is_multicast or ip.is_unspecified)
+
+
+async def _check_url(url: str | None) -> None:
+    """Refuse localhost / private / cloud-metadata targets unless CLEARCOTE_ALLOW_PRIVATE_EGRESS=1."""
+    if url is None:
+        return
+    if _env("ALLOW_PRIVATE_EGRESS", "0") == "1":
+        return
+    from urllib.parse import urlparse
+    host = (urlparse(url).hostname or "").strip("[]")
+    if not host:
+        return
+    if host.lower() in ("localhost", "metadata.google.internal"):
+        raise ValueError(f"refused private/metadata host {host!r} (set CLEARCOTE_ALLOW_PRIVATE_EGRESS=1 to allow)")
+    if _ip_blocked(host):
+        raise ValueError(f"refused private/internal address {host!r} (set CLEARCOTE_ALLOW_PRIVATE_EGRESS=1 to allow)")
+    try:
+        loop = asyncio.get_running_loop()
+        infos = await loop.getaddrinfo(host, None)
+    except Exception:
+        return
+    for info in infos:
+        if _ip_blocked(info[4][0]):
+            raise ValueError(f"refused private/internal address for {host!r} (set CLEARCOTE_ALLOW_PRIVATE_EGRESS=1 to allow)")
+
+
+# ── write-path sandbox ───────────────────────────────────────────────────────
+def _write_root() -> str:
+    import tempfile
+    root = _env("MCP_WRITE_DIR") or os.path.join(tempfile.gettempdir(), "clearcote-mcp")
+    os.makedirs(root, exist_ok=True)
+    return os.path.abspath(root)
+
+
+def _confine_path(path: str | None, suffix: str) -> str:
+    import tempfile
+    root = _write_root()
+    if _env("MCP_ALLOW_ANY_PATH", "0") == "1" and path:
+        return path
+    if not path:
+        fd, p = tempfile.mkstemp(suffix=suffix, prefix="clearcote_", dir=root)
+        os.close(fd)
+        return p
+    name = os.path.basename(path) or ("out" + suffix)
+    if not os.path.splitext(name)[1]:
+        name += suffix
+    return os.path.join(root, name)
+
+
+def _cap(d: dict, limits: dict[str, int]) -> dict:
+    out = dict(d)
+    for field, n in limits.items():
+        v = out.get(field)
+        if isinstance(v, str) and len(v) > n:
+            out[field] = v[:n]
+            out[f"{field}_truncated"] = True
+    return out
+
+
+# ── shared browser ───────────────────────────────────────────────────────────
+def _persona_from_env() -> dict:
+    p: dict = {}
+    for env_key, opt in (("FINGERPRINT", "fingerprint"), ("PLATFORM", "platform"),
+                         ("BRAND", "brand"), ("TIMEZONE", "timezone"),
+                         ("ACCEPT_LANGUAGE", "accept_language")):
+        v = _env(env_key)
+        if v:
+            p[opt] = v
+    if _env("GEOIP", "0") == "1":
+        p["geoip"] = True
+    if _env("BINARY"):
+        p["executable_path"] = _env("BINARY")
+    proxy = _env("PROXY")
+    if proxy:
+        from clearcote._serve import _parse_proxy
+        p["proxy"] = _parse_proxy(proxy)
+    port = _env("SERVE_PORT")
+    if port:
+        p["port"] = int(port)
+    p["headless"] = _env("HEADLESS", "1") != "0"
+    return p
+
+
+_browser: ClearcoteBrowser | None = None
+_lock: asyncio.Lock | None = None
+
+
+async def _b() -> ClearcoteBrowser:
+    """Shared stealth browser; started on first use, rebuilt if it dies. Concurrency-safe."""
+    global _browser, _lock
+    if _lock is None:
+        _lock = asyncio.Lock()
+    async with _lock:
+        if _browser is not None and not _browser.is_healthy():
+            try:
+                await _browser.close()
+            except Exception:
+                pass
+            _browser = None
+        if _browser is None:
+            inst = ClearcoteBrowser(_persona_from_env())
+            await inst.start()
+            _browser = inst
+    return _browser
+
+
+@asynccontextmanager
+async def _lifespan(_server):
+    """Pre-warm the browser so the agent's first tool call is warm, not a cold launch."""
+    if _env("MCP_PREWARM", "1") != "0":
+        try:
+            await _b()
+        except Exception:
+            pass
+    try:
+        yield
+    finally:
+        global _browser
+        if _browser is not None:
+            try:
+                await _browser.close()
+            except Exception:
+                pass
+            _browser = None
+
+
+mcp = FastMCP("Clearcote Stealth Browser", lifespan=_lifespan)
+
+
+# ── tools ─────────────────────────────────────────────────────────────────────
+@mcp.tool(annotations=_WRITE)
+@_safe
+async def navigate(url: str) -> dict:
+    """Navigate the current tab to a URL. Returns the resolved url + title."""
+    await _check_url(url)
+    return await (await _b()).navigate(url)
+
+
+@mcp.tool(annotations=_READ)
+@_safe
+async def read_page(url: str | None = None) -> dict:
+    """Read the current page (or navigate to `url` first) as clean text + Markdown."""
+    await _check_url(url)
+    return _cap(await (await _b()).read_page(url), {"text": 20000, "markdown": 40000})
+
+
+@mcp.tool(annotations=_READ)
+@_safe
+async def get_page_html(url: str | None = None) -> dict:
+    """Get the raw HTML of the current page (or navigate to `url` first)."""
+    await _check_url(url)
+    return _cap(await (await _b()).get_html(url), {"html": 80000})
+
+
+@mcp.tool(annotations=_READ)
+@_safe
+async def page_elements(url: str | None = None) -> dict:
+    """List the interactive elements (links, buttons, inputs) on the page, each with a selector."""
+    await _check_url(url)
+    return await (await _b()).page_elements(url)
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+async def click(target: str, url: str | None = None) -> dict:
+    """Click an element by CSS selector or by visible text (navigate to `url` first if given)."""
+    await _check_url(url)
+    return await (await _b()).click(target, url)
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+async def fill_field(field: str, value: str, url: str | None = None) -> dict:
+    """Fill an input matched by selector, label, placeholder, or name."""
+    await _check_url(url)
+    return await (await _b()).fill(field, value, url)
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+async def press_key(key: str) -> dict:
+    """Press a key on the current page, e.g. 'Enter', 'Tab', 'Control+A'."""
+    return await (await _b()).press(key)
+
+
+@mcp.tool(annotations=_READ)
+@_safe
+async def evaluate_js(expression: str, url: str | None = None) -> dict:
+    """Evaluate a JavaScript expression in the page and return the (JSON-serializable) result."""
+    await _check_url(url)
+    return await (await _b()).evaluate(expression, url)
+
+
+@mcp.tool(annotations=_READ)
+@_safe
+async def wait_for(selector: str, url: str | None = None, timeout_ms: int = 10000) -> dict:
+    """Wait until a selector appears (up to timeout_ms)."""
+    await _check_url(url)
+    return await (await _b()).wait_for(selector, url, timeout_ms)
+
+
+@mcp.tool(annotations=_READ)
+@_safe
+async def current_page() -> dict:
+    """Return the current tab's url + title."""
+    return await (await _b()).current_page()
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+async def screenshot_page(url: str | None = None, path: str | None = None) -> dict:
+    """Screenshot the current page (or navigate to `url` first). Saved under the sandbox dir."""
+    await _check_url(url)
+    return await (await _b()).screenshot(_confine_path(path, ".png"), url)
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+async def save_page_pdf(url: str | None = None, path: str | None = None) -> dict:
+    """Save the current page as a PDF (headless only). Saved under the sandbox dir."""
+    await _check_url(url)
+    return await (await _b()).save_pdf(_confine_path(path, ".pdf"), url)
+
+
+@mcp.tool(annotations=_READ)
+@_safe
+async def get_cookies(url: str | None = None) -> dict:
+    """Get cookies for the current context (optionally filtered to `url`)."""
+    await _check_url(url)
+    return await (await _b()).cookies(url)
+
+
+@mcp.tool(annotations=_LOCAL)
+@_safe
+async def list_tabs() -> dict:
+    """List open tabs (index, url, title, which is current)."""
+    return await (await _b()).list_tabs()
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+async def new_tab(url: str | None = None) -> dict:
+    """Open a new tab (optionally navigate it) and make it current."""
+    await _check_url(url)
+    return await (await _b()).new_tab(url)
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+async def close_tab(index: int) -> dict:
+    """Close the tab at `index` (from list_tabs)."""
+    return await (await _b()).close_tab(index)
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+async def save_profile(name: str = "session") -> dict:
+    """Save cookies + storage state to a named profile under the sandbox dir."""
+    return await (await _b()).save_profile(_confine_path(name, ".json"))
+
+
+@mcp.tool(annotations=_WRITE)
+@_safe
+async def load_profile(name: str = "session") -> dict:
+    """Restore cookies + storage from a named profile (see save_profile)."""
+    return await (await _b()).load_profile(_confine_path(name, ".json"))
+
+
+@mcp.tool(annotations=_LOCAL)
+@_safe
+async def get_egress_info() -> dict:
+    """Report the browser's public egress IP (through any configured proxy) + the active persona."""
+    return await (await _b()).egress_info()
+
+
+@mcp.tool(annotations=_LOCAL)
+@_safe
+async def get_cdp_endpoint() -> dict:
+    """Return the stealth browser's raw CDP endpoint so ANY other client (Playwright / Puppeteer /
+    browser-use / Crawl4AI / Stagehand) can attach to the SAME browser with `connect_over_cdp`,
+    keeping the stealth persona. This is the whole point of the drop-in model."""
+    b = await _b()
+    return {"status": "ok", "cdp_url": b.cdp_url,
+            "connect": {
+                "playwright_python": f"p.chromium.connect_over_cdp({b.cdp_url!r})",
+                "playwright_node": f'chromium.connectOverCDP("{b.cdp_url}")',
+                "puppeteer": f'puppeteer.connect({{ browserURL: "{b.cdp_url}" }})',
+                "browser_use": f'cdp_url="{b.cdp_url}"'}}
+
+
+def main() -> None:
+    """stdio MCP entry point (used by `clearcote-mcp` and `python -m clearcote_mcp`)."""
+    try:
+        mcp.run()
+    except KeyboardInterrupt:
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

clearcote_mcp-0.1.0/clearcote_mcp.egg-info/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: clearcote-mcp
+Version: 0.1.0
+Summary: MCP server for Clearcote — drive the open-source stealth Chromium from Claude Desktop, Cursor, Cline, and any MCP client.
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/clearcotelabs/clearcote-browser
+Project-URL: Source, https://github.com/clearcotelabs/clearcote-browser/tree/main/mcp
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: clearcote>=0.13
+Requires-Dist: mcp[cli]>=1.2
+Requires-Dist: markdownify>=0.11
+
+# Clearcote MCP server
+
+Drive the open-source **Clearcote stealth Chromium** from any MCP client — Claude Desktop, Cursor,
+Cline, Continue, or your own agent. One shared, coherent stealth browser; ~20 tools to navigate,
+read, extract, click, fill, screenshot, and persist sessions — plus `get_cdp_endpoint`, which hands
+the **same** stealth browser to any Playwright / Puppeteer / browser-use / Crawl4AI client.
+
+The fingerprint is corrected in Chromium's **C++**, so you do **not** add `puppeteer-stealth` /
+`undetected-chromedriver` / any JS patching — those self-reveal and undo it. Driving over CDP adds
+no automation flags, so `navigator.webdriver` stays `false` and the persona is intact end to end.
+
+---
+
+## Run it
+
+**Node (no install):**
+```bash
+npx clearcote-mcp
+```
+
+**Python:**
+```bash
+pip install clearcote-mcp
+clearcote-mcp            # stdio server
+```
+
+Both auto-download + SHA-256-verify the right Clearcote binary per OS on first use (native Windows
+x64 + Linux x64).
+
+## Add it to a client
+
+Claude Desktop / Cursor / Cline `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "clearcote": {
+      "command": "npx",
+      "args": ["-y", "clearcote-mcp"],
+      "env": {
+        "CLEARCOTE_FINGERPRINT": "acct-1",
+        "CLEARCOTE_PLATFORM": "windows",
+        "CLEARCOTE_PROXY": "http://user:pass@host:port",
+        "CLEARCOTE_GEOIP": "1"
+      }
+    }
+  }
+}
+```
+
+The **persona lives in the environment**, so the tool surface stays clean:
+
+| env var | meaning |
+|---|---|
+| `CLEARCOTE_FINGERPRINT` | seed → one stable, coherent identity (same seed = same machine across runs) |
+| `CLEARCOTE_PLATFORM` | `windows` \| `linux` \| `macos` \| `android` |
+| `CLEARCOTE_BRAND` | `Chrome` \| `Edge` \| `Opera` \| `Vivaldi` |
+| `CLEARCOTE_PROXY` | `http://user:pass@host:port` (routes all traffic) |
+| `CLEARCOTE_GEOIP` | `1` → derive timezone/locale/WebRTC IP from the proxy exit IP |
+| `CLEARCOTE_TIMEZONE` / `CLEARCOTE_ACCEPT_LANGUAGE` | explicit overrides |
+| `CLEARCOTE_HEADLESS` | `0` for a visible window (default headless) |
+| `CLEARCOTE_BINARY` | path to a specific Clearcote binary (optional) |
+
+Hardening knobs: `CLEARCOTE_MCP_TOOL_TIMEOUT` (s), `CLEARCOTE_MCP_WRITE_DIR` (sandbox for file
+writes), `CLEARCOTE_MCP_ALLOW_ANY_PATH=1`, `CLEARCOTE_ALLOW_PRIVATE_EGRESS=1` (allow localhost /
+private targets), `CLEARCOTE_MCP_PREWARM=0`, `CLEARCOTE_SERVE_PORT`.
+
+## Tools
+
+**Read** · `read_page` (text + Markdown) · `get_page_html` · `page_elements` (interactive elements +
+selectors) · `evaluate_js` · `wait_for` · `current_page` · `get_cookies` · `list_tabs`
+**Act** · `navigate` · `click` (selector or visible text) · `fill_field` (selector/label/placeholder/name)
+· `press_key` · `new_tab` · `close_tab`
+**Capture** · `screenshot_page` · `save_page_pdf`
+**Session** · `save_profile` / `load_profile` (cookies + storage)
+**Stealth / infra** · `get_egress_info` (public IP + active persona) · **`get_cdp_endpoint`** (attach any
+other CDP client to the same stealth browser)
+
+## Guardrails (built in)
+
+- Every tool has a wall-clock timeout and returns a **structured error** instead of crashing the server.
+- URL args are **SSRF-checked** — localhost / private / cloud-metadata are refused unless you opt in.
+- File writes are **confined** to a sandbox dir (no path traversal).
+- Oversized text is **capped** so a response never floods the agent's context.
+- The shared browser is **rebuilt** automatically if it dies.
+
+## Just want the raw endpoint?
+
+If you don't need the tools, run the browser as a standing CDP endpoint and attach your existing code:
+
+```bash
+clearcote-serve --port 9222 --fingerprint acct-1 --platform windows
+# → prints http://127.0.0.1:9222 ; then:  connect_over_cdp / puppeteer.connect({browserURL})
+```
+
+See [USAGE.md](USAGE.md) for per-client examples. Part of
+[clearcote-browser](https://github.com/clearcotelabs/clearcote-browser) (BSD-3).

clearcote_mcp-0.1.0/clearcote_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+clearcote_mcp/__init__.py
+clearcote_mcp/__main__.py
+clearcote_mcp/_facade.py
+clearcote_mcp/server.py
+clearcote_mcp.egg-info/PKG-INFO
+clearcote_mcp.egg-info/SOURCES.txt
+clearcote_mcp.egg-info/dependency_links.txt
+clearcote_mcp.egg-info/entry_points.txt
+clearcote_mcp.egg-info/requires.txt
+clearcote_mcp.egg-info/top_level.txt
+tests/test_server.py

clearcote_mcp-0.1.0/clearcote_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clearcote_mcp-0.1.0/clearcote_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clearcote-mcp = clearcote_mcp.server:main

clearcote_mcp-0.1.0/clearcote_mcp.egg-info/requires.txt

@@ -0,0 +1,3 @@
+clearcote>=0.13
+mcp[cli]>=1.2
+markdownify>=0.11

clearcote_mcp-0.1.0/clearcote_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+clearcote_mcp

clearcote_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clearcote-mcp"
+version = "0.1.0"
+description = "MCP server for Clearcote — drive the open-source stealth Chromium from Claude Desktop, Cursor, Cline, and any MCP client."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "BSD-3-Clause" }
+dependencies = [
+    "clearcote>=0.13",
+    "mcp[cli]>=1.2",
+    "markdownify>=0.11",
+]
+
+[project.scripts]
+clearcote-mcp = "clearcote_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/clearcotelabs/clearcote-browser"
+Source = "https://github.com/clearcotelabs/clearcote-browser/tree/main/mcp"
+
+[tool.setuptools]
+packages = ["clearcote_mcp"]

clearcote_mcp-0.1.0/setup.cfg

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

clearcote_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,73 @@
+import os
+import pytest
+from clearcote_mcp import server as S
+
+
+@pytest.mark.asyncio
+async def test_all_tools_registered():
+    tools = await S.mcp.list_tools()
+    names = {t.name for t in tools}
+    assert {"navigate", "read_page", "get_page_html", "page_elements", "click",
+            "fill_field", "press_key", "evaluate_js", "wait_for", "current_page",
+            "screenshot_page", "save_page_pdf", "get_cookies", "list_tabs", "new_tab",
+            "close_tab", "save_profile", "load_profile", "get_egress_info",
+            "get_cdp_endpoint"} <= names
+    assert len(tools) >= 20
+
+
+def test_ip_blocked():
+    assert S._ip_blocked("127.0.0.1")
+    assert S._ip_blocked("169.254.169.254")   # cloud metadata
+    assert S._ip_blocked("10.0.0.5")
+    assert S._ip_blocked("::1")
+    assert not S._ip_blocked("8.8.8.8")
+    assert not S._ip_blocked("not-an-ip")
+
+
+@pytest.mark.asyncio
+async def test_check_url_ssrf_guard(monkeypatch):
+    monkeypatch.delenv("CLEARCOTE_ALLOW_PRIVATE_EGRESS", raising=False)
+    with pytest.raises(ValueError):
+        await S._check_url("http://localhost/x")
+    with pytest.raises(ValueError):
+        await S._check_url("http://169.254.169.254/latest/meta-data/")
+    await S._check_url("https://example.com")   # public → ok
+    await S._check_url(None)                     # no url → ok
+    monkeypatch.setenv("CLEARCOTE_ALLOW_PRIVATE_EGRESS", "1")
+    await S._check_url("http://localhost/x")     # opted in → ok
+
+
+def test_confine_path_blocks_traversal(tmp_path, monkeypatch):
+    monkeypatch.setenv("CLEARCOTE_MCP_WRITE_DIR", str(tmp_path))
+    monkeypatch.delenv("CLEARCOTE_MCP_ALLOW_ANY_PATH", raising=False)
+    p = S._confine_path("../../etc/passwd", ".png")
+    assert os.path.dirname(p) == str(tmp_path)          # confined to sandbox root
+    assert os.path.basename(p) == "passwd.png"          # traversal + missing ext handled
+
+
+def test_cap_trims_and_flags():
+    out = S._cap({"text": "x" * 100, "small": "ok"}, {"text": 10})
+    assert out["text"] == "x" * 10 and out["text_truncated"] is True
+    assert out["small"] == "ok" and "small_truncated" not in out
+
+
+def test_persona_from_env(monkeypatch):
+    for k in ("FINGERPRINT", "PLATFORM", "GEOIP", "HEADLESS", "PROXY", "BINARY"):
+        monkeypatch.delenv("CLEARCOTE_" + k, raising=False)
+    monkeypatch.setenv("CLEARCOTE_FINGERPRINT", "seed-9")
+    monkeypatch.setenv("CLEARCOTE_PLATFORM", "windows")
+    monkeypatch.setenv("CLEARCOTE_HEADLESS", "0")
+    monkeypatch.setenv("CLEARCOTE_PROXY", "http://u:p@h:8080")
+    p = S._persona_from_env()
+    assert p["fingerprint"] == "seed-9" and p["platform"] == "windows"
+    assert p["headless"] is False
+    assert p["proxy"] == {"server": "http://h:8080", "username": "u", "password": "p"}
+
+
+@pytest.mark.asyncio
+async def test_safe_returns_structured_error():
+    @S._safe
+    async def boom():
+        raise RuntimeError("nope")
+    r = await boom()
+    assert r["status"] == "error" and "RuntimeError" in r["error"]