@debugg-ai/debugg-ai-mcp 2.1.2 → 2.1.3

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed — MCP now validates local reachability BEFORE hitting the backend (fixes 5-min false-pass regression)
+
+- `check_app_in_browser` and `trigger_crawl` now do a pre-flight TCP probe to `127.0.0.1:<port>` before provisioning a backend tunnel key. If the dev server isn't listening, we return a structured `LocalServerUnreachable` error in ~ms instead of letting the browser agent burn its 5-minute step budget on `ERR_NGROK_8012`. Bead `1om`.
+- After the tunnel is established, we do a second `GET /` probe through the tunnel itself and parse the body for `ERR_NGROK_*` markers. If ngrok received traffic but couldn't dial our backend (e.g., the dev server binds to 0.0.0.0/::1 but not 127.0.0.1), we tear down the tunnel, revoke the key, and return `TunnelTrafficBlocked` — again, fast, with a message that points at the actual cause.
+- End-to-end proof: new eval flow `28-localhost-not-listening.mjs` against a guaranteed-free port, asserts response arrives in <10s with `error:'LocalServerUnreachable'`. Measured **9ms** in practice vs. the prior **5-minute false-pass**.
+
 ### Fixed — ngrok now dials IPv4 loopback explicitly (fixes ERR_NGROK_8012 on macOS Next.js)
 
 - `ngrok.connect({addr})` now passes `127.0.0.1:<port>` instead of the bare port number for plain-http localhost URLs. Bare port / `localhost` could resolve to IPv6 `[::1]` first on modern macOS, but Next.js / Vite / most Node dev servers bind to `127.0.0.1` only. Result was a successful tunnel that dialed `[::1]:<port>` and got `connection refused`, surfacing to users as `ERR_NGROK_8012` inside the browser agent trace. Bead `fhg`. Evidenced by real incident log 2026-04-24T19:37Z.

package/dist/handlers/testPageChangesHandler.js

@@ -11,6 +11,9 @@ import { DebuggAIServerClient } from '../services/index.js';
 import { TunnelProvisionError } from '../services/tunnels.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 import { detectRepoName } from '../utils/gitContext.js';
+import { tunnelManager } from '../services/ngrok/tunnelManager.js';
+import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
+import { extractLocalhostPort } from '../utils/urlParser.js';
 const logger = new Logger({ module: 'testPageChangesHandler' });
 // Cache the template UUID and project UUIDs within a server session to avoid re-fetching
 let cachedTemplateUuid = null;
@@ -86,6 +89,28 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
     try {
         // --- Tunnel: reuse existing or provision a fresh one ---
         if (ctx.isLocalhost) {
+            // Bead 1om: pre-flight local port probe BEFORE committing to backend
+            // provision + ngrok session. If the user's dev server isn't listening,
+            // fail in ~1.5s with a structured error instead of burning 5 minutes
+            // on a browser agent trying to reach a dead tunnel.
+            const localPort = extractLocalhostPort(ctx.originalUrl);
+            if (typeof localPort === 'number') {
+                const probe = await probeLocalPort(localPort);
+                if (!probe.reachable) {
+                    const payload = {
+                        error: 'LocalServerUnreachable',
+                        message: `No server listening on 127.0.0.1:${localPort}. Start your dev server on that port before running check_app_in_browser. Probe result: ${probe.code} (${probe.detail ?? 'no detail'}).`,
+                        detail: {
+                            port: localPort,
+                            probeCode: probe.code,
+                            probeDetail: probe.detail,
+                            elapsedMs: probe.elapsedMs,
+                        },
+                    };
+                    logger.warn(`Pre-flight port probe failed for ${ctx.originalUrl}: ${probe.code} in ${probe.elapsedMs}ms`);
+                    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+                }
+            }
             if (progressCallback) {
                 await progressCallback({ progress: 1, total: TOTAL_STEPS, message: 'Provisioning secure tunnel for localhost...' });
             }
@@ -120,6 +145,37 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                 }
                 logger.info(`Tunnel ready: ${ctx.targetUrl} (id: ${ctx.tunnelId})`);
             }
