release: 0.6.5 humanlike captcha recovery

Author: HarimxChoi

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.6.5]
+
+### Changed
+- CAPTCHA recovery seeds the original query instead of `hello world`.
+- Recovery forces humanlike inline mode: random per-char typing, Tab+Enter variability, then 1-3 result visits with dwell, scroll, goBack.
+- Removed `SURF_CAPTCHA_GRACE_MS`. `SURF_CAPTCHA_TIMEOUT_MS` default 240s to 180s.
+
 ## [0.6.4]
 
 ### Fixed

manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "google-surf-mcp",
   "display_name": "Google Surf",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Free Google search MCP that actually works — no API key, no proxies, no solvers. Search + extraction in one MCP.",
   "long_description": "Free Google search MCP that actually works — no API key, no proxies, no solvers (most free Google search MCPs fail in practice; this one drives a warm Chrome profile via Playwright + stealth). Search + page extraction in one MCP: `search_extract` returns SERP results already enriched with article bodies — replaces the usual search-MCP + fetch-MCP combo. CAPTCHA opens a visible Chrome window for a human to solve (shared-IP reputation protection); `SURF_CLOUD_MODE=true` for headless/serverless fail-fast.",
   "author": {
@@ -36,7 +36,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "google-surf-mcp@0.6.4"
+        "google-surf-mcp@0.6.5"
       ],
       "env": {
         "CHROME_PATH": "${user_config.chrome_path}",

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "google-surf-mcp",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "mcpName": "io.github.HarimxChoi/google-surf-mcp",
   "description": "MCP server for Google search via warm Chrome profile. No API key.",
   "type": "module",

package.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/HarimxChoi/google-surf-mcp",
     "source": "github"
   },
-  "version": "0.6.4",
+  "version": "0.6.5",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "google-surf-mcp",
-      "version": "0.6.4",
+      "version": "0.6.5",
       "transport": {
         "type": "stdio"
       },

server.json

@@ -41,7 +41,7 @@ export interface Deps {
   acquirePool: (mode: StealthMode) => Promise<PoolHandle>;
   closeSeq: () => Promise<void>;
   resetPool: () => Promise<void>;
-  recoverHuman: () => Promise<void>;
+  recoverHuman: (seedQuery?: string) => Promise<void>;
   getPoolHealth: () => PoolHealthSnapshot;
 }
 
@@ -60,18 +60,19 @@ export function initDeps(env: NodeJS.ProcessEnv = process.env): Pick<Deps, 'conf
   return { config, cache, cascade, limiter, tel, healing };
 }
 
