@debugg-ai/debugg-ai-mcp 1.0.1

package/README.md

@@ -0,0 +1,2 @@
+# debugg-ai-mcp
+MCP Server for debugg ai web browsing

package/dist/e2e-agents/e2eRunner.js

@@ -0,0 +1,169 @@
+import { downloadBinary } from '../tunnels/ngrok/index.js';
+import { v4 as uuidv4 } from 'uuid';
+import ngrok from 'ngrok';
+async function startTunnel(localPort, domain) {
+    try {
+        // await start({
+        //     addr: localPort,
+        //     hostname: domain,
+        // });
+        const url = await ngrok.connect({ addr: localPort, hostname: domain });
+        return url;
+    }
+    catch (err) {
+        console.error('Error starting ngrok tunnel:', err);
+    }
+}
+async function stopTunnel(url) {
+    if (url) {
+        await ngrok.disconnect(url);
+    }
+    else {
+        await ngrok.disconnect();
+    }
+}
+export class E2eTestRunner {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async setup() {
+        await this.configureNgrok();
+    }
+    async configureNgrok() {
+        await downloadBinary();
+    }
+    async startTunnel(port, url) {
+        await startTunnel(port, url);
+        console.error(`Tunnel started at: ${url}`);
+        return url;
+    }
+    /**
+     * Run E2E test generator for a single file *quietly* in the background.
+     * @param filePath absolute path of the file to test
+     */
+    async runTests(e2eRun) {
+        // Start by opening an ngrok tunnel.
+        // call the debugg ai endpoint to start running the test
+        // retrieve the results when done
+        // save files locally somewhere
+        const listener = await startTunnel(3011, `${e2eRun.key}.ngrok.debugg.ai`);
+        console.error(`Tunnel started at: ${listener}`);
+        const interval = setInterval(async () => {
+            const newE2eRun = await this.client.e2es?.getE2eRun(e2eRun.uuid);
+            console.error(`E2E run - ${newE2eRun}`);
+            if (newE2eRun?.status === 'completed') {
+                console.error(`E2E run completed - ${newE2eRun}`);
+                clearInterval(interval);
+                await stopTunnel(listener);
+            }
+        }, 1000);
+        // if the run doesn't complete in time, disconnect the tunnel
+        const setTimer = setTimeout(async () => {
+            clearInterval(interval);
+            clearTimeout(setTimer);
+            await stopTunnel(listener);
+        }, 300000);
+        return undefined;
+    }
+    /**
+     * Create a new E2E test and run it.
+     * @param testPort - The port to use for the test.
+     * @param testDescription - The description of the test.
+     * @param filePath - The path to the file to test.
+     * @param repoName - The name of the repository.
+     * @param branchName - The name of the branch.
+     * @param repoPath - The path to the repository.
+     */
+    async createNewE2eTest(testPort, testDescription, repoName, branchName, repoPath, filePath) {
+        console.error(`Creating new E2E test with description: ${testDescription}`);
+        const key = uuidv4();
+        await startTunnel(testPort, `${key}.ngrok.debugg.ai`);
+        const e2eTest = await this.client.e2es?.createE2eTest(testDescription, filePath ?? "", repoName, branchName, {
+            repoPath: repoPath,
+            key: key
+        });
+        console.error(`E2E test created - ${e2eTest}`);
+        if (!e2eTest) {
+            console.error("Failed to create E2E test.");
+            return null;
+        }
+        if (!e2eTest.curRun) {
+            console.error("Failed to create E2E test run.");
+            return null;
+        }
+        return e2eTest.curRun;
+    }
+    async handleE2eRun(e2eRun, onUpdate) {
+        console.error(`🔧 Handling E2E run - ${e2eRun.uuid}`);
+        console.error(`🌐 Tunnel started at: ${e2eRun.key}.ngrok.debugg.ai`);
+        let stopped = false;
+        let updatedRun = e2eRun;
+        const timeout = setTimeout(async () => {
+            if (stopped)
+                return;
+            clearInterval(interval);
+            await stopTunnel(`https://${e2eRun.key}.ngrok.debugg.ai`);
+            console.error(`⏰ E2E test timed out after 15 minutes`);
+            stopped = true;
+        }, 900_000);
+        const interval = setInterval(async () => {
+            const latestRun = await this.client.e2es?.getE2eRun(e2eRun.uuid);
+            if (!latestRun)
+                return;
+            updatedRun = latestRun;
+            console.error(`📡 Polled E2E run status: ${updatedRun.status}`);
+            await onUpdate(updatedRun); // 🔁 Invoke the callback with the updated run
+            if (updatedRun.status === 'completed') {
+                clearInterval(interval);
+                clearTimeout(timeout);
+                await stopTunnel(`https://${e2eRun.key}.ngrok.debugg.ai`);
+                stopped = true;
+            }
+        }, 5000);
+        while (!stopped) {
+            await new Promise(resolve => setTimeout(resolve, 1000));
+        }
+        return updatedRun;
+    }
+    async blockingHandleE2eRun(port, e2eRun) {
+        console.error(`🔧 Handling E2E run - ${e2eRun.uuid}`);
+        // Start ngrok tunnel
+        await startTunnel(port, `${e2eRun.key}.ngrok.debugg.ai`);
+        console.error(`🌐 Tunnel started at: ${e2eRun.key}.ngrok.debugg.ai`);
+        let stopped = false;
+        let lastStep = 0;
+        let updatedRun = e2eRun;
+        // Poll every second for completion
+        const interval = setInterval(async () => {
+            updatedRun = await this.client.e2es?.getE2eRun(e2eRun.uuid);
+            if (!updatedRun)
+                return;
+            console.error(`📡 Polled E2E run status: ${updatedRun.status}`);
+            if (updatedRun.status === 'completed') {
+                clearInterval(interval);
+                clearTimeout(timeout);
+                await stopTunnel(`https://${e2eRun.key}.ngrok.debugg.ai`);
+                // if (updatedRun.runGif) {
+                //     fetchAndOpenGif(this.repoPath ?? "", updatedRun.runGif, updatedRun.test?.name ?? "", updatedRun.uuid);
+                // }
+                stopped = true;
+            }
+        }, 5000);
+        // Timeout safeguard
+        const timeout = setTimeout(async () => {
+            if (stopped)
+                return;
+            clearInterval(interval);
+            await stopTunnel(`https://${e2eRun.key}.ngrok.debugg.ai`);
+            console.error(`⏰ E2E test timed out after 15 minutes\n`);
+            stopped = true;
+        }, 900_000);
+        // Wait for the polling to complete or timeout to expire
+        while (!stopped) {
+            await new Promise(resolve => setTimeout(resolve, 1000));
+        }
+        return updatedRun;
+    }
+}
+export default E2eTestRunner;