+            // Bead 1om: verify traffic actually flows through the tunnel. The
+            // tunnel can be established (ngrok.connect returns OK) yet refuse
+            // to forward traffic — e.g., IPv4/IPv6 bind mismatch, or the dev
+            // server died between the pre-flight probe and here. Catch it now,
+            // in ~1s, not via a 5-minute browser-agent false-pass.
+            if (ctx.targetUrl) {
+                const health = await probeTunnelHealth(ctx.targetUrl);
+                if (!health.healthy) {
+                    const payload = {
+                        error: 'TunnelTrafficBlocked',
+                        message: `Tunnel was established but traffic isn't reaching the dev server. ${health.detail ?? ''} Common causes: dev server binds to 0.0.0.0 or ::1 but not 127.0.0.1; dev server crashed; firewall.`,
+                        detail: {
+                            code: health.code,
+                            status: health.status,
+                            ngrokErrorCode: health.ngrokErrorCode,
+                            elapsedMs: health.elapsedMs,
+                        },
+                    };
+                    logger.warn(`Tunnel health probe failed for ${ctx.targetUrl}: ${health.code} ${health.ngrokErrorCode ?? ''} in ${health.elapsedMs}ms`);
+                    // Tear down the broken tunnel so a subsequent call doesn't reuse it.
+                    // stopTunnel handles both owned (ngrok disconnect + key revoke) and
+                    // borrowed (just drops local ref) cases.
+                    if (ctx.tunnelId) {
+                        tunnelManager.stopTunnel(ctx.tunnelId).catch((err) => logger.warn(`Failed to stop broken tunnel ${ctx.tunnelId}: ${err}`));
+                    }
+                    // keyId is consumed by stopTunnel's revoke path; clear so the
+                    // outer finally block doesn't double-revoke.
+                    keyId = undefined;
+                    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+                }
+            }
         }
         // --- Find workflow template ---
         if (progressCallback) {

package/dist/handlers/triggerCrawlHandler.js

@@ -15,6 +15,9 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { TunnelProvisionError } from '../services/tunnels.js';
+import { tunnelManager } from '../services/ngrok/tunnelManager.js';
+import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
+import { extractLocalhostPort } from '../utils/urlParser.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 const logger = new Logger({ module: 'triggerCrawlHandler' });
 const TEMPLATE_KEYWORD = 'raw crawl';
@@ -52,6 +55,20 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
     try {
         // --- Tunnel: reuse existing or provision a fresh one ---
         if (ctx.isLocalhost) {
+            // Bead 1om: pre-flight local port probe BEFORE provision/ngrok/backend.
+            const localPort = extractLocalhostPort(ctx.originalUrl);
+            if (typeof localPort === 'number') {
+                const probe = await probeLocalPort(localPort);
+                if (!probe.reachable) {
+                    const payload = {
+                        error: 'LocalServerUnreachable',
+                        message: `No server listening on 127.0.0.1:${localPort}. Start your dev server on that port before running trigger_crawl. Probe result: ${probe.code} (${probe.detail ?? 'no detail'}).`,
+                        detail: { port: localPort, probeCode: probe.code, probeDetail: probe.detail, elapsedMs: probe.elapsedMs },
+                    };
+                    logger.warn(`Pre-flight port probe failed for ${ctx.originalUrl}: ${probe.code} in ${probe.elapsedMs}ms`);
+                    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+                }
+            }
             if (progressCallback) {
                 await progressCallback({ progress: 1, total: 4, message: 'Provisioning secure tunnel for localhost...' });
             }
@@ -74,6 +91,28 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
                 keyId = tunnel.keyId;
                 ctx = await ensureTunnel(ctx, tunnel.tunnelKey, tunnel.tunnelId, tunnel.keyId, () => client.revokeNgrokKey(tunnel.keyId));
             }
+            // Bead 1om: post-tunnel health check — verify traffic actually flows.
+            if (ctx.targetUrl) {
+                const health = await probeTunnelHealth(ctx.targetUrl);
+                if (!health.healthy) {
+                    const payload = {
+                        error: 'TunnelTrafficBlocked',
+                        message: `Tunnel was established but traffic isn't reaching the dev server. ${health.detail ?? ''} Common causes: dev server binds to 0.0.0.0 or ::1 but not 127.0.0.1; dev server crashed; firewall.`,
+                        detail: {
+                            code: health.code,
+                            status: health.status,
+                            ngrokErrorCode: health.ngrokErrorCode,
+                            elapsedMs: health.elapsedMs,
+                        },
+                    };
+                    logger.warn(`Tunnel health probe failed for ${ctx.targetUrl}: ${health.code} ${health.ngrokErrorCode ?? ''} in ${health.elapsedMs}ms`);
+                    if (ctx.tunnelId) {
+                        tunnelManager.stopTunnel(ctx.tunnelId).catch((err) => logger.warn(`Failed to stop broken tunnel ${ctx.tunnelId}: ${err}`));
+                    }
+                    keyId = undefined;
+                    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+                }
+            }
         }
         // --- Find the crawl workflow template ---
         if (progressCallback) {

package/dist/utils/localReachability.js

@@ -0,0 +1,156 @@
+/**
+ * Local reachability probes (bead 1om).
+ *
+ * MCP owns the tunnel lifecycle. It must validate that the user's claimed
+ * localhost URL is actually reachable BEFORE calling the backend provision
+ * API and BEFORE committing to the slow ngrok/browser-agent path. Without
+ * these probes, unreachable apps result in a 5-minute false-positive pass
+ * as the browser agent burns its step budget on ERR_NGROK_8012.
+ *
+ * Two probes:
+ *   - probeLocalPort(port): pre-flight TCP connect to 127.0.0.1:<port>
+ *   - probeTunnelHealth(url): HTTP check that traffic actually flows through
+ *     the tunnel to our local server (catches IPv4/IPv6 bind mismatches,
+ *     misconfigured ngrok, etc.)
+ */
+import { createConnection } from 'node:net';
+export async function probeLocalPort(port, opts = {}) {
+    const host = opts.host ?? '127.0.0.1';
+    const timeoutMs = opts.timeoutMs ?? 1500;
+    const started = Date.now();
+    return new Promise((resolve) => {
+        const socket = createConnection({ host, port, timeout: timeoutMs });
+        let settled = false;
+        const done = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                socket.destroy();
+            }
+            catch { /* ignore */ }
+            resolve(result);
+        };
+        socket.once('connect', () => {
+            done({ reachable: true, elapsedMs: Date.now() - started });
+        });
+        socket.once('timeout', () => {
+            done({
+                reachable: false,
+                code: 'ETIMEDOUT',
+                detail: `connect timeout after ${timeoutMs}ms`,
+                elapsedMs: Date.now() - started,
+            });
+        });
+        socket.once('error', (err) => {
+            done({
+                reachable: false,
+                code: err.code ?? 'UNKNOWN',
+                detail: err.message,
+                elapsedMs: Date.now() - started,
+            });
+        });
+    });
+}
+export async function probeTunnelHealth(tunnelUrl, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 5000;
+    const fetchImpl = opts.fetchFn ?? fetch;
+    const started = Date.now();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(tunnelUrl, {
+            method: 'GET',
+            redirect: 'manual',
+            signal: controller.signal,
+            // Many user apps reject HEAD; stick to GET for broader compatibility.
+            headers: { 'User-Agent': 'debugg-ai-mcp/tunnel-health-probe' },
+        });
+        clearTimeout(timer);
+        // Read body so we can inspect for ngrok error markers. Cap at 4KB —
+        // ngrok error pages are small; a full user app body is a waste.
+        const bodyText = await readCapped(res, 4096);
+        const ngrokErr = extractNgrokErrorCode(bodyText);
+        // 502/504 + ngrok error marker → ngrok couldn't reach our server
+        if (ngrokErr) {
+            return {
+                healthy: false,
+                status: res.status,
+                code: 'NGROK_ERROR',
+                ngrokErrorCode: ngrokErr,
+                detail: `ngrok returned ${ngrokErr} — tunnel established but traffic could not reach dev server`,
+                elapsedMs: Date.now() - started,
+            };
+        }
+        if (res.status === 502 || res.status === 504) {
+            return {
+                healthy: false,
+                status: res.status,
+                code: 'BAD_GATEWAY',
+                detail: `tunnel returned ${res.status} without an ngrok error marker — gateway is rejecting upstream`,
+                elapsedMs: Date.now() - started,
+            };
+        }
+        // Any other response (incl. 4xx from user's app) means traffic reached
+        // the dev server — that's healthy from the TUNNEL's perspective. The
+        // user's 404 is a user concern, not a tunnel concern.
+        return {
+            healthy: true,
+            status: res.status,
+            elapsedMs: Date.now() - started,
+        };
+    }
+    catch (err) {
+        clearTimeout(timer);
+        const e = err;
+        if (e?.name === 'AbortError' || /abort|timeout/i.test(e?.message ?? '')) {
+            return {
+                healthy: false,
+                code: 'TIMEOUT',
+                detail: `tunnel health probe timed out after ${timeoutMs}ms`,
+                elapsedMs: Date.now() - started,
+            };
+        }
+        return {
+            healthy: false,
+            code: 'NETWORK_ERROR',
+            detail: e?.message ?? String(err),
+            elapsedMs: Date.now() - started,
+        };
+    }
+}
+// ─ helpers ───────────────────────────────────────────────────────────────────
+async function readCapped(res, maxBytes) {
+    if (!res.body)
+        return '';
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let total = 0;
+    let out = '';
+    try {
+        while (total < maxBytes) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            const remaining = maxBytes - total;
+            const chunk = value.length > remaining ? value.slice(0, remaining) : value;
+            out += decoder.decode(chunk, { stream: true });
+            total += chunk.length;
+            if (value.length > remaining) {
+                // Got enough; cancel the rest.
+                await reader.cancel().catch(() => { });
+                break;
+            }
+        }
+        out += decoder.decode();
+    }
+    catch {
+        /* ignore read errors — we return what we have */
+    }
+    return out;
+}
+export function extractNgrokErrorCode(body) {
+    // ngrok error pages surface codes like "ERR_NGROK_8012", "ERR_NGROK_3200", etc.
+    const match = body.match(/ERR_NGROK_\d+/);
+    return match ? match[0] : undefined;
+}

package/package.json

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