@debugg-ai/debugg-ai-mcp 6.2.1 → 6.2.2

package/CHANGELOG.md

@@ -7,9 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [6.2.0] — 2026-11-13
+- Local browser runs are headless by default (check_app_in_browser, probe_page, profile path). `headless: false` is opt-in and now launches minimized and off-screen without taking focus.
 
-> Local click-through needs a backend with local executors enabled (platform flag `EXECUTORS_LOCAL_ENABLED`) and `DEBUGGAI_LOCAL_BROWSER=1` on the MCP server. Without both, nothing changes for existing calls.
+### Changed — local browser is the free default; cloud browsers are the paid option
+- `check_app_in_browser`: leave `browser` unset and it uses your own Chrome when one is installed (stdio server), else the cloud browser; `browser: "local"` or `"remote"` still force one. `DEBUGGAI_LOCAL_BROWSER` is gone: asking for `browser: "local"` is the consent, and the allowlist, sealed credentials and MCP-owned profile are unchanged. It is refused on the hosted HTTP server (no machine of yours). On a backend without local executors an unset `browser` falls back to the cloud browser.
+- A plan without cloud browsers gets a structured `PLAN_REQUIRED` error (HTTP 402) with the message, upgrade link, docs link and how to run in your own Chrome, shown as-is and never retried or silently switched. `probe_page` keeps `browser` defaulting to remote.
+
+## [6.2.1] — 2026-11-13
+
+> 6.2.0 was never published; this is its first release. Local click-through needs a backend with local executors enabled (platform flag `EXECUTORS_LOCAL_ENABLED`) and `DEBUGGAI_LOCAL_BROWSER=1` on the MCP server. Without both, nothing changes for existing calls.
 
 ### Added — check_app_in_browser on your local Chrome, cloud brain (`browser: "local"`) (epic m7un)
 - New `browser: "local"` (also `headless`, `useProfile`, `allowedDomains`) runs the check in Chrome on your machine while the cloud brain decides each step. The laptop dials out, so no tunnel is needed for localhost or private apps. Opt-in: set `DEBUGGAI_LOCAL_BROWSER=1` in the MCP server environment; stdio only (not the remote HTTP/OAuth server). The platform side is flag-gated, so it needs a backend that has local executors enabled.

package/README.md

@@ -23,6 +23,18 @@ clear error on the first localhost-URL call, not a silent hang. Public-URL calls
 non-browser tool, and `test_suite {action:"run"}` (which uses its own dedicated tunnel and
 bypasses Caddy entirely) don't need it either way.
 
+## Local Chrome click-through (`browser: "local"`) — free on every plan
+
+`check_app_in_browser` can run the check in Chrome on your own machine while the DebuggAI cloud brain decides each step (no tunnel needed, works for private and localhost apps):
+
+```
+check_app_in_browser  { "url": "http://localhost:4040", "description": "Sign in and add a task", "browser": "local", "username": "me@x.com", "password": "..." }
+```
+
+- **Free on every plan, and the default when Chrome is installed.** Leave `browser` unset and `check_app_in_browser` uses your own Chrome if it finds one (stdio server); otherwise it uses a cloud browser. Passing `browser: "local"` is all the consent it needs: there is no environment variable to set. Cloud browsers through the MCP (`browser: "remote"`) are included in Professional and above; a plan without them gets `PLAN_REQUIRED` (message, upgrade link, docs link, and how to use your own Chrome instead), never a silent switch. Server-run tests are unchanged.
+- Local runs need a backend with local executors enabled; an unset `browser` quietly uses the cloud browser on a backend without them, while `browser: "local"` says so. Not available on the hosted HTTP/OAuth MCP server (no machine of yours to open Chrome on).
+- Every navigation hop must be on the allowlist (the target host plus `allowedDomains`). Passwords you pass stay on your machine: the cloud sees `{{cred:label}}` and the MCP fills the real value locally. Screenshots go to the cloud by default; `DEBUGGAI_LOCAL_SCREENSHOTS=local_only` keeps them local. `useProfile` keeps persistent cookies between runs, not session cookies.
+
 ## Testing a local app (no Tailscale, no port exposure)
 
 Start your app on localhost, then pass the `http://localhost:<port>` URL straight to the tool. The MCP
