@debugg-ai/debugg-ai-mcp 2.6.0 → 2.8.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added — E2E test suite management (8 new MCP tools)
+
+Eight new tools for building and managing automated E2E test suites directly via MCP:
+
+- `create_test_suite` — Create a named test suite for a project
+- `search_test_suites` — List/search suites for a project with pagination and text filter
+- `delete_test_suite` — Soft-delete (disable) a test suite
+- `create_test_case` — Create a test case assigned to a suite (no auto-run)
+- `update_test_case` — Update a test case's name, description, or agent task description
+- `delete_test_case` — Soft-delete (disable) a test case
+- `run_test_suite` — Trigger all test cases in a suite asynchronously
+- `get_test_suite_results` — Fetch suite with per-test pass/fail outcomes and run history
+
+All tools support name-based resolution (projectName, suiteName) with the same case-insensitive exact-match + ambiguity handling as existing tools. All backed by `/api/v1/test-suites/` and `/api/v1/e2e-tests/` endpoints on the DebuggAI backend. 80 new unit + integration tests added.
+
 ### Fixed — MCP now validates local reachability BEFORE hitting the backend (fixes 5-min false-pass regression)
 
 - `check_app_in_browser` and `trigger_crawl` now do a pre-flight TCP probe to `127.0.0.1:<port>` before provisioning a backend tunnel key. If the dev server isn't listening, we return a structured `LocalServerUnreachable` error in ~ms instead of letting the browser agent burn its 5-minute step budget on `ERR_NGROK_8012`. Bead `1om`.

package/dist/handlers/createTestCaseHandler.js

