@debugg-ai/debugg-ai-mcp 6.1.3 → 6.1.4

package/README.md

@@ -23,6 +23,30 @@ 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.
 
+## 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
+opens its own DebuggAI tunnel (one per session, dialed through a local Caddy proxy) — do not expose the
+port with Tailscale, ngrok, or anything else, and do not rewrite the URL to a tunnel hostname yourself.
+
+```json
+probe_page            { "targets": [{ "url": "http://localhost:4040" }] }
+check_app_in_browser  { "url": "http://localhost:4040", "description": "Open the home page and confirm the hero renders" }
+```
+
+Verified 2026-11-10 against a Next.js dev server on `localhost:4040`: `probe_page` returned
+`statusCode 200`, title, 0 console errors, and every asset request resolved via the tunnel.
+Prerequisites: `DEBUGGAI_API_KEY` set for the MCP, the `caddy` binary available (see above), and the
+app actually listening (a dead port fails fast with `LocalServerUnreachable`). Several pages on the
+same port can share one `probe_page` call; mixing ports in one call works but runs serially.
+
+`TunnelTrafficBlocked` means the tunnel came up but the health probe through it got no valid response. First
+check you are on the latest MCP (`npx -y @debugg-ai/debugg-ai-mcp@latest`; a stale pinned version is the usual
+cause), then that your dev server answers a plain `curl http://127.0.0.1:<port>/` and does not reject unknown
+`Host` headers (tunnel requests carry the tunnel hostname; a gateway that routes by `Host` needs a catch-all).
+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>`.
+
 Get an API key at [debugg.ai](https://debugg.ai), then add to your MCP client config:
 
 ```json

package/dist/utils/localReachability.js

@@ -101,10 +101,13 @@ export async function probeTunnelHealth(tunnelUrl, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 5000;
     const started = Date.now();
     let last;
+    let allClosed = true;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         const { result, retryable } = await probeOverControlChannel(tunnelUrl, timeoutMs, started);
         if (!retryable)
             return result;
+        if (!result.detail?.endsWith(' CLOSED'))
+            allClosed = false;
         last = result;
         if (attempt < maxAttempts) {
             await sleep(backoff[attempt - 1] ?? backoff[backoff.length - 1] ?? 150);
@@ -112,6 +115,14 @@ export async function probeTunnelHealth(tunnelUrl, opts = {}) {
     }
     // Ladder exhausted on a transient error — the tunnel never came up. Report
     // it: "not ready" that never becomes ready IS unhealthy.
+    //
+    // A control channel CLOSED on every attempt means the tunnel has no live
+    // session at all (a reconnect that never lands, or the transport forgot the
+    // tunnel while the manager still holds it). It can never serve a request, so
+    // flag it for eviction — otherwise every later call reuses the corpse and
+    // fails identically until the MCP process restarts.
+    if (allClosed && last)
+        last.tunnelErrorCode = 'CONTROL_CHANNEL_CLOSED';
     return last;
 }
 // ─ Control-channel probe ─────────────────────────────────────────────────────

package/dist/utils/tunnelDisposition.js

@@ -69,6 +69,11 @@ const logger = new Logger({ module: 'tunnelDisposition' });
 const ENDPOINT_GONE_CODES = Object.freeze([
     'DEBUGG_TUNNEL_OFFLINE',
     'DEBUGG_TUNNEL_UNKNOWN',
+    // Client-side verdict, not a server marker: probeTunnelHealth saw the tunnel's
+    // own control channel CLOSED on every attempt of its ladder, i.e. there is no
+    // session left to carry traffic. Keeping it makes every later call fail the
+    // same way (the crochets build lead's "stuck at CLOSED" report).
+    'CONTROL_CHANNEL_CLOSED',
 ]);
 const ENDPOINT_GONE_LOOKUP = new Set(ENDPOINT_GONE_CODES);
 /** The allowlist, as an immutable list. Read-only by construction. */

package/package.json

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