fagun 0.2.0__py3-none-any.whl

fagun/__init__.py

@@ -0,0 +1,3 @@
+"""Fagun — cross-tool browser + QA MCP server."""
+
+__version__ = "0.2.0"

fagun/__main__.py

@@ -0,0 +1,29 @@
+"""Entry point. `fagun` (or `uvx fagun`) starts the MCP server over stdio.
+
+Env vars:
+  FAGUN_HEADLESS   "0" to show the browser window (default "1" = headless)
+  FAGUN_CDP_URL    connect to an already-running Chrome via CDP instead of
+                   launching a fresh one, e.g. http://127.0.0.1:9222
+  FAGUN_BROWSER    chromium | firefox | webkit  (default chromium)
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    # Support `fagun install` helper without importing the heavy MCP stack.
+    if len(sys.argv) > 1 and sys.argv[1] in {"install", "--install", "help", "--help", "-h"}:
+        from .install import run_cli
+
+        run_cli(sys.argv[1:])
+        return
+
+    from .server import serve
+
+    serve()
+
+
+if __name__ == "__main__":
+    main()

fagun/browser.py

@@ -0,0 +1,143 @@
+"""Playwright wrapper. One shared browser/context/page per server process.
+
+Captures console messages and network requests as they happen so the QA tools
+and the AI can inspect them at any time.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from playwright.async_api import (
+    Browser,
+    BrowserContext,
+    Page,
+    Playwright,
+    async_playwright,
+)
+
+
+@dataclass
+class NetworkEntry:
+    method: str
+    url: str
+    status: Optional[int] = None
+    resource_type: str = ""
+    failure: Optional[str] = None
+
+
+@dataclass
+class ConsoleEntry:
+    type: str
+    text: str
+    location: str = ""
+
+
+@dataclass
+class BrowserManager:
+    _pw: Optional[Playwright] = None
+    _browser: Optional[Browser] = None
+    _context: Optional[BrowserContext] = None
+    _page: Optional[Page] = None
+    console: list[ConsoleEntry] = field(default_factory=list)
+    network: list[NetworkEntry] = field(default_factory=list)
+
+    @property
+    def is_open(self) -> bool:
+        return self._page is not None and not self._page.is_closed()
+
+    async def start(self, headless: Optional[bool] = None) -> str:
+        if self.is_open:
+            return f"Browser already open at {self._page.url or 'about:blank'}"
+
+        self._pw = await async_playwright().start()
+        engine = os.environ.get("FAGUN_BROWSER", "chromium").lower()
+        launcher = {
+            "chromium": self._pw.chromium,
+            "firefox": self._pw.firefox,
+            "webkit": self._pw.webkit,
+        }.get(engine, self._pw.chromium)
+
+        cdp = os.environ.get("FAGUN_CDP_URL")
+        if cdp:
+            # Attach to an already-running Chrome (the "autoConnect" style flow).
+            self._browser = await launcher.connect_over_cdp(cdp)
+            self._context = (
+                self._browser.contexts[0]
+                if self._browser.contexts
+                else await self._browser.new_context()
+            )
+        else:
+            if headless is None:
+                headless = os.environ.get("FAGUN_HEADLESS", "1") != "0"
+            self._browser = await launcher.launch(headless=headless)
+            self._context = await self._browser.new_context()
+
+        self._page = (
+            self._context.pages[0]
+            if self._context.pages
+            else await self._context.new_page()
+        )
+        self._wire_listeners(self._page)
+        return f"Browser started ({engine}, {'CDP' if cdp else 'launched'})."
+
+    def _wire_listeners(self, page: Page) -> None:
+        def on_console(msg: Any) -> None:
+            loc = msg.location or {}
+            where = f"{loc.get('url', '')}:{loc.get('lineNumber', '')}"
+            self.console.append(ConsoleEntry(msg.type, msg.text, where))
+
+        def on_response(resp: Any) -> None:
+            self.network.append(
+                NetworkEntry(
+                    method=resp.request.method,
+                    url=resp.url,
+                    status=resp.status,
+                    resource_type=resp.request.resource_type,
+                )
+            )
+
+        def on_request_failed(req: Any) -> None:
+            self.network.append(
+                NetworkEntry(
+                    method=req.method,
+                    url=req.url,
+                    failure=(req.failure or "failed"),
+                    resource_type=req.resource_type,
+                )
+            )
+
+        page.on("console", on_console)
+        page.on("response", on_response)
+        page.on("requestfailed", on_request_failed)
+
+    async def page(self) -> Page:
+        if not self.is_open:
+            await self.start()
+        assert self._page is not None
+        return self._page
+
+    def clear_logs(self) -> None:
+        self.console.clear()
+        self.network.clear()
+
+    async def stop(self) -> str:
+        for closer in (self._context, self._browser):
+            try:
+                if closer is not None:
+                    await closer.close()
+            except Exception:
+                pass
+        if self._pw is not None:
+            try:
+                await self._pw.stop()
+            except Exception:
+                pass
+        self._pw = self._browser = self._context = self._page = None
+        self.clear_logs()
+        return "Browser closed."
+
+
+manager = BrowserManager()

