@debugg-ai/debugg-ai-mcp 1.0.29 → 1.0.31

package/README.md

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

package/dist/handlers/index.js

@@ -1,6 +1 @@
-/**
- * Handler exports for DebuggAI MCP Server
- */
 export * from './testPageChangesHandler.js';
-export * from './e2eSuiteHandlers.js';
-export * from './liveSessionHandlers.js';

package/dist/handlers/testPageChangesHandler.js

@@ -20,6 +20,9 @@ export async function testPageChangesHandler(input, context, progressCallback) {
     const originalUrl = resolveTargetUrl(input);
     let ctx = buildContext(originalUrl);
     let ngrokKeyId;
+    const abortController = new AbortController();
+    const onStdinClose = () => abortController.abort();
+    process.stdin.once('close', onStdinClose);
     try {
         // --- Find workflow template ---
         if (progressCallback) {
@@ -71,22 +74,29 @@ export async function testPageChangesHandler(input, context, progressCallback) {
             logger.info(`Tunnel ready for ${originalUrl} (id: ${executionUuid})`);
         }
         // --- Poll ---
-        let lastSteps = 0;
+        // nodeExecutions grows as each node completes: trigger → browser.setup → surfer.execute_task → browser.teardown
+        const NODE_PHASE_LABELS = {
+            0: 'Browser agent starting up...',
+            1: 'Browser ready, agent navigating...',
+            2: 'Agent evaluating app...',
+            3: 'Wrapping up...',
+        };
+        let lastNodeCount = 0;
         const finalExecution = await client.workflows.pollExecution(executionUuid, async (exec) => {
-            const steps = exec.state?.stepsTaken ?? 0;
-            if (steps !== lastSteps || exec.status !== 'pending') {
-                lastSteps = steps;
-                logger.info(`Execution status: ${exec.status}, steps: ${steps}`);
+            const nodeCount = exec.nodeExecutions?.length ?? 0;
+            if (nodeCount !== lastNodeCount || exec.status !== 'pending') {
+                lastNodeCount = nodeCount;
+                logger.info(`Execution status: ${exec.status}, nodes completed: ${nodeCount}`);
             }
             if (progressCallback) {
-                const progress = Math.min(3 + steps, 9);
-                await progressCallback({
-                    progress,
-                    total: 10,
-                    message: `${exec.status}: ${steps} step${steps !== 1 ? 's' : ''} taken`,
-                }).catch(() => { });
+                // Map 0-4 completed nodes to progress 3-9 (3 reserved for tunnel setup)
+                const progress = Math.min(3 + nodeCount * 2, 9);
+                const message = exec.status === 'running'
+                    ? (NODE_PHASE_LABELS[nodeCount] ?? 'Agent working...')
+                    : exec.status;
+                await progressCallback({ progress, total: 10, message });
             }
-        });
+        }, abortController.signal);
         const duration = Date.now() - startTime;
         // --- Format result ---
         const outcome = finalExecution.state?.outcome ?? finalExecution.status;
@@ -145,6 +155,7 @@ export async function testPageChangesHandler(input, context, progressCallback) {
         throw handleExternalServiceError(error, 'DebuggAI', 'test execution');
     }
     finally {
+        process.stdin.removeListener('close', onStdinClose);
         if (ngrokKeyId) {
             client.revokeNgrokKey(ngrokKeyId).catch(err => logger.warn(`Failed to revoke ngrok key ${ngrokKeyId}: ${err}`));
         }

package/dist/services/index.js

@@ -1,5 +1,3 @@
-import { createE2esService } from "./e2es.js";
-import { createBrowserSessionsService } from "./browserSessions.js";
 import { createWorkflowsService } from "./workflows.js";
 import { AxiosTransport } from "../utils/axiosTransport.js";
 import { config } from "../config/index.js";
@@ -34,9 +32,6 @@ export class DebuggAIServerClient {
     userApiKey;
     tx;
     url;
-    // Public "sub‑APIs"
-    e2es;
-    browserSessions;
     workflows;
     constructor(userApiKey) {
         this.userApiKey = userApiKey;
@@ -46,8 +41,6 @@ export class DebuggAIServerClient {
         const serverUrl = config.api.baseUrl;
         this.url = new URL(serverUrl);
         this.tx = new DebuggTransport({ baseUrl: serverUrl, apiKey: this.userApiKey, tokenType: config.api.tokenType });
-        this.e2es = createE2esService(this.tx);
-        this.browserSessions = createBrowserSessionsService(this.tx);
         this.workflows = createWorkflowsService(this.tx);
     }
     /**

package/dist/services/workflows.js

@@ -10,8 +10,15 @@ export const createWorkflowsService = (tx) => {
         async findEvaluationTemplate() {
             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'));
-            return evalTemplate ?? templates[0] ?? null;
+            if (!evalTemplate) {
+                throw new Error(`No "App Evaluation" workflow template found. ` +
+                    `Available templates: ${templates.map(t => `"${t.name}"`).join(', ')}. ` +
+                    `Ensure the backend has a template with "App Evaluation" in its name.`);
+            }
+            return evalTemplate;
         },
         async executeWorkflow(workflowUuid, contextData, env) {
             const body = { contextData };
@@ -38,9 +45,12 @@ export const createWorkflowsService = (tx) => {
             }
             return response;
         },
-        async pollExecution(executionUuid, onUpdate) {
+        async pollExecution(executionUuid, onUpdate, signal) {
             const deadline = Date.now() + EXECUTION_TIMEOUT_MS;
             while (Date.now() < deadline) {
+                if (signal?.aborted) {
+                    throw new Error(`Polling cancelled for execution ${executionUuid}`);
+                }
                 const execution = await service.getExecution(executionUuid);
                 if (onUpdate) {
                     await onUpdate(execution).catch(() => { });
@@ -48,7 +58,15 @@ export const createWorkflowsService = (tx) => {
                 if (TERMINAL_STATUSES.has(execution.status)) {
                     return execution;
                 }
-                await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS));
+                await new Promise((resolve, reject) => {
+                    const timer = setTimeout(resolve, POLL_INTERVAL_MS);
+                    if (signal) {
+                        signal.addEventListener('abort', () => {
+                            clearTimeout(timer);
+                            reject(new Error(`Polling cancelled for execution ${executionUuid}`));
+                        }, { once: true });
+                    }
+                });
             }
             throw new Error(`Execution ${executionUuid} timed out after ${EXECUTION_TIMEOUT_MS / 1000}s`);
         }

package/dist/tools/index.js

@@ -1,61 +1,17 @@
-/**
- * Tool registry and exports
- * Centralized location for all DebuggAI MCP tool definitions
- *
- * These tools provide AI agents with:
- * - Live remote browser sessions for real-time monitoring
- * - End-to-end testing with natural language descriptions
- * - Browser console logs, network traffic, and screenshot capture
- * - Test suite management and Git commit-based test generation
- */
 import { testPageChangesTool, validatedTestPageChangesTool } from './testPageChanges.js';
-import { startLiveSessionTool, stopLiveSessionTool, getLiveSessionStatusTool, getLiveSessionLogsTool, getLiveSessionScreenshotTool, validatedLiveSessionTools } from './liveSession.js';
-import { listTestsTool, listTestSuitesTool, createTestSuiteTool, createCommitSuiteTool, listCommitSuitesTool, getTestStatusTool, validatedE2ESuiteTools } from './e2eSuites.js';
-import { quickScreenshotTool, validatedQuickScreenshotTool } from './quickScreenshot.js';
-/**
- * All available tools for MCP server
- */
 export const tools = [
     testPageChangesTool,
-    startLiveSessionTool,
-    stopLiveSessionTool,
-    getLiveSessionStatusTool,
-    getLiveSessionLogsTool,
-    getLiveSessionScreenshotTool,
-    listTestsTool,
-    listTestSuitesTool,
-    createTestSuiteTool,
-    createCommitSuiteTool,
-    listCommitSuitesTool,
-    getTestStatusTool,
-    quickScreenshotTool,
 ];
-/**
- * All validated tools with handlers
- */
 export const validatedTools = [
     validatedTestPageChangesTool,
-    ...validatedLiveSessionTools,
-    ...validatedE2ESuiteTools,
-    validatedQuickScreenshotTool,
 ];
-/**
- * Tool registry for quick lookup
- */
 export const toolRegistry = new Map();
-// Initialize tool registry
 for (const tool of validatedTools) {
     toolRegistry.set(tool.name, tool);
 }
-/**
- * Get tool by name
- */
 export function getTool(name) {
     return toolRegistry.get(name);
 }
-/**
- * Check if tool exists
- */
 export function hasToolTool(name) {
     return toolRegistry.has(name);
 }

package/dist/types/index.js

@@ -15,79 +15,7 @@ export const TestPageChangesInputSchema = z.object({
     credentialRole: z.string().optional(),
     username: z.string().optional(),
     password: z.string().optional(),
-});
-/**
- * E2E Suite Tool Schemas
- */
-export const ListTestsInputSchema = z.object({
-    repoName: z.string().optional(),
-    branchName: z.string().optional(),
-    status: z.enum(['pending', 'running', 'completed', 'failed']).optional(),
-    page: z.number().int().positive().optional().default(1),
-    limit: z.number().int().min(1).max(100).optional().default(20),
-});
-export const ListTestSuitesInputSchema = z.object({
-    repoName: z.string().optional(),
-    branchName: z.string().optional(),
-    status: z.enum(['pending', 'running', 'completed', 'failed']).optional(),
-    page: z.number().int().positive().optional().default(1),
-    limit: z.number().int().min(1).max(100).optional().default(20),
-});
-export const CreateTestSuiteInputSchema = z.object({
-    description: z.string().min(1, 'Description is required'),
-    repoName: z.string().optional(),
-    branchName: z.string().optional(),
-    repoPath: z.string().optional(),
-    filePath: z.string().optional(),
-});
-export const CreateCommitSuiteInputSchema = z.object({
-    description: z.string().min(1, 'Description is required'),
-    repoName: z.string().optional(),
-    branchName: z.string().optional(),
-    repoPath: z.string().optional(),
-    filePath: z.string().optional(),
-});
-export const ListCommitSuitesInputSchema = z.object({
-    repoName: z.string().optional(),
-    branchName: z.string().optional(),
-    status: z.enum(['pending', 'running', 'completed', 'failed']).optional(),
-    page: z.number().int().positive().optional().default(1),
-    limit: z.number().int().min(1).max(100).optional().default(20),
-});
-export const GetTestStatusInputSchema = z.object({
-    suiteUuid: z.string().uuid('Invalid suite UUID'),
-    suiteType: z.enum(['test', 'commit']).optional().default('test'),
-});
-/**
- * Live Session Tool Schemas
- */
-export const StartLiveSessionInputSchema = z.object({
-    url: z.string().min(1, 'URL is required'),
-    localPort: z.number().int().min(1).max(65535).optional(),
-    sessionName: z.string().max(100).optional(),
-    monitorConsole: z.boolean().optional().default(true),
-    monitorNetwork: z.boolean().optional().default(true),
-    takeScreenshots: z.boolean().optional().default(false),
-    screenshotInterval: z.number().int().min(1).max(300).optional().default(10),
-});
-export const StopLiveSessionInputSchema = z.object({
-    sessionId: z.string().optional(),
-});
-export const GetLiveSessionStatusInputSchema = z.object({
-    sessionId: z.string().optional(),
-});
-export const GetLiveSessionLogsInputSchema = z.object({
-    sessionId: z.string().optional(),
-    logType: z.enum(['console', 'network', 'errors', 'all']).optional().default('all'),
-    since: z.string().datetime().optional(),
-    limit: z.number().int().min(1).max(1000).optional().default(100),
-});
-export const GetLiveSessionScreenshotInputSchema = z.object({
-    sessionId: z.string().optional(),
-    fullPage: z.boolean().optional().default(false),
-    quality: z.number().int().min(1).max(100).optional().default(90),
-    format: z.enum(['png', 'jpeg']).optional().default('png'),
-});
+}).refine((data) => data.url !== undefined || data.localPort !== undefined, { message: 'Provide a target via "url" (e.g. "https://example.com") or "localPort" for a local dev server' });
 /**
  * Error types
  */

package/package.json

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