@debugg-ai/debugg-ai-mcp 1.0.31 → 1.0.32

package/dist/handlers/testPageChangesHandler.js

@@ -8,7 +8,7 @@ import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
 import { fetchImageAsBase64, imageContentBlock } from '../utils/imageUtils.js';
 import { DebuggAIServerClient } from '../services/index.js';
-import { resolveTargetUrl, buildContext, ensureTunnel, releaseTunnel, sanitizeResponseUrls, } from '../utils/tunnelContext.js';
+import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, } from '../utils/tunnelContext.js';
 const logger = new Logger({ module: 'testPageChangesHandler' });
 // Cache the template UUID within a server session to avoid re-fetching
 let cachedTemplateUuid = null;
@@ -19,14 +19,32 @@ export async function testPageChangesHandler(input, context, progressCallback) {
     await client.init();
     const originalUrl = resolveTargetUrl(input);
     let ctx = buildContext(originalUrl);
-    let ngrokKeyId;
+    let keyId;
     const abortController = new AbortController();
     const onStdinClose = () => abortController.abort();
     process.stdin.once('close', onStdinClose);
     try {
+        // --- Tunnel: reuse existing or provision a fresh one ---
+        if (ctx.isLocalhost) {
+            if (progressCallback) {
+                await progressCallback({ progress: 1, total: 10, message: 'Provisioning secure tunnel for localhost...' });
+            }
+            const reused = findExistingTunnel(ctx);
+            if (reused) {
+                ctx = reused;
+                logger.info(`Reusing tunnel: ${ctx.targetUrl} (id: ${ctx.tunnelId})`);
+            }
+            else {
+                const tunnel = await client.tunnels.provision();
+                keyId = tunnel.keyId;
+                // revokeKey is stored on the TunnelInfo and fires when the tunnel auto-stops.
+                ctx = await ensureTunnel(ctx, tunnel.tunnelKey, tunnel.tunnelId, tunnel.keyId, () => client.revokeNgrokKey(tunnel.keyId));
+                logger.info(`Tunnel ready: ${ctx.targetUrl} (id: ${ctx.tunnelId})`);
+            }
+        }
         // --- Find workflow template ---
         if (progressCallback) {
-            await progressCallback({ progress: 1, total: 10, message: 'Locating evaluation workflow template...' });
+            await progressCallback({ progress: 2, total: 10, message: 'Locating evaluation workflow template...' });
         }
         if (!cachedTemplateUuid) {
             const template = await client.workflows.findEvaluationTemplate();
@@ -37,9 +55,9 @@ export async function testPageChangesHandler(input, context, progressCallback) {
             cachedTemplateUuid = template.uuid;
             logger.info(`Using workflow template: ${template.name} (${template.uuid})`);
         }
-        // --- Build context data ---
+        // --- Build context data (targetUrl is the tunnel URL for localhost, original URL otherwise) ---
         const contextData = {
-            targetUrl: originalUrl,
+            targetUrl: ctx.targetUrl ?? originalUrl,
             goal: input.description,
         };
         // --- Build env (credentials/environment) ---
@@ -56,23 +74,11 @@ export async function testPageChangesHandler(input, context, progressCallback) {
             env.password = input.password;
         // --- Execute ---
         if (progressCallback) {
-            await progressCallback({ progress: 2, total: 10, message: 'Queuing workflow execution...' });
+            await progressCallback({ progress: 3, total: 10, message: 'Queuing workflow execution...' });
         }
         const executeResponse = await client.workflows.executeWorkflow(cachedTemplateUuid, contextData, Object.keys(env).length > 0 ? env : undefined);
         const executionUuid = executeResponse.executionUuid;
-        ngrokKeyId = executeResponse.ngrokKeyId ?? undefined;
         logger.info(`Execution queued: ${executionUuid}`);
-        // --- Tunnel (after execute — backend returns tunnelKey, executionUuid is the subdomain) ---
-        if (ctx.isLocalhost) {
-            if (progressCallback) {
-                await progressCallback({ progress: 3, total: 10, message: 'Creating secure tunnel for localhost...' });
-            }
-            if (!executeResponse.tunnelKey) {
-                throw new Error('Backend did not return a tunnel key for localhost execution');
-            }
-            ctx = await ensureTunnel(ctx, executeResponse.tunnelKey, executionUuid);
-            logger.info(`Tunnel ready for ${originalUrl} (id: ${executionUuid})`);
-        }
         // --- Poll ---
         // nodeExecutions grows as each node completes: trigger → browser.setup → surfer.execute_task → browser.teardown
         const NODE_PHASE_LABELS = {
@@ -101,6 +107,17 @@ export async function testPageChangesHandler(input, context, progressCallback) {
         // --- Format result ---
         const outcome = finalExecution.state?.outcome ?? finalExecution.status;
         const surferNode = finalExecution.nodeExecutions?.find(n => n.nodeType === 'surfer.execute_task');
+        // Log all node executions to diagnose what the backend returns
+        logger.info('Node executions raw data', {
+            nodeCount: finalExecution.nodeExecutions?.length ?? 0,
+            nodes: finalExecution.nodeExecutions?.map(n => ({
+                nodeId: n.nodeId,
+                nodeType: n.nodeType,
+                status: n.status,
+                outputKeys: n.outputData ? Object.keys(n.outputData) : [],
+                outputData: n.outputData,
+            })),
+        });
         const responsePayload = {
             outcome,
             success: finalExecution.state?.success ?? false,
@@ -130,16 +147,40 @@ export async function testPageChangesHandler(input, context, progressCallback) {
         const content = [
             { type: 'text', text: JSON.stringify(responsePayload, null, 2) },
         ];
-        // Embed screenshot / GIF from the surfer node output when URLs are present
-        const outputData = surferNode?.outputData ?? {};
-        const screenshotUrl = outputData.finalScreenshot ?? outputData.screenshot ?? outputData.screenshotUrl ?? null;
-        const gifUrl = outputData.runGif ?? outputData.gifUrl ?? null;
+        // Search all node outputs for screenshot/gif URLs — not just the surfer node
+        const SCREENSHOT_KEYS = ['finalScreenshot', 'screenshot', 'screenshotUrl', 'screenshotUri'];
+        const GIF_KEYS = ['runGif', 'gifUrl', 'gif', 'videoUrl', 'recordingUrl'];
+        let screenshotUrl = null;
+        let gifUrl = null;
+        for (const node of finalExecution.nodeExecutions ?? []) {
+            const data = node.outputData ?? {};
+            if (!screenshotUrl) {
+                for (const key of SCREENSHOT_KEYS) {
+                    if (typeof data[key] === 'string' && data[key]) {
+                        screenshotUrl = data[key];
+                        break;
+                    }
+                }
+            }
+            if (!gifUrl) {
+                for (const key of GIF_KEYS) {
+                    if (typeof data[key] === 'string' && data[key]) {
+                        gifUrl = data[key];
+                        break;
+                    }
+                }
+            }
+            if (screenshotUrl && gifUrl)
+                break;
+        }
         if (screenshotUrl) {
+            logger.info(`Embedding screenshot: ${screenshotUrl}`);
             const img = await fetchImageAsBase64(screenshotUrl).catch(() => null);
             if (img)
                 content.push(imageContentBlock(img.data, img.mimeType));
         }
         if (gifUrl) {
+            logger.info(`Embedding GIF/video: ${gifUrl}`);
             const gif = await fetchImageAsBase64(gifUrl).catch(() => null);
             if (gif)
                 content.push(imageContentBlock(gif.data, 'image/gif'));
@@ -156,9 +197,13 @@ export async function testPageChangesHandler(input, context, progressCallback) {
     }
     finally {
         process.stdin.removeListener('close', onStdinClose);
-        if (ngrokKeyId) {
-            client.revokeNgrokKey(ngrokKeyId).catch(err => logger.warn(`Failed to revoke ngrok key ${ngrokKeyId}: ${err}`));
+        // Tunnels stay alive for reuse — the 55-min auto-shutoff on TunnelManager
+        // fires revokeKey when the tunnel actually stops.
+        //
+        // Only revoke explicitly when we provisioned a key but tunnel creation failed
+        // (keyId set, ctx.tunnelId not set → key was never attached to a tunnel).
+        if (keyId && !ctx.tunnelId) {
+            client.revokeNgrokKey(keyId).catch(err => logger.warn(`Failed to revoke unused ngrok key ${keyId}: ${err}`));
         }
-        releaseTunnel(ctx).catch(err => logger.warn(`Failed to stop tunnel: ${err}`));
     }
 }

package/dist/services/index.js

@@ -1,4 +1,5 @@
 import { createWorkflowsService } from "./workflows.js";
+import { createTunnelsService } from "./tunnels.js";
 import { AxiosTransport } from "../utils/axiosTransport.js";
 import { config } from "../config/index.js";
 /**
@@ -33,6 +34,7 @@ export class DebuggAIServerClient {
     tx;
     url;
     workflows;
+    tunnels;
     constructor(userApiKey) {
         this.userApiKey = userApiKey;
         // Note: init() is async and should be called separately
@@ -42,6 +44,7 @@ export class DebuggAIServerClient {
         this.url = new URL(serverUrl);
         this.tx = new DebuggTransport({ baseUrl: serverUrl, apiKey: this.userApiKey, tokenType: config.api.tokenType });
         this.workflows = createWorkflowsService(this.tx);
+        this.tunnels = createTunnelsService(this.tx);
     }
     /**
      * Revoke an ngrok API key by its key ID.

package/dist/services/ngrok/tunnelManager.js

@@ -1,18 +1,30 @@
 /**
  * Tunnel Management Service
- * Provides high-level tunnel management abstraction for localhost URLs
+ *
+ * Manages per-port ngrok tunnels with two layers of reuse:
+ *
+ *   1. Within-process  — activeTunnels map, 55-min auto-shutoff timer.
+ *   2. Cross-process   — file-backed RegistryStore so a second MCP instance
+ *                        on the same machine borrows an existing tunnel instead
+ *                        of provisioning a new one for the same port.
+ *
+ * Lifecycle:
+ *   - Owned tunnels  (isOwned=true)  : this process created them; it disconnects
+ *                                      and revokes the key on stop.
+ *   - Borrowed tunnels (isOwned=false): another process owns them; on stop we
+ *                                       only remove the local reference.
+ *   - Auto-shutoff timer checks the shared registry before firing: if another
+ *     process recently touched the entry the timer resets instead of stopping.
  */
 import { Logger } from '../../utils/logger.js';
 import { isLocalhostUrl, extractLocalhostPort, generateTunnelUrl } from '../../utils/urlParser.js';
 import { v4 as uuidv4 } from 'uuid';
-import { createRequire } from 'module';
-// Use createRequire to avoid ES module resolution issues
-const require = createRequire(import.meta.url);
+import { getDefaultRegistry, } from './tunnelRegistry.js';
 let ngrokModule = null;
 async function getNgrok() {
     if (!ngrokModule) {
         try {
-            ngrokModule = require('ngrok');
+            ngrokModule = await import('ngrok');
         }
         catch (error) {
             throw new Error(`Failed to load ngrok module: ${error}`);
@@ -21,103 +33,189 @@ async function getNgrok() {
     return ngrokModule;
 }
 const logger = new Logger({ module: 'tunnelManager' });
+// ── TunnelManager ─────────────────────────────────────────────────────────────
 class TunnelManager {
+    reg;
     activeTunnels = new Map();
     pendingTunnels = new Map();
     initialized = false;
-    TUNNEL_TIMEOUT_MS = 60 * 55 * 1000; // 55 minutes (we get billed by the hour, so dont want to run 1 min past the hour)
-    async ensureInitialized() {
-        if (!this.initialized) {
-            try {
-                const ngrok = await getNgrok();
-                // Try to get the API to check if ngrok is running
-                const api = ngrok.getApi();
-                if (!api) {
-                    logger.debug('ngrok API not available, may need to start first tunnel');
-                }
-                this.initialized = true;
-            }
-            catch (error) {
-                logger.debug(`ngrok initialization check: ${error}`);
-                this.initialized = true; // Continue anyway, let connection attempt handle the error
-            }
+    TUNNEL_TIMEOUT_MS = 55 * 60 * 1000;
+    constructor(reg = getDefaultRegistry()) {
+        this.reg = reg;
+    }
+    // ── Public API ──────────────────────────────────────────────────────────────
+    async processUrl(url, authToken, specificTunnelId, keyId, revokeKey) {
+        if (!isLocalhostUrl(url)) {
+            return { url, isLocalhost: false };
+        }
+        const port = extractLocalhostPort(url);
+        if (!port) {
+            throw new Error(`Could not extract port from localhost URL: ${url}`);
         }
+        if (!authToken) {
+            throw new Error('Auth token required to create tunnel for localhost URL');
+        }
+        const tunnelId = specificTunnelId || uuidv4();
+        return this.processPerPort(url, port, authToken, tunnelId, keyId, revokeKey);
     }
     /**
-     * Reset the auto-shutoff timer for a tunnel
+     * Return an active tunnel for the given local port, or undefined.
+     * For borrowed tunnels, evicts the entry if the owning process has died.
      */
-    resetTunnelTimer(tunnelInfo) {
-        // Clear existing timer
-        if (tunnelInfo.autoShutoffTimer) {
-            clearTimeout(tunnelInfo.autoShutoffTimer);
-        }
-        // Update last access time
-        tunnelInfo.lastAccessedAt = Date.now();
-        // Set new timer
-        tunnelInfo.autoShutoffTimer = setTimeout(async () => {
-            logger.info(`Auto-shutting down tunnel ${tunnelInfo.tunnelId} after 60 minutes of inactivity`);
-            try {
-                await this.stopTunnel(tunnelInfo.tunnelId);
-            }
-            catch (error) {
-                logger.error(`Failed to auto-shutdown tunnel ${tunnelInfo.tunnelId}:`, error);
+    getTunnelForPort(port) {
+        const existing = this.findTunnelByPort(port);
+        if (!existing)
+            return undefined;
+        if (!existing.isOwned) {
+            // Verify the owning process is still alive
+            const entry = this.reg.read()[String(port)];
+            if (!entry || !this.reg.isPidAlive(entry.ownerPid)) {
+                this.activeTunnels.delete(existing.tunnelId);
+                logger.info(`Evicted stale borrowed tunnel ${existing.tunnelId} (owner PID ${entry?.ownerPid} dead)`);
+                return undefined;
             }
-        }, this.TUNNEL_TIMEOUT_MS);
-        logger.debug(`Reset timer for tunnel ${tunnelInfo.tunnelId}, will auto-shutdown at ${new Date(tunnelInfo.lastAccessedAt + this.TUNNEL_TIMEOUT_MS).toISOString()}`);
+        }
+        return existing;
     }
-    /**
-     * Touch a tunnel to reset its timer (called when the tunnel is used)
-     */
     touchTunnel(tunnelId) {
         const tunnelInfo = this.activeTunnels.get(tunnelId);
-        if (tunnelInfo) {
-            this.resetTunnelTimer(tunnelInfo);
+        if (!tunnelInfo)
+            return;
+        // Refresh the shared registry entry so the owning process won't auto-shutoff
+        // while we're actively using the tunnel (even if we're borrowing it).
+        try {
+            const registry = this.reg.read();
+            const entry = registry[String(tunnelInfo.port)];
+            if (entry) {
+                entry.lastAccessedAt = Date.now();
+                this.reg.write(registry);
+            }
+        }
+        catch {
+            // best-effort
         }
+        this.resetTunnelTimer(tunnelInfo);
     }
-    /**
-     * Touch a tunnel by URL (convenience method)
-     */
     touchTunnelByUrl(url) {
         const tunnelId = this.extractTunnelId(url);
         if (tunnelId) {
             this.touchTunnel(tunnelId);
         }
     }
-    /**
-     * Process a URL and create a tunnel if needed
-     * Returns the URL to use (either original or tunneled) and tunnel metadata
-     */
-    async processUrl(url, authToken, specificTunnelId) {
-        if (!isLocalhostUrl(url)) {
-            return {
-                url,
-                isLocalhost: false
-            };
+    isTunnelUrl(url) {
+        return url.includes('.ngrok.debugg.ai');
+    }
+    extractTunnelId(url) {
+        const match = url.match(/https?:\/\/([^.]+)\.ngrok\.debugg\.ai/);
+        return match ? match[1] : null;
+    }
+    getTunnelInfo(tunnelId) {
+        return this.activeTunnels.get(tunnelId);
+    }
+    getActiveTunnels() {
+        return Array.from(this.activeTunnels.values());
+    }
+    async stopTunnel(tunnelId) {
+        const tunnelInfo = this.activeTunnels.get(tunnelId);
+        if (!tunnelInfo) {
+            logger.warn(`Tunnel ${tunnelId} not found for cleanup`);
+            return;
         }
-        const port = extractLocalhostPort(url);
-        if (!port) {
-            throw new Error(`Could not extract port from localhost URL: ${url}`);
+        if (tunnelInfo.autoShutoffTimer) {
+            clearTimeout(tunnelInfo.autoShutoffTimer);
+        }
+        this.activeTunnels.delete(tunnelId);
+        if (!tunnelInfo.isOwned) {
+            // Borrowed — just drop the local reference; owner manages the real tunnel
+            logger.info(`Released borrowed tunnel reference: ${tunnelInfo.publicUrl}`);
+            return;
+        }
+        // Owned — remove from shared registry, then disconnect + revoke
+        try {
+            const registry = this.reg.read();
+            delete registry[String(tunnelInfo.port)];
+            this.reg.write(registry);
+        }
+        catch {
+            // best-effort
+        }
+        try {
+            const ngrok = await getNgrok();
+            await ngrok.disconnect(tunnelInfo.tunnelUrl);
+            logger.info(`Cleaned up tunnel: ${tunnelInfo.publicUrl}`);
         }
-        // Check if we already have an active tunnel for this port
-        const existingTunnel = this.findTunnelByPort(port);
-        if (existingTunnel) {
-            const publicUrl = generateTunnelUrl(url, existingTunnel.tunnelId);
-            logger.info(`Reusing existing tunnel for port ${port}: ${publicUrl}`);
-            return { url: publicUrl, tunnelId: existingTunnel.tunnelId, isLocalhost: true };
+        catch (error) {
+            logger.warn(`ngrok.disconnect failed for tunnel ${tunnelId} (already cleaned up):`, error);
+        }
+        if (tunnelInfo.revokeKey) {
+            tunnelInfo.revokeKey().catch((err) => logger.warn(`Failed to revoke key for tunnel ${tunnelId}:`, err));
+        }
+    }
+    async stopAllTunnels() {
+        const ids = Array.from(this.activeTunnels.keys());
+        await Promise.all(ids.map((id) => this.stopTunnel(id).catch((err) => logger.error(`Failed to stop tunnel ${id}:`, err))));
+        logger.info(`Stopped ${ids.length} tunnel(s)`);
+    }
+    getTunnelStatus(tunnelId) {
+        const tunnel = this.activeTunnels.get(tunnelId);
+        if (!tunnel)
+            return null;
+        const now = Date.now();
+        return {
+            tunnel,
+            age: now - tunnel.createdAt,
+            timeSinceLastAccess: now - tunnel.lastAccessedAt,
+            timeUntilAutoShutoff: Math.max(0, tunnel.lastAccessedAt + this.TUNNEL_TIMEOUT_MS - now),
+        };
+    }
+    getAllTunnelStatuses() {
+        const statuses = [];
+        for (const tunnelId of this.activeTunnels.keys()) {
+            const status = this.getTunnelStatus(tunnelId);
+            if (status)
+                statuses.push(status);
+        }
+        return statuses;
+    }
+    // ── Per-port tunnel ─────────────────────────────────────────────────────────
+    async processPerPort(url, port, authToken, tunnelId, keyId, revokeKey) {
+        // 1. Check local in-process map (handles owned + borrowed with liveness check)
+        const existing = this.getTunnelForPort(port);
+        if (existing) {
+            logger.info(`Reusing existing tunnel for port ${port}: ${existing.publicUrl}`);
+            return { url: existing.publicUrl, tunnelId: existing.tunnelId, isLocalhost: true };
         }
-        // If a tunnel creation is already in-flight for this port, wait for it
+        // 2. Deduplicate concurrent creation requests for the same port
         const pending = this.pendingTunnels.get(port);
         if (pending) {
-            logger.info(`Waiting for in-flight tunnel creation for port ${port}`);
-            const tunnelInfo = await pending;
-            return { url: tunnelInfo.publicUrl, tunnelId: tunnelInfo.tunnelId, isLocalhost: true };
+            const info = await pending;
+            return { url: info.publicUrl, tunnelId: info.tunnelId, isLocalhost: true };
         }
-        // Create new tunnel
-        if (!authToken) {
-            throw new Error('Auth token required to create tunnel for localhost URL');
+        // 3. Check cross-process registry — another MCP instance may own a tunnel
+        const registry = this.reg.read();
+        const regEntry = registry[String(port)];
+        if (regEntry && this.reg.isPidAlive(regEntry.ownerPid)) {
+            logger.info(`Borrowing tunnel from PID ${regEntry.ownerPid} for port ${port}: ${regEntry.publicUrl}`);
+            const now = Date.now();
+            const borrowed = {
+                tunnelId: regEntry.tunnelId,
+                originalUrl: url,
+                tunnelUrl: regEntry.tunnelUrl,
+                publicUrl: regEntry.publicUrl,
+                port,
+                createdAt: now,
+                lastAccessedAt: now,
+                isOwned: false,
+            };
+            this.activeTunnels.set(regEntry.tunnelId, borrowed);
+            // Touch registry so the owner knows not to auto-shutoff
+            regEntry.lastAccessedAt = now;
+            this.reg.write(registry);
+            this.resetTunnelTimer(borrowed);
+            return { url: regEntry.publicUrl, tunnelId: regEntry.tunnelId, isLocalhost: true };
         }
-        const tunnelId = specificTunnelId || uuidv4();
-        const creationPromise = this.createTunnel(url, port, tunnelId, authToken);
+        // 4. Create a new tunnel (this process becomes the owner)
+        const creationPromise = this.createTunnel(url, port, tunnelId, authToken, keyId, revokeKey);
         this.pendingTunnels.set(port, creationPromise);
         let tunnelInfo;
         try {
@@ -126,90 +224,40 @@ class TunnelManager {
         finally {
             this.pendingTunnels.delete(port);
         }
-        return {
-            url: tunnelInfo.publicUrl,
-            tunnelId: tunnelInfo.tunnelId,
-            isLocalhost: true
-        };
+        return { url: tunnelInfo.publicUrl, tunnelId: tunnelInfo.tunnelId, isLocalhost: true };
     }
-    /**
-     * Check if a URL is a tunnel URL
-     */
-    isTunnelUrl(url) {
-        return url.includes('.ngrok.debugg.ai');
-    }
-    /**
-     * Extract tunnel ID from a tunnel URL
-     */
-    extractTunnelId(url) {
-        const match = url.match(/https?:\/\/([^.]+)\.ngrok\.debugg\.ai/);
-        return match ? match[1] : null;
-    }
-    /**
-     * Get tunnel info by ID
-     */
-    getTunnelInfo(tunnelId) {
-        return this.activeTunnels.get(tunnelId);
-    }
-    /**
-     * Find tunnel by port
-     */
     findTunnelByPort(port) {
         for (const tunnel of this.activeTunnels.values()) {
-            if (tunnel.port === port) {
+            if (tunnel.port === port)
                 return tunnel;
-            }
         }
         return undefined;
     }
-    /**
-     * Create a new tunnel
-     */
-    async createTunnel(originalUrl, port, tunnelId, authToken) {
+    async createTunnel(originalUrl, port, tunnelId, authToken, keyId, revokeKey) {
         await this.ensureInitialized();
         const tunnelDomain = `${tunnelId}.ngrok.debugg.ai`;
-        logger.info(`Creating tunnel for localhost:${port} with domain ${tunnelDomain}`);
+        logger.info(`Creating tunnel for localhost:${port} (domain: ${tunnelDomain})`);
+        const isHttpsLocal = originalUrl.startsWith('https:');
+        const inDocker = process.env.DOCKER_CONTAINER === 'true';
+        const dockerHost = 'host.docker.internal';
+        let localAddr;
+        if (isHttpsLocal) {
+            localAddr = inDocker ? `https://${dockerHost}:${port}` : `https://localhost:${port}`;
+        }
+        else {
+            localAddr = inDocker ? `${dockerHost}:${port}` : port;
+        }
         try {
-            // Get ngrok module dynamically
             const ngrok = await getNgrok();
-            // Set auth token first
-            logger.debug(`Setting ngrok auth token`);
-            await ngrok.authtoken({ authtoken: authToken });
-            // Create tunnel options
-            const tunnelOptions = {
+            const tunnelUrl = await ngrok.connect({
                 proto: 'http',
-                addr: process.env.DOCKER_CONTAINER === "true" ? `host.docker.internal:${port}` : port,
+                addr: localAddr,
                 hostname: tunnelDomain,
-                authtoken: authToken
-                // Don't override configPath - let ngrok use its default configuration
-            };
-            logger.debug(`Connecting tunnel with options: ${JSON.stringify({ ...tunnelOptions, authtoken: '[REDACTED]' })}`);
-            // For ngrok v5, we might need to handle the connection differently
-            let tunnelUrl;
-            try {
-                tunnelUrl = await ngrok.connect(tunnelOptions);
-            }
-            catch (connectError) {
-                // If connection fails due to ngrok not running, try with different options
-                if (connectError instanceof Error && connectError.message.includes('ECONNREFUSED')) {
-                    logger.info('ngrok daemon not running, attempting to start tunnel with minimal options');
-                    const minimalOptions = {
-                        proto: 'http',
-                        addr: process.env.DOCKER_CONTAINER === "true" ? `host.docker.internal:${port}` : port,
-                        authtoken: authToken
-                    };
-                    tunnelUrl = await ngrok.connect(minimalOptions);
-                }
-                else {
-                    throw connectError;
-                }
-            }
-            if (!tunnelUrl) {
-                throw new Error('Failed to create tunnel');
-            }
-            // Generate the public URL maintaining path, search, and hash from original
+                authtoken: authToken,
+            });
+            if (!tunnelUrl)
+                throw new Error('ngrok.connect() returned empty URL');
             const publicUrl = generateTunnelUrl(originalUrl, tunnelId);
-            // Store tunnel info
             const now = Date.now();
             const tunnelInfo = {
                 tunnelId,
@@ -218,101 +266,78 @@ class TunnelManager {
                 publicUrl,
                 port,
                 createdAt: now,
-                lastAccessedAt: now
+                lastAccessedAt: now,
+                isOwned: true,
+                keyId,
+                revokeKey,
             };
             this.activeTunnels.set(tunnelId, tunnelInfo);
-            // Start the auto-shutoff timer
+            // Register in shared cross-process registry
+            try {
+                const registry = this.reg.read();
+                registry[String(port)] = {
+                    tunnelId,
+                    publicUrl,
+                    tunnelUrl,
+                    port,
+                    ownerPid: process.pid,
+                    lastAccessedAt: now,
+                };
+                this.reg.write(registry);
+            }
+            catch {
+                // best-effort
+            }
             this.resetTunnelTimer(tunnelInfo);
-            logger.info(`Tunnel created: ${publicUrl} -> localhost:${port}`);
+            logger.info(`Tunnel created: ${publicUrl} → localhost:${port}`);
             return tunnelInfo;
         }
         catch (error) {
-            logger.error(`Failed to create tunnel for ${originalUrl}:`, error);
-            // Try to provide more helpful error messages
-            if (error instanceof Error && error.message.includes('ECONNREFUSED')) {
-                throw new Error(`Failed to create tunnel: ngrok daemon not running or connection refused. Original error: ${error.message}`);
-            }
-            else if (error instanceof Error && error.message.includes('authtoken')) {
-                throw new Error(`Failed to create tunnel: Invalid or missing auth token. Original error: ${error.message}`);
-            }
-            else {
-                throw new Error(`Failed to create tunnel: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            if (msg.includes('authtoken')) {
+                throw new Error(`Failed to create tunnel: invalid auth token. ${msg}`);
             }
+            throw new Error(`Failed to create tunnel: ${msg}`);
         }
     }
-    /**
-     * Stop a tunnel by ID
-     */
-    async stopTunnel(tunnelId) {
-        const tunnelInfo = this.activeTunnels.get(tunnelId);
-        if (!tunnelInfo) {
-            logger.warn(`Tunnel ${tunnelId} not found for cleanup`);
-            return;
-        }
-        try {
-            // Clear the auto-shutoff timer
-            if (tunnelInfo.autoShutoffTimer) {
-                clearTimeout(tunnelInfo.autoShutoffTimer);
+    // ── Helpers ─────────────────────────────────────────────────────────────────
+    async ensureInitialized() {
+        if (!this.initialized) {
+            try {
+                const ngrok = await getNgrok();
+                ngrok.getApi();
             }
-            const ngrok = await getNgrok();
-            await ngrok.disconnect(tunnelInfo.tunnelUrl);
-            this.activeTunnels.delete(tunnelId);
-            logger.info(`Cleaned up tunnel: ${tunnelInfo.publicUrl}`);
-        }
-        catch (error) {
-            logger.error(`Failed to cleanup tunnel ${tunnelId}:`, error);
-            throw error;
-        }
-    }
-    /**
-     * Stop all active tunnels
-     */
-    async stopAllTunnels() {
-        const tunnelIds = Array.from(this.activeTunnels.keys());
-        const cleanupPromises = tunnelIds.map(tunnelId => this.stopTunnel(tunnelId).catch(error => logger.error(`Failed to stop tunnel ${tunnelId}:`, error)));
-        await Promise.all(cleanupPromises);
-        logger.info(`Stopped ${tunnelIds.length} tunnels`);
-    }
-    /**
-     * Get all active tunnels
-     */
-    getActiveTunnels() {
-        return Array.from(this.activeTunnels.values());
-    }
-    /**
-     * Get tunnel status with timing information
-     */
-    getTunnelStatus(tunnelId) {
-        const tunnel = this.activeTunnels.get(tunnelId);
-        if (!tunnel) {
-            return null;
+            catch {
+                // ignore — let connect surface real errors
+            }
+            this.initialized = true;
         }
-        const now = Date.now();
-        const age = now - tunnel.createdAt;
-        const timeSinceLastAccess = now - tunnel.lastAccessedAt;
-        const timeUntilAutoShutoff = Math.max(0, (tunnel.lastAccessedAt + this.TUNNEL_TIMEOUT_MS) - now);
-        return {
-            tunnel,
-            age,
-            timeSinceLastAccess,
-            timeUntilAutoShutoff
-        };
     }
-    /**
-     * Get all tunnel statuses
-     */
-    getAllTunnelStatuses() {
-        const statuses = [];
-        for (const tunnelId of this.activeTunnels.keys()) {
-            const status = this.getTunnelStatus(tunnelId);
-            if (status) {
-                statuses.push(status);
+    resetTunnelTimer(tunnelInfo) {
+        if (tunnelInfo.autoShutoffTimer)
+            clearTimeout(tunnelInfo.autoShutoffTimer);
+        tunnelInfo.lastAccessedAt = Date.now();
+        tunnelInfo.autoShutoffTimer = setTimeout(async () => {
+            // For owned tunnels: if another process recently touched the registry entry,
+            // reset the timer rather than disconnecting — that process is still using it.
+            if (tunnelInfo.isOwned) {
+                try {
+                    const entry = this.reg.read()[String(tunnelInfo.port)];
+                    if (entry && Date.now() - entry.lastAccessedAt < this.TUNNEL_TIMEOUT_MS) {
+                        logger.info(`Tunnel ${tunnelInfo.tunnelId} accessed by another process — extending lifetime`);
+                        this.resetTunnelTimer(tunnelInfo);
+                        return;
+                    }
+                }
+                catch {
+                    // best-effort; proceed with shutoff
+                }
             }
-        }
-        return statuses;
+            logger.info(`Auto-shutting down tunnel ${tunnelInfo.tunnelId} after inactivity`);
+            await this.stopTunnel(tunnelInfo.tunnelId).catch((err) => logger.error(`Failed to auto-shutdown tunnel ${tunnelInfo.tunnelId}:`, err));
+        }, this.TUNNEL_TIMEOUT_MS);
     }
 }
-// Singleton instance
 const tunnelManager = new TunnelManager();
 export { tunnelManager };
 export default TunnelManager;

package/dist/services/ngrok/tunnelRegistry.js

@@ -0,0 +1,75 @@
+/**
+ * Cross-process tunnel registry.
+ *
+ * Lets multiple MCP server instances on the same machine discover and share
+ * ngrok tunnels instead of each provisioning a duplicate for the same port.
+ *
+ * The file registry uses an atomic rename-write so concurrent processes never
+ * see a partial JSON file.  All operations are best-effort — errors are
+ * swallowed so a broken registry never blocks tunnel creation.
+ */
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+// ── File-backed implementation (production) ───────────────────────────────────
+const REGISTRY_FILE = join(tmpdir(), 'debugg-ai-tunnels.json');
+export function createFileRegistry() {
+    return {
+        read() {
+            try {
+                if (!existsSync(REGISTRY_FILE))
+                    return {};
+                return JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));
+            }
+            catch {
+                return {};
+            }
+        },
+        write(data) {
+            const tmp = `${REGISTRY_FILE}.${process.pid}.tmp`;
+            try {
+                writeFileSync(tmp, JSON.stringify(data));
+                renameSync(tmp, REGISTRY_FILE);
+            }
+            catch {
+                // best-effort
+            }
+        },
+        isPidAlive(pid) {
+            return checkPid(pid);
+        },
+    };
+}
+// ── In-memory implementation (tests / injectable) ─────────────────────────────
+export function createInMemoryRegistry(isPidAliveImpl) {
+    let store = {};
+    return {
+        read: () => ({ ...store }),
+        write: (data) => { store = { ...data }; },
+        isPidAlive: isPidAliveImpl ?? checkPid,
+    };
+}
+// ── No-op implementation (tests that don't exercise registry) ─────────────────
+export const noopRegistry = {
+    read: () => ({}),
+    write: () => { },
+    isPidAlive: () => false,
+};
+// ── Default selection ─────────────────────────────────────────────────────────
+/**
+ * Returns the appropriate registry for the current environment.
+ * Tests (NODE_ENV=test) get the no-op registry; production gets file-backed.
+ */
+export function getDefaultRegistry() {
+    return process.env.NODE_ENV === 'test' ? noopRegistry : createFileRegistry();
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function checkPid(pid) {
+    try {
+        process.kill(pid, 0); // signal 0 = existence check, no signal sent
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/services/tunnels.js

@@ -0,0 +1,19 @@
+/**
+ * Tunnels Service
+ * Provisions short-lived ngrok keys for MCP-managed tunnel setup.
+ * Called before executeWorkflow so the tunnel URL is known before execution starts.
+ */
+export const createTunnelsService = (tx) => ({
+    async provision(purpose = 'workflow') {
+        const response = await tx.post('api/v1/tunnels/', { purpose });
+        if (!response?.tunnelId || !response?.tunnelKey) {
+            throw new Error('Tunnel provisioning failed: missing tunnelId or tunnelKey in response');
+        }
+        return {
+            tunnelId: response.tunnelId,
+            tunnelKey: response.tunnelKey,
+            keyId: response.keyId,
+            expiresAt: response.expiresAt,
+        };
+    },
+});

package/dist/services/workflows.js

@@ -31,9 +31,6 @@ export const createWorkflowsService = (tx) => {
             }
             return {
                 executionUuid: response.resourceUuid,
-                tunnelKey: response.tunnelKey ?? null,
-                ngrokKeyId: response.ngrokKeyId ?? null,
-                ngrokExpiresAt: response.ngrokExpiresAt ?? null,
                 resolvedEnvironmentId: response.resolvedEnvironmentId ?? null,
                 resolvedCredentialId: response.resolvedCredentialId ?? null,
             };

package/dist/tools/testPageChanges.js

@@ -21,13 +21,7 @@ export const testPageChangesTool = {
             },
             url: {
                 type: "string",
-                description: "Target URL for the browser agent to navigate to (e.g., 'https://example.com' or 'http://localhost:3000'). Use this for external URLs. For local dev servers, use localPort instead."
-            },
-            localPort: {
-                type: "number",
-                description: "Port of your local dev server (e.g. 3000, 8080). A secure tunnel is created automatically so the remote browser can reach it.",
-                minimum: 1,
-                maximum: 65535
+                description: "URL to navigate to. Accepts any URL including localhost (e.g. 'http://localhost:3000', 'https://example.com'). Localhost URLs are automatically tunneled so the remote browser can reach them."
             },
             environmentId: {
                 type: "string",
@@ -50,7 +44,7 @@ export const testPageChangesTool = {
                 description: "Password to log in with (used together with username)"
             },
         },
-        required: ["description"],
+        required: ["description", "url"],
         additionalProperties: false
     },
 };

package/dist/types/index.js

@@ -2,20 +2,20 @@
  * Comprehensive type definitions for DebuggAI MCP Server
  */
 import { z } from 'zod';
+import { normalizeUrl } from '../utils/urlParser.js';
 /**
  * Tool input validation schemas
  */
 export const TestPageChangesInputSchema = z.object({
     description: z.string().min(1, 'Description is required'),
-    url: z.string().url('Must be a valid URL').optional(),
-    localPort: z.number().int().min(1).max(65535).optional(),
+    url: z.preprocess(normalizeUrl, z.string().url('Must be a valid URL — accepts localhost (e.g. "http://localhost:3000") or any public URL')),
     // Credential/environment resolution
     environmentId: z.string().uuid().optional(),
     credentialId: z.string().uuid().optional(),
     credentialRole: z.string().optional(),
     username: z.string().optional(),
     password: z.string().optional(),
-}).refine((data) => data.url !== undefined || data.localPort !== undefined, { message: 'Provide a target via "url" (e.g. "https://example.com") or "localPort" for a local dev server' });
+});
 /**
  * Error types
  */

package/dist/utils/tunnelContext.js

@@ -2,24 +2,18 @@
  * Shared tunnel and URL resolution context used by all MCP tools.
  *
  * Centralizes:
- *  - resolving user input (url / localPort) to a concrete URL
+ *  - resolving user input url to a concrete URL
  *  - creating / reusing ngrok tunnels after the backend returns a tunnelKey
  *  - sanitizing backend responses so callers only ever see the original URL
  */
 import { tunnelManager } from '../services/ngrok/tunnelManager.js';
-import { isLocalhostUrl, replaceTunnelUrls } from './urlParser.js';
+import { isLocalhostUrl, replaceTunnelUrls, extractLocalhostPort } from './urlParser.js';
 // ─── URL resolution ──────────────────────────────────────────────────────────
 /**
  * Resolve tool input to a concrete URL string.
- * Accepts either a `url` string or a `localPort` number; throws if neither provided.
  */
 export function resolveTargetUrl(input) {
-    if (input.url)
-        return input.url;
-    if (input.localPort)
-        return `http://localhost:${input.localPort}`;
-    throw new Error('Provide a target URL via "url" (e.g. "https://example.com") ' +
-        'or "localPort" for a local dev server.');
+    return input.url;
 }
 /**
  * Build a TunnelContext for a resolved URL.
@@ -33,22 +27,41 @@ export function buildContext(originalUrl) {
 }
 // ─── Tunnel creation ─────────────────────────────────────────────────────────
 /**
- * Create (or reuse) a tunnel for a localhost URL.
+ * Check whether an active tunnel already exists for the same local port.
+ * If found, touches its timer and returns an enriched context pointing at it.
+ * Returns null for public URLs or when no tunnel is active for that port.
  *
- * Call this AFTER the backend returns a `tunnelKey` and `tunnelId`
- * (e.g. executionUuid from executeWorkflow, sessionId from startSession).
+ * Call this BEFORE provisioning a new key — if it returns a context, skip the provision.
+ */
+export function findExistingTunnel(ctx) {
+    if (!ctx.isLocalhost)
+        return null;
+    const port = extractLocalhostPort(ctx.originalUrl);
+    if (!port)
+        return null;
+    const existing = tunnelManager.getTunnelForPort(port);
+    if (!existing)
+        return null;
+    tunnelManager.touchTunnel(existing.tunnelId);
+    return { ...ctx, tunnelId: existing.tunnelId, targetUrl: existing.publicUrl };
+}
+/**
+ * Create (or reuse) a tunnel for a localhost URL.
  *
- * No-op and returns null for public URLs.
+ * Call this AFTER the backend returns a `tunnelKey` and `tunnelId`.
+ * No-op for public URLs.
  *
  * @param ctx       - Context built from `buildContext()`
  * @param tunnelKey - Auth token from the backend (short-lived ngrok key)
- * @param tunnelId  - ID to use as the ngrok subdomain (must match what the backend expects)
+ * @param tunnelId  - ID to use as the ngrok subdomain
+ * @param keyId     - Backend key ID; stored on the tunnel so it is revoked on stop
+ * @param revokeKey - Callback that revokes the backend key (called when tunnel stops)
  */
-export async function ensureTunnel(ctx, tunnelKey, tunnelId) {
+export async function ensureTunnel(ctx, tunnelKey, tunnelId, keyId, revokeKey) {
     if (!ctx.isLocalhost)
         return ctx;
-    const result = await tunnelManager.processUrl(ctx.originalUrl, tunnelKey, tunnelId);
-    return { ...ctx, tunnelId: result.tunnelId };
+    const result = await tunnelManager.processUrl(ctx.originalUrl, tunnelKey, tunnelId, keyId, revokeKey);
+    return { ...ctx, tunnelId: result.tunnelId, targetUrl: result.url };
 }
 /**
  * Stop the tunnel associated with a context (fire-and-forget safe).

package/dist/utils/urlParser.js

@@ -3,18 +3,37 @@
  * Helper functions for parsing and validating URLs, specifically for detecting localhost URLs
  */
 /**
- * Check if a hostname represents localhost
+ * Normalize a user-supplied URL string before validation.
+ * Handles bare hostnames without a scheme (e.g. "localhost:3000" → "http://localhost:3000").
+ */
+export function normalizeUrl(input) {
+    if (typeof input !== 'string')
+        return input;
+    if (/^https?:\/\//i.test(input))
+        return input;
+    // Bare local hostname (no scheme) — prepend http://
+    if (/^(localhost\.?|127\.0\.0\.1|0\.0\.0\.0|host\.docker\.internal|\[::1\])(:\d+)?(\/.*)?$/i.test(input)) {
+        return `http://${input}`;
+    }
+    return input;
+}
+/**
+ * Check if a hostname represents a local/tunnelable address.
  */
 function isLocalhostHostname(hostname) {
-    const lowercaseHostname = hostname.toLowerCase();
-    return (lowercaseHostname === 'localhost' ||
-        lowercaseHostname === '127.0.0.1' ||
-        lowercaseHostname === '::1' ||
-        lowercaseHostname.startsWith('192.168.') ||
-        lowercaseHostname.startsWith('10.') ||
-        (lowercaseHostname.startsWith('172.') &&
-            parseInt(lowercaseHostname.split('.')[1], 10) >= 16 &&
-            parseInt(lowercaseHostname.split('.')[1], 10) <= 31));
+    // Strip IPv6 brackets: new URL('http://[::1]:3000').hostname === '[::1]' in WHATWG spec
+    const h = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    return (h === 'localhost' ||
+        h === 'localhost.' || // trailing-dot FQDN notation
+        h === '127.0.0.1' ||
+        h === '::1' ||
+        h === '0.0.0.0' ||
+        h === 'host.docker.internal' ||
+        h.startsWith('192.168.') ||
+        h.startsWith('10.') ||
+        (h.startsWith('172.') &&
+            parseInt(h.split('.')[1], 10) >= 16 &&
+            parseInt(h.split('.')[1], 10) <= 31));
 }
 /**
  * Parse a URL and determine if it's a localhost URL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "1.0.31",
+  "version": "1.0.32",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {
@@ -24,7 +24,9 @@
     "version:minor": "npm version minor --no-git-tag-version",
     "version:major": "npm version major --no-git-tag-version",
     "publish:check": "npm pack --dry-run",
-    "prepublishOnly": "npm test && npm run build"
+    "prepublishOnly": "npm test && npm run build",
+    "mcp:local": "npm run build && claude mcp remove debugg-ai 2>/dev/null; claude mcp add debugg-ai -s user -e DEBUGGAI_API_KEY=KrvXlzVFXVZO82UErXye5N7CtnmBTu1GKULrJnwXRRU -- node /Users/qosha/Repos/debugg-ai/debugg-ai-mcp/dist/index.js",
+    "mcp:npm": "claude mcp remove debugg-ai 2>/dev/null; claude mcp add debugg-ai -s user -e DEBUGGAI_API_KEY=KrvXlzVFXVZO82UErXye5N7CtnmBTu1GKULrJnwXRRU -- npx -y @debugg-ai/debugg-ai-mcp"
   },
   "keywords": [
     "debugg",