package/dist/e2e-agents/recordingHandler.js

@@ -0,0 +1,57 @@
+import * as fs from "fs";
+import * as http from "http";
+import * as https from "https";
+import * as path from "path";
+import { URL } from "url";
+export async function fetchAndOpenGif(projectRoot, recordingUrl, testName, testId) {
+    const cacheDir = path.join(projectRoot, ".debugg-ai", "e2e-runs");
+    console.error('....downloading gif....');
+    console.error('cacheDir', cacheDir);
+    console.error('testId', testId);
+    console.error('recordingUrl', recordingUrl);
+    let localUrl = recordingUrl.replace('localhost', 'localhost:8002');
+    console.error('localUrl', localUrl);
+    await fs.promises.mkdir(cacheDir, { recursive: true });
+    const filePath = path.join(cacheDir, `${testName.replace(/[^a-zA-Z0-9]/g, '-')}-${testId.slice(0, 4)}.gif`);
+    const fileUrl = new URL(localUrl);
+    const file = fs.createWriteStream(filePath);
+    console.error(`⬇️ Downloading test recording...`);
+    await new Promise((resolve, reject) => {
+        console.error('fetching gif', fileUrl);
+        if (fileUrl.protocol === 'https:') {
+            https.get(localUrl, (response) => {
+                if (response.statusCode !== 200) {
+                    reject(new Error(`Failed to download file: ${response.statusCode}`));
+                    return;
+                }
+                response.pipe(file);
+                file.on("finish", () => {
+                    file.close();
+                    resolve();
+                });
+            }).on("error", (err) => {
+                fs.unlinkSync(filePath);
+                reject(err);
+            });
+        }
+        else {
+            http.get(localUrl, (response) => {
+                if (response.statusCode !== 200) {
+                    reject(new Error(`Failed to download file: ${response.statusCode}`));
+                    return;
+                }
+                response.pipe(file);
+                file.on("finish", () => {
+                    file.close();
+                    resolve();
+                });
+            }).on("error", (err) => {
+                fs.unlinkSync(filePath);
+                reject(err);
+            });
+        }
+    });
+    console.error(`📂 Opening test recording`);
+    // const fileUri = vscode.Uri.file(filePath);
+    // await vscode.commands.executeCommand('vscode.open', fileUri);
+}