fagun/install.py

@@ -0,0 +1,81 @@
+"""`fagun install` — print copy-paste MCP config for each AI tool.
+
+We only PRINT config (and offer to write Claude/Cursor JSON) so the user never
+has to hand-edit blind. Every tool that speaks MCP can run Fagun with:
+
+    command: uvx   args: ["fagun"]
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+SERVER_BLOCK = {"command": "uvx", "args": ["fagun"]}
+
+CLAUDE = json.dumps({"mcpServers": {"fagun": SERVER_BLOCK}}, indent=2)
+CURSOR = json.dumps({"mcpServers": {"fagun": SERVER_BLOCK}}, indent=2)
+VSCODE = json.dumps({"servers": {"fagun": {"type": "stdio", **SERVER_BLOCK}}}, indent=2)
+CODEX = '[mcp_servers.fagun]\ncommand = "uvx"\nargs = ["fagun"]'
+
+HELP = f"""🦊 Fagun install — add this MCP server to your AI tool, then say "fagun".
+
+Prereqs (once):
+  pip install uv           # gives you uvx
+  uvx --from fagun python -m playwright install chromium   # browser engine
+
+────────────────────────────────────────────────────────────────────
+Claude Code        →  run:  claude mcp add fagun -- uvx fagun
+Claude Desktop     →  ~/Library/Application Support/Claude/claude_desktop_config.json
+Cursor             →  ~/.cursor/mcp.json   (or .cursor/mcp.json in project)
+Windsurf / Cline / Antigravity  →  their MCP settings, same JSON as Cursor
+{CURSOR}
+
+VS Code (Copilot MCP) →  .vscode/mcp.json
+{VSCODE}
+
+Codex CLI          →  ~/.codex/config.toml
+{CODEX}
+────────────────────────────────────────────────────────────────────
+After adding: restart the tool, then type  fagun  to start.
+"""
+
+
+def _write_json_server(path: Path, key: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = {}
+    if path.exists():
+        try:
+            data = json.loads(path.read_text() or "{}")
+        except json.JSONDecodeError:
+            print(f"⚠️  {path} exists but is not valid JSON — skipped, add manually.")
+            return
+    data.setdefault(key, {})
+    if key == "servers":
+        data[key]["fagun"] = {"type": "stdio", **SERVER_BLOCK}
+    else:
+        data[key]["fagun"] = SERVER_BLOCK
+    path.write_text(json.dumps(data, indent=2))
+    print(f"✅ wrote fagun to {path}")
+
+
+def run_cli(argv: list[str]) -> None:
+    if not argv or argv[0] in {"help", "--help", "-h"}:
+        print(HELP)
+        return
+
+    # `fagun install cursor` / `install claude` writes the file for you.
+    target = argv[1] if len(argv) > 1 else ""
+    home = Path.home()
+    if target == "cursor":
+        _write_json_server(home / ".cursor" / "mcp.json", "mcpServers")
+    elif target == "claude":
+        _write_json_server(
+            home / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",
+            "mcpServers",
+        )
+    elif target == "vscode":
+        _write_json_server(Path.cwd() / ".vscode" / "mcp.json", "servers")
+    else:
+        print(HELP)

fagun/qa.py

@@ -0,0 +1,285 @@
+"""QA engine — crawl a site and run an automated bug/quality sweep.
+
+Findings are plain dicts so they serialize cleanly back to the AI tool and into
+the report writer.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+from urllib.parse import urldefrag, urljoin, urlparse
+
+from .browser import manager
+
+
+def _same_site(a: str, b: str) -> bool:
+    return urlparse(a).netloc == urlparse(b).netloc
+
+
+async def crawl(start_url: str, max_pages: int = 20) -> dict[str, Any]:
+    """Breadth-first crawl within the same host. Returns discovered pages."""
+    page = await manager.page()
+    seen: set[str] = set()
+    queue: list[str] = [urldefrag(start_url)[0]]
+    pages: list[dict[str, Any]] = []
+
+    while queue and len(pages) < max_pages:
+        url = queue.pop(0)
+        if url in seen:
+            continue
+        seen.add(url)
+        try:
+            resp = await page.goto(url, wait_until="domcontentloaded", timeout=20000)
+            status = resp.status if resp else None
+            title = await page.title()
+        except Exception as e:
+            pages.append({"url": url, "status": None, "error": str(e)})
+            continue
+
+        hrefs = await page.eval_on_selector_all(
+            "a[href]", "els => els.map(e => e.getAttribute('href'))"
+        )
+        links = []
+        for h in hrefs:
+            if not h or h.startswith(("mailto:", "tel:", "javascript:", "#")):
+                continue
+            absolute = urldefrag(urljoin(url, h))[0]
+            links.append(absolute)
+            if _same_site(start_url, absolute) and absolute not in seen:
+                queue.append(absolute)
+
+        pages.append(
+            {"url": url, "status": status, "title": title, "links_found": len(links)}
+        )
+
+    return {"start": start_url, "crawled": len(pages), "pages": pages}
+
+
+async def run_qa(url: str) -> dict[str, Any]:
+    """Load one page and collect findings across several quality dimensions."""
+    page = await manager.page()
+    manager.clear_logs()
+    findings: list[dict[str, Any]] = []
+
+    t0 = time.perf_counter()
+    resp = None
+    last_err: Exception | None = None
+    for attempt in range(2):
+        try:
+            resp = await page.goto(url, wait_until="load", timeout=30000)
+            last_err = None
+            break
+        except Exception as e:
+            last_err = e  # e.g. "interrupted by another navigation" — settle and retry
+            try:
+                await page.wait_for_load_state("load", timeout=5000)
+            except Exception:
+                pass
+    if last_err is not None:
+        return {
+            "url": url,
+            "ok": False,
+            "findings": [{"severity": "high", "type": "load-failure", "detail": str(last_err)}],
+        }
+    load_ms = round((time.perf_counter() - t0) * 1000)
+
+    status = resp.status if resp else None
+    if status and status >= 400:
+        findings.append(
+            {"severity": "high", "type": "http-error", "detail": f"Page returned {status}"}
+        )
+
+    # Console errors / warnings.
+    for c in manager.console:
+        if c.type in ("error", "warning"):
+            findings.append(
+                {
+                    "severity": "high" if c.type == "error" else "low",
+                    "type": f"console-{c.type}",
+                    "detail": c.text[:300],
+                    "at": c.location,
+                }
+            )
+
+    # Failed / erroring network requests.
+    for n in manager.network:
+        if n.failure:
+            findings.append(
+                {"severity": "high", "type": "request-failed", "detail": f"{n.method} {n.url} — {n.failure}"}
+            )
+        elif n.status and n.status >= 400:
+            findings.append(
+                {"severity": "medium", "type": "bad-response", "detail": f"{n.status} {n.method} {n.url}"}
+            )
+
+    # Basic accessibility heuristics.
+    imgs_no_alt = await page.eval_on_selector_all(
+        "img:not([alt])", "els => els.length"
+    )
+    if imgs_no_alt:
+        findings.append(
+            {"severity": "low", "type": "a11y-img-alt", "detail": f"{imgs_no_alt} <img> without alt"}
+        )
+    inputs_no_label = await page.evaluate(
+        """() => {
+            const inputs = [...document.querySelectorAll('input,select,textarea')];
+            return inputs.filter(el => {
+                if (el.type === 'hidden' || el.type === 'submit' || el.type === 'button') return false;
+                if (el.getAttribute('aria-label') || el.getAttribute('aria-labelledby')) return false;
+                if (el.id && document.querySelector(`label[for="${el.id}"]`)) return false;
+                return !el.closest('label');
+            }).length;
+        }"""
+    )
+    if inputs_no_label:
+        findings.append(
+            {"severity": "low", "type": "a11y-input-label", "detail": f"{inputs_no_label} form fields without a label"}
+        )
+    if not await page.query_selector("title, h1"):
+        findings.append({"severity": "low", "type": "seo", "detail": "No <title> or <h1>"})
+
+    # Performance signal.
+    if load_ms > 4000:
+        findings.append(
+            {"severity": "medium", "type": "perf", "detail": f"Load took {load_ms} ms (>4s)"}
+        )
+
+    # Dedup identical findings (a retried load can double-fire console/network).
+    seen: set[tuple[str, str]] = set()
+    unique: list[dict[str, Any]] = []
+    for f in findings:
+        key = (f.get("type", ""), f.get("detail", ""))
+        if key not in seen:
+            seen.add(key)
+            unique.append(f)
+
+    return {
+        "url": url,
+        "ok": True,
+        "status": status,
+        "load_ms": load_ms,
+        "console_count": len(manager.console),
+        "network_count": len(manager.network),
+        "findings": unique,
+    }
+
+
+# --- security headers ------------------------------------------------------
+_SEC_HEADERS = {
+    "content-security-policy": ("high", "Missing CSP — XSS/injection risk"),
+    "strict-transport-security": ("medium", "Missing HSTS — downgrade/MITM risk"),
+    "x-frame-options": ("medium", "Missing X-Frame-Options — clickjacking risk"),
+    "x-content-type-options": ("low", "Missing X-Content-Type-Options: nosniff"),
+    "referrer-policy": ("low", "Missing Referrer-Policy"),
+    "permissions-policy": ("low", "Missing Permissions-Policy"),
+}
+
+
+async def security_headers(url: str) -> dict[str, Any]:
+    """Fetch a URL and check for missing/weak security response headers."""
+    page = await manager.page()
+    findings: list[dict[str, Any]] = []
+    if not url.lower().startswith("http"):
+        return {"url": url, "skipped": "security headers only apply to http(s)", "findings": []}
+    resp = await page.request.get(url, timeout=20000)
+    headers = {k.lower(): v for k, v in resp.headers.items()}
+
+    for h, (sev, msg) in _SEC_HEADERS.items():
+        if h not in headers:
+            findings.append({"severity": sev, "type": "sec-header", "detail": msg})
+
+    server = headers.get("server", "")
+    if server and any(c.isdigit() for c in server):
+        findings.append(
+            {"severity": "low", "type": "info-leak", "detail": f"Server header leaks version: {server}"}
+        )
+    if "x-powered-by" in headers:
+        findings.append(
+            {"severity": "low", "type": "info-leak", "detail": f"X-Powered-By leaks stack: {headers['x-powered-by']}"}
+        )
+    return {"url": url, "status": resp.status, "headers_present": sorted(headers), "findings": findings}
+
+
+# --- broken link checker ---------------------------------------------------
+async def check_links(url: str, max_links: int = 100) -> dict[str, Any]:
+    """Collect links on a page and probe each; report broken ones (4xx/5xx/fail)."""
+    page = await manager.page()
+    await page.goto(url, wait_until="domcontentloaded", timeout=20000)
+    hrefs = await page.eval_on_selector_all(
+        "a[href]", "els => [...new Set(els.map(e => e.href))]"
+    )
+    hrefs = [h for h in hrefs if h.startswith("http")][:max_links]
+    findings: list[dict[str, Any]] = []
+    checked = 0
+    for h in hrefs:
+        try:
+            r = await page.request.head(h, timeout=15000)
+            st = r.status
+            if st == 405:  # HEAD not allowed -> retry GET
+                r = await page.request.get(h, timeout=15000)
+                st = r.status
+            checked += 1
+            if st >= 400:
+                findings.append(
+                    {"severity": "medium", "type": "broken-link", "detail": f"{st} → {h}"}
+                )
+        except Exception as e:
+            findings.append({"severity": "medium", "type": "broken-link", "detail": f"unreachable → {h} ({e})"})
+    return {"url": url, "links_checked": checked, "findings": findings}
+
+
+# --- form auditor ----------------------------------------------------------
+async def test_forms(url: str) -> dict[str, Any]:
+    """Static + DOM audit of every form on a page. Non-destructive (no submit)."""
+    page = await manager.page()
+    await page.goto(url, wait_until="load", timeout=20000)
+    forms = await page.evaluate(
+        """() => [...document.forms].map(f => ({
+            action: f.getAttribute('action') || location.href,
+            method: (f.getAttribute('method') || 'get').toLowerCase(),
+            fields: [...f.elements].filter(e => e.name || e.id).map(e => ({
+                name: e.name || e.id, type: e.type,
+                required: e.required, hasLabel: !!(e.labels && e.labels.length) ||
+                    !!e.getAttribute('aria-label'),
+                autocomplete: e.getAttribute('autocomplete') || ''
+            }))
+        }))"""
+    )
+    findings: list[dict[str, Any]] = []
+    for i, f in enumerate(forms):
+        tag = f"form#{i} ({f['method'].upper()} {f['action']})"
+        if f["method"] == "get" and any(
+            fld["type"] == "password" for fld in f["fields"]
+        ):
+            findings.append({"severity": "high", "type": "form-security", "detail": f"{tag} submits a password over GET"})
+        if str(f["action"]).startswith("http://"):
+            findings.append({"severity": "high", "type": "form-security", "detail": f"{tag} posts to insecure http://"})
+        for fld in f["fields"]:
+            if not fld["hasLabel"] and fld["type"] not in ("hidden", "submit", "button"):
+                findings.append({"severity": "low", "type": "form-a11y", "detail": f"{tag} field {fld['name']!r} has no label"})
+            if fld["type"] == "password" and fld["autocomplete"] not in ("new-password", "current-password"):
+                findings.append({"severity": "low", "type": "form-hint", "detail": f"{tag} password field missing autocomplete hint"})
+            if not fld["required"] and fld["type"] in ("email", "password", "tel"):
+                findings.append({"severity": "low", "type": "form-validation", "detail": f"{tag} {fld['type']} field {fld['name']!r} not marked required"})
+    return {"url": url, "forms": len(forms), "findings": findings}
+
+
+async def deep_test(url: str, max_pages: int = 8) -> dict[str, Any]:
+    """Everything: crawl → per-page QA + forms + security headers, aggregated."""
+    crawl_result = await crawl(url, max_pages)
+    results: list[dict[str, Any]] = []
+    for p in crawl_result["pages"]:
+        if p.get("error") or (p.get("status") and p["status"] >= 400):
+            continue
+        page_url = p["url"]
+        merged = await run_qa(page_url)
+        for check in (test_forms, security_headers):
+            try:
+                merged["findings"].extend((await check(page_url)).get("findings", []))
+            except Exception as e:
+                merged["findings"].append(
+                    {"severity": "low", "type": "check-error", "detail": f"{check.__name__} failed: {e}"}
+                )
+        results.append(merged)
+    return {"start": url, "pages_tested": len(results), "results": results}