@@ -49,7 +61,7 @@ Verified 2026-11-10: servers bound to `127.0.0.1` only (IPv4 Caddy gateways on :
 
 ### 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.
+`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). stdio server only; Chrome is found automatically or via `DEBUGGAI_CHROME_PATH`; `playwright-core` is an optional dependency. Local runs are headless by default and never open a visible window; `headless: false` is opt-in and launches minimized and off-screen without taking focus. `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:
 

package/dist/handlers/localExecutorBridge.js

@@ -7,7 +7,7 @@
  */
 import { config } from '../config/index.js';
 import { logger } from '../utils/logger.js';
-import { localBrowserEnabled, LocalBrowserError, resolveAllowedDomains } from '../services/localBrowser.js';
+import { localBrowserEnabled, LocalBrowserError, LOCAL_UNAVAILABLE_MESSAGE, findChrome, resolveAllowedDomains } from '../services/localBrowser.js';
 import { OpRunner } from '../services/localExecutor/opRunner.js';
 import { runExecutorSession } from '../services/localExecutor/session.js';
 import { HttpExecutorTransport } from '../services/localExecutor/httpTransport.js';
@@ -31,6 +31,53 @@ export function localizeCredentials(input) {
     }
     return { input: out, secrets };
 }
+/**
+ * Local runs are a paid feature. The backend answers a plan that does not include them with
+ * HTTP 402 (or a 403 whose code names the plan/entitlement) and a structured body; show its
+ * message, upgrade link and docs link as they are and never retry. Returns undefined for any
+ * other error.
+ */
+export function planRequiredFromError(err, mode = 'local') {
+    const e = err;
+    const status = e?.statusCode ?? e?.response?.status;
+    const raw = (e?.responseData ?? e?.response?.data);
+    const body = (raw && typeof raw.error === 'object' && raw.error ? raw.error : raw);
+    const pick = (...keys) => { for (const k of keys) {
+        const v = body?.[k];
+        if (typeof v === 'string' && v)
+            return v;
+    } return undefined; };
+    const code = pick('code', 'error_code', 'errorCode');
+    const planish = !!code && /plan|entitle|upgrade|subscription|not_included/i.test(code);
+    if (status !== 402 && !(status === 403 && planish))
+        return undefined;
+    const feature = pick('feature');
+    const message = pick('error', 'message', 'detail') ?? (mode === 'remote' ? 'Cloud browsers are not included in your plan.' : 'This run is not included in your plan.');
+    const upgradeUrl = pick('upgrade_url', 'upgradeUrl');
+    const docsUrl = pick('docs_url', 'docsUrl');
+    const required = body?.required_plans ?? body?.requiredPlans;
+    // A plan without cloud browsers can still run in the caller's own Chrome, for free. Say how; never fall back silently.
+    const alternative = mode === 'remote' ? 'Run it free in your own Chrome: install Chrome and call with browser: "local".' : undefined;
+    const hasHint = /browser:\s*["']?local/i.test(message);
+    const text = [message, alternative && !hasHint ? alternative : undefined, upgradeUrl ? `Upgrade: ${upgradeUrl}` : undefined, docsUrl ? `Docs: ${docsUrl}` : undefined].filter(Boolean).join(' ');
+    return new LocalBrowserError(text, 'PLAN_REQUIRED', { upgradeUrl, docsUrl, ...(feature ? { feature } : {}), ...(required ? { requiredPlans: required } : {}), ...(alternative ? { alternative } : {}) });
+}
+/**
+ * Which browser runs this call. An explicit `browser` always wins. Unset: your own Chrome when it is
+ * installed, the server is not the hosted one, or the call asks for something only local can do
+ * (useProfile); otherwise the cloud browser.
+ */
+export function chooseBrowser(input, env) {
+    if (input.browser === 'local')
+        return { mode: 'local', auto: false };
+    if (input.browser === 'remote')
+        return { mode: 'remote', auto: false };
+    if (input.useProfile)
+        return { mode: 'local', auto: false }; // a profile only exists on this machine
+    const hosted = env?.hosted ?? !localBrowserEnabled();
+    const chrome = env?.chrome ?? !!findChrome();
+    return hosted || !chrome ? { mode: 'remote', auto: false } : { mode: 'local', auto: true };
+}
 export function localAllowedDomains(input, startUrl) {
     const startHost = (() => { try {
         return new URL(startUrl).hostname;
@@ -51,7 +98,7 @@ export function localAllowedDomains(input, startUrl) {
 export async function prepareLocalRun(args) {
     const { client, input, startUrl, secrets, signal } = args;
     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');
+        throw new LocalBrowserError(LOCAL_UNAVAILABLE_MESSAGE, 'LOCAL_BROWSER_DISABLED');
     }
     const allowed = localAllowedDomains(input, startUrl);
     if (allowed.length === 0) {
@@ -83,7 +130,10 @@ export async function prepareLocalRun(args) {
     }
     catch (err) {
         (await runnerP.catch(() => null))?.close();
-        const status = err?.response?.status;
+        const planErr = planRequiredFromError(err);
+        if (planErr)
+            throw planErr;
+        const status = err?.response?.status ?? err?.statusCode;
         if (status === 404) {
             throw new LocalBrowserError('The DebuggAI backend does not offer local browser execution yet (executor API not enabled for this account).', 'LOCAL_EXECUTOR_UNAVAILABLE');
         }

package/dist/handlers/probePageHandler.js

@@ -291,6 +291,7 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                 const firstTargetUrl = targetContexts[group.indices[0]]?.targetUrl ?? groupTargets[0].url;
                 const contextData = {
                     targetUrl: firstTargetUrl,
+                    browserChoice: 'remote', // cloud-browser run: lets the backend apply the plan gate
                     targets: group.indices.map(i => ({
                         url: targetContexts[i].targetUrl ?? input.targets[i].url,
                         // Send null (not undefined) for optional fields so the field exists

package/dist/handlers/testPageChangesHandler.js

@@ -23,7 +23,7 @@ import { extractLocalhostPort, rewriteLocalhostInText } from '../utils/urlParser
 import { getCachedTemplateUuid, getCachedProjectUuid, invalidateTemplateCache, invalidateProjectCache, } from '../utils/handlerCaches.js';
 import { isTransientWorkflowError, transientReasonTag } from '../utils/transientErrors.js';
 import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
-import { prepareLocalRun, localizeCredentials } from './localExecutorBridge.js';
+import { prepareLocalRun, localizeCredentials, planRequiredFromError, chooseBrowser } from './localExecutorBridge.js';
 import { LocalBrowserError } from '../services/localBrowser.js';
 import { projectRequiredMessage, projectLookupFailedPayload } from '../utils/projectRequired.js';
 const logger = new Logger({ module: 'testPageChangesHandler' });
@@ -114,6 +114,7 @@ export async function testPageChangesHandler(input, context, progressCallback) {
 }
 async function testPageChangesHandlerInner(input, context, rawProgressCallback) {
     const startTime = Date.now();
+    const originalInput = input; // before local credential placeholders are applied
     logger.toolStart('check_app_in_browser', input);
     // Bead 0bq: wrap the progress callback in a circuit-breaker so a single
     // client-side rejection of a stale progressToken (which would normally
@@ -139,7 +140,8 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
     const client = new DebuggAIServerClient(config.api.key);
     await client.init();
     // browser:'local': Chrome on this machine does the clicking (no tunnel); passwords stay local.
-    const localMode = input.browser === 'local';
+    const choice = chooseBrowser(input);
+    const localMode = choice.mode === 'local';
     let localSecrets = {};
     if (localMode) {
         const l = localizeCredentials(input);
@@ -412,6 +414,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             contextData.projectId = projectUuid;
         }
         contextData.headless = true; // D7: the MCP always runs headless — no opt-out.
+        contextData.browserChoice = localMode ? 'local' : 'remote'; // lets the backend apply the cloud-browser plan gate
         if (localMode) {
             localRun = await prepareLocalRun({ client, input, startUrl: originalUrl, secrets: localSecrets, signal: abortController.signal, projectId: projectUuid || undefined });
             contextData.executorSessionId = localRun.sessionId;
@@ -953,9 +956,16 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         return tunnelFault ? { content, isError: true } : { content };
     }
     catch (error) {
-        if (error instanceof LocalBrowserError) {
-            const payload = { error: error.code, message: error.message };
-            logger.warn(`check_app_in_browser (local): ${error.code}: ${error.message}`);
+        // Browser was not chosen and this backend has no local executors: use the cloud browser instead.
+        if (choice.auto && error instanceof LocalBrowserError && error.code === 'LOCAL_EXECUTOR_UNAVAILABLE') {
+            logger.info('check_app_in_browser: local executors are not available on this backend; using the cloud browser');
+            return testPageChangesHandlerInner({ ...originalInput, browser: 'remote' }, context, rawProgressCallback);
+        }
+        const planErr = planRequiredFromError(error, localMode ? 'local' : 'remote');
+        if (error instanceof LocalBrowserError || planErr) {
+            const lbe = (planErr ?? error);
+            const payload = { error: lbe.code, message: lbe.message, ...(lbe.details ?? {}) };
+            logger.warn(`check_app_in_browser (local): ${lbe.code}: ${lbe.message}`);
             return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
         }
         const duration = Date.now() - startTime;

package/dist/services/localBrowser.js

@@ -6,7 +6,8 @@
  * 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
+ * No server opt-in: asking for `browser: "local"` in the call is the consent (the allowlist stays
+ * required). It is unavailable on the hosted HTTP server, which has no machine of yours. 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.
@@ -17,9 +18,11 @@ import path from 'node:path';
 import { installNavigationGuard, isLoopbackHost } from './navigationGuard.js';
 export class LocalBrowserError extends Error {
     code;
-    constructor(message, code) {
+    details;
+    constructor(message, code, details) {
         super(message);
         this.code = code;
+        this.details = details;
         this.name = 'LocalBrowserError';
     }
 }
@@ -40,9 +43,11 @@ 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);
 }
+/** Local Chrome needs a machine of the caller's: it is available on stdio, never on the hosted HTTP server. */
 export function localBrowserEnabled(env = process.env) {
-    return env.DEBUGGAI_LOCAL_BROWSER === '1' || env.DEBUGGAI_LOCAL_BROWSER === 'true';
+    return (env.DEBUGGAI_MCP_TRANSPORT || 'stdio').toLowerCase() !== 'http';
 }
+export const LOCAL_UNAVAILABLE_MESSAGE = 'Local browser runs are not available on the hosted (HTTP) MCP server: there is no machine of yours to open Chrome on. Use browser "remote", or run the MCP on your own machine (stdio).';
 export function debuggHome(env = process.env) {
     return env.DEBUGGAI_HOME || path.join(os.homedir(), '.debugg-ai');
 }
@@ -74,10 +79,12 @@ async function loadPlaywright() {
 export function ensurePrivateDir(dir) {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
 }
+/** Headed runs are opt-in; even then keep the window out of the way: off-screen, minimized, no focus grab. */
+export const HEADED_QUIET_ARGS = ['--start-minimized', '--window-position=-32000,-32000', '--no-first-run', '--no-default-browser-check'];
 export async function launch(opts) {
     const pw = await loadPlaywright();
     const executablePath = findChrome();
-    const base = { headless: opts.headless, ...(executablePath ? { executablePath } : { channel: 'chrome' }) };
+    const base = { headless: opts.headless, ...(opts.headless ? {} : { args: HEADED_QUIET_ARGS }), ...(executablePath ? { executablePath } : { channel: 'chrome' }) };
     try {
         if (opts.useProfile) {
             const dir = profileDir();
@@ -120,7 +127,7 @@ function summarize(entries) {
 }
 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');
+        throw new LocalBrowserError(LOCAL_UNAVAILABLE_MESSAGE, 'LOCAL_BROWSER_DISABLED');
     }
     const allowed = o.useProfile ? resolveAllowedDomains(o.allowedDomains) : [];
     if (o.useProfile && allowed.length === 0) {

package/dist/services/localExecutor/opRunner.js

@@ -6,7 +6,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { launch, localBrowserEnabled, LocalBrowserError, hostAllowed, resolveAllowedDomains, debuggHome, ensurePrivateDir } from '../localBrowser.js';
+import { launch, localBrowserEnabled, LocalBrowserError, LOCAL_UNAVAILABLE_MESSAGE, hostAllowed, resolveAllowedDomains, debuggHome, ensurePrivateDir } from '../localBrowser.js';
 import { installNavigationGuard, isLoopbackHost } from '../navigationGuard.js';
 import { OPS } from './ops.js';
 const SECRET_RE = /\{\{cred:([^}]+)\}\}/g;
@@ -45,7 +45,7 @@ export class OpRunner {
     static supportedOps() { return OPS; }
     static async open(opts) {
         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');
+            throw new LocalBrowserError(LOCAL_UNAVAILABLE_MESSAGE, 'LOCAL_BROWSER_DISABLED');
         }
         const allowed = opts.useProfile ? resolveAllowedDomains(opts.allowedDomains) : opts.allowedDomains;
         if (allowed.length === 0) {

package/dist/tools/probePage.js

@@ -84,7 +84,7 @@ export function buildProbePageTool() {
                 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.",
+                    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 (stdio). waitForSelector/waitForLoadState/timeoutMs apply; the local mode returns screenshot, console errors, network summary, title and (optionally) HTML.",
                 },
                 headless: {
                     type: 'boolean',

package/dist/tools/testPageChanges.js

@@ -109,7 +109,7 @@ export function buildTestPageChangesTool(ctx) {
                 browser: {
                     type: "string",
                     enum: ["remote", "local"],
-                    description: "Default 'remote' (cloud browser; localhost is tunneled). 'local' runs the clicking in Chrome on THIS machine — no tunnel, no *.localhost limits, much faster — while the cloud agent still decides each step. Needs DEBUGGAI_LOCAL_BROWSER=1 on the MCP server and the backend's local executor enabled. Passwords passed in this call stay on this machine. Page screenshots and text are still sent to the cloud agent. Not available over the remote HTTP MCP."
+                    description: "Unset: Chrome on THIS machine when it is installed, otherwise the cloud browser (a plan with cloud browsers; localhost is tunneled). 'local' runs the clicking in your own Chrome — free on every plan, no tunnel, no *.localhost limits, much faster — while the cloud agent still decides each step. 'remote' forces the cloud browser (Professional and above). Passwords passed in this call stay on this machine. Page screenshots and text are still sent to the cloud agent. Not available over the remote HTTP MCP."
                 },
                 headless: { type: "boolean", description: "browser:'local' only. Default true; false shows the Chrome window." },
                 useProfile: { type: "boolean", description: "browser:'local' only. Use the MCP-owned logged-in Chrome profile (never your everyday Chrome). Requires allowedDomains." },

package/dist/types/index.js

@@ -65,8 +65,8 @@ export const TestPageChangesInputSchema = z.object({
     // you are checking, or when the app's only route between personas is a logout.
     freshSession: z.boolean().optional(),
     // 'local' runs the clicking in Chrome on THIS machine (no tunnel); the cloud agent still decides each step.
-    // Needs DEBUGGAI_LOCAL_BROWSER=1 on the MCP server.
-    browser: z.enum(['remote', 'local']).default('remote'),
+    // Unset: your own Chrome when it is installed (stdio server), otherwise the cloud browser.
+    browser: z.enum(['remote', 'local']).optional(),
     headless: z.boolean().optional(),
     useProfile: z.boolean().optional(),
     allowedDomains: z.array(z.string().min(1)).max(32).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "6.2.1",
+  "version": "6.2.2",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "caddy": "2.11.3",