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

package/dist/handlers/triggerCrawlHandler.js

@@ -0,0 +1,208 @@
+/**
+ * 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, rawProgressCallback) {
+    const startTime = Date.now();
+    logger.toolStart('trigger_crawl', input);
+    // Bead 0bq: progress circuit-breaker — see testPageChangesHandler for rationale.
+    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();
+        progressDisabled = true;
+    };
+    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 ---
+        // Bead 0bq: emit the final progress (4/4 "Complete:...") INSIDE onUpdate
+        // when terminal status detected, so there's no post-resolve emission that
+        // could race the response and cause stale-progressToken transport tear-down.
+        const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+        const finalExecution = await client.workflows.pollExecution(executionUuid, async (exec) => {
+            if (ctx.tunnelId)
+                touchTunnelById(ctx.tunnelId);
+            if (!progressCallback)
+                return;
+            const nodeCount = (exec.nodeExecutions ?? []).length;
+            if (TERMINAL_STATUSES.has(exec.status)) {
+                await progressCallback({
+                    progress: 4, total: 4,
+                    message: `Crawl ${exec.status} (${nodeCount} nodes)`,
+                });
+                return;
+            }
+            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);
+        // Bead 0bq: final progress is emitted INSIDE pollExecution's onUpdate when
+        // terminal status is detected. Emitting it here would race the response
+        // and could cause stale-progressToken transport tear-down.
+        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/handlers/updateEnvironmentHandler.js

@@ -14,11 +14,23 @@ function notFound(uuid, context) {
         isError: true,
     };
 }
+function stripPassword(c) {
+    return {
+        uuid: c.uuid,
+        label: c.label,
+        username: c.username,
+        role: c.role ?? null,
+        environmentUuid: c.environmentUuid,
+    };
+}
 export async function updateEnvironmentHandler(input, _context) {
     const start = Date.now();
     logger.toolStart('update_environment', {
         uuid: input.uuid,
-        patchKeys: Object.keys(input).filter(k => k !== 'uuid' && k !== 'projectUuid'),
+        hasEnvPatch: !!(input.name || input.url || input.description),
+        addCount: input.addCredentials?.length ?? 0,
+        updateCount: input.updateCredentials?.length ?? 0,
+        removeCount: input.removeCredentialIds?.length ?? 0,
         projectUuid: input.projectUuid,
     });
     try {
@@ -34,23 +46,90 @@ export async function updateEnvironmentHandler(input, _context) {
                 return notFound(input.uuid, `no project found for repo "${repoName}"`);
             projectUuid = project.uuid;
         }
-        try {
-            const environment = await client.updateEnvironment(projectUuid, input.uuid, {
-                name: input.name,
-                url: input.url,
-                description: input.description,
-            });
-            logger.toolComplete('update_environment', Date.now() - start);
-            return {
-                content: [{ type: 'text', text: JSON.stringify({ updated: true, environment }, null, 2) }],
-            };
+        // ── Env field patch (only if any env field is present) ──────────────────
+        const hasEnvPatch = input.name !== undefined || input.url !== undefined || input.description !== undefined;
+        let environment = null;
+        if (hasEnvPatch) {
+            try {
+                environment = await client.updateEnvironment(projectUuid, input.uuid, {
+                    name: input.name, url: input.url, description: input.description,
+                });
+            }
+            catch (err) {
+                if (err?.statusCode === 404 || err?.response?.status === 404) {
+                    return notFound(input.uuid, `backend returned 404 for project ${projectUuid}`);
+                }
+                throw err;
+            }
+        }
+        else {
+            // Echo the uuid so the response shape stays consistent. Include projectUuid
+            // for downstream tooling. Only populate `environment` if we patched.
+            environment = { uuid: input.uuid };
+        }
+        // ── Cred sub-actions (remove → update → add) ────────────────────────────
+        const warnings = [];
+        const addedCredentials = [];
+        const updatedCredentials = [];
+        const removedCredentialIds = [];
+        if (input.removeCredentialIds) {
+            for (const credUuid of input.removeCredentialIds) {
+                try {
+                    await client.deleteCredential(projectUuid, input.uuid, credUuid);
+                    removedCredentialIds.push(credUuid);
+                }
+                catch (err) {
+                    warnings.push({ op: 'remove', uuid: credUuid, error: err?.message ?? String(err) });
+                }
+            }
+        }
+        if (input.updateCredentials) {
+            for (const patch of input.updateCredentials) {
+                try {
+                    const updated = await client.updateCredential(projectUuid, input.uuid, patch.uuid, {
+                        label: patch.label,
+                        username: patch.username,
+                        password: patch.password,
+                        role: patch.role,
+                    });
+                    updatedCredentials.push(stripPassword(updated));
+                }
+                catch (err) {
+                    warnings.push({ op: 'update', uuid: patch.uuid, error: err?.message ?? String(err) });
+                }
+            }
         }
-        catch (err) {
-            if (err?.statusCode === 404 || err?.response?.status === 404) {
-                return notFound(input.uuid, `backend returned 404 for project ${projectUuid}`);
+        if (input.addCredentials) {
+            for (const seed of input.addCredentials) {
+                try {
+                    const cred = await client.createCredential(projectUuid, input.uuid, {
+                        label: seed.label,
+                        username: seed.username,
+                        password: seed.password,
+                        role: seed.role,
+                    });
+                    addedCredentials.push(stripPassword(cred));
+                }
+                catch (err) {
+                    warnings.push({ op: 'add', label: seed.label, error: err?.message ?? String(err) });
+                }
             }
-            throw err;
         }
+        // ── Build response ──────────────────────────────────────────────────────
+        const payload = {
+            updated: hasEnvPatch,
+            environment,
+        };
+        if (addedCredentials.length > 0)
+            payload.addedCredentials = addedCredentials;
+        if (updatedCredentials.length > 0)
+            payload.updatedCredentials = updatedCredentials;
+        if (removedCredentialIds.length > 0)
+            payload.removedCredentialIds = removedCredentialIds;
+        if (warnings.length > 0)
+            payload.credentialWarnings = warnings;
+        logger.toolComplete('update_environment', Date.now() - start);
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
     }
     catch (error) {
         logger.toolError('update_environment', error, Date.now() - start);

package/dist/index.js

@@ -22,6 +22,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { config } from "./config/index.js";
 import { initTools, getTools, getTool } from "./tools/index.js";
 import { Logger, validateInput, createErrorResponse, toMCPError, handleConfigurationError, Telemetry, TelemetryEvents, } from "./utils/index.js";
+import { MCPErrorCode, MCPError, } from "./types/index.js";
 // Logger and server are initialized lazily in main() to avoid triggering
 // config loading at module load time. If config validation fails (bad env vars),
 // the error is caught by main()'s try-catch instead of crashing before any
@@ -91,6 +92,16 @@ function registerHandlers() {
             requestLogger.warn(`Tool not found: ${name}`);
             throw new Error(`Unknown tool: ${name}`);
         }
+        // Deferred config validation (bead cma): if DEBUGGAI_API_KEY is missing,
+        // return a structured error MCP clients can surface in their UI — instead
+        // of letting the backend return a cryptic 401.
+        if (!config.api.key) {
+            const mcpError = new MCPError(MCPErrorCode.CONFIGURATION_ERROR, 'DEBUGGAI_API_KEY is not set. ' +
+                'Configure it in your MCP server registration (e.g. `claude mcp add debugg-ai -s user -e DEBUGGAI_API_KEY=<your-key> -- npx -y @debugg-ai/debugg-ai-mcp`). ' +
+                'Get a key at https://debugg.ai.', { missingEnvVars: ['DEBUGGAI_API_KEY'] });
+            requestLogger.warn('Tool call blocked — DEBUGGAI_API_KEY missing', { tool: name });
+            return createErrorResponse(mcpError, name);
+        }
         try {
             const validatedInput = validateInput(tool.inputSchema, args, name);
             const context = {
@@ -141,9 +152,11 @@ async function main() {
             architecture: process.arch,
             pid: process.pid
         });
-        // Validate required environment variables
+        // NOTE: DEBUGGAI_API_KEY validation is deferred to the first tool call so
+        // MCP clients see a proper initialize response + a structured tool error,
+        // rather than the subprocess dying with "Failed to reconnect" (bead cma).
         if (!config.api.key) {
-            throw new Error('Missing required environment variable: DEBUGGAI_API_KEY');
+            logger.warn('DEBUGGAI_API_KEY is not set. Server will boot but every tool call will return a ConfigurationError until the env var is configured.');
         }
         // Initialize telemetry (PostHog when key is set, Noop otherwise)
         Telemetry.setDistinctId(config.api.key);

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/createEnvironment.js

@@ -1,6 +1,10 @@
 import { CreateEnvironmentInputSchema } from '../types/index.js';
 import { createEnvironmentHandler } from '../handlers/createEnvironmentHandler.js';
-const DESCRIPTION = `Create a new environment under a DebuggAI project. Both name and url are required (backend rejects standard environments without a URL). Optional description. Defaults to the project resolved from the current git repo; pass projectUuid to target a different project (get UUIDs via list_projects). Returns the created environment's uuid so you can reference it when running check_app_in_browser or creating credentials.`;
+const DESCRIPTION = `Create a new environment under a DebuggAI project. Both name and url are required (backend rejects standard environments without a URL). Optional description. Defaults to the project resolved from the current git repo; pass projectUuid to target a different project (get UUIDs via search_projects).
+
+OPTIONAL credentials seed: pass \`credentials: [{label, username, password, role?}]\` to create login credentials alongside the environment in a single call. Each cred is created best-effort; failures go to \`credentialWarnings\` without blocking env creation. Passwords are write-only and NEVER returned.
+
+Returns the created environment's uuid (and the seeded credentials, if any). Reference the env uuid when running check_app_in_browser.`;
 export function buildCreateEnvironmentTool() {
     return {
         name: 'create_environment',

package/dist/tools/index.js

@@ -1,23 +1,13 @@
 import { buildTestPageChangesTool, buildValidatedTestPageChangesTool } from './testPageChanges.js';
-import { buildListEnvironmentsTool, buildValidatedListEnvironmentsTool } from './listEnvironments.js';
-import { buildListCredentialsTool, buildValidatedListCredentialsTool } from './listCredentials.js';
-import { buildListProjectsTool, buildValidatedListProjectsTool } from './listProjects.js';
+import { buildTriggerCrawlTool, buildValidatedTriggerCrawlTool } from './triggerCrawl.js';
+import { buildSearchProjectsTool, buildValidatedSearchProjectsTool } from './searchProjects.js';
+import { buildSearchEnvironmentsTool, buildValidatedSearchEnvironmentsTool } from './searchEnvironments.js';
+import { buildSearchExecutionsTool, buildValidatedSearchExecutionsTool } from './searchExecutions.js';
 import { buildCreateEnvironmentTool, buildValidatedCreateEnvironmentTool } from './createEnvironment.js';
-import { buildCreateCredentialTool, buildValidatedCreateCredentialTool } from './createCredential.js';
-import { buildGetEnvironmentTool, buildValidatedGetEnvironmentTool } from './getEnvironment.js';
 import { buildUpdateEnvironmentTool, buildValidatedUpdateEnvironmentTool } from './updateEnvironment.js';
 import { buildDeleteEnvironmentTool, buildValidatedDeleteEnvironmentTool } from './deleteEnvironment.js';
-import { buildGetCredentialTool, buildValidatedGetCredentialTool } from './getCredential.js';
-import { buildUpdateCredentialTool, buildValidatedUpdateCredentialTool } from './updateCredential.js';
-import { buildDeleteCredentialTool, buildValidatedDeleteCredentialTool } from './deleteCredential.js';
-import { buildGetProjectTool, buildValidatedGetProjectTool } from './getProject.js';
 import { buildUpdateProjectTool, buildValidatedUpdateProjectTool } from './updateProject.js';
 import { buildDeleteProjectTool, buildValidatedDeleteProjectTool } from './deleteProject.js';
-import { buildListExecutionsTool, buildValidatedListExecutionsTool } from './listExecutions.js';
-import { buildGetExecutionTool, buildValidatedGetExecutionTool } from './getExecution.js';
-import { buildCancelExecutionTool, buildValidatedCancelExecutionTool } from './cancelExecution.js';
-import { buildListTeamsTool, buildValidatedListTeamsTool } from './listTeams.js';
-import { buildListReposTool, buildValidatedListReposTool } from './listRepos.js';
 import { buildCreateProjectTool, buildValidatedCreateProjectTool } from './createProject.js';
 let _tools = null;
 let _validatedTools = null;
@@ -28,48 +18,28 @@ const toolRegistry = new Map();
 export function initTools(ctx) {
     const tools = [
         buildTestPageChangesTool(ctx),
-        buildListProjectsTool(),
-        buildListEnvironmentsTool(),
-        buildListCredentialsTool(),
+        buildTriggerCrawlTool(ctx),
+        buildSearchProjectsTool(),
+        buildSearchEnvironmentsTool(),
         buildCreateEnvironmentTool(),
-        buildCreateCredentialTool(),
-        buildGetEnvironmentTool(),
         buildUpdateEnvironmentTool(),
         buildDeleteEnvironmentTool(),
-        buildGetCredentialTool(),
-        buildUpdateCredentialTool(),
-        buildDeleteCredentialTool(),
-        buildGetProjectTool(),
         buildUpdateProjectTool(),
         buildDeleteProjectTool(),
-        buildListExecutionsTool(),
-        buildGetExecutionTool(),
-        buildCancelExecutionTool(),
-        buildListTeamsTool(),
-        buildListReposTool(),
+        buildSearchExecutionsTool(),
         buildCreateProjectTool(),
     ];
     const validated = [
         buildValidatedTestPageChangesTool(ctx),
-        buildValidatedListProjectsTool(),
-        buildValidatedListEnvironmentsTool(),
-        buildValidatedListCredentialsTool(),
+        buildValidatedTriggerCrawlTool(ctx),
+        buildValidatedSearchProjectsTool(),
+        buildValidatedSearchEnvironmentsTool(),
         buildValidatedCreateEnvironmentTool(),
-        buildValidatedCreateCredentialTool(),
-        buildValidatedGetEnvironmentTool(),
         buildValidatedUpdateEnvironmentTool(),
         buildValidatedDeleteEnvironmentTool(),
-        buildValidatedGetCredentialTool(),
-        buildValidatedUpdateCredentialTool(),
-        buildValidatedDeleteCredentialTool(),
-        buildValidatedGetProjectTool(),
         buildValidatedUpdateProjectTool(),
         buildValidatedDeleteProjectTool(),
-        buildValidatedListExecutionsTool(),
-        buildValidatedGetExecutionTool(),
-        buildValidatedCancelExecutionTool(),
-        buildValidatedListTeamsTool(),
-        buildValidatedListReposTool(),
+        buildValidatedSearchExecutionsTool(),
         buildValidatedCreateProjectTool(),
     ];
     _tools = tools;

package/dist/tools/searchEnvironments.js

@@ -0,0 +1,35 @@
+import { SearchEnvironmentsInputSchema } from '../types/index.js';
+import { searchEnvironmentsHandler } from '../handlers/searchEnvironmentsHandler.js';
+const DESCRIPTION = `Search or look up environments, with credentials expanded inline per environment.
+
+Two modes:
+  - uuid mode: {"uuid": "<env-uuid>"} → single env with full detail + its credentials. NotFound if the uuid doesn't exist.
+  - filter mode: omit uuid, optionally {"q": "<keyword>", "projectUuid", "page", "pageSize"} → paginated envs, each with its credentials.
+
+Project resolution: if projectUuid is omitted, the current git repo's origin is auto-resolved to a DebuggAI project. Returns {error:"NoProjectResolved", environments:[]} if neither is available.
+
+Credentials are returned inline per env as {uuid, label, username, role}. Password is NEVER returned — the handler defensively strips it regardless of what the service layer provides.
+
+Response: {project, filter, pageInfo, environments[]} — each environment includes a credentials[] array.`;
+export function buildSearchEnvironmentsTool() {
+    return {
+        name: 'search_environments',
+        title: 'Search Environments',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uuid: { type: 'string', description: 'Environment UUID. Returns single env with credentials inline. Mutually exclusive with projectUuid/q filter params.' },
+                projectUuid: { type: 'string', description: 'Override the auto-detected project. Used in filter mode.' },
+                q: { type: 'string', description: 'Free-text search over environment name. Mutually exclusive with uuid.' },
+                page: { type: 'number', description: 'Page number (1-indexed).' },
+                pageSize: { type: 'number', description: 'Page size (1..200). Default 20.' },
+            },
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedSearchEnvironmentsTool() {
+    const tool = buildSearchEnvironmentsTool();
+    return { ...tool, inputSchema: SearchEnvironmentsInputSchema, handler: searchEnvironmentsHandler };
+}

package/dist/tools/searchExecutions.js

@@ -0,0 +1,31 @@
+import { SearchExecutionsInputSchema } from '../types/index.js';
+import { searchExecutionsHandler } from '../handlers/searchExecutionsHandler.js';
+const DESCRIPTION = `Search or look up workflow executions (history of check_app_in_browser, trigger_crawl, and other workflow runs).
+
+Two modes:
+  - uuid mode: {"uuid": "<execution-uuid>"} → single execution with FULL detail including nodeExecutions, state, errorInfo. NotFound if the uuid doesn't exist.
+  - filter mode: {"status": "completed"|"running"|"failed"|"cancelled", "projectUuid": "...", "page", "pageSize"} → paginated summaries.
+
+Response shape: {filter, pageInfo, executions[]}. Summary items have outcome/status/durationMs/timestamps; uuid-mode items additionally have nodeExecutions + state + errorInfo.`;
+export function buildSearchExecutionsTool() {
+    return {
+        name: 'search_executions',
+        title: 'Search Workflow Executions',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uuid: { type: 'string', description: 'Execution UUID. Returns single execution with full detail. Mutually exclusive with projectUuid/status filters.' },
+                projectUuid: { type: 'string', description: 'Filter by project UUID.' },
+                status: { type: 'string', description: 'Filter by status: completed | running | failed | cancelled | pending.' },
+                page: { type: 'number', description: 'Page number (1-indexed).' },
+                pageSize: { type: 'number', description: 'Page size (1..200). Default 20.' },
+            },
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedSearchExecutionsTool() {
+    const tool = buildSearchExecutionsTool();
+    return { ...tool, inputSchema: SearchExecutionsInputSchema, handler: searchExecutionsHandler };
+}

package/dist/tools/searchProjects.js

@@ -0,0 +1,30 @@
+import { SearchProjectsInputSchema } from '../types/index.js';
+import { searchProjectsHandler } from '../handlers/searchProjectsHandler.js';
+const DESCRIPTION = `Search or look up projects.
+
+Two modes:
+  - uuid mode: pass {"uuid": "<project-uuid>"} → returns that project with the curated detail view (uuid, name, slug, platform, repoName, description, status, language, framework, timestamp, lastMod), or isError:true NotFound.
+  - filter mode: omit uuid, optionally pass {"q": "<keyword>", "page": 1, "pageSize": 20} → returns a paginated list of summaries (uuid, name, slug, repoName).
+
+Response shape is always {filter, pageInfo, projects[]}. uuid mode returns exactly one project; filter mode returns summaries.`;
+export function buildSearchProjectsTool() {
+    return {
+        name: 'search_projects',
+        title: 'Search Projects',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uuid: { type: 'string', description: 'Project UUID. When provided, returns exactly that project with full detail. Mutually exclusive with q.' },
+                q: { type: 'string', description: 'Free-text search (backend-side). Mutually exclusive with uuid.' },
+                page: { type: 'number', description: 'Page number (1-indexed). Default 1.' },
+                pageSize: { type: 'number', description: 'Page size (1..200). Default 20.' },
+            },
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedSearchProjectsTool() {
+    const tool = buildSearchProjectsTool();
+    return { ...tool, inputSchema: SearchProjectsInputSchema, handler: searchProjectsHandler };
+}