fagun/report.py

@@ -0,0 +1,55 @@
+"""Turn QA results into a Markdown report."""
+
+from __future__ import annotations
+
+from typing import Any
+
+_SEV_ORDER = {"high": 0, "medium": 1, "low": 2}
+_SEV_ICON = {"high": "🔴", "medium": "🟠", "low": "🟡"}
+
+
+def build_markdown(results: list[dict[str, Any]], title: str = "Fagun QA Report") -> str:
+    lines = [f"# {title}", ""]
+    all_findings: list[tuple[str, dict[str, Any]]] = []
+    for r in results:
+        for f in r.get("findings", []):
+            all_findings.append((r.get("url", "?"), f))
+
+    counts = {"high": 0, "medium": 0, "low": 0}
+    for _, f in all_findings:
+        counts[f.get("severity", "low")] = counts.get(f.get("severity", "low"), 0) + 1
+
+    lines += [
+        "## Summary",
+        "",
+        f"- Pages checked: **{len(results)}**",
+        f"- Findings: **{len(all_findings)}** "
+        f"({_SEV_ICON['high']} {counts['high']} high · "
+        f"{_SEV_ICON['medium']} {counts['medium']} medium · "
+        f"{_SEV_ICON['low']} {counts['low']} low)",
+        "",
+    ]
+
+    for r in results:
+        lines.append(f"## {r.get('url', '?')}")
+        meta = []
+        if r.get("status") is not None:
+            meta.append(f"status {r['status']}")
+        if r.get("load_ms") is not None:
+            meta.append(f"{r['load_ms']} ms")
+        if meta:
+            lines.append(f"_{' · '.join(meta)}_")
+        lines.append("")
+        fs = sorted(
+            r.get("findings", []), key=lambda f: _SEV_ORDER.get(f.get("severity", "low"), 3)
+        )
+        if not fs:
+            lines.append("✅ No findings.")
+        else:
+            for f in fs:
+                icon = _SEV_ICON.get(f.get("severity", "low"), "•")
+                extra = f" _(at {f['at']})_" if f.get("at") else ""
+                lines.append(f"- {icon} **{f.get('type')}**: {f.get('detail')}{extra}")
+        lines.append("")
+
+    return "\n".join(lines)

