mcp-camoufox 0.5.1 → 0.5.3

package/README.md

@@ -11,7 +11,7 @@
 
 </div>
 
-The most feature-rich stealth browser MCP server. **79 tools** for full browser control powered by [Camoufox](https://github.com/daijro/camoufox) — a Firefox fork with C++ level anti-detection that bypasses Cloudflare, bot detection, and anti-automation.
+The most feature-rich stealth browser MCP server. **80 tools** for full browser control powered by [Camoufox](https://github.com/daijro/camoufox) — a Firefox fork with C++ level anti-detection that bypasses Cloudflare, bot detection, and anti-automation.
 
 > **One command. No Python. No manual setup. Everything auto-installs.**
 
@@ -39,7 +39,35 @@ claude mcp add camoufox -- npx -y mcp-camoufox@latest
 | redf0x1/camofox-mcp | 45 | Yes | No (clone) | Yes |
 | Sekinal/camoufox-mcp | 49 | Yes | No (clone) | Yes |
 | Playwright CLI | 60+ | No | Yes | Yes |
-| **[mcp-camoufox](https://github.com/RobithYusuf/mcp-camoufox)** | **79** | **Yes** | **Yes** | **Yes** |
+| **[mcp-camoufox](https://github.com/RobithYusuf/mcp-camoufox)** | **80** | **Yes** | **Yes** | **Yes** |
+
+## Proven on Real Sites
+
+| Site | Challenge | Result |
+|------|-----------|--------|
+| `2captcha.com/demo/cloudflare-turnstile` | Cloudflare Turnstile widget | ✅ **"Success!"** via `click_turnstile()` tool ([proof](docs/images/turnstile.jpg)) |
+| `bot.sannysoft.com` | Firefox fingerprint tests | ✅ All green ([proof](docs/images/sannysoft.jpg)) |
+| `browserscan.net/bot-detection` | WebDriver/UA/CDP/Navigator | ✅ All categories "Normal" ([proof](docs/images/browserscan.jpg)) |
+
+### 🎯 Cloudflare Turnstile → Success via `click_turnstile()`
+
+<img src="docs/images/turnstile.jpg" alt="Cloudflare Turnstile success" width="500">
+
+`click_turnstile()` auto-detects the widget via 6 selector fallback (`iframe[src*=challenges.cloudflare.com]`, `[data-sitekey]`, `.cf-turnstile`, …), computes checkbox position (offset_x=30 from widget left), and clicks with a 3-step Bezier-like approach — combined with Camoufox's native `humanize` + `disable_coop` for cross-origin iframe click.
+
+**Scope:** works on **Interactive Turnstile** (visible iframe widget). **Managed Challenge** interstitials ("Just a moment...") render the widget in shadow DOM — not supported here; use sister project [mcp-stealth-chrome](https://github.com/RobithYusuf/mcp-stealth-chrome) (Chrome+CDP) for those. Real-world bypass success also depends on IP reputation and browser fingerprint — code alone doesn't guarantee it.
+
+### 🧪 bot.sannysoft.com → Firefox Fingerprint Pass
+
+<img src="docs/images/sannysoft.jpg" alt="sannysoft Firefox pass" width="500">
+
+User Agent reports `Firefox/135.0`, WebDriver missing, WebDriver Advanced passed, Permissions prompt, Plugins length 5 passed, Languages `en-US,en`, WebGL Intel HD Graphics — all green. ("Chrome: missing" is expected — Camoufox spoofs Firefox, not Chrome.)
+
+### 🔍 browserscan.net/bot-detection → All Categories Normal
+
+<img src="docs/images/browserscan.jpg" alt="browserscan normal" width="500">
+
+WebDriver, User-Agent, CDP, Navigator — every detection category returns **"Normal"**. Camoufox's C++-level Firefox patches leave zero automation signals.
 
 ## Setup
 
@@ -234,7 +262,7 @@ Or via UI: Agent Panel > `...` > MCP Servers > Manage MCP Servers > View raw con
 
 That's all. Camoufox browser binary (~80MB) downloads automatically on first launch.
 
-## All 79 Tools
+## All 80 Tools
 
 ### Browser Lifecycle (2)
 
@@ -283,12 +311,13 @@ That's all. Camoufox browser binary (~80MB) downloads automatically on first lau
 | `type_text` | Type char by char. Options: `delay`. For OTP, masked inputs, date pickers. |
 | `press_key` | Key or combo: `Enter`, `Escape`, `Tab`, `Control+a`, `Meta+c` |
 
-### Mouse XY (3)
+### Mouse XY (4)
 
 | Tool | Description |
 |------|-------------|
-| `mouse_click_xy` | Click at exact coordinates |
-| `mouse_move` | Move cursor to coordinates |
+| `mouse_click_xy` | Click at exact coordinates. Optional `steps` (0=instant, 15-30=human-like pre-movement) |
+| `mouse_move` | Move cursor to coordinates. Optional `steps` for interpolated path |
+| `click_turnstile` | Auto-find + humanized click on Cloudflare Turnstile widget. Params: `offset_x` (default 30), `offset_y`, `wait_render_ms`. Works on Interactive Turnstile (visible iframe widget). Not for Managed Challenge interstitials. |
 | `drag_and_drop` | Drag between two elements |
 
 ### Wait (4)

package/dist/index.js

@@ -113,6 +113,37 @@ const server = new McpServer({
     version: "0.2.0",
 });
 // ── Tools: Browser Lifecycle ───────────────────────────────────────────────
+async function ensureCamoufoxBinary() {
+    const { execSync } = await import("child_process");
+    const { existsSync } = await import("fs");
+    const { join: pathJoin } = await import("path");
+    const os = await import("os");
+    const homeDir = os.homedir();
+    const platform = os.platform();
+    let cacheDir;
+    if (platform === "darwin") {
+        cacheDir = pathJoin(homeDir, "Library", "Caches", "camoufox");
+    }
+    else if (platform === "win32") {
+        cacheDir = pathJoin(process.env.LOCALAPPDATA || pathJoin(homeDir, "AppData", "Local"), "camoufox");
+    }
+    else {
+        cacheDir = pathJoin(process.env.XDG_CACHE_HOME || pathJoin(homeDir, ".cache"), "camoufox");
+    }
+    const versionFile = pathJoin(cacheDir, "version.json");
+    if (existsSync(versionFile))
+        return;
+    console.error("\n" + "=".repeat(60));
+    console.error("[mcp-camoufox] First-time setup: downloading Camoufox (~500MB)");
+    console.error("[mcp-camoufox] Please wait 2-5 minutes...");
+    console.error("=".repeat(60) + "\n");
+    const cmd = platform === "win32" ? "npx.cmd" : "npx";
+    execSync(`${cmd} camoufox-js fetch`, {
+        stdio: "inherit", timeout: 900000,
+        env: { ...process.env, npm_config_yes: "true" },
+    });
+    console.error("\n[mcp-camoufox] Download complete.\n");
+}
 server.tool("browser_launch", "Launch Camoufox stealth browser and navigate to URL. Browser persists between calls. Call this first.", {
     url: z.string().default("about:blank").describe("URL to navigate to"),
     headless: z.boolean().default(true).describe("Run without visible window"),
@@ -133,57 +164,7 @@ server.tool("browser_launch", "Launch Camoufox stealth browser and navigate to U
     ensureDirs();
     const w = width > 0 ? width : 1280;
     const h = height > 0 ? height : 800;
-    // Auto-download Camoufox binary if not installed
-    // camoufox-js does NOT auto-download — we handle it here
-    await (async () => {
-        const { execSync } = await import("child_process");
-        const { existsSync, readdirSync } = await import("fs");
-        const { join: pathJoin } = await import("path");
-        const os = await import("os");
-        // Detect cache dir per platform (same logic as camoufox-js pkgman.ts)
-        const homeDir = os.homedir();
-        const platform = os.platform();
-        let cacheDir;
-        if (platform === "darwin") {
-            cacheDir = pathJoin(homeDir, "Library", "Caches", "camoufox");
-        }
-        else if (platform === "win32") {
-            cacheDir = pathJoin(process.env.LOCALAPPDATA || pathJoin(homeDir, "AppData", "Local"), "camoufox");
-        }
-        else {
-            cacheDir = pathJoin(process.env.XDG_CACHE_HOME || pathJoin(homeDir, ".cache"), "camoufox");
-        }
-        // Check if binary exists (look for version.json inside cache dir)
-        const versionFile = pathJoin(cacheDir, "version.json");
-        const isInstalled = existsSync(versionFile);
-        if (!isInstalled) {
-            console.error("");
-            console.error("=".repeat(60));
-            console.error("[mcp-camoufox] First-time setup: downloading Camoufox browser");
-            console.error("[mcp-camoufox] This is ~500MB and only happens once.");
-            console.error("[mcp-camoufox] Please wait 2-5 minutes...");
-            console.error("=".repeat(60));
-            console.error("");
-            try {
-                // Use npx to run camoufox-js CLI fetch command
-                const cmd = platform === "win32" ? "npx.cmd" : "npx";
-                execSync(`${cmd} camoufox-js fetch`, {
-                    stdio: "inherit",
-                    timeout: 900000, // 15 min max
-                    env: { ...process.env, npm_config_yes: "true" },
-                });
-                console.error("");
-                console.error("[mcp-camoufox] Download complete! Browser ready.");
-                console.error("");
-            }
-            catch (fetchErr) {
-                console.error(`[mcp-camoufox] Auto-download failed: ${fetchErr.message?.slice(0, 200)}`);
-                console.error("[mcp-camoufox] Try manually: npx camoufox-js fetch");
-                throw new Error("Camoufox browser binary not found. Auto-download failed. " +
-                    "Please run manually: npx camoufox-js fetch");
-            }
-        }
-    })();
+    await ensureCamoufoxBinary();
     const ctx = await Camoufox({
         headless,
         humanize,
@@ -823,21 +804,74 @@ server.tool("sessionstorage_set", "Set a sessionStorage item.", {
     return { content: [{ type: "text", text: `sessionStorage set: ${key}` }] };
 });
 // ── Tools: Mouse XY ────────────────────────────────────────────────────────
-server.tool("mouse_click_xy", "Click at exact x,y coordinates on the page.", {
+server.tool("mouse_click_xy", "Click at exact x,y coordinates. steps>0 adds interpolated pre-movement (human-like).", {
     x: z.number(), y: z.number(),
     button: z.enum(["left", "right", "middle"]).default("left"),
-}, async ({ x, y, button }) => {
+    steps: z.number().default(0).describe("Interpolation steps for pre-click movement (0=instant, 15-30=human-like)"),
+}, async ({ x, y, button, steps }) => {
     const page = getPage();
+    if (steps > 0) {
+        await page.mouse.move(x, y, { steps });
+        await page.waitForTimeout(80 + Math.random() * 60);
+    }
     await page.mouse.click(x, y, { button });
     await page.waitForTimeout(500);
-    return { content: [{ type: "text", text: `Clicked at (${x}, ${y}) button=${button}` }] };
+    return { content: [{ type: "text", text: `Clicked at (${x}, ${y}) button=${button} steps=${steps}` }] };
 });
-server.tool("mouse_move", "Move mouse to exact x,y coordinates.", {
+server.tool("mouse_move", "Move mouse to x,y. steps>0 interpolates path (human-like).", {
     x: z.number(), y: z.number(),
-}, async ({ x, y }) => {
-    const page = getPage();
-    await page.mouse.move(x, y);
-    return { content: [{ type: "text", text: `Mouse moved to (${x}, ${y})` }] };
+    steps: z.number().default(0).describe("Interpolation steps (0=instant jump, 15-30=smooth)"),
+}, async ({ x, y, steps }) => {
+    const page = getPage();
+    await page.mouse.move(x, y, steps > 0 ? { steps } : undefined);
+    return { content: [{ type: "text", text: `Mouse moved to (${x}, ${y}) steps=${steps}` }] };
+});
+server.tool("click_turnstile", "Auto-find and click Cloudflare Turnstile checkbox. Port of mcp-stealth-chrome's proven pattern — single pre-drift + direct click, leaning on Camoufox's built-in humanize + disable_coop for cross-origin iframe support. Works on Interactive Turnstile widgets (visible iframe). Managed Challenge interstitials not supported — use mcp-stealth-chrome for those.", {
+    offset_x: z.number().default(30).describe("Pixels from widget left edge (calibrated for CF checkbox)"),
+    offset_y: z.number().optional().describe("Vertical offset from widget top (default = height/2)"),
+    wait_render_ms: z.number().default(500).describe("Wait before detection to let widget render"),
+}, async ({ offset_x, offset_y, wait_render_ms }) => {
+    const page = getPage();
+    await page.waitForTimeout(wait_render_ms);
+    // Widget detection — 6 selectors ordered by specificity (port from mcp-stealth-chrome)
+    const coords = await page.evaluate(() => {
+        const sels = [
+            'iframe[src*="challenges.cloudflare.com"]',
+            'iframe[src*="turnstile"]',
+            '[data-testid*="challenge-widget"]',
+            '[data-testid*="turnstile"]',
+            '[data-sitekey]',
+            '.cf-turnstile',
+        ];
+        for (const sel of sels) {
+            const el = document.querySelector(sel);
+            if (!el)
+                continue;
+            const r = el.getBoundingClientRect();
+            if (r.width < 50 || r.height < 20)
+                continue;
+            return {
+                found: sel,
+                left: Math.round(r.left),
+                top: Math.round(r.top),
+                width: Math.round(r.width),
+                height: Math.round(r.height),
+            };
+        }
+        return null;
+    });
+    if (!coords) {
+        return { content: [{ type: "text", text: "Turnstile widget not found — selector miss. Likely a Managed Challenge interstitial (use mcp-stealth-chrome) or widget hasn't rendered yet (try wait_render_ms=3000)." }] };
+    }
+    const targetX = coords.left + offset_x;
+    const targetY = coords.top + (offset_y ?? Math.floor(coords.height / 2));
+    // Single pre-drift then direct click (matches stealth-chrome's pattern).
+    // Camoufox's humanize layer handles path curvature + timing automatically,
+    // so extra Bezier hops would be redundant and slow (~3s extra).
+    await page.mouse.move(targetX + 180, targetY - 80, { steps: 15 });
+    await page.waitForTimeout(150);
+    await page.mouse.click(targetX, targetY);
+    return { content: [{ type: "text", text: `clicked Turnstile at (${targetX},${targetY}) — widget found via ${coords.found} (${coords.width}x${coords.height})` }] };
 });
 server.tool("drag_and_drop", "Drag from one element to another.", {
     source_ref: z.string().describe("Ref of element to drag"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-camoufox",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "MCP server for stealth browser automation via Camoufox — 79 tools, Chrome DevTools MCP-level power with anti-bot stealth",
   "type": "module",
   "main": "dist/index.js",