@debugg-ai/debugg-ai-mcp 1.0.15 → 1.0.16

package/README.md

@@ -1,14 +1,12 @@
 # 🧪 Official MCP Server for Debugg AI
 
-**AI-driven browser automation and E2E test server** implementing the [Model Context Protocol (MCP)](https://modelcontext.org), designed to help AI agents test UI changes, simulate user behavior, and analyze visual outputs of running web applications — all via natural language and CLI tools. 
+**AI-powered development and testing toolkit** implementing the [Model Context Protocol (MCP)](https://modelcontext.org), designed to give AI agents comprehensive testing, debugging, and code analysis capabilities.
 
-End to end testing used to be a nightmare. Not just to setup, but to manage over time as you made changes to your app. 
-
-Debugg AI's MCP server offers a NEW way to test, where you never have to worry about setting up `playwright`, local browsers or proxies with it fully remote, managed browsers that simply connect to a server running locally or remotely via a secure `tunnel`. 
-
-That means no distracting chrome pop ups as it's running tests, no managing chrome or playwright versions, and best of all - ZERO CONFIGURATION. Just grab an API key and add us to your MCP server list. 
-
-Should you want to later rerun those tests or create a suite of them to run in your CI / CD pipeline, you can see all historical test results in your dashboard - [Debugg.AI App](https://app.debugg.ai) 
+Transform your development workflow with:
+- **Zero-config E2E testing** - Run browser tests with natural language descriptions
+- **Live session monitoring** - Real-time browser console, network, and screenshot monitoring
+- **Test suite management** - Create and manage comprehensive test suites
+- **Seamless CI/CD integration** - View all test results in your [Debugg.AI App](https://app.debugg.ai) dashboard 
 
 <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" />
@@ -18,23 +16,13 @@ Should you want to later rerun those tests or create a suite of them to run in y
 
 ## 🚀 Features
 
-* 🧠 **MCP Protocol Support**
-  Full MCP server implementation with CLI and tool registry support.
-
-* 🧪 **End-to-End Test Automation**
-  Trigger UI tests based on user stories or natural language descriptions via the `debugg_ai_test_page_changes` tool.
-
-* 🌐 **Localhost Web App Integration**
-  Test your running dev app on any `localhost` port with simulated user flows.
+### **12 Focused Development Tools**
 
-* 🧾 **MCP Tool Notifications**
-  Sends real-time progress updates back to clients with step descriptions and UI state goals.
-
-* 🧷 **Screenshot Support**
-  Capture final visual state of the page for LLMs with image rendering support.
-
-* 🧱 **Stdio Server Compatible**
-  Plug into any MCP-compatible client (like Claude Desktop, LangChain agents, etc.) via stdin/stdout.
+* 🧪 **E2E Testing Suite** - Run browser tests, create test suites, and generate commit-based tests
+* 🖥️ **Live Session Monitoring** - Real-time browser console, network traffic, and screenshot monitoring
+* 📊 **Test Management** - List, create, and track test suites and commit-based test suites
+* 📱 **Real-time Progress** - Live updates with screenshots and step-by-step execution
+* 🌐 **Universal Compatibility** - Works with any MCP-compatible client (Claude Desktop, LangChain, etc.)
 
 ---
 
@@ -61,145 +49,182 @@ Should you want to later rerun those tests or create a suite of them to run in y
 
 
 
-## 🛠️ Quickstart
+## 🛠️ Quick Setup
 
-### Ensure you have created a free account and generated an API Key - [DebuggAI](https://debugg.ai)
+### 1. Get Your API Key
+Create a free account at [debugg.ai](https://debugg.ai) and generate your API key.
 
-### Option 1: NPX (Local Development)
+### 2. Choose Your Installation Method
 
+**Option A: NPX (Recommended)**
 ```bash
 npx -y @debugg-ai/debugg-ai-mcp
 ```
 
-Use this when testing or integrating into tools like Claude Desktop or your own AI agent.
-
-### Option 2: Docker
-
+**Option B: Docker**
 ```bash
 docker run -i --rm --init \
   -e DEBUGGAI_API_KEY=your_api_key \
-  -e TEST_USERNAME_EMAIL=your_test_email \
-  -e TEST_USER_PASSWORD=your_password \
-  -e DEBUGGAI_LOCAL_PORT=3000 \
-  -e DEBUGGAI_LOCAL_REPO_NAME=your-org/your-repo \
-  -e DEBUGGAI_LOCAL_BRANCH_NAME=main \
-  -e DEBUGGAI_LOCAL_REPO_PATH=/app \
-  -e DEBUGGAI_LOCAL_FILE_PATH=/app/index.ts \
   quinnosha/debugg-ai-mcp
 ```
 
 ---
 
-## 🧰 MCP Tool: `debugg_ai_test_page_changes`
+## 🧰 Available Tools
 
-### Description
+### **E2E Testing Tools**
+- `debugg_ai_test_page_changes` - Run browser tests with natural language descriptions
+- `debugg_ai_create_test_suite` - Create organized test suites for features
+- `debugg_ai_create_commit_suite` - Generate tests based on git commits
+- `debugg_ai_get_test_status` - Monitor test execution and results
 
-Run an end-to-end test on a running web app, testing a UI feature or flow described in natural language. Allows AI agents in ANY code gen platform to quickly evaluate proposed changes and 
-ensure new functionality works as expected.
+### **Test Management Tools**
+- `debugg_ai_list_tests` - List all E2E tests with filtering and pagination
+- `debugg_ai_list_test_suites` - List all test suites with filtering options
+- `debugg_ai_list_commit_suites` - List all commit-based test suites
 
-### Input Parameters
-
-| Name          | Type   | Required  | Description                                            |
-| ------------- | ------ | --------- | ------------------------------------------------------ |
-| `description` | string | ✅        | What feature or page to test (e.g. "Signup page form") |
-| `localPort`   | number | ❌        | Port of your running app (default: `3000`)             |
-| `repoName`    | string | ❌        | GitHub repo name                                       |
-| `branchName`  | string | ❌        | Current branch                                         |
-| `repoPath`    | string | ❌        | Absolute path to the repo                              |
-| `filePath`    | string | ❌        | File to test                                           |
+### **Live Session Monitoring Tools**
+- `debugg_ai_start_live_session` - Start a live browser session with real-time monitoring
+- `debugg_ai_stop_live_session` - Stop an active live session
+- `debugg_ai_get_live_session_status` - Get the current status of a live session
+- `debugg_ai_get_live_session_logs` - Retrieve console and network logs from a live session
+- `debugg_ai_get_live_session_screenshot` - Capture screenshots from an active live session
 
 ---
 
-## 🧪 Example Claude Desktop Config
+## ⚙️ Configuration
+
+### **For Claude Desktop**
 
-```jsonc
+Add this to your MCP settings file:
+
+```json
 {
   "mcpServers": {
     "debugg-ai-mcp": {
       "command": "npx",
       "args": ["-y", "@debugg-ai/debugg-ai-mcp"],
       "env": {
-        "DEBUGGAI_API_KEY": "YOUR_API_KEY",
-        "TEST_USERNAME_EMAIL": "test@example.com",
-        "TEST_USER_PASSWORD": "supersecure",
-        "DEBUGGAI_LOCAL_PORT": 3000,
-        "DEBUGGAI_LOCAL_REPO_NAME": "org/project",
-        "DEBUGGAI_LOCAL_BRANCH_NAME": "main",
-        "DEBUGGAI_LOCAL_REPO_PATH": "/Users/you/project",
-        "DEBUGGAI_LOCAL_FILE_PATH": "/Users/you/project/index.ts"
+        "DEBUGGAI_API_KEY": "your_api_key_here"
       }
     }
   }
 }
 ```
 
----
+### **Optional Environment Variables**
+```bash
+# Required
+DEBUGGAI_API_KEY=your_api_key
+
+# Optional (with sensible defaults)
+DEBUGGAI_LOCAL_PORT=3000                    # Your app's port
+DEBUGGAI_LOCAL_REPO_NAME=your-org/repo      # GitHub repo name
+DEBUGGAI_LOCAL_REPO_PATH=/path/to/project   # Project directory
+```
+
+## 💡 Usage Examples
 
-## 🔐 Environment Variables
+### **Run a Quick E2E Test**
+```
+"Test the user login flow on my app running on port 3000"
+```
 
-| Variable                                | Description                                | Required |
-| --------------------------------------- | ------------------------------------------ | -------- |
-| `DEBUGGAI_API_KEY`                      | API key for calling DebuggAI backend       | ✅       |
-| `TEST_USERNAME_EMAIL`                   | Email of test user account                 | ❌       |
-| `TEST_USER_PASSWORD`                    | Password of test user account              | ❌       |
-| `DEBUGGAI_LOCAL_PORT`                   | Local port your app runs on                | ✅       |
-| `DEBUGGAI_LOCAL_REPO_NAME`              | GitHub repo name                           | ❌       |
-| `DEBUGGAI_LOCAL_BRANCH_NAME`            | Branch name                                | ❌       |
-| `DEBUGGAI_LOCAL_REPO_PATH`              | Local path to repo root                    | ❌       |
-| `DEBUGGAI_LOCAL_FILE_PATH`              | File to test                               | ❌       |
+### **Analyze Your Project** 
+```
+"What frameworks and languages are used in my codebase?"
+```
 
+### **Get Issue Insights**
+```
+"Show me all high-priority issues in my project"
+```
+
+### **Generate Test Coverage**
+```
+"Generate test coverage for the authentication module"
+```
 
 ---
 
 ## 🧑‍💻 Local Development
 
 ```bash
-# Clone the repo and install dependencies
+# Install dependencies
 npm install
 
-# Copy the test config and insert your creds
-cp test-config-example.json test-config.json
+# Run tests
+npm test
 
-# Run the local node-built dist
-npx @modelcontextprotocol/inspector --config test-config.json --server debugg-ai-mcp-node
+# Build project
+npm run build
 
-# OR Run the MCP server locally from above toplevel dir. 
-npx @modelcontextprotocol/inspector --config debugg-ai-mcp/test-config.json --server debugg-ai-mcp
+# Start server locally
+node dist/index.js
 ```
 
 ---
 
-## 📁 Repo Structure
+## 📁 Project Structure
 
 ```
-.
-├── e2e-agents/             # E2E browser test runners
-├── services/               # Client for DebuggAI API
-├── tunnels /               # Secure connections to remote web browsers
-├── index.ts                # Main MCP server entry
-├── Dockerfile              # Docker build config
-└── README.md
+debugg-ai-mcp/
+├── config/          # Configuration management  
+├── tools/           # 14 MCP tool definitions
+├── handlers/        # Tool implementation logic
+├── services/        # DebuggAI API integration
+├── utils/           # Shared utilities & logging
+├── types/           # TypeScript type definitions
+├── __tests__/       # Comprehensive test suite
+└── index.ts         # Main server entry point
 ```
 
 ---
 
-## 🧱 Built With
+## 🚀 Publishing & Releases
 
-* [Model Context Protocol SDK](https://github.com/modelcontextprotocol)
+This project uses automated publishing to NPM. Here's how it works:
+
+### **Automatic Publishing**
+- Every push to `main` triggers automatic NPM publishing
+- Only publishes if the version doesn't already exist
+- Includes full test suite validation and build verification
+
+### **Version Management**
+```bash
+# Bump version locally
+npm run version:patch  # 1.0.15 → 1.0.16
+npm run version:minor  # 1.0.15 → 1.1.0
+npm run version:major  # 1.0.15 → 2.0.0
+
+# Check package contents
+npm run publish:check
+```
+
+### **Manual Version Bump via GitHub**
+1. Go to **Actions** → **Version Bump**
+2. Click **"Run workflow"**
+3. Select version type or enter custom version
+4. Workflow will update version and trigger publish
+
+### **Setup for Contributors**
+See [`.github/PUBLISHING_SETUP.md`](.github/PUBLISHING_SETUP.md) for complete setup instructions.
 
 ---
 
-## 💬 Feedback & Issues
+## 💬 Support & Links
 
-For bugs, ideas, or integration help, open an issue or contact the DebuggAI team directly.
+- 📖 **Documentation**: [debugg.ai/docs](https://debugg.ai/docs)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/debugg-ai/debugg-ai-mcp/issues)
+- 💬 **Discord**: [Join our community](https://debugg.ai/discord)
+- 🌐 **Dashboard**: [app.debugg.ai](https://app.debugg.ai)
 
 ---
 
 ## 🔒 License
 
-MIT License © 2025 DebuggAI
+Apache-2.0 License © 2025 DebuggAI
 
 ---
 
-
-<p style="padding-top: 20px; text-align: center;">Made with 🩸, 💦, and 😭 in San Francisco</p>
+<p align="center">Made with ❤️ in San Francisco</p>

package/dist/config/index.js

@@ -0,0 +1,92 @@
+/**
+ * Centralized configuration management for DebuggAI MCP Server
+ * Handles environment variable validation and default values
+ */
+import { z } from 'zod';
+/**
+ * Configuration schema with validation
+ */
+const configSchema = z.object({
+    server: z.object({
+        name: z.string().default('DebuggAI MCP Server'),
+        version: z.string().default('0.1.1'),
+    }),
+    api: z.object({
+        key: z.string().min(1, 'DEBUGGAI_API_KEY is required'),
+        baseUrl: z.string().url().optional(),
+    }),
+    auth: z.object({
+        testUsername: z.string().optional(),
+        testPassword: z.string().optional(),
+    }),
+    defaults: z.object({
+        localPort: z.number().int().min(1).max(65535).optional(),
+        repoName: z.string().optional(),
+        branchName: z.string().optional(),
+        repoPath: z.string().optional(),
+        filePath: z.string().optional(),
+    }),
+    logging: z.object({
+        level: z.enum(['error', 'warn', 'info', 'debug']).default('info'),
+        format: z.enum(['json', 'simple']).default('simple'),
+    }),
+});
+/**
+ * Load and validate configuration from environment variables
+ */
+export function loadConfig() {
+    const rawConfig = {
+        server: {
+            name: 'DebuggAI MCP Server',
+            version: '0.1.1',
+        },
+        api: {
+            key: process.env.DEBUGGAI_API_KEY || '',
+            baseUrl: process.env.DEBUGGAI_API_BASE_URL,
+        },
+        auth: {
+            testUsername: process.env.TEST_USERNAME_EMAIL || '',
+            testPassword: process.env.TEST_USER_PASSWORD || '',
+        },
+        defaults: {
+            localPort: process.env.DEBUGGAI_LOCAL_PORT ? parseInt(process.env.DEBUGGAI_LOCAL_PORT, 10) : undefined,
+            repoName: process.env.DEBUGGAI_LOCAL_REPO_NAME || undefined,
+            branchName: process.env.DEBUGGAI_LOCAL_BRANCH_NAME || undefined,
+            repoPath: process.env.DEBUGGAI_LOCAL_REPO_PATH || undefined,
+            filePath: process.env.DEBUGGAI_LOCAL_FILE_PATH || undefined,
+        },
+        logging: {
+            level: process.env.LOG_LEVEL || 'info',
+            format: process.env.LOG_FORMAT || 'simple',
+        },
+    };
+    try {
+        return configSchema.parse(rawConfig);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const missingFields = error.errors
+                .map(err => `${err.path.join('.')}: ${err.message}`)
+                .join(', ');
+            throw new Error(`Configuration validation failed: ${missingFields}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Global configuration instance - loaded lazily to avoid import-time errors in tests
+ */
+let _config;
+export const config = {
+    get server() { return getConfig().server; },
+    get api() { return getConfig().api; },
+    get auth() { return getConfig().auth; },
+    get defaults() { return getConfig().defaults; },
+    get logging() { return getConfig().logging; }
+};
+function getConfig() {
+    if (!_config) {
+        _config = loadConfig();
+    }
+    return _config;
+}

package/dist/e2e-agents/e2eRunner.js

@@ -1,12 +1,22 @@
-import { downloadBinary } from '../tunnels/ngrok/index.js';
 import { v4 as uuidv4 } from 'uuid';
-import ngrok from 'ngrok';
+import { createRequire } from 'module';
+// Use createRequire to avoid ES module resolution issues
+const require = createRequire(import.meta.url);
+let ngrokModule = null;
+async function getNgrok() {
+    if (!ngrokModule) {
+        try {
+            ngrokModule = require('ngrok');
+        }
+        catch (error) {
+            throw new Error(`Failed to load ngrok module: ${error}`);
+        }
+    }
+    return ngrokModule;
+}
 async function startTunnel(authToken, localPort, domain) {
     try {
-        // await start({
-        //     addr: localPort,
-        //     hostname: domain,
-        // });
+        const ngrok = await getNgrok();
         if (process.env.DOCKER_CONTAINER === "true") {
             const url = await ngrok.connect({ proto: 'http', addr: `host.docker.internal:${localPort}`, hostname: domain, authtoken: authToken });
             return url;
@@ -18,14 +28,21 @@ async function startTunnel(authToken, localPort, domain) {
     }
     catch (err) {
         console.error('Error starting ngrok tunnel:', err);
+        throw err;
     }
 }
 async function stopTunnel(url) {
-    if (url) {
-        await ngrok.disconnect(url);
+    try {
+        const ngrok = await getNgrok();
+        if (url) {
+            await ngrok.disconnect(url);
+        }
+        else {
+            await ngrok.disconnect();
+        }
     }
-    else {
-        await ngrok.disconnect();
+    catch (err) {
+        console.error('Error stopping ngrok tunnel:', err);
     }
 }
 export class E2eTestRunner {
@@ -37,7 +54,7 @@ export class E2eTestRunner {
         await this.configureNgrok();
     }
     async configureNgrok() {
-        await downloadBinary();
+        // ngrok binary is downloaded automatically by the ngrok package
     }
     async startTunnel(authToken, port, url) {
         await startTunnel(authToken, port, url);
@@ -85,9 +102,11 @@ export class E2eTestRunner {
         console.error(`Creating new E2E test with description: ${testDescription}`);
         const key = uuidv4();
         const e2eTest = await this.client.e2es?.createE2eTest(testDescription, { filePath: filePath ?? "", repoName: repoName, branchName: branchName, repoPath: repoPath, key: key });
+        console.error("E2E test creation response:", JSON.stringify(e2eTest, null, 2));
         const authToken = e2eTest?.tunnelKey;
         if (!authToken) {
-            console.error("Failed to get auth token.");
+            console.error("Failed to get auth token. E2E test response:", e2eTest);
+            console.error("Available keys in response:", e2eTest ? Object.keys(e2eTest) : 'null response');
             return null;
         }
         await startTunnel(authToken, testPort, `${key}.ngrok.debugg.ai`);
@@ -157,7 +176,7 @@ export class E2eTestRunner {
                 // }
                 stopped = true;
             }
-        }, 5000);
+        }, 2000);
         // Timeout safeguard
         const timeout = setTimeout(async () => {
             if (stopped)