fagun/server.py

@@ -0,0 +1,238 @@
+"""Fagun MCP server.
+
+Exposes browser-driving + QA tools over MCP so ANY MCP-capable AI tool
+(Claude Code/Desktop, Cursor, Codex, Antigravity, Windsurf, Cline, VS Code)
+can use them. The `fagun` prompt is the entry point users invoke.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from . import __version__
+from .browser import manager
+from .qa import check_links as _check_links
+from .qa import crawl as _crawl
+from .qa import deep_test as _deep_test
+from .qa import run_qa as _run_qa
+from .qa import security_headers as _security_headers
+from .qa import test_forms as _test_forms
+from .report import build_markdown
+
+mcp = FastMCP("fagun")
+
+MENU = f"""🦊 **Fagun v{__version__}** — browser + QA agent, ready.
+
+I can drive a real browser and run a full quality sweep. Ask me to:
+
+**Browse & debug**
+- `open the browser` / `go to <url>`
+- `click <text>` · `type <text> into <field>` · `press Enter`
+- `screenshot` · `show console errors` · `show network requests`
+- `run this JS: <code>`
+
+**QA & bug hunting**
+- `crawl <url>` — map the site
+- `run QA on <url>` — console errors, failed requests, a11y, perf, SEO
+- `check links on <url>` — find broken links
+- `test forms on <url>` — form security / validation / a11y
+- `security headers of <url>` — CSP, HSTS, X-Frame, info leaks
+- `deep test <url>` — crawl + QA + forms + headers, full report
+- `write the report to <path>`
+
+Tell me a URL to start. Example: *"deep test https://example.com and write the report to ./report.md."*
+"""
+
+
+@mcp.prompt(title="Start Fagun")
+def fagun() -> str:
+    """Entry point. Invoke this to start Fagun and see what it can do."""
+    return MENU
+
+
+@mcp.tool()
+def fagun_start() -> str:
+    """Start Fagun and list its capabilities. Call this when the user says 'fagun'."""
+    return MENU
+
+
+# ---------------------------------------------------------------- browser tools
+@mcp.tool()
+async def open_browser(headless: bool = True) -> str:
+    """Launch (or attach to) the browser."""
+    return await manager.start(headless=headless)
+
+
+@mcp.tool()
+async def navigate(url: str) -> str:
+    """Go to a URL."""
+    page = await manager.page()
+    resp = await page.goto(url, wait_until="load", timeout=30000)
+    return f"Loaded {page.url} (status {resp.status if resp else '?'}) — title: {await page.title()!r}"
+
+
+@mcp.tool()
+async def click(target: str) -> str:
+    """Click an element by CSS selector or visible text."""
+    page = await manager.page()
+    try:
+        await page.click(target, timeout=8000)
+    except Exception:
+        await page.get_by_text(target, exact=False).first.click(timeout=8000)
+    return f"Clicked {target!r}. Now at {page.url}"
+
+
+@mcp.tool()
+async def fill(selector: str, value: str) -> str:
+    """Type text into a form field (CSS selector or label/placeholder text)."""
+    page = await manager.page()
+    try:
+        await page.fill(selector, value, timeout=8000)
+    except Exception:
+        await page.get_by_label(selector).fill(value, timeout=8000)
+    return f"Filled {selector!r}."
+
+
+@mcp.tool()
+async def press_key(key: str) -> str:
+    """Press a keyboard key, e.g. 'Enter', 'Tab', 'Escape'."""
+    page = await manager.page()
+    await page.keyboard.press(key)
+    return f"Pressed {key}."
+
+
+@mcp.tool()
+async def screenshot(full_page: bool = False) -> str:
+    """Take a screenshot; saves a PNG and returns its path."""
+    page = await manager.page()
+    path = os.path.join(tempfile.gettempdir(), f"fagun-{abs(hash(page.url)) % 10**6}.png")
+    await page.screenshot(path=path, full_page=full_page)
+    return f"Screenshot saved: {path}"
+
+
+@mcp.tool()
+async def evaluate_js(code: str) -> str:
+    """Run JavaScript in the page and return the result as JSON."""
+    page = await manager.page()
+    result = await page.evaluate(code)
+    try:
+        return json.dumps(result, default=str)[:5000]
+    except Exception:
+        return str(result)[:5000]
+
+
+@mcp.tool()
+async def get_console(only_errors: bool = False) -> str:
+    """Return captured console messages."""
+    entries = manager.console
+    if only_errors:
+        entries = [c for c in entries if c.type == "error"]
+    if not entries:
+        return "No console messages captured."
+    return "\n".join(f"[{c.type}] {c.text} ({c.location})" for c in entries[-100:])
+
+
+@mcp.tool()
+async def get_network(only_problems: bool = False) -> str:
+    """Return captured network requests. only_problems -> failures / 4xx / 5xx."""
+    entries = manager.network
+    if only_problems:
+        entries = [n for n in entries if n.failure or (n.status and n.status >= 400)]
+    if not entries:
+        return "No network activity matched."
+    out = []
+    for n in entries[-150:]:
+        state = n.failure or n.status
+        out.append(f"{n.method} {state} [{n.resource_type}] {n.url}")
+    return "\n".join(out)
+
+
+@mcp.tool()
+async def close_browser() -> str:
+    """Close the browser and free resources."""
+    return await manager.stop()
+
+
+# --------------------------------------------------------------------- qa tools
+@mcp.tool()
+async def crawl(url: str, max_pages: int = 20) -> str:
+    """Crawl a site within the same host, up to max_pages. Returns JSON."""
+    return json.dumps(await _crawl(url, max_pages), indent=2)
+
+
+@mcp.tool()
+async def run_qa(url: str) -> str:
+    """Run the QA sweep on a single page (console, network, a11y, perf, SEO)."""
+    return json.dumps(await _run_qa(url), indent=2)
+
+
+@mcp.tool()
+async def full_qa_sweep(url: str, max_pages: int = 10, report_path: Optional[str] = None) -> str:
+    """Crawl a site, run QA on each page, and (optionally) write a Markdown report."""
+    crawl_result = await _crawl(url, max_pages)
+    results = []
+    for p in crawl_result["pages"]:
+        if p.get("status") and p["status"] < 400 and not p.get("error"):
+            results.append(await _run_qa(p["url"]))
+    md = build_markdown(results, title=f"Fagun QA Report — {url}")
+    if report_path:
+        with open(report_path, "w", encoding="utf-8") as fh:
+            fh.write(md)
+        return f"Swept {len(results)} pages. Report written to {report_path}\n\n{md[:1500]}"
+    return md
+
+
+@mcp.tool()
+async def security_headers(url: str) -> str:
+    """Check a page for missing/weak security headers (CSP, HSTS, X-Frame, etc.)."""
+    return json.dumps(await _security_headers(url), indent=2)
+
+
+@mcp.tool()
+async def check_links(url: str, max_links: int = 100) -> str:
+    """Find broken links (4xx/5xx/unreachable) among the links on a page."""
+    return json.dumps(await _check_links(url, max_links), indent=2)
+
+
+@mcp.tool()
+async def test_forms(url: str) -> str:
+    """Audit every form on a page for security, validation and a11y issues (no submit)."""
+    return json.dumps(await _test_forms(url), indent=2)
+
+
+@mcp.tool()
+async def deep_test(url: str, max_pages: int = 8, report_path: Optional[str] = None) -> str:
+    """Full audit: crawl + QA + forms + security headers across the site, one report."""
+    result = await _deep_test(url, max_pages)
+    md = build_markdown(result["results"], title=f"Fagun Deep Test — {url}")
+    if report_path:
+        with open(report_path, "w", encoding="utf-8") as fh:
+            fh.write(md)
+        return f"Deep-tested {result['pages_tested']} pages. Report → {report_path}\n\n{md[:1800]}"
+    return md
+
+
+@mcp.tool()
+async def write_report(results_json: str, path: str, title: str = "Fagun QA Report") -> str:
+    """Write a Markdown report from a JSON list of run_qa results."""
+    results = json.loads(results_json)
+    if isinstance(results, dict):
+        results = [results]
+    md = build_markdown(results, title=title)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(md)
+    return f"Report written to {path}"
+
+
+def serve() -> None:
+    """Run the MCP server over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    serve()

