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

package/dist/config/index.js

@@ -28,7 +28,10 @@ const configSchema = z.object({
         version: z.string(),
     }),
     api: z.object({
-        key: z.string().min(1, 'API key is required (set DEBUGGAI_API_KEY)'),
+        // key is validated at tool-call time (not at boot) so MCP clients can surface
+        // a proper error message instead of seeing the subprocess die → "Failed to
+        // reconnect". See bead cma + flow 25.
+        key: z.string(),
         tokenType: z.enum(['token', 'bearer']).default('token'),
         baseUrl: z.string().url().default('https://api.debugg.ai'),
     }),

package/dist/handlers/createEnvironmentHandler.js

@@ -44,6 +44,39 @@ export async function createEnvironmentHandler(input, _context) {
             projectUuid,
             environment: env,
         };
+        // Optional credentials seed: best-effort per-cred. Success goes to
+        // credentials[]; failure goes to credentialWarnings[] (never blocks env creation).
+        if (input.credentials && input.credentials.length > 0) {
+            const created = [];
+            const warnings = [];
+            for (const seed of input.credentials) {
+                try {
+                    const cred = await client.createCredential(projectUuid, env.uuid, {
+                        label: seed.label,
+                        username: seed.username,
+                        password: seed.password,
+                        role: seed.role,
+                    });
+                    // Defensive: drop any stray password from the response shape
+                    created.push({
+                        uuid: cred.uuid,
+                        label: cred.label,
+                        username: cred.username,
+                        role: cred.role ?? null,
+                        environmentUuid: cred.environmentUuid,
+                    });
+                }
+                catch (err) {
+                    warnings.push({
+                        label: seed.label,
+                        error: err?.message ?? String(err),
+                    });
+                }
+            }
+            payload.credentials = created;
+            if (warnings.length > 0)
+                payload.credentialWarnings = warnings;
+        }
         logger.toolComplete('create_environment', Date.now() - start);
         return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
     }

package/dist/handlers/createProjectHandler.js

@@ -3,26 +3,78 @@ import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { config } from '../config/index.js';
 const logger = new Logger({ module: 'createProjectHandler' });