@@ -0,0 +1,46 @@
+import { Logger } from '../utils/logger.js';
+import { handleExternalServiceError } from '../utils/errors.js';
+import { DebuggAIServerClient } from '../services/index.js';
+import { config } from '../config/index.js';
+import { resolveProject, resolveTestSuite } from '../utils/resolveProject.js';
+const logger = new Logger({ module: 'createTestCaseHandler' });
+function errorResp(error, message, extra = {}) {
+    return { content: [{ type: 'text', text: JSON.stringify({ error, message, ...extra }, null, 2) }], isError: true };
+}
+export async function createTestCaseHandler(input, _context) {
+    const start = Date.now();
+    logger.toolStart('create_test_case', input);
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        let projectUuid = input.projectUuid;
+        if (!projectUuid) {
+            const resolved = await resolveProject(client, input.projectName);
+            if ('error' in resolved)
+                return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+            projectUuid = resolved.uuid;
+        }
+        let suiteUuid = input.suiteUuid;
+        if (!suiteUuid) {
+            const resolved = await resolveTestSuite(client, input.suiteName, projectUuid);
+            if ('error' in resolved)
+                return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+            suiteUuid = resolved.uuid;
+        }
+        const testCase = await client.createTestCase({
+            name: input.name,
+            description: input.description,
+            agentTaskDescription: input.agentTaskDescription,
+            suiteUuid,
+            projectUuid,
+            relativeUrl: input.relativeUrl,
+            maxSteps: input.maxSteps,
+        });
+        logger.toolComplete('create_test_case', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(testCase, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('create_test_case', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'create_test_case');
+    }
+}

package/dist/handlers/createTestSuiteHandler.js

@@ -0,0 +1,31 @@
+import { Logger } from '../utils/logger.js';
+import { handleExternalServiceError } from '../utils/errors.js';
+import { DebuggAIServerClient } from '../services/index.js';
+import { config } from '../config/index.js';
+import { resolveProject } from '../utils/resolveProject.js';
+const logger = new Logger({ module: 'createTestSuiteHandler' });
+function errorResp(error, message, extra = {}) {
+    return { content: [{ type: 'text', text: JSON.stringify({ error, message, ...extra }, null, 2) }], isError: true };
+}
+export async function createTestSuiteHandler(input, _context) {
+    const start = Date.now();
+    logger.toolStart('create_test_suite', input);
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        let projectUuid = input.projectUuid;
+        if (!projectUuid) {
+            const resolved = await resolveProject(client, input.projectName);
+            if ('error' in resolved)
+                return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+            projectUuid = resolved.uuid;
+        }
+        const suite = await client.createTestSuite({ name: input.name, description: input.description, projectUuid });
+        logger.toolComplete('create_test_suite', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(suite, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('create_test_suite', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'create_test_suite');
+    }
+}

package/dist/handlers/deleteTestCaseHandler.js

@@ -0,0 +1,20 @@
+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: 'deleteTestCaseHandler' });
+export async function deleteTestCaseHandler(input, _context) {
+    const start = Date.now();
+    logger.toolStart('delete_test_case', input);
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        await client.disableTestCase(input.testUuid);
+        logger.toolComplete('delete_test_case', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify({ deleted: true, testUuid: input.testUuid }, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('delete_test_case', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'delete_test_case');
+    }
+}

package/dist/handlers/deleteTestSuiteHandler.js

@@ -0,0 +1,38 @@
+import { Logger } from '../utils/logger.js';
+import { handleExternalServiceError } from '../utils/errors.js';
+import { DebuggAIServerClient } from '../services/index.js';
+import { config } from '../config/index.js';
+import { resolveProject, resolveTestSuite } from '../utils/resolveProject.js';
+const logger = new Logger({ module: 'deleteTestSuiteHandler' });
+function errorResp(error, message, extra = {}) {
+    return { content: [{ type: 'text', text: JSON.stringify({ error, message, ...extra }, null, 2) }], isError: true };
+}
+export async function deleteTestSuiteHandler(input, _context) {
+    const start = Date.now();
+    logger.toolStart('delete_test_suite', input);
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        let suiteUuid = input.suiteUuid;
+        if (!suiteUuid) {
+            let projectUuid = input.projectUuid;
+            if (!projectUuid) {
+                const resolved = await resolveProject(client, input.projectName);
+                if ('error' in resolved)
+                    return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+                projectUuid = resolved.uuid;
+            }
+            const resolved = await resolveTestSuite(client, input.suiteName, projectUuid);
+            if ('error' in resolved)
+                return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+            suiteUuid = resolved.uuid;
+        }
+        await client.disableTestSuite(suiteUuid);
+        logger.toolComplete('delete_test_suite', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify({ deleted: true, suiteUuid }, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('delete_test_suite', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'delete_test_suite');
+    }
+}

package/dist/handlers/getTestSuiteResultsHandler.js

@@ -0,0 +1,38 @@
+import { Logger } from '../utils/logger.js';
+import { handleExternalServiceError } from '../utils/errors.js';
+import { DebuggAIServerClient } from '../services/index.js';
+import { config } from '../config/index.js';
+import { resolveProject, resolveTestSuite } from '../utils/resolveProject.js';
+const logger = new Logger({ module: 'getTestSuiteResultsHandler' });
+function errorResp(error, message, extra = {}) {
+    return { content: [{ type: 'text', text: JSON.stringify({ error, message, ...extra }, null, 2) }], isError: true };
+}
+export async function getTestSuiteResultsHandler(input, _context) {
+    const start = Date.now();
+    logger.toolStart('get_test_suite_results', input);
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        let suiteUuid = input.suiteUuid;
+        if (!suiteUuid) {
+            let projectUuid = input.projectUuid;
+            if (!projectUuid) {
+                const resolved = await resolveProject(client, input.projectName);
+                if ('error' in resolved)
+                    return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+                projectUuid = resolved.uuid;
+            }
+            const resolved = await resolveTestSuite(client, input.suiteName, projectUuid);
+            if ('error' in resolved)
+                return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+            suiteUuid = resolved.uuid;
+        }
+        const detail = await client.getTestSuiteDetail(suiteUuid);
+        logger.toolComplete('get_test_suite_results', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(detail, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('get_test_suite_results', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'get_test_suite_results');
+    }
+}

package/dist/handlers/index.js

@@ -11,3 +11,11 @@ export * from './deleteEnvironmentHandler.js';
 export * from './updateProjectHandler.js';
 export * from './deleteProjectHandler.js';
 export * from './createProjectHandler.js';
+export * from './createTestSuiteHandler.js';
+export * from './searchTestSuitesHandler.js';
+export * from './deleteTestSuiteHandler.js';
+export * from './createTestCaseHandler.js';
+export * from './updateTestCaseHandler.js';
+export * from './deleteTestCaseHandler.js';
+export * from './runTestSuiteHandler.js';
+export * from './getTestSuiteResultsHandler.js';

package/dist/handlers/probePageHandler.js

@@ -24,6 +24,7 @@ import { extractLocalhostPort } from '../utils/urlParser.js';
 import { buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 import { getCachedTemplateUuid, invalidateTemplateCache } from '../utils/handlerCaches.js';
 import { reaggregateByOriginPath, mapConsoleSlice } from '../utils/harSummarizer.js';
+import { fetchImageAsBase64, imageContentBlock } from '../utils/imageUtils.js';
 const logger = new Logger({ module: 'probePageHandler' });
 const TEMPLATE_KEYWORD = 'page probe';
 export async function probePageHandler(input, context, rawProgressCallback) {
@@ -256,12 +257,6 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                 result.surferPageUuid = data.surferPageUuid;
             }
             results.push(result);
-            // Backend stores screenshots on the SurferPage row referenced by
-            // surfer_page_uuid; the inline screenshotB64 is no longer in capture
-            // output. v1: skip the per-result image content block; the screenshot
-            // is reachable via search_executions detail's surfer_page_uuid → SurferPage.
-            // (Future enhancement: fetch the SurferPage's presigned screenshot_url
-            // when input.captureScreenshots is true.)
         }
         const responsePayload = {
             executionId: executionUuid,
@@ -284,11 +279,35 @@ export async function probePageHandler(input, context, rawProgressCallback) {
             }
         }
         logger.toolComplete('probe_page', duration);
-        return {
-            content: [
-                { type: 'text', text: JSON.stringify(sanitizedPayload, null, 2) },
-            ],
-        };
+        const responseContent = [
+            { type: 'text', text: JSON.stringify(sanitizedPayload, null, 2) },
+        ];
+        // Embed screenshots when captureScreenshots is true. The backend may return
+        // screenshotB64 or a URL-keyed field on browser.capture outputData.
+        if (input.captureScreenshots) {
+            const SCREENSHOT_URL_KEYS = ['screenshotB64', 'screenshot', 'screenshotUrl', 'screenshotUri', 'finalScreenshot'];
+            for (const node of captureNodes) {
+                const data = node?.outputData ?? {};
+                if (typeof data.screenshotB64 === 'string' && data.screenshotB64) {
+                    responseContent.push(imageContentBlock(data.screenshotB64, 'image/png'));
+                }
+                else {
+                    let screenshotUrl = null;
+                    for (const key of SCREENSHOT_URL_KEYS) {
+                        if (key !== 'screenshotB64' && typeof data[key] === 'string' && data[key]) {
+                            screenshotUrl = data[key];
+                            break;
+                        }
+                    }
+                    if (screenshotUrl) {
+                        const img = await fetchImageAsBase64(screenshotUrl).catch(() => null);
+                        if (img)
+                            responseContent.push(imageContentBlock(img.data, img.mimeType));
+                    }
+                }
+            }
+        }
+        return { content: responseContent };
     }
     catch (error) {
         const duration = Date.now() - startTime;

package/dist/handlers/runTestSuiteHandler.js

@@ -0,0 +1,116 @@
+import { Logger } from '../utils/logger.js';
+import { handleExternalServiceError } from '../utils/errors.js';
+import { DebuggAIServerClient } from '../services/index.js';
+import { TunnelProvisionError } from '../services/tunnels.js';
+import { tunnelManager } from '../services/ngrok/tunnelManager.js';
+import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
+import { extractLocalhostPort } from '../utils/urlParser.js';
+import { buildContext, findExistingTunnel, ensureTunnel } from '../utils/tunnelContext.js';
+import { config } from '../config/index.js';
+import { resolveProject, resolveTestSuite } from '../utils/resolveProject.js';
+const logger = new Logger({ module: 'runTestSuiteHandler' });
+function errorResp(error, message, extra = {}) {
+    return { content: [{ type: 'text', text: JSON.stringify({ error, message, ...extra }, null, 2) }], isError: true };
+}
+export async function runTestSuiteHandler(input, _context) {
+    const start = Date.now();
+    logger.toolStart('run_test_suite', input);
+    const client = new DebuggAIServerClient(config.api.key);
+    await client.init();
+    let acquiredKeyId = null;
+    let tunnelId;
+    try {
+        let suiteUuid = input.suiteUuid;
+        if (!suiteUuid) {
+            let projectUuid = input.projectUuid;
+            if (!projectUuid) {
+                const resolved = await resolveProject(client, input.projectName);
+                if ('error' in resolved)
+                    return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+                projectUuid = resolved.uuid;
+            }
+            const resolved = await resolveTestSuite(client, input.suiteName, projectUuid);
+            if ('error' in resolved)
+                return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+            suiteUuid = resolved.uuid;
+        }
+        // Resolve the effective target URL — tunnel if localhost, pass-through otherwise.
+        let effectiveTargetUrl = input.targetUrl;
+        if (input.targetUrl) {
+            const ctx = buildContext(input.targetUrl);
+            if (ctx.isLocalhost) {
+                const port = extractLocalhostPort(ctx.originalUrl);
+                if (typeof port === 'number') {
+                    const probe = await probeLocalPort(port);
+                    if (!probe.reachable) {
+                        return errorResp('LocalServerUnreachable', `No server listening on 127.0.0.1:${port}. Start your dev server before running the suite. (${probe.code}: ${probe.detail ?? 'no detail'})`, { port, probeCode: probe.code, elapsedMs: probe.elapsedMs });
+                    }
+                }
+                // Reuse an existing tunnel for this port if one is already active.
+                const reused = findExistingTunnel(ctx);
+                if (reused) {
+                    effectiveTargetUrl = reused.targetUrl ?? input.targetUrl;
+                    tunnelId = reused.tunnelId;
+                }
+                else {
+                    // Provision a new tunnel.
+                    let tunnel;
+                    try {
+                        tunnel = await client.tunnels.provisionWithRetry();
+                    }
+                    catch (provisionError) {
+                        const msg = provisionError instanceof Error ? provisionError.message : String(provisionError);
+                        const diag = provisionError instanceof TunnelProvisionError ? ` ${provisionError.diagnosticSuffix()}` : '';
+                        return errorResp('TunnelProvisionFailed', `Failed to provision tunnel for ${input.targetUrl}. (Detail: ${msg})${diag}`);
+                    }
+                    acquiredKeyId = tunnel.keyId;
+                    let tunneled;
+                    try {
+                        tunneled = await ensureTunnel(ctx, tunnel.tunnelKey, tunnel.tunnelId, tunnel.keyId, () => client.revokeNgrokKey(tunnel.keyId));
+                    }
+                    catch (tunnelError) {
+                        const msg = tunnelError instanceof Error ? tunnelError.message : String(tunnelError);
+                        return errorResp('TunnelCreationFailed', `Tunnel creation failed for ${input.targetUrl}. (Detail: ${msg})`);
+                    }
+                    // Health probe — catches ERR_NGROK_8012 and bind mismatches before
+                    // the remote agent wastes steps trying to reach the server.
+                    if (tunneled.targetUrl) {
+                        const health = await probeTunnelHealth(tunneled.targetUrl);
+                        if (!health.healthy) {
+                            if (tunneled.tunnelId) {
+                                tunnelManager.stopTunnel(tunneled.tunnelId).catch((err) => logger.warn(`Failed to stop broken tunnel ${tunneled.tunnelId}: ${err}`));
+                            }
+                            return errorResp('TunnelTrafficBlocked', `Tunnel established but traffic isn't reaching the dev server. ${health.detail ?? ''}`, { code: health.code, ngrokErrorCode: health.ngrokErrorCode, elapsedMs: health.elapsedMs });
+                        }
+                    }
+                    effectiveTargetUrl = tunneled.targetUrl ?? input.targetUrl;
+                    tunnelId = tunneled.tunnelId;
+                }
+                logger.info(`run_test_suite: localhost detected, tunneled ${input.targetUrl} → ${effectiveTargetUrl}`);
+            }
+        }
+        const result = await client.runTestSuite(suiteUuid, { targetUrl: effectiveTargetUrl });
+        logger.toolComplete('run_test_suite', Date.now() - start);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        ...result,
+                        ...(tunnelId ? { tunnelActive: true, originalUrl: input.targetUrl } : {}),
+                        note: 'Tests are running asynchronously. Use get_test_suite_results to check progress.',
+                    }, null, 2),
+                }],
+        };
+    }
+    catch (error) {
+        logger.toolError('run_test_suite', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'run_test_suite');
+    }
+    finally {
+        // Tunnels are NOT torn down — reuse pattern + 55-min idle auto-shutoff.
+        // Only revoke an orphaned key (acquired but tunnel creation failed).
+        if (acquiredKeyId && !tunnelId) {
+            client.revokeNgrokKey(acquiredKeyId).catch((err) => logger.warn(`Failed to revoke unused ngrok key ${acquiredKeyId}: ${err}`));
+        }
+    }
+}