fagun-0.2.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: fagun
+Version: 0.2.0
+Summary: Fagun — one MCP server that lets any AI tool (Claude, Cursor, Codex, Antigravity, Windsurf) drive a browser, hunt bugs, and run a full QA sweep.
+Project-URL: Homepage, https://github.com/fagun-dev/fagun
+Author-email: Mejbaur Bahar Fagun <mejbaur@markopolo.ai>
+License: MIT
+License-File: LICENSE
+Keywords: ai,browser,claude,codex,cursor,mcp,playwright,qa,testing
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: playwright>=1.44.0
+Description-Content-Type: text/markdown
+
+# 🦊 Fagun
+
+**One MCP server. Every AI tool. Type `fagun` and it drives a browser + runs full QA.**
+
+Fagun is an [MCP](https://modelcontextprotocol.io) server that lets any AI coding
+tool — **Claude Code / Desktop, Cursor, Codex, Antigravity, Windsurf, Cline, VS Code** —
+control a real browser, debug it (console, network, DOM, screenshots, JS eval), and
+run an automated quality sweep (broken requests, console errors, accessibility,
+performance, SEO) with a Markdown report.
+
+You set it up once. Then inside any of those tools you just say **`fagun`** (or `/fagun`) and it starts.
+
+---
+
+## One-line setup (paste into your AI tool)
+
+Tell your AI agent (Claude, Cursor, Codex, Antigravity, …) exactly this:
+
+> Install or upgrade **fagun** to the latest stable version with `uv` using Python
+> 3.12, register the skill from `fagun skill`, and connect it to my browser. Follow
+> https://github.com/mejbaurbahar/fagun/blob/main/install.md if setup or connection fails.
+
+The agent follows [`install.md`](install.md) and wires everything up. Then just type
+**`/fagun`** and describe what to test.
+
+---
+
+## Setup (once, ~2 min)
+
+**1. Install the runner + browser engine**
+
+```bash
+pip install uv
+uvx --from fagun python -m playwright install chromium
+```
+
+`uvx` runs Fagun without a permanent install and always uses the latest version.
+
+**2. Add Fagun to your AI tool**
+
+Print ready-to-paste config for every tool:
+
+```bash
+uvx fagun install
+```
+
+Or let Fagun write the file for you:
+
+```bash
+uvx fagun install cursor     # writes ~/.cursor/mcp.json
+uvx fagun install claude     # writes Claude Desktop config
+uvx fagun install vscode     # writes .vscode/mcp.json
+```
+
+Manual config is identical everywhere — command `uvx`, args `["fagun"]`:
+
+| Tool | Where |
+|------|-------|
+| **Claude Code** | `claude mcp add fagun -- uvx fagun` |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| **Cursor** | `~/.cursor/mcp.json` |
+| **Windsurf / Cline / Antigravity** | their MCP settings (same JSON as Cursor) |
+| **VS Code (Copilot)** | `.vscode/mcp.json` |
+| **Codex CLI** | `~/.codex/config.toml` |
+
+```jsonc
+// Claude Desktop / Cursor / Windsurf / Cline / Antigravity
+{ "mcpServers": { "fagun": { "command": "uvx", "args": ["fagun"] } } }
+```
+
+```toml
+# Codex ~/.codex/config.toml
+[mcp_servers.fagun]
+command = "uvx"
+args = ["fagun"]
+```
+
+**3. Restart the tool. Say `fagun`.**
+
+---
+
+## Use it
+
+Inside any tool, just talk:
+
+- *"fagun"* → shows the menu and starts up
+- *"go to example.com and screenshot it"*
+- *"run QA on https://example.com"*
+- *"full QA sweep of https://example.com, write the report to ./qa.md"*
+- *"show me the console errors"* · *"any failed network requests?"*
+- *"click Sign in, type me@x.com into email, press Enter"*
+
+- *"deep test https://example.com and write the report to ./report.md"* — the full sweep
+
+## The `/fagun` skill — autonomous bug hunter
+
+`skills/fagun/SKILL.md` is a full QA methodology the AI follows: it hunts **real,
+reproducible** bugs across 10 scenario classes — functional, JS/runtime errors,
+network/API, form validation, auth/session/authorization, accessibility,
+performance, visual/responsive, security posture, and edge cases — with an
+evidence-or-it-didn't-happen rule and impact-based severity. Register it (see
+`install.md` Step 5) to get the `/fagun` slash command.
+
+## What it exposes (MCP tools)
+
+`fagun_start` · `open_browser` · `navigate` · `click` · `fill` · `press_key` ·
+`screenshot` · `evaluate_js` · `get_console` · `get_network` · `crawl` · `run_qa` ·
+`check_links` · `test_forms` · `security_headers` · `deep_test` · `full_qa_sweep` ·
+`write_report` · `close_browser`
+
+Plus a **`fagun` prompt** — appears as a slash command in tools that surface MCP prompts.
+
+## Options (env vars)
+
+| Var | Default | Meaning |
+|-----|---------|---------|
+| `FAGUN_HEADLESS` | `1` | `0` shows the browser window |
+| `FAGUN_BROWSER` | `chromium` | `chromium` \| `firefox` \| `webkit` |
+| `FAGUN_CDP_URL` | — | Attach to a running Chrome, e.g. `http://127.0.0.1:9222` |
+
+## Local dev
+
+```bash
+git clone <repo> && cd fagun
+pip install -e .
+python -m playwright install chromium
+python -m fagun        # starts the MCP server on stdio
+```
+
+## Releasing to PyPI (maintainer)
+
+Auto-publish is wired via GitHub Actions using **PyPI Trusted Publishing** (OIDC —
+no API token stored). One-time setup on [pypi.org](https://pypi.org/manage/account/publishing/):
+
+- Project: `fagun` · Owner: `mejbaurbahar` · Repo: `fagun`
+- Workflow: `publish.yml` · Environment: `pypi`
+
+Then every release is just a tag:
+
+```bash
+# bump version in pyproject.toml + src/fagun/__init__.py first
+git tag v0.2.0 && git push origin v0.2.0
+```
+
+The `Publish to PyPI` workflow builds, checks, and uploads automatically. Build
+locally to verify anytime: `python -m build && twine check dist/*`.
+
+MIT © Mejbaur Bahar Fagun

fagun-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+fagun/__init__.py,sha256=KRibwFKmcW2hhBUg53-j0JQXo06SZiMCnuKJfSATTmw,75
+fagun/__main__.py,sha256=_EEe7-N8GQGS1-lmru2kAxsReB8Om5QAkhIEG84QDsU,783
+fagun/browser.py,sha256=9s3kuRYQiaOIbSckdtRrN7dNaePLmHHxbq9auADusCQ,4345
+fagun/install.py,sha256=uKWJOStiY0nOzx0fZ4QcFBbTno8FjSzLd1TPLo2fkKA,3134
+fagun/qa.py,sha256=P06_UAtGZcP4H0LvQ-jediaDq5YJhcRGHVQeKSrg5ck,11889
+fagun/report.py,sha256=EHPfcUAC-4iQC56HAGzVK0YmoQAWMG1Xal2WQlAAA7A,1882
+fagun/server.py,sha256=heRyAavapuRwaABFmjosGx23NP5PpbtunHZNibux9-U,7946
+fagun-0.2.0.dist-info/METADATA,sha256=cPEkvyCWvhPVPdjkcTnUF5IyioR5We-Rrc6AZ3MuWBg,5471
+fagun-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+fagun-0.2.0.dist-info/entry_points.txt,sha256=lZbZrR6m6teanwWcsPZEJVkyPv4XDf-Lh5jDDvhypuo,46
+fagun-0.2.0.dist-info/licenses/LICENSE,sha256=_LmB-jVUi9jVftzdcpoccXXHGXX-drSazWxjveIuH_U,1076
+fagun-0.2.0.dist-info/RECORD,,

fagun-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

fagun-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fagun = fagun.__main__:main

fagun-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mejbaur Bahar Fagun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.