package/dist/e2e-agents/resultsFormatter.js

@@ -0,0 +1,102 @@
+export class RunResultFormatter {
+    steps = [];
+    passed(result) {
+        return result.status === "completed" && result.outcome === "pass";
+    }
+    formatFailures(result) {
+        if (this.passed(result) || !result.outcome)
+            return "";
+        return "\n\n❌ Failures:" + "\n" + `> ${result.outcome}`;
+    }
+    formatStepsAsMarkdown() {
+        if (this.steps.length === 0)
+            return "";
+        return ("\n\n" +
+            this.steps
+                .map((s, idx) => {
+                const num = `Step ${idx + 1}:`;
+                const label = s.label.padEnd(30);
+                const icon = "✅ Success";
+                // s.status === "pending"
+                //     ? chalk.yellow("⏳ Pending")
+                //     : s.status === "success"
+                //         ? chalk.green("✅ Success")
+                //         : chalk.red("❌ Failed");
+                return `${num} ${label} ${icon}`;
+            })
+                .join("\n\n"));
+    }
+    updateStep(label, status) {
+        const existing = this.steps.find((s) => s.label === label);
+        if (existing) {
+            existing.status = status;
+        }
+        else {
+            this.steps.push({ label, status });
+        }
+        console.error('updating step. steps ->', this.steps);
+        // Clear terminal and redraw
+        console.error("\x1Bc"); // ANSI clear screen
+        console.error("🧪 E2E Test Progress" +
+            `\r\n${this.steps
+                .map((s, i) => {
+                const icon = s.status === "pending"
+                    ? "⏳"
+                    : s.status === "success"
+                        ? "✅"
+                        : "❌";
+                return `${`Step ${i + 1}:`} ${s.label.padEnd(30)} ${icon}`;
+            })
+                .join("\r\n")}`);
+    }
+    formatTerminalBox(result) {
+        const header = this.passed(result)
+            ? "✅ Test Passed"
+            : "❌ Test Failed";
+        const body = [
+            "Test: " + result.test?.name,
+            "Description: " + (result.test?.description ?? "None"),
+            "Duration: " + `${result.metrics?.executionTime ?? 0}s`,
+            "Status: " + result.status,
+            "Outcome: " + result.outcome,
+            this.formatStepsAsMarkdown(),
+            this.passed(result) ? "" : this.formatFailures(result),
+        ]
+            .filter(Boolean)
+            .join("\n");
+        return `${header}\n${body}`;
+    }
+    formatMarkdownSummary(result) {
+        return [
+            `🧪 **Test Name:** ${result.test?.name ?? "Unknown"}`,
+            `📄 **Description:** ${result.test?.description ?? "None"}`,
+            `⏱ **Duration:** ${result.metrics?.executionTime ?? 0}s`,
+            `🔎 **Status:** ${result.status}`,
+            `📊 **Outcome:** ${result.outcome}`,
+            this.formatStepsAsMarkdown(),
+            this.formatFailures(result),
+        ]
+            .filter(Boolean)
+            .join("\n")
+            .trim();
+    }
+    /*
+    Terminal uses different formatting than markdown.
+    */
+    terminalSummary(result) {
+        return [
+            `🧪 Test Name: ${result.test?.name ?? "Unknown"}`,
+            `📄 Description: ${result.test?.description ?? "None"}`,
+            `⏱ Duration: ${result.metrics?.executionTime ?? 0}s`,
+            `🔎 Status: ${result.status}`,
+            `📊 Outcome: ${result.outcome}`,
+            this.formatFailures(result),
+        ]
+            .filter(Boolean)
+            .join("\r\n")
+            .trim();
+    }
+    appendToTestRun(result) {
+        console.error(this.terminalSummary(result));
+    }
+}

package/dist/index.js

