@debugg-ai/debugg-ai-mcp 3.10.0 → 4.1.0

package/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to the DebuggAI MCP project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased] — BREAKING
+
+### Changed — one ngrok tunnel per session instead of one per local port
+
+`check_app_in_browser`, `probe_page`, and `trigger_crawl` now share a **single**
+ngrok tunnel per session (keyed per-caller on HTTP transport, so different
+callers never share state), backed by a local Caddy reverse proxy that gets
+repointed at whichever local port a call targets immediately before dispatch.
+Previously every distinct local port tested in a session opened its own ngrok
+tunnel — N ports meant N billed tunnels. Full design:
+`docs/local-tunnel-multiplexer-architecture-2026-07-31.md`.
+
+This replaces (not extends) a Feb 2026 attempt at the same goal that used
+path-prefix routing (`/p/{port}/*`) and broke on any root-absolute asset/API
+path (`/api/...`, `/_next/...` — the default in most modern frameworks). The
+new design routes through a single dynamic upstream with zero path/host
+rewriting, so that failure mode is structurally impossible rather than patched.
+A live-browser regression test for exactly this case now exists and passes
+(`__tests__/integration/caddyProxy.test.ts`).
+
+**New runtime dependency, auto-installed:** `check_app_in_browser`/`probe_page`/`trigger_crawl`
+now need the `caddy` binary for any `http://localhost:...` call. It installs itself — the
+`@radically-straightforward/caddy` npm dependency downloads a pinned Caddy release (`2.11.3`) for
+your platform during `npm install`/`npx`, the same pattern this project already uses for the
+`ngrok` binary. Falls back to `CADDY_BIN` (or a system `caddy` on `PATH`) if that download never
+ran (`npm install --ignore-scripts`, offline install) — fails fast with a clear
+`CaddyBinaryNotFoundError` rather than a silent hang if none of those resolve.
+`test_suite {action:"run"}` is unaffected either way (dedicated per-run tunnel, bypasses Caddy).
+
+**Deployment precondition for HTTP transport:** multi-replica deployments that
+want the one-tunnel-per-session guarantee need session-affine load-balancer
+routing (consistent hash / sticky on the caller's bearer token). Without it,
+tunnel count degrades to bounded, cost-only over-provisioning (never a
+correctness issue) — see architecture doc §2.1.
+
+### Fixed — two latent response-sanitization bugs surfaced by the above
+
+- `probe_page` multi-target batches could cross-attribute a tunnel-hostname
+  rewrite from one target's result onto another's once targets started sharing
+  a session hostname (they didn't, before this change).
+- `run_test_suite` had no defensive URL-sanitization call at all.
+
 ## [3.5.1]
 
 ### Fixed — default OAuth issuer points at the Django AS

package/README.md

@@ -10,6 +10,18 @@ AI-powered browser testing via the [Model Context Protocol](https://modelcontext
 
 **Requires Node.js 20.20.0 or later** (transitive requirement from `posthog-node@^5.26.0`).
 
+**Testing `http://localhost:...` URLs requires the `caddy` binary** — `check_app_in_browser`,
+`probe_page`, and `trigger_crawl` tunnel localhost targets through a local Caddy reverse proxy.
+This installs automatically: the `@radically-straightforward/caddy` npm dependency downloads a
+pinned Caddy release for your platform during `npm install`/`npx`, same as this project already
+does for the `ngrok` binary — nothing to install yourself in the normal case. If that download
+never ran (`npm install --ignore-scripts`, an offline/air-gapped install), point `CADDY_BIN` at
+your own install (`brew install caddy` / `apt install caddy` / see
+[caddyserver.com/docs/install](https://caddyserver.com/docs/install)) — missing it surfaces as a
+clear error on the first localhost-URL call, not a silent hang. Public-URL calls, every
+non-browser tool, and `test_suite {action:"run"}` (which uses its own dedicated tunnel and
+bypasses Caddy entirely) don't need it either way.
+
 Get an API key at [debugg.ai](https://debugg.ai), then add to your MCP client config:
 
 ```json
@@ -32,6 +44,17 @@ Or with Docker:
 docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-mcp
 ```
 
+The `Dockerfile`'s `npm install` step would pick up `caddy` the same automatic way local installs
+do, in principle — but as of this writing the `Dockerfile` doesn't `COPY` several directories the
+build now needs (`handlers`, `tools`, `types`, `config`) and still references a `tunnels/`
+directory that no longer exists, so a fresh build likely fails before that matters. That's a
+pre-existing gap, unrelated to Caddy. The **currently published** `quinnosha/debugg-ai-mcp` image
+predates the Caddy dependency regardless — localhost-URL calls to
+`check_app_in_browser`/`probe_page`/`trigger_crawl` will fail with `CaddyBinaryNotFoundError`
+inside that image until it's rebuilt (Dockerfile fixed) and republished, or `CADDY_BIN` points at
+one baked in separately. Public-URL calls, the non-browser tools, and `test_suite {action:"run"}`
+are unaffected either way.
+
 ## Tools
 
 The server exposes **8** tools: three **Browser** tools plus one **action-based** tool per managed entity. The headline tools are `check_app_in_browser` (full AI agent) and `probe_page` (lightweight no-LLM page probe). The rest — `project`, `environment`, `test_suite`, `test_case`, `executions` — each take an `action` discriminator (e.g. `{"action":"list"}`) that selects the operation. Destructive `delete` actions require confirmation (an elicitation prompt where supported, otherwise `confirm: true`).
@@ -53,6 +76,7 @@ Runs an AI browser agent against your app. The agent navigates, interacts, and r
 | `password` | string | Password for login (ephemeral — not persisted) |
 | `loginCredentials` | array | Accounts for logins the agent hits **during** the task — `[{username, password, label?}]` |
 | `useEnvironmentCredentials` | boolean | Default `true`. `false` forbids auto-filling the environment's stored credentials |
+| `freshSession` | boolean | Default `false`. `true` forces a real login instead of reusing the warm session held for that account |
 | `auth` | object | Auth precondition — `{precondition, entryUrl, deepUrl, environmentId, username, password}` |
 | `repoName` | string | Override auto-detected git repo name (e.g. `my-org/my-repo`) |
 
@@ -68,6 +92,17 @@ Naming an account only in `description` does **not** make the agent use it — i
 
 Set `useEnvironmentCredentials: false` when a silent fallback to the default test user would invalidate the check. The call is rejected if you opt out without naming an account, since the run would have no way to authenticate.
 
+##### Session reuse: why a check can report "no login form"
+
+Runs don't log in every time. After a verified login the backend captures that account's session and **restores** it on the next run for the same identity, which skips the login entirely — that's why a check can legitimately come back with `submitted: false` and no login form: it was already signed in. A restored run reports itself in `logins` with `reason: "restored_session"`, so you can tell it apart from a run that genuinely found no form.
+
+Sessions are keyed per **account**, so naming a different account never reuses somebody else's. Two ways to bypass reuse:
+
+- `freshSession: true` on a single call — log in for real this once, then re-capture. Use it when the login flow *is* what you're checking, when you suspect the stored session is stale, or when the app's only route between personas is a logout.
+- `environment` tool, `action: "clearSessions"` — invalidate the stored sessions so subsequent runs log in. Narrow with `username` / `credentialId`; unscoped clears require confirmation because every account on the environment then re-authenticates.
+
+Use `action: "sessions"` to see what an environment is currently holding and whether each would be reused.
+
 Results report the identity actually used, so a wrong one is visible rather than masquerading as a broken app:
 
 ```json
@@ -117,7 +152,7 @@ Fires a server-side browser-agent crawl to populate the project's knowledge grap
 | `includeHtml` | boolean | Return raw HTML in each result (default false) |
 | `captureScreenshots` | boolean | Return one PNG per target (default true) |
 
-The whole batch shares a single backend execution + browser session + tunnel — 5 URLs in one call is dramatically faster than 5 parallel single-URL calls. Per-URL `error` field preserves batch resilience: a single failed target doesn't fail the others.
+All targets in a batch share one session tunnel, but only same-port (or all-public) batches share a **single** backend execution — 5 URLs on one port in one call is dramatically faster than 5 parallel single-URL calls. A batch that mixes multiple **local** ports decomposes into one sequential backend execution per port group (still one call, still one merged `results[]` in your original order, but N backend round-trips instead of one — slower, not rejected). Per-URL `error` field preserves batch resilience: a single failed target doesn't fail the others.
 
 **`networkSummary` aggregation key is `origin + pathname`** — refetch loops (`?n=0..4` repeatedly hitting the same endpoint) collapse into a single entry with the count, so `/api/poll` showing up with `count: 47` is the actionable "infinite refetch loop" signal users originally asked for.
 
@@ -142,9 +177,13 @@ Team and repo resolve by **either** uuid **or** name (case-insensitive exact mat
 | `create` | `{name, url, description?, projectUuid?, credentials?}` | Created env (optionally seeds credentials) |
 | `update` | `{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}` | Patched env; credential ops run **remove → update → add** |
 | `delete` | `{uuid, projectUuid?, confirm?}` | Deletes env (cascades credentials) — **requires confirmation** |
+| `sessions` | `{uuid, username?, credentialId?}` | Captured login sessions the env holds, per account, with `isUsable` and a `usableCount` |
+| `clearSessions` | `{uuid, username?, credentialId?, confirm?}` | Invalidates them so the next run logs in for real — **unscoped clears require confirmation** |
 
 `projectUuid` auto-resolves from the git repo when omitted. Per-cred failures surface in `credentialWarnings[]` without blocking the env op.
 
+`sessions` / `clearSessions` manage the warm authenticated sessions the backend reuses to skip login (see [Session reuse](#session-reuse-why-a-check-can-report-no-login-form)). Session contents are never returned — a session cookie is a bearer credential. `clearSessions` marks sessions invalid rather than deleting the rows, so reuse stops immediately while the capture history stays readable.
+
 ### `test_suite`
 
 | Action | Params | Result |
@@ -294,6 +333,19 @@ flow against the advertised authorization server. The bearer is request-scoped
 
 stdio installs need none of these.
 
+**Multi-replica deployments (go/no-go before rollout):** tunnel state (the ngrok session tunnel,
+its Caddy instance, and its port-route lock) is in-process, keyed per caller by a hash of the
+bearer token — there is no cross-process coordination. Running several replicas behind a plain
+round-robin load balancer means one caller's calls can land on different replicas and mint one
+tunnel **per replica they hit** instead of one for the whole session (extra ngrok cost, bounded by
+replica count, self-healing via the existing 55-minute idle auto-shutoff — never a cross-session
+correctness bug, since any single tool call stays on one replica for its whole duration). To get
+the intended "one tunnel per session" behavior on a multi-replica HTTP deployment, configure
+**session-affine routing** at the load balancer (sticky/consistent-hash keyed on the same identity
+`getSessionKey()` derives — in practice, the caller's `Authorization` bearer token). See
+`docs/local-tunnel-multiplexer-architecture-2026-07-31.md` §2.1 for the full reasoning and the
+honest degrade path if this isn't configured.
+
 ## Telemetry
 
 The MCP server ships with telemetry enabled by default — an embedded write-only PostHog project key (`phc_*`) so the team can observe cache hit rates, poll cadence, tunnel reliability, and other operational metrics across the install base. Captured events:

package/dist/handlers/environmentHandler.js

@@ -3,6 +3,7 @@ import { searchEnvironmentsHandler } from './searchEnvironmentsHandler.js';
 import { createEnvironmentHandler } from './createEnvironmentHandler.js';
 import { updateEnvironmentHandler } from './updateEnvironmentHandler.js';
 import { deleteEnvironmentHandler } from './deleteEnvironmentHandler.js';
+import { clearEnvironmentSessionsHandler, listEnvironmentSessionsHandler, } from './environmentSessionsHandler.js';
 export async function environmentHandler(input, ctx) {
     switch (input.action) {
         case 'get':
@@ -23,5 +24,19 @@ export async function environmentHandler(input, ctx) {
                 return refusal;
             return deleteEnvironmentHandler({ uuid: input.uuid, projectUuid: input.projectUuid }, ctx);
         }
+        case 'sessions':
+            return listEnvironmentSessionsHandler(input, ctx);
+        case 'clearSessions': {
+            // Confirmed like a delete when it is UNSCOPED. Clearing one account's
+            // session costs that account one login; clearing an environment's costs
+            // every account on it one, which is a different size of action and should
+            // not happen because a filter was mistyped.
+            if (!input.username && !input.credentialId) {
+                const refusal = await ensureConfirmed('clearSessions', `environment ${input.uuid}`, input, ctx);
+                if (refusal)
+                    return refusal;
+            }
+            return clearEnvironmentSessionsHandler(input, ctx);
+        }
     }
 }

package/dist/handlers/environmentSessionsHandler.js

@@ -0,0 +1,60 @@
+import { Logger } from '../utils/logger.js';
+import { handleExternalServiceError } from '../utils/errors.js';
+import { DebuggAIServerClient } from '../services/index.js';
+import { config } from '../config/index.js';
+const logger = new Logger({ module: 'environmentSessionsHandler' });
+function ok(payload) {
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+export async function listEnvironmentSessionsHandler(input, _context) {
+    logger.toolStart('environment.sessions', { uuid: input.uuid, username: input.username });
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        const sessions = await client.listEnvironmentSessions(input.uuid, {
+            ...(input.username ? { username: input.username } : {}),
+            ...(input.credentialId ? { credentialId: input.credentialId } : {}),
+        });
+        // usableCount, not just the rows: "does this environment currently hold a
+        // session that will be restored?" is the question a caller is actually
+        // asking, and an expired row still reports status 'valid'.
+        const usableCount = sessions.filter(s => s.isUsable).length;
+        return ok({
+            environmentUuid: input.uuid,
+            sessions,
+            pageInfo: { totalCount: sessions.length, usableCount },
+            note: sessions.length === 0
+                ? 'No captured sessions — every run for this environment logs in for real.'
+                : `${usableCount} of ${sessions.length} session(s) would be restored instead of logging in. `
+                    + 'Use action "clearSessions" to force a real login, or pass freshSession:true on a single run.',
+        });
+    }
+    catch (error) {
+        throw handleExternalServiceError(error, 'DebuggAI', 'environment.sessions');
+    }
+}
+export async function clearEnvironmentSessionsHandler(input, _context) {
+    logger.toolStart('environment.clearSessions', { uuid: input.uuid, username: input.username });
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        const filters = {
+            ...(input.username ? { username: input.username } : {}),
+            ...(input.credentialId ? { credentialId: input.credentialId } : {}),
+        };
+        const { invalidated } = await client.clearEnvironmentSessions(input.uuid, filters);
+        const scope = input.username ?? input.credentialId ?? 'all accounts';
+        logger.info(`environment.clearSessions: invalidated ${invalidated} session(s) for ${scope}`);
+        return ok({
+            environmentUuid: input.uuid,
+            invalidated,
+            scope,
+            note: invalidated === 0
+                ? 'Nothing to clear — no usable captured session matched.'
+                : 'The next run for this identity will perform a real login and re-capture.',
+        });
+    }
+    catch (error) {
+        throw handleExternalServiceError(error, 'DebuggAI', 'environment.clearSessions');
+    }
+}