@debugg-ai/debugg-ai-mcp 6.1.5 → 6.1.6

package/README.md

@@ -47,6 +47,10 @@ cause), then that your dev server answers a plain `curl http://127.0.0.1:<port>/
 Verified 2026-11-10: servers bound to `127.0.0.1` only (IPv4 Caddy gateways on :4040 and :4043) probe fine via
 `http://localhost:<port>` and `http://127.0.0.1:<port>`.
 
+### Local Chrome capture (opt-in)
+
+`probe_page` accepts `browser: "local"` to capture with Chrome on your own machine: no tunnel, no cloud browser, nothing uploaded (screenshots also saved under `~/.debugg-ai/captures`, mode 0600). The server owner must set `DEBUGGAI_LOCAL_BROWSER=1`; Chrome is found automatically or via `DEBUGGAI_CHROME_PATH`; `playwright-core` is an optional dependency. `useProfile: true` uses an MCP-owned persistent profile (`~/.debugg-ai/chrome-profile`, never your everyday Chrome profile): sign in once with `headless: false, loginWindowMs: 120000`, later local probes are logged in. Profile sessions require `allowedDomains` (or the owner's `DEBUGGAI_PROFILE_ALLOWED_DOMAINS`, which overrides it); top-level navigations off the list, redirect hops included, are blocked.
+
 Get an API key at [debugg.ai](https://debugg.ai), then add to your MCP client config:
 
 ```json

package/dist/handlers/localProbeHandler.js

@@ -0,0 +1,46 @@
+/**
+ * probe_page with browser:'local' (bead jpw3.1/.2): capture each target with the
+ * user's own Chrome on this machine. No backend call, no tunnel.
+ */
+import { localCapture, LocalBrowserError } from '../services/localBrowser.js';
+import { imageContentBlock } from '../utils/imageUtils.js';
+import { logger } from '../utils/logger.js';
+export async function localProbe(input, context) {
+    const results = [];
+    const images = [];
+    for (const t of input.targets) {
+        try {
+            const r = await localCapture({
+                url: t.url,
+                headless: input.headless,
+                useProfile: input.useProfile,
+                loginWindowMs: input.loginWindowMs,
+                allowedDomains: input.allowedDomains,
+                waitForSelector: t.waitForSelector,
+                waitForLoadState: t.waitForLoadState,
+                timeoutMs: t.timeoutMs,
+                includeHtml: input.includeHtml,
+                captureScreenshot: input.captureScreenshots,
+                signal: context.signal,
+            });
+            const { screenshotBase64, ...rest } = r;
+            results.push(rest);
+            if (screenshotBase64)
+                images.push(imageContentBlock(screenshotBase64, 'image/png'));
+        }
+        catch (err) {
+            if (err instanceof LocalBrowserError && (err.code === 'LOCAL_BROWSER_DISABLED' || err.code === 'PLAYWRIGHT_MISSING' || err.code === 'PROFILE_ALLOWLIST_REQUIRED')) {
+                return { content: [{ type: 'text', text: JSON.stringify({ error: err.code, message: err.message }, null, 2) }], isError: true };
+            }
+            const message = err instanceof Error ? err.message.split('\n')[0] : String(err);
+            logger.warn(`probe_page local: ${t.url} failed: ${message}`);
+            results.push({ url: t.url, error: message, ...(err instanceof LocalBrowserError ? { errorCode: err.code } : {}) });
+        }
+    }
+    return {
+        content: [
+            { type: 'text', text: JSON.stringify({ browser: 'local', results }, null, 2) },
+            ...images,
+        ],
+    };
+}

package/dist/handlers/probePageHandler.js

@@ -25,6 +25,7 @@ import { buildContext, findExistingTunnel, ensureTunnel, acquirePortRoute, relea
 import { randomUUID } from 'node:crypto';
 import { getCachedTemplateUuid, invalidateTemplateCache } from '../utils/handlerCaches.js';
 import { getPageProbeTemplateSlug } from '../services/workflows.js';
+import { localProbe } from './localProbeHandler.js';
 import { reaggregateByOriginPath, mapConsoleSlice } from '../utils/harSummarizer.js';
 import { fetchImageAsBase64, imageContentBlock } from '../utils/imageUtils.js';
 const logger = new Logger({ module: 'probePageHandler' });
@@ -76,6 +77,9 @@ export async function probePageHandler(input, context, rawProgressCallback) {
             }
         }
         : undefined;
+    if (input.browser === 'local') {
+        return localProbe(input, context);
+    }
     const client = new DebuggAIServerClient(config.api.key);
     await client.init();
     // Bead 56kd.7: cancellation is driven by the MCP request/transport lifecycle

package/dist/services/localBrowser.js

@@ -0,0 +1,266 @@
+/**
+ * Local Chrome capture for probe_page (bead jpw3.1 / jpw3.2).
+ *
+ * Launches the user's installed Chrome through playwright-core on THIS machine
+ * and captures a page directly — no tunnel, no cloud browser, nothing uploaded.
+ * Everything stays local: screenshots are returned inline and also written under
+ * ~/.debugg-ai/captures (0600).
+ *
+ * Opt-in at the server: DEBUGGAI_LOCAL_BROWSER=1. With `useProfile`, the browser
+ * uses an MCP-owned persistent profile (~/.debugg-ai/chrome-profile, override with
+ * DEBUGGAI_CHROME_PROFILE_DIR) the user logs into once via `loginToLocalProfile`;
+ * the user's everyday Chrome profile is never touched.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export class LocalBrowserError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'LocalBrowserError';
+    }
+}
+/** Host matches an allowed domain exactly or as a subdomain. */
+export function hostAllowed(host, allowed) {
+    const h = host.toLowerCase();
+    return allowed.some((d) => {
+        const a = d.trim().toLowerCase().replace(/^\*?\./, '');
+        return a !== '' && (h === a || h.endsWith(`.${a}`));
+    });
+}
+/**
+ * Allowlist for a profile session (bead jpw3.3). The server owner's
+ * DEBUGGAI_PROFILE_ALLOWED_DOMAINS (comma list) is authoritative when set;
+ * otherwise the call must name allowedDomains. Never empty for a profile run.
+ */
+export function resolveAllowedDomains(perCall, env = process.env) {
+    const owner = (env.DEBUGGAI_PROFILE_ALLOWED_DOMAINS ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    return owner.length > 0 ? owner : (perCall ?? []).filter(Boolean);
+}
+export function localBrowserEnabled(env = process.env) {
+    return env.DEBUGGAI_LOCAL_BROWSER === '1' || env.DEBUGGAI_LOCAL_BROWSER === 'true';
+}
+export function debuggHome(env = process.env) {
+    return env.DEBUGGAI_HOME || path.join(os.homedir(), '.debugg-ai');
+}
+export function profileDir(env = process.env) {
+    return env.DEBUGGAI_CHROME_PROFILE_DIR || path.join(debuggHome(env), 'chrome-profile');
+}
+/** Well-known Chrome locations; DEBUGGAI_CHROME_PATH wins. undefined => let playwright try channel 'chrome'. */
+export function findChrome(env = process.env) {
+    if (env.DEBUGGAI_CHROME_PATH)
+        return env.DEBUGGAI_CHROME_PATH;
+    const candidates = process.platform === 'darwin'
+        ? ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium']
+        : process.platform === 'win32'
+            ? [
+                `${env.PROGRAMFILES ?? 'C:\\Program Files'}\\Google\\Chrome\\Application\\chrome.exe`,
+                `${env['PROGRAMFILES(X86)'] ?? 'C:\\Program Files (x86)'}\\Google\\Chrome\\Application\\chrome.exe`,
+            ]
+            : ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser'];
+    return candidates.find((p) => fs.existsSync(p));
+}
+async function loadPlaywright() {
+    try {
+        return await import('playwright-core');
+    }
+    catch {
+        throw new LocalBrowserError('Local browser mode needs the optional dependency playwright-core, which is not installed. Run `npm i playwright-core` next to the MCP.', 'PLAYWRIGHT_MISSING');
+    }
+}
+function safeHost(u) {
+    try {
+        return new URL(u).hostname;
+    }
+    catch {
+        return u;
+    }
+}
+function ensurePrivateDir(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+async function launch(opts) {
+    const pw = await loadPlaywright();
+    const executablePath = findChrome();
+    const base = { headless: opts.headless, ...(executablePath ? { executablePath } : { channel: 'chrome' }) };
+    try {
+        if (opts.useProfile) {
+            const dir = profileDir();
+            ensurePrivateDir(dir);
+            const context = await pw.chromium.launchPersistentContext(dir, { ...base, viewport: { width: 1280, height: 800 } });
+            return { context, close: () => context.close() };
+        }
+        const browser = await pw.chromium.launch(base);
+        const context = await browser.newContext({ viewport: { width: 1280, height: 800 } });
+        return { context, close: () => browser.close() };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/ProcessSingleton|SingletonLock|profile.*in use|already running/i.test(msg)) {
+            throw new LocalBrowserError(`The MCP's Chrome profile (${profileDir()}) is already open in another Chrome window. Close it and retry.`, 'PROFILE_LOCKED');
+        }
+        if (/Executable doesn't exist|Failed to launch|chrome.*not found|distribution/i.test(msg)) {
+            throw new LocalBrowserError(`Could not start Chrome (${executablePath ?? "channel 'chrome'"}). Install Google Chrome or set DEBUGGAI_CHROME_PATH. Detail: ${msg.split('\n')[0]}`, 'CHROME_NOT_FOUND');
+        }
+        throw err;
+    }
+}
+/** Aggregate responses by origin+path (query stripped), capped. */
+function summarize(entries) {
+    const map = new Map();
+    for (const e of entries) {
+        let key = e.url;
+        try {
+            const u = new URL(e.url);
+            key = u.origin + u.pathname;
+        }
+        catch { /* keep raw */ }
+        const row = map.get(key) ?? { url: key, count: 0, statuses: {}, totalBytes: 0 };
+        row.count++;
+        row.statuses[String(e.status)] = (row.statuses[String(e.status)] ?? 0) + 1;
+        row.totalBytes += e.bytes;
+        map.set(key, row);
+    }
+    return [...map.values()].sort((a, b) => b.count - a.count).slice(0, 50);
+}
+export async function localCapture(o) {
+    if (!localBrowserEnabled()) {
+        throw new LocalBrowserError('Local browser mode is off. Set DEBUGGAI_LOCAL_BROWSER=1 in the MCP server environment to allow it.', 'LOCAL_BROWSER_DISABLED');
+    }
+    const allowed = o.useProfile ? resolveAllowedDomains(o.allowedDomains) : [];
+    if (o.useProfile && allowed.length === 0) {
+        throw new LocalBrowserError('A profile session needs an allowlist of domains it may visit: pass allowedDomains (e.g. ["example.com"]) or have the server owner set DEBUGGAI_PROFILE_ALLOWED_DOMAINS.', 'PROFILE_ALLOWLIST_REQUIRED');
+    }
+    const timeout = Math.min(Math.max(o.timeoutMs ?? 10000, 1000), 30000);
+    const { context, close } = await launch({ headless: o.headless !== false, useProfile: !!o.useProfile });
+    const onAbort = () => { void close().catch(() => { }); };
+    o.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        const page = context.pages()[0] ?? await context.newPage();
+        if (o.useProfile) {
+            const isLocal = (h) => ['localhost', '127.0.0.1', '[::1]', '::1'].includes(h);
+            const startHost = (() => { try {
+                return new URL(o.url).hostname;
+            }
+            catch {
+                return '';
+            } })();
+            if (!hostAllowed(startHost, allowed) && !isLocal(startHost)) {
+                throw new LocalBrowserError(`${startHost || o.url} is not in the allowlist for this profile session.`, 'DOMAIN_NOT_ALLOWED');
+            }
+            // Block top-level DOCUMENT loads off the allowlist, redirect hops included, via
+            // CDP Fetch (Playwright's route() never sees server-side redirect hops, so it
+            // cannot enforce this). Sub-resources (CDNs) pass.
+            const guard = async (pg) => {
+                const cdp = await context.newCDPSession(pg);
+                const mainFrameId = (await cdp.send('Page.getFrameTree')).frameTree.frame.id;
+                await cdp.send('Fetch.enable', { patterns: [
+                        { urlPattern: '*', resourceType: 'Document', requestStage: 'Request' },
+                        { urlPattern: '*', resourceType: 'Document', requestStage: 'Response' },
+                    ] });
+                cdp.on('Fetch.requestPaused', (ev) => {
+                    void (async () => {
+                        const check = (u) => {
+                            try {
+                                const h = new URL(u).hostname;
+                                return hostAllowed(h, allowed) || isLocal(h);
+                            }
+                            catch {
+                                return false;
+                            }
+                        };
+                        try {
+                            if (ev.frameId !== mainFrameId) {
+                                await cdp.send(ev.responseStatusCode ? 'Fetch.continueResponse' : 'Fetch.continueRequest', { requestId: ev.requestId });
+                                return;
+                            }
+                            if (ev.responseStatusCode === undefined) {
+                                if (!check(ev.request.url)) {
+                                    blocked.push(safeHost(ev.request.url));
+                                    await cdp.send('Fetch.failRequest', { requestId: ev.requestId, errorReason: 'BlockedByClient' });
+                                    return;
+                                }
+                                await cdp.send('Fetch.continueRequest', { requestId: ev.requestId });
+                                return;
+                            }
+                            const loc = ev.responseHeaders?.find((h) => h.name.toLowerCase() === 'location')?.value;
+                            if (ev.responseStatusCode >= 300 && ev.responseStatusCode < 400 && loc) {
+                                const next = new URL(loc, ev.request.url).toString();
+                                if (!check(next)) {
+                                    blocked.push(safeHost(next));
+                                    await cdp.send('Fetch.failRequest', { requestId: ev.requestId, errorReason: 'BlockedByClient' });
+                                    return;
+                                }
+                            }
+                            await cdp.send('Fetch.continueResponse', { requestId: ev.requestId });
+                        }
+                        catch { /* page closed */ }
+                    })();
+                });
+            };
+            await guard(page);
+            context.on('page', (pg) => { void guard(pg).catch(() => { }); });
+        }
+        const blocked = [];
+        const consoleErrors = [];
+        const net = [];
+        page.on('console', (m) => { if (m.type() === 'error' || m.type() === 'warning')
+            consoleErrors.push({ level: m.type(), text: m.text() }); });
+        page.on('pageerror', (e) => consoleErrors.push({ level: 'error', text: e.message }));
+        page.on('response', (r) => {
+            const len = Number(r.headers()['content-length'] ?? 0);
+            net.push({ url: r.url(), status: r.status(), bytes: Number.isFinite(len) ? len : 0 });
+        });
+        const t0 = Date.now();
+        let resp;
+        try {
+            resp = await page.goto(o.url, { waitUntil: o.waitForLoadState === 'load' ? 'load' : 'domcontentloaded', timeout });
+        }
+        catch (err) {
+            if (blocked.length > 0) {
+                throw new LocalBrowserError(`Navigation to ${[...new Set(blocked)].join(', ')} was blocked: not in this profile session's allowlist.`, 'NAVIGATION_BLOCKED');
+            }
+            throw err;
+        }
+        if (o.waitForSelector)
+            await page.waitForSelector(o.waitForSelector, { timeout: Math.max(1000, timeout - (Date.now() - t0)) });
+        else
+            await page.waitForLoadState('networkidle', { timeout: Math.min(2000, Math.max(500, timeout - (Date.now() - t0))) }).catch(() => { });
+        const result = {
+            url: o.url,
+            finalUrl: page.url() || null,
+            statusCode: resp ? resp.status() : null,
+            title: (await page.title().catch(() => '')) || null,
+            loadTimeMs: Date.now() - t0,
+            consoleErrors,
+            networkSummary: summarize(net),
+        };
+        if (blocked.length > 0)
+            result.blockedNavigations = [...new Set(blocked)];
+        if (o.loginWindowMs && o.useProfile && o.headless === false) {
+            const ms = Math.min(o.loginWindowMs, 600000);
+            await new Promise((resolve) => {
+                const t = setTimeout(resolve, ms);
+                context.once('close', () => { clearTimeout(t); resolve(); });
+            });
+        }
+        if (o.includeHtml)
+            result.html = await page.content();
+        if (o.captureScreenshot !== false) {
+            const buf = await page.screenshot({ type: 'png' });
+            result.screenshotBase64 = buf.toString('base64');
+            const dir = path.join(debuggHome(), 'captures');
+            ensurePrivateDir(dir);
+            const file = path.join(dir, `probe-${Date.now()}-${Math.random().toString(16).slice(2, 8)}.png`);
+            fs.writeFileSync(file, buf, { mode: 0o600 });
+            result.screenshotPath = file;
+        }
+        return result;
+    }
+    finally {
+        o.signal?.removeEventListener('abort', onAbort);
+        await close().catch(() => { });
+    }
+}

