ghostfox 0.2.0__tar.gz

ghostfox-0.2.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: ghostfox
+Version: 0.2.0
+Summary: Ghostfox — the agent-native stealth browser you can own. Python client + engine installer for the Ghostfox MCP runtime.
+Author: autokeren
+License: MIT OR Apache-2.0
+Project-URL: Repository, https://github.com/autokeren/ghostfox
+Keywords: browser,stealth,anti-detect,mcp,ai-agents,scraping
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ghostfox (Python)
+
+Python surface for the [Ghostfox](https://github.com/autokeren/ghostfox)
+agent-native stealth browser.
+
+```python
+import ghostfox
+
+# one-time: download the prebuilt engine + runtime (Linux x86_64)
+ghostfox.install_engine()
+ghostfox.install_runtime()
+
+fox = ghostfox.GhostfoxMCP()
+sid  = fox.session_create(platform="android")   # coherent mobile persona
+page = fox.page_open(sid, "https://example.com")
+print(fox.page_snapshot(sid, page)["content"])
+fox.page_screenshot(sid, page)                   # evidence + live view
+fox.close()
+```
+
+Zero Python dependencies — it drives the Rust MCP runtime over stdio, the
+same server AI agents use.

ghostfox-0.2.0/README.md

@@ -0,0 +1,22 @@
+# ghostfox (Python)
+
+Python surface for the [Ghostfox](https://github.com/autokeren/ghostfox)
+agent-native stealth browser.
+
+```python
+import ghostfox
+
+# one-time: download the prebuilt engine + runtime (Linux x86_64)
+ghostfox.install_engine()
+ghostfox.install_runtime()
+
+fox = ghostfox.GhostfoxMCP()
+sid  = fox.session_create(platform="android")   # coherent mobile persona
+page = fox.page_open(sid, "https://example.com")
+print(fox.page_snapshot(sid, page)["content"])
+fox.page_screenshot(sid, page)                   # evidence + live view
+fox.close()
+```
+
+Zero Python dependencies — it drives the Rust MCP runtime over stdio, the
+same server AI agents use.

ghostfox-0.2.0/ghostfox/__init__.py

@@ -0,0 +1,16 @@
+"""Ghostfox — the agent-native stealth browser you can own.
+
+Python surface for the Ghostfox stack:
+- ``ghostfox.install_engine()`` — download + unpack the prebuilt engine
+- ``ghostfox.GhostfoxMCP`` — drive the runtime (the same MCP server agents
+  use) from plain Python
+
+The runtime is a Rust binary (``ghostcloak-mcp``); this package wraps it so
+the Python world gets the same one-command story as ``pip install browser-use``.
+"""
+
+from .mcp import GhostfoxMCP, McpError
+from .engine import install_engine, engine_home
+
+__version__ = "0.2.0"
+__all__ = ["GhostfoxMCP", "McpError", "install_engine", "engine_home"]

ghostfox-0.2.0/ghostfox/engine.py

@@ -0,0 +1,110 @@
+"""Engine installer: fetch the prebuilt Ghostfox engine from GitHub Releases.
+
+Layout after install: ``~/.ghostfox/engine`` (override the root with
+``GHOSTFOX_HOME_ROOT``). Point ``GHOSTFOX_HOME`` at the returned path when
+launching the runtime.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import shutil
+import sys
+import urllib.request
+import zipfile
+from pathlib import Path
+
+REPO = "autokeren/ghostfox"
+
+
+def _latest_release() -> dict:
+    url = f"https://api.github.com/repos/{REPO}//releases/latest"
+    req = urllib.request.Request(url, headers={"User-Agent": "ghostfox-py"})
+    with urllib.request.urlopen(req, timeout=30) as r:
+        return json.load(r)
+
+
+def engine_home() -> Path:
+    """Where the engine is (or will be) installed."""
+    root = Path(os.environ.get("GHOSTFOX_HOME_ROOT", Path.home() / ".ghostfox"))
+    return root / "engine"
+
+
+def install_engine(dest: Path | None = None, quiet: bool = False) -> Path:
+    """Download and unpack the latest prebuilt engine. Returns its path."""
+    dest = dest or engine_home()
+    if (dest / "ghostfox-bin").exists():
+        if not quiet:
+            print(f"engine already installed at {dest}", file=sys.stderr)
+        return dest
+
+    rel = _latest_release()
+    assets = {
+        a["name"]: a["browser_download_url"] for a in rel.get("assets", [])
+    }
+    url = next(
+        (u for n, u in assets.items() if "lin.x86_64" in n and n.endswith(".zip")),
+        None,
+    )
+    if not url:
+        raise RuntimeError(f"no Linux x86_64 engine asset in release {rel.get('tag_name')}")
+
+    if not quiet:
+        print(f"downloading {url.split('/')[-1]} ...", file=sys.stderr)
+    req = urllib.request.Request(url, headers={"User-Agent": "ghostfox-py"})
+    data = urllib.request.urlopen(req, timeout=600).read()
+
+    tmp = dest.parent / ".engine-download"
+    shutil.rmtree(tmp, ignore_errors=True)
+    tmp.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(io.BytesIO(data)) as zf:
+        zf.extractall(tmp)
+
+    src = tmp / "ghostfox" if (tmp / "ghostfox").is_dir() else tmp
+    shutil.rmtree(dest, ignore_errors=True)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(src), dest)
+    shutil.rmtree(tmp, ignore_errors=True)
+    if not quiet:
+        print(f"engine installed at {dest}", file=sys.stderr)
+    return dest
+
+
+def install_runtime(dest: Path | None = None, quiet: bool = False) -> Path:
+    """Download the prebuilt ``ghostcloak-mcp`` runtime binary (Linux x86_64)."""
+    dest = dest or engine_home().parent / "mcp" / "ghostcloak-mcp"
+    if dest.exists():
+        return dest
+    rel = _latest_release()
+    url = next(
+        (a["browser_download_url"] for a in rel.get("assets", []) if a["name"] == "ghostcloak-mcp"),
+        None,
+    )
+    if not url:
+        raise RuntimeError("no prebuilt runtime asset — build it with cargo (see README)")
+    if not quiet:
+        print("downloading ghostcloak-mcp ...", file=sys.stderr)
+    req = urllib.request.Request(url, headers={"User-Agent": "ghostfox-py"})
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_bytes(urllib.request.urlopen(req, timeout=120).read())
+    dest.chmod(0o755)
+    return dest
+
+
+def default_runtime() -> Path:
+    """Find a runtime: $GHOSTFOX_MCP, the installed copy, or one on PATH."""
+    if v := os.environ.get("GHOSTFOX_MCP"):
+        p = Path(v)
+        if p.exists():
+            return p
+    installed = engine_home().parent / "mcp" / "ghostcloak-mcp"
+    if installed.exists():
+        return installed
+    if shutil.which("ghostcloak-mcp"):
+        return Path(shutil.which("ghostcloak-mcp"))
+    raise RuntimeError(
+        "runtime not found: set GHOSTFOX_MCP, or call ghostfox.install_runtime()"
+    )
+

ghostfox-0.2.0/ghostfox/mcp.py

@@ -0,0 +1,158 @@
+"""Synchronous Python client for the Ghostfox MCP runtime (ghostcloak-mcp).
+
+The runtime is the same MCP server AI agents use; this client gives plain
+Python the same surface:
+
+    from ghostfox import GhostfoxMCP
+
+    fox = GhostfoxMCP()                      # finds/downloads nothing; requires runtime+engine
+    sid = fox.session_create(platform="android")
+    page = fox.page_open(sid, "https://example.com")
+    print(fox.page_snapshot(sid, page)["content"])
+    fox.close()
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+from .engine import default_runtime
+
+
+class McpError(RuntimeError):
+    pass
+
+
+class GhostfoxMCP:
+    """Drive the Ghostfox runtime over MCP stdio from Python."""
+
+    def __init__(
+        self,
+        runtime: Path | str | None = None,
+        engine_home: Path | str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> None:
+        self.runtime = Path(runtime) if runtime else default_runtime()
+        self.env = dict(os.environ)
+        self.env["GHOSTFOX_HOME"] = str(engine_home or os.environ.get("GHOSTFOX_HOME") or Path.home() / ".ghostfox" / "engine")
+        if env:
+            self.env.update(env)
+        self.env.setdefault("RUST_LOG", "warn")
+
+        self.proc = subprocess.Popen(
+            [str(self.runtime)],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            bufsize=1,
+            env=self.env,
+        )
+        self._id = 0
+        self._call("initialize", {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "ghostfox-py", "version": "0.1.0"},
+        })
+        self._notify("notifications/initialized")
+
+    # -- protocol plumbing ---------------------------------------------------
+
+    def _send(self, method: str, params: dict | None = None, notify: bool = False) -> None:
+        msg: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+        if params is not None:
+            msg["params"] = params
+        if not notify:
+            self._id += 1
+            msg["id"] = self._id
+        self.proc.stdin.write(json.dumps(msg) + "\n")
+        self.proc.stdin.flush()
+
+    def _recv(self, want: int, timeout: float = 120.0) -> dict:
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            line = self.proc.stdout.readline()
+            if not line:
+                raise McpError("runtime closed the connection")
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                resp = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if resp.get("id") == want:
+                return resp
+        raise McpError(f"timeout waiting for response {want}")
+
+    def _call(self, method: str, params: dict | None = None, timeout: float = 120.0) -> Any:
+        self._send(method, params)
+        resp = self._recv(self._id, timeout)
+        if "error" in resp:
+            raise McpError(f"{method}: {resp['error'].get('message')}")
+        return resp.get("result")
+
+    def _notify(self, method: str) -> None:
+        self._send(method, notify=True)
+
+    def _tool(self, name: str, args: dict, timeout: float = 180.0) -> str:
+        result = self._call("tools/call", {"name": name, "arguments": args}, timeout)
+        if result.get("isError"):
+            texts = [c.get("text", "") for c in result.get("content", [])]
+            raise McpError(f"{name}: {' '.join(texts)}")
+        return result["content"][0]["text"]
+
+    # -- the browser surface ---------------------------------------------------
+
+    def session_create(self, platform: str | None = None, profile_dir: str | None = None, proxy: str | None = None) -> str:
+        args: dict[str, Any] = {}
+        if platform:
+            args["platform"] = platform
+        if profile_dir:
+            args["profile_dir"] = profile_dir
+        if proxy:
+            args["proxy"] = proxy
+        return self._tool("session_create", args)
+
+    def page_open(self, session_id: str, url: str) -> str:
+        return self._tool("page_open", {"session_id": session_id, "url": url})
+
+    def page_snapshot(self, session_id: str, page_id: str) -> dict:
+        return json.loads(self._tool("page_snapshot", {"session_id": session_id, "page_id": page_id}))
+
+    def page_screenshot(self, session_id: str, page_id: str, full_page: bool = False) -> dict:
+        return json.loads(self._tool("page_screenshot", {"session_id": session_id, "page_id": page_id, "full_page": full_page}))
+
+    def page_click(self, session_id: str, page_id: str, selector: str) -> None:
+        self._tool("page_click", {"session_id": session_id, "page_id": page_id, "selector": selector})
+
+    def page_type(self, session_id: str, page_id: str, selector: str, text: str) -> None:
+        self._tool("page_type", {"session_id": session_id, "page_id": page_id, "selector": selector, "text": text})
+
+    def page_fill(self, session_id: str, page_id: str, selector: str, text: str) -> None:
+        self._tool("page_fill", {"session_id": session_id, "page_id": page_id, "selector": selector, "text": text})
+
+    def page_press(self, session_id: str, page_id: str, key: str) -> None:
+        self._tool("page_press", {"session_id": session_id, "page_id": page_id, "key": key})
+
+    def identity_generate(self) -> str:
+        return self._tool("identity_generate", {})
+
+    def identity_audit(self, identity_toml: str) -> str:
+        return self._tool("identity_audit", {"identity_toml": identity_toml})
+
+    def session_evidence(self, session_id: str) -> dict:
+        return json.loads(self._tool("session_evidence", {"session_id": session_id}))
+
+    def close(self) -> None:
+        if self.proc.poll() is None:
+            self.proc.terminate()
+            try:
+                self.proc.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                self.proc.kill()

ghostfox-0.2.0/ghostfox.egg-info/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: ghostfox
+Version: 0.2.0
+Summary: Ghostfox — the agent-native stealth browser you can own. Python client + engine installer for the Ghostfox MCP runtime.
+Author: autokeren
+License: MIT OR Apache-2.0
+Project-URL: Repository, https://github.com/autokeren/ghostfox
+Keywords: browser,stealth,anti-detect,mcp,ai-agents,scraping
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ghostfox (Python)
+
+Python surface for the [Ghostfox](https://github.com/autokeren/ghostfox)
+agent-native stealth browser.
+
+```python
+import ghostfox
+
+# one-time: download the prebuilt engine + runtime (Linux x86_64)
+ghostfox.install_engine()
+ghostfox.install_runtime()
+
+fox = ghostfox.GhostfoxMCP()
+sid  = fox.session_create(platform="android")   # coherent mobile persona
+page = fox.page_open(sid, "https://example.com")
+print(fox.page_snapshot(sid, page)["content"])
+fox.page_screenshot(sid, page)                   # evidence + live view
+fox.close()
+```
+
+Zero Python dependencies — it drives the Rust MCP runtime over stdio, the
+same server AI agents use.

ghostfox-0.2.0/ghostfox.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+ghostfox/__init__.py
+ghostfox/engine.py
+ghostfox/mcp.py
+ghostfox.egg-info/PKG-INFO
+ghostfox.egg-info/SOURCES.txt
+ghostfox.egg-info/dependency_links.txt
+ghostfox.egg-info/top_level.txt

ghostfox-0.2.0/ghostfox.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ghostfox-0.2.0/ghostfox.egg-info/top_level.txt

@@ -0,0 +1 @@
+ghostfox

ghostfox-0.2.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ghostfox"
+version = "0.2.0"
+description = "Ghostfox — the agent-native stealth browser you can own. Python client + engine installer for the Ghostfox MCP runtime."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT OR Apache-2.0" }
+authors = [{ name = "autokeren" }]
+keywords = ["browser", "stealth", "anti-detect", "mcp", "ai-agents", "scraping"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+]
+
+[project.urls]
+Repository = "https://github.com/autokeren/ghostfox"
+
+[tool.setuptools.packages.find]
+include = ["ghostfox*"]

ghostfox-0.2.0/setup.cfg

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