@debugg-ai/debugg-ai-mcp 1.0.28 → 1.0.30

package/dist/handlers/index.js

@@ -1,6 +1 @@
-/**
- * Handler exports for DebuggAI MCP Server
- */
 export * from './testPageChangesHandler.js';
-export * from './e2eSuiteHandlers.js';
-export * from './liveSessionHandlers.js';

package/dist/handlers/testPageChangesHandler.js

@@ -8,38 +8,19 @@ 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 { tunnelManager } from '../services/ngrok/tunnelManager.js';
-import { extractLocalhostPort, replaceTunnelUrls } from '../utils/urlParser.js';
+import { resolveTargetUrl, buildContext, ensureTunnel, releaseTunnel, 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;
-function isLocalhostUrl(url) {
-    return url.includes('localhost') || url.includes('127.0.0.1');
-}
-/**
- * Resolve the target URL from input.
- * - If `url` is provided, use it directly.
- * - If only `localPort` is provided, construct http://localhost:{port}.
- * - Otherwise error.
- */
-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 the "url" parameter (e.g. "https://example.com") ' +
-        'or a "localPort" for a local dev server.');
-}
 export async function testPageChangesHandler(input, context, progressCallback) {
     const startTime = Date.now();
     logger.toolStart('check_app_in_browser', input);
     const client = new DebuggAIServerClient(config.api.key);
     await client.init();
-    let tunnelId;
+    const originalUrl = resolveTargetUrl(input);
+    let ctx = buildContext(originalUrl);
     let ngrokKeyId;
     try {
-        const targetUrlRaw = resolveTargetUrl(input);
-        const isLocalhost = isLocalhostUrl(targetUrlRaw);
         // --- Find workflow template ---
         if (progressCallback) {
             await progressCallback({ progress: 1, total: 10, message: 'Locating evaluation workflow template...' });
@@ -55,7 +36,7 @@ export async function testPageChangesHandler(input, context, progressCallback) {
         }
         // --- Build context data ---
         const contextData = {
-            targetUrl: targetUrlRaw,
+            targetUrl: originalUrl,
             goal: input.description,
         };
         // --- Build env (credentials/environment) ---
@@ -78,37 +59,39 @@ export async function testPageChangesHandler(input, context, progressCallback) {
         const executionUuid = executeResponse.executionUuid;
         ngrokKeyId = executeResponse.ngrokKeyId ?? undefined;
         logger.info(`Execution queued: ${executionUuid}`);
-        // --- Localhost tunneling (after execute, using tunnel_key + executionUuid as subdomain) ---
-        if (isLocalhost) {
+        // --- 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...' });
             }
-            const port = extractLocalhostPort(targetUrlRaw);
-            if (!port) {
-                throw new Error(`Could not extract port from localhost URL: ${targetUrlRaw}`);
-            }
             if (!executeResponse.tunnelKey) {
                 throw new Error('Backend did not return a tunnel key for localhost execution');
             }
-            tunnelId = executionUuid;
-            const tunnelResult = await tunnelManager.processUrl(targetUrlRaw, executeResponse.tunnelKey, tunnelId);
-            logger.info(`Tunnel ready: ${tunnelResult.url}`);
+            ctx = await ensureTunnel(ctx, executeResponse.tunnelKey, executionUuid);
+            logger.info(`Tunnel ready for ${originalUrl} (id: ${executionUuid})`);
         }
         // --- Poll ---
-        let lastSteps = 0;
+        // nodeExecutions grows as each node completes: trigger → browser.setup → surfer.execute_task → browser.teardown
+        const NODE_PHASE_LABELS = {
+            0: 'Browser agent starting up...',
+            1: 'Browser ready, agent navigating...',
+            2: 'Agent evaluating app...',
+            3: 'Wrapping up...',
+        };
+        let lastNodeCount = 0;
         const finalExecution = await client.workflows.pollExecution(executionUuid, async (exec) => {
-            const steps = exec.state?.stepsTaken ?? 0;
-            if (steps !== lastSteps || exec.status !== 'pending') {
-                lastSteps = steps;
-                logger.info(`Execution status: ${exec.status}, steps: ${steps}`);
+            const nodeCount = exec.nodeExecutions?.length ?? 0;
+            if (nodeCount !== lastNodeCount || exec.status !== 'pending') {
+                lastNodeCount = nodeCount;
+                logger.info(`Execution status: ${exec.status}, nodes completed: ${nodeCount}`);
             }
             if (progressCallback) {
-                const progress = Math.min(3 + steps, 9);
-                await progressCallback({
-                    progress,
-                    total: 10,
-                    message: `${exec.status}: ${steps} step${steps !== 1 ? 's' : ''} taken`,
-                }).catch(() => { });
+                // Map 0-4 completed nodes to progress 3-9 (3 reserved for tunnel setup)
+                const progress = Math.min(3 + nodeCount * 2, 9);
+                const message = exec.status === 'running'
+                    ? (NODE_PHASE_LABELS[nodeCount] ?? 'Agent working...')
+                    : exec.status;
+                await progressCallback({ progress, total: 10, message });
             }
         });
         const duration = Date.now() - startTime;
@@ -120,30 +103,22 @@ export async function testPageChangesHandler(input, context, progressCallback) {
             success: finalExecution.state?.success ?? false,
             status: finalExecution.status,
             stepsTaken: finalExecution.state?.stepsTaken ?? surferNode?.outputData?.stepsTaken ?? 0,
-            targetUrl: targetUrlRaw,
+            targetUrl: originalUrl,
             executionId: executionUuid,
             durationMs: finalExecution.durationMs ?? duration,
         };
-        if (finalExecution.state?.error) {
+        if (finalExecution.state?.error)
             responsePayload.agentError = finalExecution.state.error;
-        }
-        if (finalExecution.errorMessage) {
+        if (finalExecution.errorMessage)
             responsePayload.errorMessage = finalExecution.errorMessage;
-        }
-        if (finalExecution.errorInfo?.failedNodeId) {
+        if (finalExecution.errorInfo?.failedNodeId)
             responsePayload.failedNode = finalExecution.errorInfo.failedNodeId;
-        }
-        if (executeResponse.resolvedEnvironmentId) {
+        if (executeResponse.resolvedEnvironmentId)
             responsePayload.resolvedEnvironmentId = executeResponse.resolvedEnvironmentId;
-        }
-        if (executeResponse.resolvedCredentialId) {
+        if (executeResponse.resolvedCredentialId)
             responsePayload.resolvedCredentialId = executeResponse.resolvedCredentialId;
-        }
         if (surferNode?.outputData) {
-            const surferOutput = isLocalhost
-                ? replaceTunnelUrls(surferNode.outputData, new URL(targetUrlRaw).origin)
-                : surferNode.outputData;
-            responsePayload.surferOutput = surferOutput;
+            responsePayload.surferOutput = sanitizeResponseUrls(surferNode.outputData, ctx);
         }
         logger.toolComplete('check_app_in_browser', duration);
         if (progressCallback) {
@@ -171,20 +146,15 @@ export async function testPageChangesHandler(input, context, progressCallback) {
     catch (error) {
         const duration = Date.now() - startTime;
         logger.toolError('check_app_in_browser', error, duration);
-        // Invalidate cached template UUID on auth/not-found errors
         if (error instanceof Error && (error.message.includes('not found') || error.message.includes('401'))) {
             cachedTemplateUuid = null;
         }
         throw handleExternalServiceError(error, 'DebuggAI', 'test execution');
     }
     finally {
-        // Revoke the short-lived ngrok key
         if (ngrokKeyId) {
             client.revokeNgrokKey(ngrokKeyId).catch(err => logger.warn(`Failed to revoke ngrok key ${ngrokKeyId}: ${err}`));
         }
-        // Clean up tunnel if we created one
-        if (tunnelId) {
-            tunnelManager.stopTunnel(tunnelId).catch(err => logger.warn(`Failed to stop tunnel ${tunnelId}: ${err}`));
-        }
+        releaseTunnel(ctx).catch(err => logger.warn(`Failed to stop tunnel: ${err}`));
     }
 }

package/dist/services/index.js

@@ -1,5 +1,3 @@
-import { createE2esService } from "./e2es.js";
-import { createBrowserSessionsService } from "./browserSessions.js";
 import { createWorkflowsService } from "./workflows.js";
 import { AxiosTransport } from "../utils/axiosTransport.js";
 import { config } from "../config/index.js";
@@ -34,9 +32,6 @@ export class DebuggAIServerClient {
     userApiKey;
     tx;
     url;
-    // Public "sub‑APIs"
-    e2es;
-    browserSessions;
     workflows;
     constructor(userApiKey) {
         this.userApiKey = userApiKey;
@@ -46,8 +41,6 @@ export class DebuggAIServerClient {
         const serverUrl = config.api.baseUrl;
         this.url = new URL(serverUrl);
         this.tx = new DebuggTransport({ baseUrl: serverUrl, apiKey: this.userApiKey, tokenType: config.api.tokenType });
-        this.e2es = createE2esService(this.tx);
-        this.browserSessions = createBrowserSessionsService(this.tx);
         this.workflows = createWorkflowsService(this.tx);
     }
     /**

package/dist/tools/index.js

@@ -1,61 +1,17 @@
-/**
- * Tool registry and exports
- * Centralized location for all DebuggAI MCP tool definitions
- *
- * These tools provide AI agents with:
- * - Live remote browser sessions for real-time monitoring
- * - End-to-end testing with natural language descriptions
- * - Browser console logs, network traffic, and screenshot capture
- * - Test suite management and Git commit-based test generation
- */
 import { testPageChangesTool, validatedTestPageChangesTool } from './testPageChanges.js';
-import { startLiveSessionTool, stopLiveSessionTool, getLiveSessionStatusTool, getLiveSessionLogsTool, getLiveSessionScreenshotTool, validatedLiveSessionTools } from './liveSession.js';
-import { listTestsTool, listTestSuitesTool, createTestSuiteTool, createCommitSuiteTool, listCommitSuitesTool, getTestStatusTool, validatedE2ESuiteTools } from './e2eSuites.js';
-import { quickScreenshotTool, validatedQuickScreenshotTool } from './quickScreenshot.js';
-/**
- * All available tools for MCP server
- */
 export const tools = [
     testPageChangesTool,
-    startLiveSessionTool,
-    stopLiveSessionTool,
-    getLiveSessionStatusTool,
-    getLiveSessionLogsTool,
-    getLiveSessionScreenshotTool,
-    listTestsTool,
-    listTestSuitesTool,
-    createTestSuiteTool,
-    createCommitSuiteTool,
-    listCommitSuitesTool,
-    getTestStatusTool,
-    quickScreenshotTool,
 ];
-/**
- * All validated tools with handlers
- */
 export const validatedTools = [
     validatedTestPageChangesTool,
-    ...validatedLiveSessionTools,
-    ...validatedE2ESuiteTools,
-    validatedQuickScreenshotTool,
 ];
-/**
- * Tool registry for quick lookup
- */
 export const toolRegistry = new Map();
-// Initialize tool registry
 for (const tool of validatedTools) {
     toolRegistry.set(tool.name, tool);
 }
-/**
- * Get tool by name
- */
 export function getTool(name) {
     return toolRegistry.get(name);
 }
-/**
- * Check if tool exists
- */
 export function hasToolTool(name) {
     return toolRegistry.has(name);
 }

package/dist/utils/tunnelContext.js

@@ -0,0 +1,73 @@
+/**
+ * Shared tunnel and URL resolution context used by all MCP tools.
+ *
+ * Centralizes:
+ *  - resolving user input (url / localPort) 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';
+// ─── 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.');
+}
+/**
+ * Build a TunnelContext for a resolved URL.
+ * Call this right after resolving the target URL — before any backend call.
+ */
+export function buildContext(originalUrl) {
+    return {
+        originalUrl,
+        isLocalhost: isLocalhostUrl(originalUrl),
+    };
+}
+// ─── Tunnel creation ─────────────────────────────────────────────────────────
+/**
+ * Create (or reuse) a tunnel for a localhost URL.
+ *
+ * Call this AFTER the backend returns a `tunnelKey` and `tunnelId`
+ * (e.g. executionUuid from executeWorkflow, sessionId from startSession).
+ *
+ * No-op and returns null 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)
+ */
+export async function ensureTunnel(ctx, tunnelKey, tunnelId) {
+    if (!ctx.isLocalhost)
+        return ctx;
+    const result = await tunnelManager.processUrl(ctx.originalUrl, tunnelKey, tunnelId);
+    return { ...ctx, tunnelId: result.tunnelId };
+}
+/**
+ * Stop the tunnel associated with a context (fire-and-forget safe).
+ */
+export async function releaseTunnel(ctx) {
+    if (ctx.tunnelId) {
+        await tunnelManager.stopTunnel(ctx.tunnelId);
+    }
+}
+// ─── Response sanitization ───────────────────────────────────────────────────
+/**
+ * Replace any tunnel URLs in a backend response with the original localhost origin.
+ * No-op when the original URL was not localhost.
+ *
+ * Handles nested objects, arrays, and strings recursively.
+ */
+export function sanitizeResponseUrls(value, ctx) {
+    if (!ctx.isLocalhost)
+        return value;
+    const origin = new URL(ctx.originalUrl).origin;
+    return replaceTunnelUrls(value, origin);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {
@@ -18,6 +18,8 @@
     "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
     "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js --config jest.integration.config.js",
     "test:integration:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --config jest.integration.config.js --watch",
+    "test:e2e": "node scripts/e2e.mjs",
+    "test:e2e:skip-build": "node scripts/e2e.mjs --skip-build",
     "version:patch": "npm version patch --no-git-tag-version",
     "version:minor": "npm version minor --no-git-tag-version",
     "version:major": "npm version major --no-git-tag-version",