package/dist/services/workflows.js

@@ -3,12 +3,22 @@
  * 4-step integration: find template → execute → poll → result
  */
 import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
+import { logger } from '../utils/logger.js';
 import { redactRunSecrets } from '../utils/redactRunSecrets.js';
 const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
 // Exponential backoff polling: short executions (10-15s crawls) detect terminal
 // status quickly via the early polls; long executions (60-150s browser runs)
 // avoid hammering the backend with 20+ roundtrips. Cap at 5s so we never wait
 // more than 5s past terminal-state achievement.
+const MAX_CONSECUTIVE_POLL_FAILURES = 5;
+/** Network-class (no response), 5xx, 408 and 429 are worth another poll; any other 4xx is a real answer. */
+function isTransientPollError(err) {
+    const e = err;
+    const status = e?.statusCode;
+    if (typeof status === 'number')
+        return status >= 500 || status === 408 || status === 429;
+    return true; // no status: network-class error (message-only), as axiosTransport shapes it
+}
 const POLL_INTERVAL_INITIAL_MS = 1000;
 const POLL_INTERVAL_MAX_MS = 5000;
 const POLL_BACKOFF_MULTIPLIER = 1.5;
@@ -128,11 +138,26 @@ export const createWorkflowsService = (tx) => {
             // partial results (screenshot + trace) instead of discarding them (bead
             // 56kd.3).
             let lastExecution;
+            let consecutivePollFailures = 0;
             while (Date.now() < deadline) {
                 if (signal?.aborted) {
                     throw new Error(`Polling cancelled for execution ${executionUuid}`);
                 }
-                const execution = await service.getExecution(executionUuid);
+                let execution;
+                try {
+                    execution = await service.getExecution(executionUuid);
+                    consecutivePollFailures = 0;
+                }
+                catch (err) {
+                    // Bead kruv: one blip (ECONNRESET, 5xx during a deploy, 30s client
+                    // timeout) must not lose a run the server is still executing. Only
+                    // transient failures are tolerated, and only a few in a row.
+                    if (!isTransientPollError(err) || ++consecutivePollFailures > MAX_CONSECUTIVE_POLL_FAILURES)
+                        throw err;
+                    logger.warn(`pollExecution: transient status-poll failure ${consecutivePollFailures}/${MAX_CONSECUTIVE_POLL_FAILURES} for ${executionUuid}: ${err instanceof Error ? err.message : err}`);
+                    await new Promise((r) => setTimeout(r, intervalMs));
+                    continue;
+                }
                 lastExecution = execution;
                 pollCount++;
                 if (onUpdate) {

package/dist/tools/probePage.js

@@ -81,6 +81,28 @@ export function buildProbePageTool() {
                     type: 'string',
                     description: "GitHub repository name (e.g. 'my-org/my-repo'). Auto-detected from the current git repo — only provide this to scope the probe to a different project context.",
                 },
+                browser: {
+                    type: 'string',
+                    enum: ['remote', 'local'],
+                    description: "Default 'remote' (cloud browser; localhost is tunneled). 'local' runs Chrome on THIS machine against the URL directly: no tunnel, nothing uploaded, screenshot also saved under ~/.debugg-ai/captures. Works only when the MCP server runs on your machine AND its owner set DEBUGGAI_LOCAL_BROWSER=1. waitForSelector/waitForLoadState/timeoutMs apply; the local mode returns screenshot, console errors, network summary, title and (optionally) HTML.",
+                },
+                headless: {
+                    type: 'boolean',
+                    description: "browser:'local' only. Default true. false opens a visible Chrome window.",
+                },
+                useProfile: {
+                    type: 'boolean',
+                    description: "browser:'local' only. Default false (fresh throwaway profile). true uses the MCP-owned persistent profile (~/.debugg-ai/chrome-profile, never your everyday Chrome profile), so pages you signed into there are captured logged-in. Sign in once with headless:false plus loginWindowMs. Captures from it never leave the machine.",
+                },
+                allowedDomains: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: "browser:'local', useProfile:true only. REQUIRED for a profile session unless the server owner set DEBUGGAI_PROFILE_ALLOWED_DOMAINS (which then overrides this). Hostnames (subdomains included) the logged-in session may navigate to; any other top-level navigation, redirects included, is blocked and reported in blockedNavigations. localhost is always allowed.",
+                },
+                loginWindowMs: {
+                    type: 'number',
+                    description: "browser:'local', useProfile:true, headless:false only. Keep the window open up to this long (1000-600000 ms) or until you close it, so you can sign in to the site once.",
+                },
             },
             required: ['targets'],
             additionalProperties: false,

package/dist/types/index.js

@@ -274,6 +274,16 @@ export const ProbePageInputSchema = z.object({
     includeHtml: z.boolean().default(false),
     captureScreenshots: z.boolean().default(true),
     repoName: z.string().optional(),
+    // Local Chrome capture (beads jpw3.1/.2). 'remote' (default) is the cloud browser.
+    browser: z.enum(['remote', 'local']).default('remote'),
+    // local only: false opens a visible window.
+    headless: z.boolean().default(true),
+    // local only: use the MCP-owned persistent profile (log in once) instead of a throwaway one.
+    useProfile: z.boolean().default(false),
+    // local + useProfile + headless:false only: keep the window open this long so the user can sign in once.
+    loginWindowMs: z.number().int().min(1000).max(600000).optional(),
+    // local + useProfile: domains (and subdomains) the session may navigate to. Required unless the server owner set DEBUGGAI_PROFILE_ALLOWED_DOMAINS.
+    allowedDomains: z.array(z.string().min(1)).max(50).optional(),
 }).strict();
 // ── E2E Suite Management ──────────────────────────────────────────────────────
 const projectIdentifier = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "6.1.5",
+  "version": "6.1.6",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "caddy": "2.11.3",
@@ -83,5 +83,8 @@
     "ts-jest": "^29.4.1",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.58.2"
+  },
+  "optionalDependencies": {
+    "playwright-core": "^1.65.0"
   }
 }