+function errorResp(error, message, extra = {}) {
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({ error, message, ...extra }, null, 2),
+            }],
+        isError: true,
+    };
+}
+/**
+ * Resolve a name to a single uuid via backend search + exact (case-insensitive)
+ * match. Returns either a uuid, a NotFound error, or an Ambiguous error with
+ * candidate options surfaced.
+ */
+function resolveName(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()} 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()}s match "${name}". Pass ${kind.toLowerCase()}Uuid explicitly.`,
+            candidates: matches.map(m => ({ uuid: m.uuid, name: m.name })),
+        };
+    }
+    return { uuid: matches[0].uuid };
+}
 export async function createProjectHandler(input, _context) {
     const start = Date.now();
     logger.toolStart('create_project', {
-        name: input.name,
-        platform: input.platform,
-        teamUuid: input.teamUuid,
-        repoUuid: input.repoUuid,
+        name: input.name, platform: input.platform,
+        teamUuid: input.teamUuid, teamName: input.teamName,
+        repoUuid: input.repoUuid, repoName: input.repoName,
     });
     try {
         const client = new DebuggAIServerClient(config.api.key);
         await client.init();
+        // Resolve team
+        let teamUuid = input.teamUuid;
+        if (!teamUuid && input.teamName) {
+            const teamsResp = await client.listTeams({ page: 1, pageSize: 100 }, input.teamName);
+            const resolved = resolveName(input.teamName, teamsResp.teams, 'Team');
+            if ('error' in resolved)
+                return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+            teamUuid = resolved.uuid;
+        }
+        // Resolve repo
+        let repoUuid = input.repoUuid;
+        if (!repoUuid && input.repoName) {
+            const reposResp = await client.listRepos({ page: 1, pageSize: 100 }, input.repoName);
+            const resolved = resolveName(input.repoName, reposResp.repos, 'Repo');
+            if ('error' in resolved)
+                return errorResp(resolved.error, resolved.message, { candidates: resolved.candidates });
+            repoUuid = resolved.uuid;
+        }
+        if (!teamUuid || !repoUuid) {
+            // Schema-level invariant should have caught this, but defensive.
+            return errorResp('ValidationError', `Unable to resolve ${!teamUuid ? 'team' : 'repo'} — provide teamUuid/teamName and repoUuid/repoName.`);
+        }
         const project = await client.createProject({
-            name: input.name,
-            platform: input.platform,
-            teamUuid: input.teamUuid,
-            repoUuid: input.repoUuid,
+            name: input.name, platform: input.platform, teamUuid, repoUuid,
         });
-        const payload = { created: true, project };
         logger.toolComplete('create_project', Date.now() - start);
-        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+        return { content: [{ type: 'text', text: JSON.stringify({ created: true, project }, null, 2) }] };
     }
     catch (error) {
         logger.toolError('create_project', error, Date.now() - start);

package/dist/handlers/index.js

@@ -1,21 +1,12 @@
 export * from './testPageChangesHandler.js';
-export * from './listEnvironmentsHandler.js';
-export * from './listCredentialsHandler.js';
-export * from './listProjectsHandler.js';
+export * from './triggerCrawlHandler.js';
+export * from './searchProjectsHandler.js';
+export * from './searchEnvironmentsHandler.js';
+export * from './searchExecutionsHandler.js';
 export * from './createEnvironmentHandler.js';
-export * from './createCredentialHandler.js';
-export * from './getEnvironmentHandler.js';
 export * from './updateEnvironmentHandler.js';
 export * from './deleteEnvironmentHandler.js';
-export * from './getCredentialHandler.js';
-export * from './updateCredentialHandler.js';
-export * from './deleteCredentialHandler.js';
-export * from './getProjectHandler.js';
+// Credential mutations are folded into create_environment + update_environment.
 export * from './updateProjectHandler.js';
 export * from './deleteProjectHandler.js';
-export * from './listExecutionsHandler.js';
-export * from './getExecutionHandler.js';
-export * from './cancelExecutionHandler.js';
-export * from './listTeamsHandler.js';
-export * from './listReposHandler.js';
 export * from './createProjectHandler.js';

package/dist/handlers/searchEnvironmentsHandler.js

@@ -0,0 +1,122 @@
+/**
+ * search_environments handler (bead 5kw)
+ *
+ * Absorbs list_environments + get_environment + all credential search.
+ * Each environment in the response has its credentials expanded inline.
+ *
+ * Modes:
+ *   uuid mode: {uuid, projectUuid?} → {filter:{uuid}, project, pageInfo:{totalCount:1,...},
+ *                                      environments:[{...env, credentials:[...]}]}
+ *   filter mode: {projectUuid?, q?, page?, pageSize?} → paginated list, creds inline per env
+ *
+ * Invariants:
+ *   - NEVER returns a password field anywhere in the response (defensive strip at handler edge)
+ *   - Git-fallback for projectUuid: detectRepoName() → findProjectByRepoName(); NoProjectResolved if both fail
+ *   - NotFound on unknown uuid returns isError:true
+ */
+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 { detectRepoName } from '../utils/gitContext.js';
+import { toPaginationParams, makePageInfo } from '../utils/pagination.js';
+const logger = new Logger({ module: 'searchEnvironmentsHandler' });
+function stripPassword(cred) {
+    // Defensive: take only known-safe keys. Never spread the source.
+    return {
+        uuid: cred.uuid,
+        label: cred.label,
+        username: cred.username,
+        role: cred.role ?? null,
+        ...(cred.environmentUuid ? { environmentUuid: cred.environmentUuid } : {}),
+    };
+}
+function notFound(uuid) {
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({ error: 'NotFound', message: `Environment ${uuid} not found.`, uuid }, null, 2),
+            }],
+        isError: true,
+    };
+}
+function noProjectResolved(pagination, reason) {
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    error: 'NoProjectResolved',
+                    message: reason,
+                    pageInfo: makePageInfo(pagination.page, pagination.pageSize, 0, null),
+                    environments: [],
+                }, null, 2),
+            }],
+    };
+}
+export async function searchEnvironmentsHandler(input, _context) {
+    const start = Date.now();
+    const pagination = toPaginationParams({ page: input.page, pageSize: input.pageSize });
+    logger.toolStart('search_environments', { ...input, ...pagination });
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        // ── Resolve projectUuid ──
+        let projectUuid = input.projectUuid;
+        let project = null;
+        if (!projectUuid) {
+            const repoName = detectRepoName();
+            if (!repoName) {
+                return noProjectResolved(pagination, 'No git repo detected and no projectUuid provided. Pass projectUuid (get via search_projects) or invoke from a directory with a git origin.');
+            }
+            const resolved = await client.findProjectByRepoName(repoName);
+            if (!resolved) {
+                return noProjectResolved(pagination, `No DebuggAI project found for repo "${repoName}". Pass projectUuid explicitly.`);
+            }
+            projectUuid = resolved.uuid;
+            project = { uuid: resolved.uuid, name: resolved.name, repoName: resolved.repo?.name ?? repoName };
+        }
+        else {
+            project = { uuid: projectUuid, name: null, repoName: null };
+        }
+        // ── uuid mode ──
+        if (input.uuid) {
+            try {
+                const env = await client.getEnvironment(projectUuid, input.uuid);
+                const creds = await client.listCredentialsForEnvironment(projectUuid, input.uuid).catch(() => []);
+                const payload = {
+                    project,
+                    filter: { uuid: input.uuid },
+                    pageInfo: { page: 1, pageSize: 1, totalCount: 1, totalPages: 1, hasMore: false },
+                    environments: [{ ...env, credentials: creds.map(stripPassword) }],
+                };
+                logger.toolComplete('search_environments', Date.now() - start);
+                return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+            }
+            catch (err) {
+                if (err?.statusCode === 404 || err?.response?.status === 404)
+                    return notFound(input.uuid);
+                throw err;
+            }
+        }
+        // ── Filter mode ──
+        const { pageInfo, environments } = await client.listEnvironmentsPaginated(projectUuid, pagination, input.q);
+        // Expand creds per env (sequential — bounded by page size, typically ≤20)
+        const withCreds = [];
+        for (const env of environments) {
+            const creds = await client.listCredentialsForEnvironment(projectUuid, env.uuid).catch(() => []);
+            withCreds.push({ ...env, credentials: creds.map(stripPassword) });
+        }
+        const payload = {
+            project,
+            filter: { q: input.q ?? null },
+            pageInfo,
+            environments: withCreds,
+        };
+        logger.toolComplete('search_environments', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('search_environments', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'search_environments');
+    }
+}

package/dist/handlers/searchExecutionsHandler.js

@@ -0,0 +1,71 @@
+/**
+ * search_executions handler (bead 49b)
+ *
+ * Absorbs list_executions + get_execution.
+ *
+ * Modes:
+ *   uuid: {uuid} → {filter:{uuid}, pageInfo:{totalCount:1,...}, executions:[fullDetail]}
+ *                  fullDetail includes nodeExecutions, state, errorInfo.
+ *   filter: {status?, projectUuid?, page?, pageSize?} → {filter, pageInfo, executions:[summary]}
+ */
+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 { toPaginationParams } from '../utils/pagination.js';
+const logger = new Logger({ module: 'searchExecutionsHandler' });
+function notFound(uuid) {
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({ error: 'NotFound', message: `Execution ${uuid} not found.`, uuid }, null, 2),
+            }],
+        isError: true,
+    };
+}
+export async function searchExecutionsHandler(input, _context) {
+    const start = Date.now();
+    logger.toolStart('search_executions', input);
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        if (input.uuid) {
+            try {
+                const execution = await client.workflows.getExecution(input.uuid);
+                const payload = {
+                    filter: { uuid: input.uuid },
+                    pageInfo: { page: 1, pageSize: 1, totalCount: 1, totalPages: 1, hasMore: false },
+                    executions: [execution],
+                };
+                logger.toolComplete('search_executions', Date.now() - start);
+                return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+            }
+            catch (err) {
+                if (err?.statusCode === 404 || err?.response?.status === 404)
+                    return notFound(input.uuid);
+                throw err;
+            }
+        }
+        const pagination = toPaginationParams({ page: input.page, pageSize: input.pageSize });
+        const { pageInfo, executions } = await client.workflows.listExecutions({
+            status: input.status,
+            projectId: input.projectUuid,
+            page: pagination.page,
+            pageSize: pagination.pageSize,
+        });
+        const payload = {
+            filter: {
+                status: input.status ?? null,
+                projectUuid: input.projectUuid ?? null,
+            },
+            pageInfo,
+            executions,
+        };
+        logger.toolComplete('search_executions', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('search_executions', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'search_executions');
+    }
+}

package/dist/handlers/searchProjectsHandler.js

@@ -0,0 +1,72 @@
+/**
+ * search_projects handler (bead ue3)
+ *
+ * Single tool covering both uuid-lookup and filter/list modes.
+ *
+ * Modes:
+ *   uuid mode:   {uuid} → {filter:{uuid}, pageInfo:{totalCount:1,...}, projects:[fullProject]}
+ *                — NotFound surfaces as isError:true
+ *   filter mode: {q?, page?, pageSize?} → {filter:{q}, pageInfo, projects:[summaries]}
+ *
+ * Response shape is uniform ({filter, pageInfo, projects}) but `projects[0]`
+ * richness differs by mode: uuid-mode returns the full project (all backend
+ * keys), filter-mode returns a summary (uuid/name/slug/repoName).
+ */
+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 { toPaginationParams } from '../utils/pagination.js';
+const logger = new Logger({ module: 'searchProjectsHandler' });
+function notFound(uuid) {
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({ error: 'NotFound', message: `Project ${uuid} not found.`, uuid }, null, 2),
+            }],
+        isError: true,
+    };
+}
+export async function searchProjectsHandler(input, _context) {
+    const start = Date.now();
+    logger.toolStart('search_projects', input);
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        if (input.uuid) {
+            try {
+                const project = await client.getProject(input.uuid);
+                const payload = {
+                    filter: { uuid: input.uuid },
+                    pageInfo: { page: 1, pageSize: 1, totalCount: 1, totalPages: 1, hasMore: false },
+                    projects: [project],
+                };
+                logger.toolComplete('search_projects', Date.now() - start);
+                return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+            }
+            catch (err) {
+                if (err?.statusCode === 404 || err?.response?.status === 404)
+                    return notFound(input.uuid);
+                throw err;
+            }
+        }
+        const pagination = toPaginationParams({ page: input.page, pageSize: input.pageSize });
+        const { pageInfo, projects } = await client.listProjects(pagination, input.q);
+        const payload = {
+            filter: { q: input.q ?? null },
+            pageInfo,
+            projects: projects.map((p) => ({
+                uuid: p.uuid,
+                name: p.name,
+                slug: p.slug,
+                repoName: p.repo?.name ?? null,
+            })),
+        };
+        logger.toolComplete('search_projects', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    }
+    catch (error) {
+        logger.toolError('search_projects', error, Date.now() - start);
+        throw handleExternalServiceError(error, 'DebuggAI', 'search_projects');
+    }
+}

package/dist/handlers/testPageChangesHandler.js

@@ -43,16 +43,40 @@ export async function testPageChangesHandler(input, context, progressCallback) {
         releaseSlot();
     }
 }
-async function testPageChangesHandlerInner(input, context, progressCallback) {
+async function testPageChangesHandlerInner(input, context, rawProgressCallback) {
     const startTime = Date.now();
     logger.toolStart('check_app_in_browser', input);
+    // Bead 0bq: wrap the progress callback in a circuit-breaker so a single
+    // client-side rejection of a stale progressToken (which would normally
+    // throw up the stack and abort the handler, or — worse — arrive post-response
+    // and tear down the stdio transport) is swallowed and disables further
+    // emissions in this request.
+    let progressDisabled = false;
+    const progressCallback = rawProgressCallback
+        ? async (update) => {
+            if (progressDisabled)
+                return;
+            try {
+                await rawProgressCallback(update);
+            }
+            catch (err) {
+                progressDisabled = true;
+                logger.warn('Progress emission failed; disabling further emissions for this request', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        : undefined;
     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();
+    const onStdinClose = () => {
+        abortController.abort();
+        progressDisabled = true; // client is gone — stop emitting
+    };
     process.stdin.once('close', onStdinClose);
     // Progress budget: 3 setup steps + 25 execution steps = 28 total
     const SETUP_STEPS = 3;
@@ -168,6 +192,7 @@ async function testPageChangesHandlerInner(input, context, progressCallback) {
         const BACKEND_SETUP_END = 6;
         let lastStepsTaken = 0;
         let observedMaxSteps = MAX_EXEC_STEPS;
+        const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
         const finalExecution = await client.workflows.pollExecution(executionUuid, async (exec) => {
             // Keep the tunnel alive while the workflow is actively running
             if (ctx.tunnelId)
@@ -180,6 +205,19 @@ async function testPageChangesHandlerInner(input, context, progressCallback) {
             }
             if (!progressCallback)
                 return;
+            // Bead 0bq: emit the final "Complete:" progress INSIDE this callback
+            // when terminal status is detected. pollExecution will return on the
+            // next line (line 183 in services/workflows.ts), so there's no
+            // post-pollExecution progress emission that could race the response.
+            if (TERMINAL_STATUSES.has(exec.status)) {
+                const terminalOutcome = exec.state?.outcome ?? exec.status;
+                await progressCallback({
+                    progress: TOTAL_STEPS,
+                    total: TOTAL_STEPS,
+                    message: `Complete: ${terminalOutcome}`,
+                });
+                return;
+            }
             // --- Compute progress number ---
             let execProgress;
             let message;
@@ -308,9 +346,12 @@ async function testPageChangesHandlerInner(input, context, progressCallback) {
             responsePayload.surferOutput = sanitizeResponseUrls(surferNode.outputData, ctx);
         }
         logger.toolComplete('check_app_in_browser', duration);
-        if (progressCallback) {
-            await progressCallback({ progress: TOTAL_STEPS, total: TOTAL_STEPS, message: `Complete: ${outcome}` });
-        }
+        // NOTE (bead 0bq): the final "Complete:" progress is emitted INSIDE
+        // pollExecution's onUpdate when terminal status is detected — see the
+        // TERMINAL_STATUSES block above. Emitting it here (post-resolve) creates
+        // a race where the progress can arrive AFTER the response on the wire,
+        // making the client reject it as an unknown progressToken and close the
+        // transport, breaking ALL subsequent tool calls.
         // Sanitize the whole payload so no tunnel URL leaks anywhere — including
         // agent-authored strings in actionTrace[*].intent, evaluation.reason, etc.
         const sanitizedPayload = sanitizeResponseUrls(responsePayload, ctx);