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

package/README.md

@@ -1,42 +1,14 @@
-# Official MCP Server for Debugg AI
+# Debugg AI — MCP Server
 
-**AI-powered browser testing and monitoring** via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Gives AI agents the ability to run end-to-end browser tests, monitor live sessions, and validate UI changes against your running application.
+AI-powered browser testing via the [Model Context Protocol](https://modelcontextprotocol.io). Point it at any URL (or localhost) and describe what to test — an AI agent browses your app and returns pass/fail with screenshots.
 
 <a href="https://glama.ai/mcp/servers/@debugg-ai/debugg-ai-mcp">
   <img width="380" height="200" src="https://glama.ai/mcp/servers/@debugg-ai/debugg-ai-mcp/badge" alt="Debugg AI MCP server" />
 </a>
 
----
-
-## What it does
-
-- **Run browser tests with natural language** — describe what to test, the AI agent clicks through your app and returns screenshots + results
-- **Monitor live browser sessions** — capture console logs, network requests, and screenshots in real time
-- **Manage test suites** — create, organize, and track E2E tests tied to features or commits
-- **Seamless CI/CD** — view all results in your [Debugg.AI dashboard](https://app.debugg.ai)
-
----
-
-## Demo
-
-### Prompt: "Test the ability to create an account and login"
-
-![Test Create Account and Login](/assets/recordings/test-create-account-login.gif)
-
-**Result:**
-- Duration: 86.80 seconds
-- Status: Success — signed up and logged in with `alice.wonderland1234@example.com`
+## Setup
 
-> [Full Use Case Demo](https://debugg.ai/demo)
-
----
-
-## Quick Setup
-
-### 1. Get your API key
-Create a free account at [debugg.ai](https://debugg.ai) and generate your API key.
-
-### 2. Add to Claude Desktop
+Get an API key at [debugg.ai](https://debugg.ai), then add to your MCP client config:
 
 ```json
 {
@@ -52,101 +24,42 @@ Create a free account at [debugg.ai](https://debugg.ai) and generate your API ke
 }
 ```
 
-**Or with Docker:**
+Or with Docker:
+
 ```bash
-docker run -i --rm --init \
-  -e DEBUGGAI_API_KEY=your_api_key \
-  quinnosha/debugg-ai-mcp
+docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-mcp
 ```
 
----
+## `check_app_in_browser`
 
-## Tools
-
-### E2E Testing
-| Tool | Description |
-|------|-------------|
-| `check_app_in_browser` | Run a browser test with a natural language description. Returns screenshots and pass/fail result. |
-| `create_test_suite` | Generate a suite of browser tests for a feature or workflow |
-| `create_commit_suite` | Auto-generate tests from recent git commits |
-| `get_test_status` | Check progress and results of a running or completed test suite |
-
-### Test Management
-| Tool | Description |
-|------|-------------|
-| `list_tests` | List all E2E tests with filtering and pagination |
-| `list_test_suites` | List all test suites |
-| `list_commit_suites` | List all commit-based test suites |
-
-### Live Session Monitoring
-| Tool | Description |
-|------|-------------|
-| `start_live_session` | Launch a remote browser session with real-time monitoring |
-| `stop_live_session` | Stop an active session and save captured data |
-| `get_live_session_status` | Check session status, current URL, and uptime |
-| `get_live_session_logs` | Retrieve console logs, network requests, and JS errors |
-| `get_live_session_screenshot` | Capture a screenshot of what the browser currently shows |
-
-### Quick Operations
-| Tool | Description |
-|------|-------------|
-| `quick_screenshot` | Capture a screenshot of any URL — no session setup required |
+Runs an AI browser agent against your app. The agent navigates, interacts, and reports back with screenshots.
 
----
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `description` | string **required** | What to test (natural language) |
+| `url` | string | Target URL — required if `localPort` not set |
+| `localPort` | number | Local dev server port — tunnel created automatically |
+| `environmentId` | string | UUID of a specific environment |
+| `credentialId` | string | UUID of a specific credential |
+| `credentialRole` | string | Pick a credential by role (e.g. `admin`, `guest`) |
+| `username` | string | Username for login |
+| `password` | string | Password for login |
 
 ## Configuration
 
 ```bash
-# Required
 DEBUGGAI_API_KEY=your_api_key
-
-# Optional — provide defaults so you don't have to pass them every time
-DEBUGGAI_LOCAL_PORT=3000                    # Your app's local port
-DEBUGGAI_LOCAL_REPO_NAME=your-org/repo      # GitHub repo name
-DEBUGGAI_LOCAL_REPO_PATH=/path/to/project   # Absolute path to project root
-DEBUGGAI_LOCAL_BRANCH_NAME=main             # Current branch
-
-# Override API endpoint (defaults to https://api.debugg.ai)
-DEBUGGAI_API_URL=https://api.debugg.ai
 ```
 
----
-
-## Usage examples
-
-```
-"Test the user login flow on my app running on port 3000"
-
-"Check that the checkout process works end to end"
-
-"Take a screenshot of localhost:3000 and tell me if anything looks broken"
-
-"Create a test suite for the user authentication feature"
-
-"Generate browser tests for my last 3 commits"
-```
-
----
-
 ## Local Development
 
 ```bash
-npm install
-npm test
-npm run build
-
-# Test with MCP inspector
-npx @modelcontextprotocol/inspector --config test-config.json --server debugg-ai
+npm install && npm test && npm run build
 ```
 
----
-
 ## Links
 
-- **Dashboard**: [app.debugg.ai](https://app.debugg.ai)
-- **Docs**: [debugg.ai/docs](https://debugg.ai/docs)
-- **Issues**: [GitHub Issues](https://github.com/debugg-ai/debugg-ai-mcp/issues)
-- **Discord**: [debugg.ai/discord](https://debugg.ai/discord)
+[Dashboard](https://app.debugg.ai) · [Docs](https://debugg.ai/docs) · [Issues](https://github.com/debugg-ai/debugg-ai-mcp/issues) · [Discord](https://debugg.ai/discord)
 
 ---
 

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,11 +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();
@@ -34,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) ---
@@ -53,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 = {
@@ -93,11 +102,22 @@ export async function testPageChangesHandler(input, context, progressCallback) {
                     : exec.status;
                 await progressCallback({ progress, total: 10, message });
             }
-        });
+        }, abortController.signal);
         const duration = Date.now() - startTime;
         // --- 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,
@@ -127,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'));
@@ -152,9 +196,14 @@ export async function testPageChangesHandler(input, context, progressCallback) {
         throw handleExternalServiceError(error, 'DebuggAI', 'test execution');
     }
     finally {
-        if (ngrokKeyId) {
-            client.revokeNgrokKey(ngrokKeyId).catch(err => logger.warn(`Failed to revoke ngrok key ${ngrokKeyId}: ${err}`));
+        process.stdin.removeListener('close', onStdinClose);
+        // 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.