-function tier3Recovery(deps: Deps): () => Promise<void> {
+function tier3Recovery(deps: Deps, seedQuery?: string): () => Promise<void> {
   return async () => {
     if (deps.config.cloudMode) {
       throw new CaptchaError('cloud-mode: tier-3 unavailable');
     }
-    await deps.recoverHuman();
+    await deps.recoverHuman(seedQuery);
   };
 }
 
 async function executeSeqWithCascade<T>(
   deps: Deps,
   op: (ctx: BrowserContext) => Promise<T>,
+  seedQuery?: string,
 ): Promise<T> {
   if (deps.config.cascadeDisabled) {
     const ctx = await deps.acquireSeqCtx(deps.config.useStealth ? 'on' : 'off');
@@ -84,7 +85,7 @@ async function executeSeqWithCascade<T>(
       return await op(ctx);
     },
     resetContext: async () => { await deps.closeSeq(); },
-    tier3Recovery: tier3Recovery(deps),
+    tier3Recovery: tier3Recovery(deps, seedQuery),
     isCaptchaError: (e) => e instanceof CaptchaError,
     onTransition: (from, to, reason) => {
       console.error(`[cascade] ${from} → ${to}: ${reason}`);
@@ -95,6 +96,7 @@ async function executeSeqWithCascade<T>(
 async function executePoolWithCascade<T>(
   deps: Deps,
   op: (pool: PoolHandle) => Promise<T>,
+  seedQuery?: string,
 ): Promise<T> {
   if (deps.config.cascadeDisabled) {
     const initialMode = deps.config.useStealth ? 'on' : 'off';
@@ -113,7 +115,7 @@ async function executePoolWithCascade<T>(
         deps.closeSeq().catch(() => {}),
       ]);
     },
-    tier3Recovery: tier3Recovery(deps),
+    tier3Recovery: tier3Recovery(deps, seedQuery),
     isCaptchaError: (e) => e instanceof CaptchaError,
     onTransition: (from, to, reason) => {
       console.error(`[cascade pool] ${from} → ${to}: ${reason}`);
@@ -161,7 +163,7 @@ export async function searchTool(
         await behavior.simulateBrowsing(page, []).catch(() => {});
       }
       return r;
-    });
+    }, query);
 
     const meta = {
       strategy: 'legacy-v0.4',
@@ -216,7 +218,7 @@ export async function searchParallelTool(
     for (let i = 0; i < queries.length; i++) await deps.limiter.acquire();
     const results = await executePoolWithCascade(deps, async (pool) => {
       return await pool.runMany(queries, limit, { locale: deps.config.locale, healing: deps.healing });
-    });
+    }, queries[0]);
 
     const elapsed = Date.now() - t0;
     for (const r of results) {

src/agent.ts

@@ -4,8 +4,11 @@ import { launch, getPage, PROFILE_MAIN, isBlocked } from './browser.js';
 import { CaptchaError } from './search.js';
 import type { CaptchaMode } from './captchaMode.js';
 import { osNotify } from './notify.js';
+import { HumanlikeBehavior, generateBehaviorParams } from './humanlike.js';
 
 const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
+const rand = (a: number, b: number) => a + Math.random() * (b - a);
+const randInt = (a: number, b: number) => a + Math.floor(Math.random() * (b - a + 1));
 
 const NOTIFY_TITLE = 'google-surf-mcp: CAPTCHA';
 const NOTIFY_BODY = 'Google CAPTCHA detected. A browser window will open — solve it to resume.';
@@ -30,7 +33,7 @@ function remoteDebugGuidance(): string {
 export interface RecoverOptions {
   mode?: CaptchaMode;
   timeoutMs?: number;
-  graceMs?: number;
+  seedQuery?: string;
 }
 
 let recoveryInFlight: Promise<void> | null = null;
@@ -44,8 +47,8 @@ function parseMs(v: string | undefined, fallback: number): number {
 export async function recoverFromCaptcha(opts: RecoverOptions | number = {}): Promise<void> {
   const o: RecoverOptions = typeof opts === 'number' ? { timeoutMs: opts } : opts;
   const mode: CaptchaMode = o.mode ?? 'notify_spawn';
-  const timeoutMs = o.timeoutMs ?? parseMs(process.env.SURF_CAPTCHA_TIMEOUT_MS, 240_000);
-  const graceMs = o.graceMs ?? parseMs(process.env.SURF_CAPTCHA_GRACE_MS, 120_000);
+  const timeoutMs = o.timeoutMs ?? parseMs(process.env.SURF_CAPTCHA_TIMEOUT_MS, 180_000);
+  const seedQuery = (o.seedQuery ?? '').trim() || 'hello world';
 
   if (mode === 'cloud_fail_fast') {
     throw new CaptchaError('cloud-mode: tier-3 unavailable');
@@ -63,41 +66,42 @@ export async function recoverFromCaptcha(opts: RecoverOptions | number = {}): Pr
       await osNotify(NOTIFY_TITLE, NOTIFY_BODY).catch(() => {});
     }
     const ctx = await launch({ profileDir: PROFILE_MAIN, headless: false, blockResources: false });
+    const behavior = new HumanlikeBehavior(generateBehaviorParams(), 'inline');
     try {
       const page = await getPage(ctx);
       await page.goto('https://www.google.com/', { waitUntil: 'domcontentloaded', timeout: 30_000 }).catch(() => {});
       try { await (page as { bringToFront?: () => Promise<void> }).bringToFront?.(); } catch {}
-      // headed often isn't served /sorry/ even when headless was; auto-search to land on /search?
+      // headed often isn't served /sorry/ even when headless was; seed the real query to reach /search?
       if (!isBlocked(page.url())) {
         try {
-          await sleep(800);
+          await sleep(rand(600, 1400));
           const sb = page.locator('textarea[name="q"], input[name="q"]').first();
           await sb.click();
-          await sleep(200);
-          await page.keyboard.type('hello world', { delay: 60 });
-          await sleep(300);
-          await page.keyboard.press('Enter');
+          await sleep(rand(150, 450));
+          await behavior.typeQuery(page, seedQuery);
+          await behavior.submitQuery(page);
         } catch {}
       }
       const start = Date.now();
-      let landedAt: number | null = null;
+      let browsed = false;
       while (Date.now() - start < timeoutMs) {
         const u = page.url();
         if (isBlocked(u)) {
-          landedAt = null;
+          browsed = false;
           await sleep(1500);
           continue;
         }
         if (u.includes('/search?')) {
-          if (landedAt === null) {
-            landedAt = Date.now();
-            console.error(`[google-surf-mcp] captcha cleared; keeping window open ${Math.round(graceMs / 1000)}s for any follow-up CAPTCHA (override via SURF_CAPTCHA_GRACE_MS)`);
+          if (!browsed) {
+            browsed = true;
+            console.error('[google-surf-mcp] captcha cleared; running humanlike browse before close');
+            await behavior.visitRandomResults(page, randInt(1, 3)).catch(() => {});
+            continue;
           }
-          if (Date.now() - landedAt >= graceMs) return;
+          return;
         }
         await sleep(1500);
       }
-      if (landedAt !== null) return;
       throw new Error(`captcha not solved within ${Math.round(timeoutMs / 1000)}s`);
     } finally {
       await ctx.close().catch(() => {});

src/captchaRecover.ts

@@ -66,6 +66,73 @@ export class HumanlikeBehavior {
     }
   }
 
+  async submitQuery(page: Page): Promise<void> {
+    await sleep(rand(300, 1200));
+    if (Math.random() < 0.6) {
+      const tabCount = randInt(1, 3);
+      for (let i = 0; i < tabCount; i++) {
+        await page.keyboard.press('Tab');
+        await sleep(rand(150, 420));
+      }
+    }
+    await page.keyboard.press('Enter');
+  }
+
+  async visitRandomResults(page: Page, n: number): Promise<void> {
+    if (n <= 0) return;
+    try {
+      await page.waitForSelector('a[href^="http"] h3', { timeout: 10_000 });
+    } catch { return; }
+
+    await sleep(rand(800, 2000));
+
+    for (let i = 0; i < n; i++) {
+      const links = page.locator('a[href^="http"]:has(h3)');
+      const count = await links.count().catch(() => 0);
+      if (count === 0) break;
+
+      // top-results bias: squared random concentrates idx near 0
+      const cap = Math.min(9, count - 1);
+      const idx = Math.floor(Math.random() ** 2 * (cap + 1));
+
+      const link = links.nth(idx);
+      try { await link.scrollIntoViewIfNeeded({ timeout: 3000 }); } catch {}
+      await sleep(rand(400, 1200));
+      try { await link.hover({ timeout: 3000 }); } catch {}
+      await sleep(rand(300, 900));
+
+      try {
+        await Promise.all([
+          page.waitForLoadState('domcontentloaded', { timeout: 12_000 }).catch(() => {}),
+          link.click({ timeout: 5000 }),
+        ]);
+      } catch { continue; }
+
+      await this.readPage(page);
+
+      await sleep(rand(400, 1200));
+      try { await page.goBack({ timeout: 10_000, waitUntil: 'domcontentloaded' }); } catch {}
+      await sleep(rand(800, 2200));
+    }
+  }
+
+  private async readPage(page: Page): Promise<void> {
+    const dwellMs = randInt(4_000, 12_000);
+    const end = Date.now() + dwellMs;
+    await sleep(rand(500, 1500));
+    while (Date.now() < end) {
+      const r = Math.random();
+      if (r < 0.7) {
+        await page.mouse.wheel(0, randInt(120, 520)).catch(() => {});
+      } else if (r < 0.9) {
+        await page.mouse.wheel(0, -randInt(80, 240)).catch(() => {});
+      } else {
+        await page.mouse.move(rand(100, 900), rand(100, 600)).catch(() => {});
+      }
+      await sleep(rand(700, 2400));
+    }
+  }
+
   async waitAfterSearch(): Promise<void> {
     if (this.mode === 'off') {
       await sleep(rand(50, 110));

src/humanlike.ts

@@ -334,7 +334,7 @@ function buildDeps(): Deps {
     headless: baseDeps.config.headless,
     remoteDebug: baseDeps.config.remoteDebug,
   });
-  const recoverHuman = async () => {
+  const recoverHuman = async (seedQuery?: string) => {
     // remote_debug: keep Chromium alive across DevTools attach window
     if (captchaMode === 'remote_debug') {
       suspendIdleClose();
@@ -344,7 +344,7 @@ function buildDeps(): Deps {
         closeSequential().catch(() => {}),
       ]);
     }
-    await recoverFromCaptcha({ mode: captchaMode });
+    await recoverFromCaptcha({ mode: captchaMode, seedQuery });
   };
 
   return {

src/index.ts

@@ -56,14 +56,14 @@ describe('recoverFromCaptcha modes', () => {
   it('notify_spawn invokes osNotify', async () => {
     const notify = await import('../src/notify.js');
     const { recoverFromCaptcha } = await import('../src/captchaRecover.js');
-    await recoverFromCaptcha({ mode: 'notify_spawn', timeoutMs: 5_000, graceMs: 0 });
+    await recoverFromCaptcha({ mode: 'notify_spawn', timeoutMs: 5_000 });
     expect(notify.osNotify).toHaveBeenCalledOnce();
   });
 
   it('always_headed skips notification but still recovers', async () => {
     const notify = await import('../src/notify.js');
     const { recoverFromCaptcha } = await import('../src/captchaRecover.js');
-    await recoverFromCaptcha({ mode: 'always_headed', timeoutMs: 5_000, graceMs: 0 });
+    await recoverFromCaptcha({ mode: 'always_headed', timeoutMs: 5_000 });
     expect(notify.osNotify).not.toHaveBeenCalled();
   });
 });