package/dist/handlers/searchExecutionsHandler.js

@@ -13,6 +13,7 @@ import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { config } from '../config/index.js';
 import { toPaginationParams } from '../utils/pagination.js';
+import { fetchImageAsBase64, imageContentBlock } from '../utils/imageUtils.js';
 const logger = new Logger({ module: 'searchExecutionsHandler' });
 function notFound(uuid) {
     return {
@@ -38,7 +39,53 @@ export async function searchExecutionsHandler(input, _context) {
                     executions: [execution],
                 };
                 logger.toolComplete('search_executions', Date.now() - start);
-                return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+                const content = [
+                    { type: 'text', text: JSON.stringify(payload, null, 2) },
+                ];
+                const SCREENSHOT_URL_KEYS = ['finalScreenshot', 'screenshot', 'screenshotUrl', 'screenshotUri'];
+                const GIF_KEYS = ['runGif', 'gifUrl', 'gif', 'videoUrl', 'recordingUrl'];
+                const nodes = execution.nodeExecutions ?? [];
+                const subworkflowNode = nodes.find((n) => n.nodeType === 'subworkflow.run');
+                let screenshotEmbedded = false;
+                let screenshotUrl = null;
+                let gifUrl = null;
+                const screenshotB64 = subworkflowNode?.outputData?.screenshotB64;
+                if (typeof screenshotB64 === 'string' && screenshotB64) {
+                    content.push(imageContentBlock(screenshotB64, 'image/png'));
+                    screenshotEmbedded = true;
+                }
+                for (const node of nodes) {
+                    const data = node.outputData ?? {};
+                    if (!screenshotEmbedded && !screenshotUrl) {
+                        for (const key of SCREENSHOT_URL_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 ((screenshotEmbedded || screenshotUrl) && gifUrl)
+                        break;
+                }
+                if (!screenshotEmbedded && screenshotUrl) {
+                    const img = await fetchImageAsBase64(screenshotUrl).catch(() => null);
+                    if (img)
+                        content.push(imageContentBlock(img.data, img.mimeType));
+                }
+                if (gifUrl) {
+                    const gif = await fetchImageAsBase64(gifUrl).catch(() => null);
+                    if (gif)
+                        content.push(imageContentBlock(gif.data, 'image/gif'));
+                }
+                return { content };
             }
             catch (err) {
                 if (err?.statusCode === 404 || err?.response?.status === 404)

package/dist/handlers/searchTestSuitesHandler.js

@@ -0,0 +1,36 @@
+import { Logger } from '../utils/logger.js';
+import { handleExternalServiceError } from '../utils/errors.js';
+import { DebuggAIServerClient } from '../services/index.js';
+import { config } from '../config/index.js';
+import { resolveProject } from '../utils/resolveProject.js';
+const logger = new Logger({ module: 'searchTestSuitesHandler' });
+function errorResp(error, message, extra = {}) {
+    return { content: [{ type: 'text', text: JSON.stringify({ error, message, ...extra }, null, 2) }], isError: true };
+}
+export async function searchTestSuitesHandler(input, _context) {
+    const start = Date.now();
+    logger.toolStart('search_test_suites', input);
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        let projectUuid = input.projectUuid;
+        if (!projectUuid) {
+            const resolved = await resolveProject(client, input.projectName);
+            if ('error' in resolved)
+                return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+            projectUuid = resolved.uuid;
+        }
+        const result = await client.listTestSuites({
+            projectUuid,
+            search: input.search,
+            page: input.page,
+            pageSize: input.pageSize,
+        });
+        logger.toolComplete('search_test_suites', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('search_test_suites', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'search_test_suites');
+    }
+}

package/dist/handlers/updateTestCaseHandler.js

@@ -0,0 +1,24 @@
+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: 'updateTestCaseHandler' });
+export async function updateTestCaseHandler(input, _context) {
+    const start = Date.now();
+    logger.toolStart('update_test_case', input);
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        const updated = await client.updateTestCase(input.testUuid, {
+            name: input.name,
+            description: input.description,
+            agentTaskDescription: input.agentTaskDescription,
+        });
+        logger.toolComplete('update_test_case', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(updated, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('update_test_case', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'update_test_case');
+    }
+}

package/dist/services/index.js

@@ -430,6 +430,151 @@ export class DebuggAIServerClient {
             throw new Error('Client not initialized — call init() first');
         await this.tx.post('api/v1/ngrok/revoke/', { ngrokKeyId });
     }
+    // ── E2E Suite Management ──────────────────────────────────────────────────
+    async createTestSuite(input) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        const s = await this.tx.post('api/v1/test-suites/', {
+            name: input.name,
+            description: input.description,
+            project: input.projectUuid,
+        });
+        return this.mapTestSuite(s);
+    }
+    async listTestSuites(params) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        const { makePageInfo } = await import('../utils/pagination.js');
+        const page = params.page ?? 1;
+        const pageSize = params.pageSize ?? 20;
+        const query = { project: params.projectUuid, page, pageSize };
+        if (params.search)
+            query.search = params.search;
+        const response = await this.tx.get('api/v1/test-suites/', query);
+        return {
+            pageInfo: makePageInfo(page, pageSize, response?.count ?? 0, response?.next),
+            suites: (response?.results ?? []).map((s) => ({
+                uuid: s.uuid,
+                name: s.name,
+                description: s.description ?? null,
+                runStatus: s.runStatus ?? s.run_status ?? 'NEVER_RUN',
+                testsCount: s.testsCount ?? s.tests_count ?? 0,
+                passRate: s.passRate ?? s.pass_rate ?? null,
+                lastRunAt: s.lastRunAt ?? s.last_run_at ?? null,
+            })),
+        };
+    }
+    async disableTestSuite(suiteUuid) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        await this.tx.post(`api/v1/test-suites/${suiteUuid}/disable/`, {});
+        return { uuid: suiteUuid, isDisabled: true };
+    }
+    async createTestCase(input) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        const body = {
+            name: input.name,
+            description: input.description,
+            agent_task_description: input.agentTaskDescription,
+            suite: input.suiteUuid,
+            project: input.projectUuid,
+            run: false,
+        };
+        if (input.relativeUrl)
+            body.relative_url = input.relativeUrl;
+        if (input.maxSteps)
+            body.max_steps = input.maxSteps;
+        const t = await this.tx.post('api/v1/e2e-tests/', body);
+        return {
+            uuid: t.uuid,
+            name: t.name,
+            description: t.description,
+            agentTaskDescription: t.agentTaskDescription ?? t.agent_task_description ?? '',
+            suite: t.suite ?? input.suiteUuid,
+            project: t.project ?? input.projectUuid,
+            runCount: t.runCount ?? t.run_count ?? 0,
+        };
+    }
+    async updateTestCase(testUuid, patch) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        const body = {};
+        if (patch.name !== undefined)
+            body.name = patch.name;
+        if (patch.description !== undefined)
+            body.description = patch.description;
+        if (patch.agentTaskDescription !== undefined)
+            body.agent_task_description = patch.agentTaskDescription;
+        const t = await this.tx.patch(`api/v1/e2e-tests/${testUuid}/`, body);
+        return {
+            uuid: t.uuid,
+            name: t.name,
+            description: t.description,
+            agentTaskDescription: t.agentTaskDescription ?? t.agent_task_description ?? '',
+        };
+    }
+    async disableTestCase(testUuid) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        await this.tx.post(`api/v1/e2e-tests/${testUuid}/disable/`, {});
+        return { uuid: testUuid, isDisabled: true };
+    }
+    async runTestSuite(suiteUuid, params) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        const body = {};
+        if (params.targetUrl)
+            body.target_url = params.targetUrl;
+        const s = await this.tx.post(`api/v1/test-suites/${suiteUuid}/run/`, body);
+        return {
+            suiteUuid,
+            runStatus: s?.runStatus ?? s?.run_status ?? 'PENDING',
+            testsTriggered: (s?.tests ?? []).length,
+        };
+    }
+    async getTestSuiteDetail(suiteUuid) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        const s = await this.tx.get(`api/v1/test-suites/${suiteUuid}/`);
+        const tests = s.tests ?? [];
+        return {
+            uuid: s.uuid,
+            name: s.name,
+            runStatus: s.runStatus ?? s.run_status ?? 'NEVER_RUN',
+            testsCount: tests.length,
+            passRate: s.passRate ?? s.pass_rate ?? null,
+            lastRunAt: s.lastRunAt ?? s.last_run_at ?? null,
+            tests: tests.map((t) => {
+                // Backend returns cur_run (latest run) per test in the suite detail view
+                const lastRun = t.curRun ?? t.cur_run ?? t.lastRun ?? t.last_run ?? null;
+                return {
+                    uuid: t.uuid,
+                    name: t.name,
+                    runCount: t.runCount ?? t.run_count ?? 0,
+                    passedRunsCount: t.passedRunsCount ?? t.passed_runs_count ?? 0,
+                    failedRunsCount: t.failedRunsCount ?? t.failed_runs_count ?? 0,
+                    passRate: t.passRate ?? t.pass_rate ?? null,
+                    lastRun: lastRun ? {
+                        uuid: lastRun.uuid,
+                        status: lastRun.status,
+                        outcome: lastRun.outcome,
+                        executionTime: lastRun.executionTime ?? lastRun.execution_time ?? null,
+                        timestamp: lastRun.timestamp,
+                    } : null,
+                };
+            }),
+        };
+    }
+    mapTestSuite(s) {
+        return {
+            uuid: s.uuid,
+            name: s.name,
+            description: s.description ?? null,
+            runStatus: s.runStatus ?? s.run_status ?? 'NEVER_RUN',
+            testsCount: s.testsCount ?? s.tests_count ?? 0,
+        };
+    }
 }
 /**
  * Create and initialize a service client

package/dist/tools/index.js

@@ -10,6 +10,7 @@ import { buildDeleteEnvironmentTool, buildValidatedDeleteEnvironmentTool } from
 import { buildUpdateProjectTool, buildValidatedUpdateProjectTool } from './updateProject.js';
 import { buildDeleteProjectTool, buildValidatedDeleteProjectTool } from './deleteProject.js';
 import { buildCreateProjectTool, buildValidatedCreateProjectTool } from './createProject.js';
+import { buildCreateTestSuiteTool, buildValidatedCreateTestSuiteTool, buildSearchTestSuitesTool, buildValidatedSearchTestSuitesTool, buildDeleteTestSuiteTool, buildValidatedDeleteTestSuiteTool, buildCreateTestCaseTool, buildValidatedCreateTestCaseTool, buildUpdateTestCaseTool, buildValidatedUpdateTestCaseTool, buildDeleteTestCaseTool, buildValidatedDeleteTestCaseTool, buildRunTestSuiteTool, buildValidatedRunTestSuiteTool, buildGetTestSuiteResultsTool, buildValidatedGetTestSuiteResultsTool, } from './testSuiteTools.js';
 let _tools = null;
 let _validatedTools = null;
 const toolRegistry = new Map();
@@ -30,6 +31,14 @@ export function initTools(ctx) {
         buildDeleteProjectTool(),
         buildSearchExecutionsTool(),
         buildCreateProjectTool(),
+        buildCreateTestSuiteTool(),
+        buildSearchTestSuitesTool(),
+        buildDeleteTestSuiteTool(),
+        buildCreateTestCaseTool(),
+        buildUpdateTestCaseTool(),
+        buildDeleteTestCaseTool(),
+        buildRunTestSuiteTool(),
+        buildGetTestSuiteResultsTool(),
     ];
     const validated = [
         buildValidatedTestPageChangesTool(ctx),
@@ -44,6 +53,14 @@ export function initTools(ctx) {
         buildValidatedDeleteProjectTool(),
         buildValidatedSearchExecutionsTool(),
         buildValidatedCreateProjectTool(),
+        buildValidatedCreateTestSuiteTool(),
+        buildValidatedSearchTestSuitesTool(),
+        buildValidatedDeleteTestSuiteTool(),
+        buildValidatedCreateTestCaseTool(),
+        buildValidatedUpdateTestCaseTool(),
+        buildValidatedDeleteTestCaseTool(),
+        buildValidatedRunTestSuiteTool(),
+        buildValidatedGetTestSuiteResultsTool(),
     ];
     _tools = tools;
     _validatedTools = validated;

package/dist/tools/testSuiteTools.js

@@ -0,0 +1,183 @@
+import { CreateTestSuiteInputSchema, SearchTestSuitesInputSchema, DeleteTestSuiteInputSchema, CreateTestCaseInputSchema, UpdateTestCaseInputSchema, DeleteTestCaseInputSchema, RunTestSuiteInputSchema, GetTestSuiteResultsInputSchema, } from '../types/index.js';
+import { createTestSuiteHandler } from '../handlers/createTestSuiteHandler.js';
+import { searchTestSuitesHandler } from '../handlers/searchTestSuitesHandler.js';
+import { deleteTestSuiteHandler } from '../handlers/deleteTestSuiteHandler.js';
+import { createTestCaseHandler } from '../handlers/createTestCaseHandler.js';
+import { updateTestCaseHandler } from '../handlers/updateTestCaseHandler.js';
+import { deleteTestCaseHandler } from '../handlers/deleteTestCaseHandler.js';
+import { runTestSuiteHandler } from '../handlers/runTestSuiteHandler.js';
+import { getTestSuiteResultsHandler } from '../handlers/getTestSuiteResultsHandler.js';
+const PROJECT_PROPS = {
+    projectUuid: { type: 'string', description: 'Project UUID. Provide projectUuid OR projectName.' },
+    projectName: { type: 'string', description: 'Project name (case-insensitive exact match). Provide projectUuid OR projectName.' },
+};
+const SUITE_PROPS = {
+    suiteUuid: { type: 'string', description: 'Test suite UUID. Provide suiteUuid OR (suiteName + project identifier).' },
+    suiteName: { type: 'string', description: 'Test suite name (case-insensitive exact match). Requires projectUuid or projectName.' },
+};
+// ── create_test_suite ─────────────────────────────────────────────────────────
+export function buildCreateTestSuiteTool() {
+    return {
+        name: 'create_test_suite',
+        title: 'Create Test Suite',
+        description: 'Create a named test suite for a project. A test suite is a collection of test cases that can be run together. Requires name, description, and a project identifier (projectUuid or projectName). Returns {uuid, name, description, runStatus, testsCount}.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Suite name. Required.', minLength: 1 },
+                description: { type: 'string', description: 'Suite description. Required.', minLength: 1 },
+                ...PROJECT_PROPS,
+            },
+            required: ['name', 'description'],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedCreateTestSuiteTool() {
+    return { ...buildCreateTestSuiteTool(), inputSchema: CreateTestSuiteInputSchema, handler: createTestSuiteHandler };
+}
+// ── search_test_suites ────────────────────────────────────────────────────────
+export function buildSearchTestSuitesTool() {
+    return {
+        name: 'search_test_suites',
+        title: 'Search Test Suites',
+        description: 'List and search test suites for a project. Returns paginated results with suite status, test counts, pass rates, and last run timestamps. Requires a project identifier (projectUuid or projectName). Optional: search text filter, page, pageSize (1-100, default 20).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...PROJECT_PROPS,
+                search: { type: 'string', description: 'Optional text filter applied to suite name and description.' },
+                page: { type: 'number', description: 'Page number (default 1).', minimum: 1 },
+                pageSize: { type: 'number', description: 'Results per page (default 20, max 100).', minimum: 1, maximum: 100 },
+            },
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedSearchTestSuitesTool() {
+    return { ...buildSearchTestSuitesTool(), inputSchema: SearchTestSuitesInputSchema, handler: searchTestSuitesHandler };
+}
+// ── delete_test_suite ─────────────────────────────────────────────────────────
+export function buildDeleteTestSuiteTool() {
+    return {
+        name: 'delete_test_suite',
+        title: 'Delete Test Suite',
+        description: 'Disable (soft-delete) a test suite. The suite and its tests are hidden from default list queries but not permanently removed. Accepts suiteUuid directly, or suiteName + project identifier for name-based lookup. Returns {deleted: true, suiteUuid}.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...SUITE_PROPS,
+                ...PROJECT_PROPS,
+            },
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedDeleteTestSuiteTool() {
+    return { ...buildDeleteTestSuiteTool(), inputSchema: DeleteTestSuiteInputSchema, handler: deleteTestSuiteHandler };
+}
+// ── create_test_case ──────────────────────────────────────────────────────────
+export function buildCreateTestCaseTool() {
+    return {
+        name: 'create_test_case',
+        title: 'Create Test Case',
+        description: 'Create an individual test case and assign it to a test suite. The test is NOT automatically executed. Requires name, description, agentTaskDescription (the AI agent\'s goal), and suite + project identifiers. Optional: relativeUrl (must start with "/") and maxSteps (1-100). Returns {uuid, name, description, agentTaskDescription, suite, project, runCount}.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Test case name. Required.', minLength: 1 },
+                description: { type: 'string', description: 'Test case description. Required.', minLength: 1 },
+                agentTaskDescription: { type: 'string', description: 'Natural language description of what the AI agent should do and verify. Required.', minLength: 1 },
+                ...SUITE_PROPS,
+                ...PROJECT_PROPS,
+                relativeUrl: { type: 'string', description: 'Optional starting URL path relative to the app root, e.g. "/login". Must start with "/".' },
+                maxSteps: { type: 'number', description: 'Maximum agent steps (1-100).', minimum: 1, maximum: 100 },
+            },
+            required: ['name', 'description', 'agentTaskDescription'],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedCreateTestCaseTool() {
+    return { ...buildCreateTestCaseTool(), inputSchema: CreateTestCaseInputSchema, handler: createTestCaseHandler };
+}
+// ── update_test_case ──────────────────────────────────────────────────────────
+export function buildUpdateTestCaseTool() {
+    return {
+        name: 'update_test_case',
+        title: 'Update Test Case',
+        description: 'Update a test case\'s name, description, or agentTaskDescription. Requires testUuid. At least one of name, description, or agentTaskDescription must be provided. Returns the updated test case.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                testUuid: { type: 'string', description: 'UUID of the test case to update. Required.' },
+                name: { type: 'string', description: 'New name for the test case.', minLength: 1 },
+                description: { type: 'string', description: 'New description.', minLength: 1 },
+                agentTaskDescription: { type: 'string', description: 'New agent task description.', minLength: 1 },
+            },
+            required: ['testUuid'],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedUpdateTestCaseTool() {
+    return { ...buildUpdateTestCaseTool(), inputSchema: UpdateTestCaseInputSchema, handler: updateTestCaseHandler };
+}
+// ── delete_test_case ──────────────────────────────────────────────────────────
+export function buildDeleteTestCaseTool() {
+    return {
+        name: 'delete_test_case',
+        title: 'Delete Test Case',
+        description: 'Disable (soft-delete) a test case. The test is hidden from default list queries but not permanently removed. Requires testUuid. Returns {deleted: true, testUuid}.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                testUuid: { type: 'string', description: 'UUID of the test case to delete. Required.' },
+            },
+            required: ['testUuid'],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedDeleteTestCaseTool() {
+    return { ...buildDeleteTestCaseTool(), inputSchema: DeleteTestCaseInputSchema, handler: deleteTestCaseHandler };
+}
+// ── run_test_suite ────────────────────────────────────────────────────────────
+export function buildRunTestSuiteTool() {
+    return {
+        name: 'run_test_suite',
+        title: 'Run Test Suite',
+        description: 'Trigger all test cases in a suite to run asynchronously. Accepts suiteUuid directly, or suiteName + project identifier. Optional: targetUrl to override the default test target. Returns {suiteUuid, runStatus, testsTriggered, note}. Use get_test_suite_results to poll for results.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...SUITE_PROPS,
+                ...PROJECT_PROPS,
+                targetUrl: { type: 'string', description: 'Optional URL to run tests against (overrides default). Must be a full URL.' },
+            },
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedRunTestSuiteTool() {
+    return { ...buildRunTestSuiteTool(), inputSchema: RunTestSuiteInputSchema, handler: runTestSuiteHandler };
+}
+// ── get_test_suite_results ────────────────────────────────────────────────────
+export function buildGetTestSuiteResultsTool() {
+    return {
+        name: 'get_test_suite_results',
+        title: 'Get Test Suite Results',
+        description: 'Fetch a test suite with full per-test results. Returns suite-level status (NEVER_RUN, PENDING, RUNNING, COMPLETED, ERROR), pass rate, last run timestamp, and per-test outcomes (PASS, FAIL, ERROR, TIMEOUT, etc.) with execution times. Accepts suiteUuid directly or suiteName + project identifier.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...SUITE_PROPS,
+                ...PROJECT_PROPS,
+            },
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedGetTestSuiteResultsTool() {
+    return { ...buildGetTestSuiteResultsTool(), inputSchema: GetTestSuiteResultsInputSchema, handler: getTestSuiteResultsHandler };
+}

package/dist/types/index.js

@@ -169,3 +169,54 @@ export const ProbePageInputSchema = z.object({
     captureScreenshots: z.boolean().default(true),
     repoName: z.string().optional(),
 }).strict();
+// ── E2E Suite Management ──────────────────────────────────────────────────────
+const projectIdentifier = {
+    projectUuid: z.string().uuid().optional(),
+    projectName: z.string().min(1).optional(),
+};
+const suiteIdentifier = {
+    suiteUuid: z.string().uuid().optional(),
+    suiteName: z.string().min(1).optional(),
+};
+export const CreateTestSuiteInputSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().min(1),
+    ...projectIdentifier,
+}).strict();
+export const SearchTestSuitesInputSchema = z.object({
+    ...projectIdentifier,
+    search: z.string().optional(),
+    page: z.number().int().min(1).optional(),
+    pageSize: z.number().int().min(1).max(100).optional(),
+}).strict();
+export const DeleteTestSuiteInputSchema = z.object({
+    ...suiteIdentifier,
+    ...projectIdentifier,
+}).strict();
+export const CreateTestCaseInputSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().min(1),
+    agentTaskDescription: z.string().min(1),
+    ...suiteIdentifier,
+    ...projectIdentifier,
+    relativeUrl: z.string().regex(/^\//, 'Must start with /').optional(),
+    maxSteps: z.number().int().min(1).max(100).optional(),
+}).strict();
+export const UpdateTestCaseInputSchema = z.object({
+    testUuid: z.string().uuid(),
+    name: z.string().min(1).optional(),
+    description: z.string().min(1).optional(),
+    agentTaskDescription: z.string().min(1).optional(),
+}).strict();
+export const DeleteTestCaseInputSchema = z.object({
+    testUuid: z.string().uuid(),
+}).strict();
+export const RunTestSuiteInputSchema = z.object({
+    ...suiteIdentifier,
+    ...projectIdentifier,
+    targetUrl: z.string().url().optional(),
+}).strict();
+export const GetTestSuiteResultsInputSchema = z.object({
+    ...suiteIdentifier,
+    ...projectIdentifier,
+}).strict();

package/dist/utils/resolveProject.js

@@ -0,0 +1,27 @@
+export async function resolveProject(client, name) {
+    const { projects } = await client.listProjects({ page: 1, pageSize: 100 }, name);
+    return resolveByName(name, projects, 'Project');
+}
+export async function resolveTestSuite(client, suiteName, projectUuid) {
+    const { suites } = await client.listTestSuites({ projectUuid, search: suiteName });
+    return resolveByName(suiteName, suites, 'TestSuite');
+}
+export function resolveByName(name, candidates, kind) {
+    const needle = name.toLowerCase();
+    const matches = candidates.filter(c => c.name.toLowerCase() === needle);
+    if (matches.length === 0) {
+        return {
+            error: `${kind}NotFound`,
+            message: `No ${kind.toLowerCase().replace('testsuite', 'test suite')} matching "${name}" found.` +
+                (candidates.length > 0 ? ` Available: ${candidates.slice(0, 10).map(c => `"${c.name}"`).join(', ')}` : ' (none accessible to this API key)'),
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            error: 'AmbiguousMatch',
+            message: `Multiple ${kind.toLowerCase().replace('testsuite', 'test suite')}s match "${name}". Pass the uuid directly.`,
+            candidates: matches.map(m => ({ uuid: m.uuid, name: m.name })),
+        };
+    }
+    return { uuid: matches[0].uuid };
+}

package/package.json

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