@@ -0,0 +1,177 @@
+// index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { DebuggAIServerClient } from "./services/index.js";
+import { E2eTestRunner } from "./e2e-agents/e2eRunner.js";
+const createE2eTestTool = {
+    name: "debugg_ai_test_page_changes",
+    description: "Use DebuggAI to run & and test UI changes that have been made with its User emulation agents",
+    inputSchema: {
+        type: "object",
+        properties: {
+            description: {
+                type: "string",
+                description: "Description of what page (relative url) and features should be tested.",
+            },
+            localPort: {
+                type: "number",
+                description: "Localhost port number where the app is running. Eg. 3000",
+            },
+            filePath: {
+                type: "string",
+                description: "Absolute path to the file to test",
+            },
+            repoName: {
+                type: "string",
+                description: "The name of the current repository",
+            },
+            branchName: {
+                type: "string",
+                description: "Current branch name",
+            },
+            repoPath: {
+                type: "string",
+                description: "Local path of the repo root",
+            },
+        },
+        required: ["description",],
+    },
+};
+async function configureTestRunner(client) {
+    const e2eTestRunner = new E2eTestRunner(client);
+    return e2eTestRunner;
+}
+const server = new Server({
+    name: "DebuggAI MCP Server",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    console.error("Received CallToolRequest:", req);
+    const apiKey = process.env.DEBUGGAI_API_KEY;
+    const testUsername = process.env.TEST_USERNAME_EMAIL;
+    const testPassword = process.env.TEST_USER_PASSWORD;
+    if (!apiKey || !testUsername || !testPassword) {
+        console.error("Missing one or more required environment variables: DEBUGGAI_API_KEY, TEST_USERNAME_EMAIL, TEST_USER_PASSWORD");
+        process.exit(1);
+    }
+    try {
+        const { name, arguments: args } = req.params;
+        if (name === "debugg_ai_test_page_changes") {
+            const { description } = args;
+            let localPort = parseInt(process.env.DEBUGGAI_LOCAL_PORT ?? "3000");
+            let repoName = process.env.DEBUGGAI_LOCAL_REPO_NAME ?? "test-user-repo/test-repo";
+            let branchName = process.env.DEBUGGAI_LOCAL_BRANCH_NAME ?? "main";
+            let repoPath = process.env.DEBUGGAI_LOCAL_REPO_PATH ?? "/Users/test-user-repo/test-repo";
+            let filePath = process.env.DEBUGGAI_LOCAL_FILE_PATH ?? "/Users/test-user-repo/test-repo/index.ts";
+            const progressToken = req.params._meta?.progressToken;
+            if (args?.localPort) {
+                localPort = args.localPort;
+            }
+            if (args?.repoName) {
+                repoName = args.repoName;
+            }
+            if (args?.branchName) {
+                branchName = args.branchName;
+            }
+            if (args?.repoPath) {
+                repoPath = args.repoPath;
+            }
+            if (args?.filePath) {
+                filePath = args.filePath;
+            }
+            if (progressToken == undefined) {
+                console.error("No progress token found");
+                return {
+                    content: [
+                        { type: "text", text: "No progress token found" },
+                    ],
+                };
+            }
+            const client = new DebuggAIServerClient(process.env.DEBUGGAI_API_KEY ?? "");
+            const e2eTestRunner = await configureTestRunner(client);
+            const e2eRun = await e2eTestRunner.createNewE2eTest(localPort, description, repoName, branchName, repoPath, filePath);
+            if (!e2eRun) {
+                console.error("Failed to create E2E test");
+                return {
+                    content: [
+                        { type: "text", text: "Failed to create E2E test" },
+                    ],
+                };
+            }
+            await server.notification({
+                method: "notifications/progress",
+                params: {
+                    progress: 0,
+                    total: 20,
+                    progressToken,
+                },
+            });
+            const finalRun = await e2eTestRunner.handleE2eRun(e2eRun, async (update) => {
+                console.error(`📢 Status: ${update.status}`);
+                const curStep = update.conversations?.[0]?.messages?.length;
+                const totalSteps = update.conversations?.[0]?.messages?.length;
+                await server.notification({
+                    method: "notifications/progress",
+                    params: {
+                        progress: curStep,
+                        total: 20,
+                        progressToken,
+                    },
+                });
+            });
+            const testOutcome = finalRun?.outcome;
+            const testDetails = finalRun?.conversations?.[0]?.messages?.map((message) => message.jsonContent?.currentState?.nextGoal);
+            const runGif = finalRun?.runGif;
+            let base64 = "";
+            if (runGif) {
+                const response = await fetch(runGif);
+                const arrayBuffer = await response.arrayBuffer();
+                base64 = Buffer.from(arrayBuffer).toString('base64');
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ testOutcome, testDetails }, null, 2),
+                    },
+                    {
+                        type: "image",
+                        data: base64,
+                        mimeType: "image/jpeg",
+                    }
+                ],
+            };
+        }
+        throw new Error(`Tool not found: ${name}`);
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }),
+                },
+            ],
+        };
+    }
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [createE2eTestTool],
+    };
+});
+async function main() {
+    console.error("Starting DebuggAI MCP server...");
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("DebuggAI MCP Server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error in main():", err);
+    process.exit(1);
+});

package/dist/services/coverage.js

