@debugg-ai/debugg-ai-mcp 1.0.62 → 1.0.63

package/dist/handlers/index.js

@@ -1,4 +1,5 @@
 export * from './testPageChangesHandler.js';
+export * from './triggerCrawlHandler.js';
 export * from './listEnvironmentsHandler.js';
 export * from './listCredentialsHandler.js';
 export * from './listProjectsHandler.js';

package/dist/handlers/triggerCrawlHandler.js

@@ -0,0 +1,178 @@
+/**
+ * Trigger Crawl Handler
+ *
+ * Executes the Raw Crawl Workflow Template via the 4-step pattern shared with
+ * testPageChangesHandler:
+ *   find template → provision tunnel if localhost → execute → poll → result
+ *
+ * Unlike check_app_in_browser, a crawl does NOT return pass/fail — it returns
+ * the execution status + metadata. The backend's job is to explore the app
+ * and populate the project knowledge graph; this handler just triggers it
+ * and reports back what happened.
+ */
+import { config } from '../config/index.js';
+import { Logger } from '../utils/logger.js';
+import { handleExternalServiceError } from '../utils/errors.js';
+import { DebuggAIServerClient } from '../services/index.js';
+import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
+const logger = new Logger({ module: 'triggerCrawlHandler' });
+const TEMPLATE_KEYWORD = 'raw crawl';
+export async function triggerCrawlHandler(input, context, progressCallback) {
+    const startTime = Date.now();
+    logger.toolStart('trigger_crawl', input);
+    const client = new DebuggAIServerClient(config.api.key);
+    await client.init();
+    const originalUrl = resolveTargetUrl(input);
+    let ctx = buildContext(originalUrl);
+    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: 4, message: 'Provisioning secure tunnel for localhost...' });
+            }
+            const reused = findExistingTunnel(ctx);
+            if (reused) {
+                ctx = reused;
+            }
+            else {
+                let tunnel;
+                try {
+                    tunnel = await client.tunnels.provision();
+                }
+                catch (provisionError) {
+                    const msg = provisionError instanceof Error ? provisionError.message : String(provisionError);
+                    throw new Error(`Failed to provision tunnel for ${ctx.originalUrl}. ` +
+                        `The remote browser needs a secure tunnel to reach your local dev server. ` +
+                        `(Detail: ${msg})`);
+                }
+                keyId = tunnel.keyId;
+                ctx = await ensureTunnel(ctx, tunnel.tunnelKey, tunnel.tunnelId, tunnel.keyId, () => client.revokeNgrokKey(tunnel.keyId));
+            }
+        }
+        // --- Find the crawl workflow template ---
+        if (progressCallback) {
+            await progressCallback({ progress: 2, total: 4, message: 'Locating crawl workflow template...' });
+        }
+        const template = await client.workflows.findTemplateByName(TEMPLATE_KEYWORD);
+        if (!template) {
+            throw new Error(`Raw Crawl Workflow Template not found. ` +
+                `Ensure the backend has a template matching "${TEMPLATE_KEYWORD}" seeded and accessible.`);
+        }
+        const templateUuid = template.uuid;
+        logger.info(`Using crawl template: ${template.name} (${templateUuid})`);
+        // --- Build contextData + env ---
+        const contextData = {
+            targetUrl: ctx.targetUrl ?? ctx.originalUrl,
+        };
+        if (input.projectUuid)
+            contextData.projectId = input.projectUuid;
+        if (typeof input.headless === 'boolean')
+            contextData.headless = input.headless;
+        if (typeof input.timeoutSeconds === 'number')
+            contextData.timeoutSeconds = input.timeoutSeconds;
+        const env = {};
+        if (input.environmentId)
+            env.environmentId = input.environmentId;
+        if (input.credentialId)
+            env.credentialId = input.credentialId;
+        if (input.credentialRole)
+            env.credentialRole = input.credentialRole;
+        if (input.username)
+            env.username = input.username;
+        if (input.password)
+            env.password = input.password;
+        // --- Execute ---
+        if (progressCallback) {
+            await progressCallback({ progress: 3, total: 4, message: 'Queuing crawl execution...' });
+        }
+        const executeResponse = await client.workflows.executeWorkflow(templateUuid, contextData, Object.keys(env).length > 0 ? env : undefined);
+        const executionUuid = executeResponse.executionUuid;
+        logger.info(`Crawl execution queued: ${executionUuid}`);
+        // --- Poll ---
+        const finalExecution = await client.workflows.pollExecution(executionUuid, async (exec) => {
+            if (ctx.tunnelId)
+                touchTunnelById(ctx.tunnelId);
+            if (!progressCallback)
+                return;
+            const nodeCount = (exec.nodeExecutions ?? []).length;
+            await progressCallback({
+                progress: 4,
+                total: 4,
+                message: `Crawl ${exec.status} (${nodeCount} nodes)`,
+            });
+        }, abortController.signal);
+        const duration = Date.now() - startTime;
+        const nodes = finalExecution.nodeExecutions ?? [];
+        // --- Format response ---
+        const responsePayload = {
+            executionId: executionUuid,
+            status: finalExecution.status,
+            targetUrl: ctx.originalUrl,
+            durationMs: finalExecution.durationMs ?? duration,
+        };
+        const outcome = finalExecution.state?.outcome;
+        if (outcome !== undefined && outcome !== null)
+            responsePayload.outcome = outcome;
+        if (finalExecution.errorMessage)
+            responsePayload.errorMessage = finalExecution.errorMessage;
+        if (finalExecution.errorInfo?.failedNodeId)
+            responsePayload.failedNode = finalExecution.errorInfo.failedNodeId;
+        if (executeResponse.resolvedEnvironmentId)
+            responsePayload.resolvedEnvironmentId = executeResponse.resolvedEnvironmentId;
+        if (executeResponse.resolvedCredentialId)
+            responsePayload.resolvedCredentialId = executeResponse.resolvedCredentialId;
+        // Extract crawl metrics from surfer.crawl node (absent in older graph shapes)
+        const crawlNode = nodes.find(n => n.nodeType === 'surfer.crawl');
+        if (crawlNode?.outputData) {
+            const d = crawlNode.outputData;
+            responsePayload.crawlSummary = {
+                pagesDiscovered: d.pagesDiscovered,
+                actionsExecuted: d.actionsExecuted,
+                stepsTaken: d.stepsTaken,
+                transitionsRecorded: d.transitionsRecorded,
+                knowledgeGraphStates: d.knowledgeGraphStates,
+                success: d.success,
+                ...(d.error ? { error: d.error } : {}),
+            };
+        }
+        // Extract KG import result from knowledge_graph.import node (absent in older graph shapes)
+        const kgNode = nodes.find(n => n.nodeType === 'knowledge_graph.import');
+        if (kgNode?.outputData) {
+            const d = kgNode.outputData;
+            responsePayload.knowledgeGraph = {
+                imported: !d.skipped,
+                skipped: d.skipped ?? false,
+                reason: d.reason ?? '',
+                edgesImported: d.edgesImported ?? 0,
+                statesImported: d.statesImported ?? 0,
+                knowledgeGraphId: d.knowledgeGraphId ?? '',
+                ...(Array.isArray(d.importErrors) && d.importErrors.length > 0 ? { importErrors: d.importErrors } : {}),
+            };
+        }
+        logger.toolComplete('trigger_crawl', duration);
+        if (progressCallback) {
+            await progressCallback({ progress: 4, total: 4, message: `Crawl ${finalExecution.status}` });
+        }
+        const sanitizedPayload = sanitizeResponseUrls(responsePayload, ctx);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(sanitizedPayload, null, 2) }],
+        };
+    }
+    catch (error) {
+        const duration = Date.now() - startTime;
+        logger.toolError('trigger_crawl', error, duration);
+        throw handleExternalServiceError(error, 'DebuggAI', 'crawl execution');
+    }
+    finally {
+        process.stdin.removeListener('close', onStdinClose);
+        // Tunnel intentionally NOT torn down (reuse path per bead vwd).
+        // If tunnel creation failed after key provision, revoke the orphaned key.
+        if (!ctx.tunnelId && keyId) {
+            client.revokeNgrokKey(keyId).catch(err => logger.warn(`Failed to revoke unused ngrok key ${keyId}: ${err}`));
+        }
+    }
+}

package/dist/services/workflows.js

@@ -8,18 +8,22 @@ const POLL_INTERVAL_MS = 3000;
 const EXECUTION_TIMEOUT_MS = 10 * 60 * 1000; // 10 min
 export const createWorkflowsService = (tx) => {
     const service = {
-        async findEvaluationTemplate() {
+        async findTemplateByName(keyword) {
             const response = await tx.get('api/v1/workflows/', { isTemplate: true });
             const templates = response?.results ?? [];
             if (templates.length === 0)
                 return null;
-            const evalTemplate = templates.find(t => t.name.toLowerCase().includes('app evaluation'));
-            if (!evalTemplate) {
-                throw new Error(`No "App Evaluation" workflow template found. ` +
+            const needle = keyword.toLowerCase();
+            const match = templates.find(t => t.name.toLowerCase().includes(needle));
+            if (!match) {
+                throw new Error(`No workflow template matching "${keyword}" found. ` +
                     `Available templates: ${templates.map(t => `"${t.name}"`).join(', ')}. ` +
-                    `Ensure the backend has a template with "App Evaluation" in its name.`);
+                    `Ensure the backend has a template with "${keyword}" in its name.`);
             }
-            return evalTemplate;
+            return match;
+        },
+        async findEvaluationTemplate() {
+            return service.findTemplateByName('app evaluation');
         },
         async executeWorkflow(workflowUuid, contextData, env) {
             const body = { contextData };

package/dist/tools/index.js

@@ -1,4 +1,5 @@
 import { buildTestPageChangesTool, buildValidatedTestPageChangesTool } from './testPageChanges.js';
+import { buildTriggerCrawlTool, buildValidatedTriggerCrawlTool } from './triggerCrawl.js';
 import { buildListEnvironmentsTool, buildValidatedListEnvironmentsTool } from './listEnvironments.js';
 import { buildListCredentialsTool, buildValidatedListCredentialsTool } from './listCredentials.js';
 import { buildListProjectsTool, buildValidatedListProjectsTool } from './listProjects.js';
@@ -28,6 +29,7 @@ const toolRegistry = new Map();
 export function initTools(ctx) {
     const tools = [
         buildTestPageChangesTool(ctx),
+        buildTriggerCrawlTool(ctx),
         buildListProjectsTool(),
         buildListEnvironmentsTool(),
         buildListCredentialsTool(),
@@ -51,6 +53,7 @@ export function initTools(ctx) {
     ];
     const validated = [
         buildValidatedTestPageChangesTool(ctx),
+        buildValidatedTriggerCrawlTool(ctx),
         buildValidatedListProjectsTool(),
         buildValidatedListEnvironmentsTool(),
         buildValidatedListCredentialsTool(),

package/dist/tools/triggerCrawl.js

@@ -0,0 +1,99 @@
+/**
+ * Trigger Crawl Tool Definition
+ * Defines the trigger_crawl tool with proper validation.
+ * Tool description is enriched at startup with available environments/credentials.
+ */
+import { TriggerCrawlInputSchema } from '../types/index.js';
+import { triggerCrawlHandler } from '../handlers/triggerCrawlHandler.js';
+const BASE_DESCRIPTION = `Trigger a browser-agent crawl of a web app to build the project's knowledge graph. The crawl systematically explores pages, UI states, and navigation flows, then populates the backend's knowledge graph so future evaluations and tests have context about the app.
+
+LOCALHOST SUPPORT: Pass any localhost URL (e.g. http://localhost:3000) and it Just Works. A secure tunnel is automatically created so the remote browser can reach your local dev server.
+
+WHEN TO USE: after a significant new feature, a new environment, or when onboarding a project. NOT for per-change verification — use check_app_in_browser for that.
+
+SCOPE: one crawl per call against one URL. The crawl is long-running (minutes to tens of minutes depending on app size) and populates backend state asynchronously; the tool returns the execution status once the workflow completes. This does NOT return pass/fail — it returns executionId + status + outcome.`;
+export function buildTriggerCrawlDescription(ctx) {
+    if (!ctx)
+        return BASE_DESCRIPTION;
+    const envsWithCreds = ctx.environments.filter(e => e.credentials.length > 0);
+    if (envsWithCreds.length === 0) {
+        return `${BASE_DESCRIPTION}\n\nDETECTED PROJECT: "${ctx.project.name}" (repo: ${ctx.repoName}). No credentials configured — provide username/password if the app requires login to crawl authenticated areas.`;
+    }
+    const lines = [
+        `\n\nDETECTED PROJECT: "${ctx.project.name}" (repo: ${ctx.repoName})`,
+        `\nAVAILABLE ENVIRONMENTS & CREDENTIALS (pass environmentId + credentialId to crawl authenticated areas):`,
+    ];
+    for (const env of envsWithCreds) {
+        lines.push(`\n  Environment: "${env.name}" (${env.uuid})${env.url ? ` — ${env.url}` : ''}`);
+        for (const cred of env.credentials) {
+            const parts = [`    - "${cred.label}" (${cred.uuid}) — user: ${cred.username}`];
+            if (cred.role)
+                parts[0] += `, role: ${cred.role}`;
+            lines.push(parts[0]);
+        }
+    }
+    lines.push(`\nTo use: pass environmentId and credentialId from above. Or provide username/password directly.`);
+    return BASE_DESCRIPTION + lines.join('\n');
+}
+export function buildTriggerCrawlTool(ctx) {
+    return {
+        name: 'trigger_crawl',
+        title: 'Trigger App Crawl',
+        description: buildTriggerCrawlDescription(ctx),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: {
+                    type: 'string',
+                    description: 'URL to crawl. Can be any public URL or a localhost/local dev server URL. For localhost URLs, a secure tunnel is automatically created — just make sure your dev server is running on that port.',
+                },
+                projectUuid: {
+                    type: 'string',
+                    description: 'UUID of the project whose knowledge graph the crawl should populate. Auto-detected from the current git repo if omitted.',
+                },
+                environmentId: {
+                    type: 'string',
+                    description: 'UUID of a specific environment to use for the crawl. See available environments in the tool description above.',
+                },
+                credentialId: {
+                    type: 'string',
+                    description: 'UUID of a specific credential for authenticated crawls. See available credentials in the tool description above.',
+                },
+                credentialRole: {
+                    type: 'string',
+                    description: "Pick a credential by role (e.g. 'admin', 'guest') from the resolved environment.",
+                },
+                username: {
+                    type: 'string',
+                    description: 'A real, existing account email for the target app. Do NOT invent credentials — use one from the available credentials or ask the user.',
+                },
+                password: {
+                    type: 'string',
+                    description: 'The real password for the username above. Do NOT guess.',
+                },
+                headless: {
+                    type: 'boolean',
+                    description: 'Run the browser in headless mode. Defaults to backend configuration.',
+                },
+                timeoutSeconds: {
+                    type: 'number',
+                    description: 'Maximum wall-time the crawl may run, in seconds (1..1800). Backend enforces this per workflow execution.',
+                },
+                repoName: {
+                    type: 'string',
+                    description: "GitHub repository name (e.g. 'my-org/my-repo'). Auto-detected from the current git repo — only provide this to run against a different project.",
+                },
+            },
+            required: ['url'],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedTriggerCrawlTool(ctx) {
+    const tool = buildTriggerCrawlTool(ctx);
+    return {
+        ...tool,
+        inputSchema: TriggerCrawlInputSchema,
+        handler: triggerCrawlHandler,
+    };
+}

package/dist/types/index.js

@@ -17,6 +17,18 @@ export const TestPageChangesInputSchema = z.object({
     password: z.string().optional(),
     repoName: z.string().optional(),
 });
+export const TriggerCrawlInputSchema = z.object({
+    url: z.preprocess(normalizeUrl, z.string().url('Invalid URL. Pass a full URL like "http://localhost:3000" or "https://example.com". Localhost URLs are auto-tunneled to the remote browser.')),
+    projectUuid: z.string().uuid().optional(),
+    environmentId: z.string().uuid().optional(),
+    credentialId: z.string().uuid().optional(),
+    credentialRole: z.string().optional(),
+    username: z.string().optional(),
+    password: z.string().optional(),
+    headless: z.boolean().optional(),
+    timeoutSeconds: z.number().int().positive().max(1800, 'timeoutSeconds cannot exceed 1800 (30 min)').optional(),
+    repoName: z.string().optional(),
+}).strict();
 export const ListEnvironmentsInputSchema = z.object({
     projectUuid: z.string().uuid().optional(),
     q: z.string().min(1).optional(),

package/package.json

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