@@ -0,0 +1,127 @@
+export const createCoverageService = (tx) => ({
+    /**
+     * Create a test coverage file for a given file
+     */
+    async createCoverage(fileContents, filePath, repoName, branchName, params) {
+        try {
+            const serverUrl = "api/v1/coverage/";
+            console.error('Branch name - ', branchName, ' repo name - ', repoName, ' repo path - ', params?.repoPath);
+            let relativePath = filePath;
+            // Convert absolute path to relative path
+            if (params?.repoPath) {
+                relativePath = filePath.replace(params?.repoPath + "/", "");
+            }
+            else {
+                console.error("No repo path found for file");
+                // split based on the repo name
+                const repoBaseName = repoName.split("/")[-1]; // typically the form of 'userName/repoName'
+                const splitPath = filePath.split(repoBaseName);
+                if (splitPath.length === 2) { // if the repo name is in the path & only once, otherwise unclear how to handle
+                    relativePath = splitPath[1];
+                }
+                else {
+                    relativePath = filePath;
+                }
+            }
+            console.error("GET_COVERAGE: Full path - ", filePath, ". Relative path - ", relativePath);
+            const fileParams = {
+                ...params,
+                fileContents: fileContents,
+                absPath: filePath,
+                filePath: relativePath,
+                repoName: repoName,
+                branchName: branchName,
+            };
+            const response = await tx.post(serverUrl, { ...fileParams });
+            console.error("Raw API response:", response);
+            return response;
+        }
+        catch (err) {
+            console.error("Error fetching issues in file:", err);
+            return null;
+        }
+    },
+    /**
+     * Log a failed run for a given test file
+     */
+    async logFailedRun(fileContents, filePath, repoName, branchName, params) {
+        try {
+            const serverUrl = "api/v1/coverage/log_failed_run/";
+            console.error('Branch name - ', branchName, ' repo name - ', repoName, ' repo path - ', params?.repoPath);
+            let relativePath = filePath;
+            // Convert absolute path to relative path
+            if (params?.repoPath) {
+                relativePath = filePath.replace(params?.repoPath + "/", "");
+            }
+            else {
+                console.error("No repo path found for file");
+                // split based on the repo name
+                const repoBaseName = repoName.split("/")[-1]; // typically the form of 'userName/repoName'
+                const splitPath = filePath.split(repoBaseName);
+                if (splitPath.length === 2) { // if the repo name is in the path & only once, otherwise unclear how to handle
+                    relativePath = splitPath[1];
+                }
+                else {
+                    relativePath = filePath;
+                }
+            }
+            console.error("GET_COVERAGE: Full path - ", filePath, ". Relative path - ", relativePath);
+            const fileParams = {
+                ...params,
+                fileContents: fileContents,
+                absPath: filePath,
+                filePath: relativePath,
+                repoName: repoName,
+                branchName: branchName,
+            };
+            const response = await tx.post(serverUrl, { ...fileParams });
+            console.error("Raw API response:", response);
+            return response;
+        }
+        catch (err) {
+            console.error("Error fetching issues in file:", err);
+            return null;
+        }
+    },
+    /**
+     * Get a test coverage file for a given file
+     */
+    async getCoverage(filePath, repoName, branchName, params) {
+        try {
+            const serverUrl = "api/v1/coverage/for_file/";
+            console.error('Branch name - ', branchName, ' repo name - ', repoName, ' repo path - ', params?.repoPath);
+            let relativePath = filePath;
+            // Convert absolute path to relative path
+            if (params?.repoPath) {
+                relativePath = filePath.replace(params?.repoPath + "/", "");
+            }
+            else {
+                console.error("No repo path found for file");
+                // split based on the repo name
+                const repoBaseName = repoName.split("/")[-1]; // typically the form of 'userName/repoName'
+                const splitPath = filePath.split(repoBaseName);
+                if (splitPath.length === 2) { // if the repo name is in the path & only once, otherwise unclear how to handle
+                    relativePath = splitPath[1];
+                }
+                else {
+                    relativePath = filePath;
+                }
+            }
+            console.error("GET_COVERAGE: Full path - ", filePath, ". Relative path - ", relativePath);
+            const fileParams = {
+                ...params,
+                filePath: relativePath,
+                absPath: filePath,
+                repoName: repoName,
+                branchName: branchName,
+            };
+            const response = await tx.get(serverUrl, { ...fileParams });
+            console.error("Raw API response:", response);
+            return response;
+        }
+        catch (err) {
+            console.error("Error fetching issues in file:", err);
+            return null;
+        }
+    }
+});