@debugg-ai/debugg-ai-mcp 1.0.32 → 1.0.33

package/dist/config/index.js

@@ -43,6 +43,10 @@ const configSchema = z.object({
         level: z.enum(['error', 'warn', 'info', 'debug']).default('info'),
         format: z.enum(['json', 'simple']).default('simple'),
     }),
+    telemetry: z.object({
+        posthogApiKey: z.string().optional(),
+        posthogHost: z.string().optional(),
+    }),
 });
 export function loadConfig() {
     const rawConfig = {
@@ -67,6 +71,10 @@ export function loadConfig() {
             level: process.env.LOG_LEVEL || 'info',
             format: process.env.LOG_FORMAT || 'simple',
         },
+        telemetry: {
+            posthogApiKey: process.env.POSTHOG_API_KEY || undefined,
+            posthogHost: process.env.POSTHOG_HOST || undefined,
+        },
     };
     try {
         return configSchema.parse(rawConfig);
@@ -86,7 +94,8 @@ export const config = {
     get server() { return getConfig().server; },
     get api() { return getConfig().api; },
     get defaults() { return getConfig().defaults; },
-    get logging() { return getConfig().logging; }
+    get logging() { return getConfig().logging; },
+    get telemetry() { return getConfig().telemetry; },
 };
 function getConfig() {
     if (!_config) {

package/dist/index.js

@@ -21,7 +21,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { config } from "./config/index.js";
 import { tools, getTool } from "./tools/index.js";
-import { Logger, validateInput, createErrorResponse, toMCPError, handleConfigurationError } from "./utils/index.js";
+import { Logger, validateInput, createErrorResponse, toMCPError, handleConfigurationError, Telemetry, TelemetryEvents, } from "./utils/index.js";
 // Initialize logger
 const logger = new Logger({ module: 'main' });
 /**
@@ -108,8 +108,11 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const progressCallback = createProgressCallback(typeof progressToken === 'string' || typeof progressToken === 'number' ? String(progressToken) : undefined);
         // Execute tool handler with progress callback
         requestLogger.info(`Executing tool: ${name}`);
+        const toolStart = Date.now();
         const result = await tool.handler(validatedInput, context, progressCallback);
+        const toolDuration = Date.now() - toolStart;
         requestLogger.info(`Tool execution completed: ${name}`);
+        Telemetry.capture(TelemetryEvents.TOOL_EXECUTED, { toolName: name, durationMs: toolDuration, success: true });
         return result;
     }
     catch (error) {
@@ -121,6 +124,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             message: mcpError.message,
             data: mcpError.data
         });
+        Telemetry.capture(TelemetryEvents.TOOL_FAILED, { toolName: name, errorCode: mcpError.code });
         return createErrorResponse(mcpError, typedReq.params.name);
     }
 });
@@ -149,6 +153,15 @@ async function main() {
         if (!config.api.key) {
             throw new Error('Missing required environment variable: DEBUGGAI_API_KEY');
         }
+        // Initialize telemetry (PostHog when key is set, Noop otherwise)
+        Telemetry.setDistinctId(config.api.key);
+        if (config.telemetry.posthogApiKey) {
+            const { PostHogProvider } = await import('./services/posthogProvider.js');
+            Telemetry.configure(new PostHogProvider(config.telemetry.posthogApiKey, {
+                host: config.telemetry.posthogHost,
+            }));
+            logger.info('Telemetry enabled (PostHog)');
+        }
         // Create and connect transport
         const transport = new StdioServerTransport();
         await server.connect(transport);
@@ -168,12 +181,14 @@ async function main() {
 /**
  * Handle graceful shutdown
  */
-process.on('SIGINT', () => {
+process.on('SIGINT', async () => {
     logger.info('Received SIGINT, shutting down gracefully');
+    await Telemetry.shutdown();
     process.exit(0);
 });
-process.on('SIGTERM', () => {
+process.on('SIGTERM', async () => {
     logger.info('Received SIGTERM, shutting down gracefully');
+    await Telemetry.shutdown();
     process.exit(0);
 });
 /**

package/dist/services/ngrok/tunnelManager.js

@@ -17,6 +17,7 @@
  *     process recently touched the entry the timer resets instead of stopping.
  */
 import { Logger } from '../../utils/logger.js';
+import { Telemetry, TelemetryEvents } from '../../utils/telemetry.js';
 import { isLocalhostUrl, extractLocalhostPort, generateTunnelUrl } from '../../utils/urlParser.js';
 import { v4 as uuidv4 } from 'uuid';
 import { getDefaultRegistry, } from './tunnelRegistry.js';
@@ -128,6 +129,7 @@ class TunnelManager {
         if (!tunnelInfo.isOwned) {
             // Borrowed — just drop the local reference; owner manages the real tunnel
             logger.info(`Released borrowed tunnel reference: ${tunnelInfo.publicUrl}`);
+            Telemetry.capture(TelemetryEvents.TUNNEL_STOPPED, { port: tunnelInfo.port, reason: 'released', isOwned: false });
             return;
         }
         // Owned — remove from shared registry, then disconnect + revoke
@@ -183,6 +185,7 @@ class TunnelManager {
         const existing = this.getTunnelForPort(port);
         if (existing) {
             logger.info(`Reusing existing tunnel for port ${port}: ${existing.publicUrl}`);
+            Telemetry.capture(TelemetryEvents.TUNNEL_PROVISIONED, { port, how: 'reused' });
             return { url: existing.publicUrl, tunnelId: existing.tunnelId, isLocalhost: true };
         }
         // 2. Deduplicate concurrent creation requests for the same port
@@ -212,6 +215,7 @@ class TunnelManager {
             regEntry.lastAccessedAt = now;
             this.reg.write(registry);
             this.resetTunnelTimer(borrowed);
+            Telemetry.capture(TelemetryEvents.TUNNEL_PROVISIONED, { port, how: 'borrowed' });
             return { url: regEntry.publicUrl, tunnelId: regEntry.tunnelId, isLocalhost: true };
         }
         // 4. Create a new tunnel (this process becomes the owner)
@@ -290,6 +294,7 @@ class TunnelManager {
             }
             this.resetTunnelTimer(tunnelInfo);
             logger.info(`Tunnel created: ${publicUrl} → localhost:${port}`);
+            Telemetry.capture(TelemetryEvents.TUNNEL_PROVISIONED, { port, how: 'created' });
             return tunnelInfo;
         }
         catch (error) {
@@ -334,6 +339,7 @@ class TunnelManager {
                 }
             }
             logger.info(`Auto-shutting down tunnel ${tunnelInfo.tunnelId} after inactivity`);
+            Telemetry.capture(TelemetryEvents.TUNNEL_STOPPED, { port: tunnelInfo.port, reason: 'auto-shutoff', isOwned: tunnelInfo.isOwned });
             await this.stopTunnel(tunnelInfo.tunnelId).catch((err) => logger.error(`Failed to auto-shutdown tunnel ${tunnelInfo.tunnelId}:`, err));
         }, this.TUNNEL_TIMEOUT_MS);
     }

package/dist/services/posthogProvider.js

@@ -0,0 +1,32 @@
+/**
+ * PostHog telemetry provider.
+ * Enabled when POSTHOG_API_KEY is set in the environment.
+ */
+import { PostHog } from 'posthog-node';
+export class PostHogProvider {
+    client;
+    constructor(apiKey, options) {
+        this.client = new PostHog(apiKey, {
+            host: options?.host ?? 'https://us.i.posthog.com',
+            flushAt: 20,
+            flushInterval: 10000,
+        });
+    }
+    capture(event) {
+        this.client.capture({
+            distinctId: event.distinctId,
+            event: event.event,
+            properties: event.properties,
+            timestamp: event.timestamp,
+        });
+    }
+    identify(distinctId, properties) {
+        this.client.identify({ distinctId, properties });
+    }
+    async flush() {
+        await this.client.flush();
+    }
+    async shutdown() {
+        await this.client.shutdown();
+    }
+}

package/dist/services/workflows.js

@@ -2,6 +2,7 @@
  * Workflows Service
  * 4-step integration: find template → execute → poll → result
  */
+import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
 const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
 const POLL_INTERVAL_MS = 3000;
 const EXECUTION_TIMEOUT_MS = 10 * 60 * 1000; // 10 min
@@ -44,15 +45,26 @@ export const createWorkflowsService = (tx) => {
         },
         async pollExecution(executionUuid, onUpdate, signal) {
             const deadline = Date.now() + EXECUTION_TIMEOUT_MS;
+            const pollStart = Date.now();
+            let pollCount = 0;
             while (Date.now() < deadline) {
                 if (signal?.aborted) {
                     throw new Error(`Polling cancelled for execution ${executionUuid}`);
                 }
                 const execution = await service.getExecution(executionUuid);
+                pollCount++;
                 if (onUpdate) {
                     await onUpdate(execution).catch(() => { });
                 }
                 if (TERMINAL_STATUSES.has(execution.status)) {
+                    Telemetry.capture(TelemetryEvents.WORKFLOW_EXECUTED, {
+                        status: execution.status,
+                        success: execution.state?.success ?? false,
+                        outcome: execution.state?.outcome ?? null,
+                        stepsTaken: execution.state?.stepsTaken ?? 0,
+                        durationMs: Date.now() - pollStart,
+                        pollCount,
+                    });
                     return execution;
                 }
                 await new Promise((resolve, reject) => {

package/dist/utils/index.js

@@ -6,3 +6,4 @@ export * from './validation.js';
 export * from './errors.js';
 export * from './projectAnalyzer.js';
 export * from './imageUtils.js';
+export * from './telemetry.js';

package/dist/utils/telemetry.js

@@ -0,0 +1,57 @@
+/**
+ * Generic telemetry abstraction layer.
+ * Providers implement TelemetryProvider; call sites use Telemetry.capture().
+ * Falls back to NoopProvider when no provider is configured.
+ */
+import { createHash } from 'crypto';
+class NoopProvider {
+    capture(_event) { }
+    identify(_distinctId, _properties) { }
+    async flush() { }
+    async shutdown() { }
+}
+let _provider = new NoopProvider();
+let _distinctId = 'anonymous';
+export const Telemetry = {
+    configure(provider) {
+        _provider = provider;
+    },
+    /**
+     * Derive a stable, anonymous identifier from the API key.
+     * Uses SHA-256 so the raw key is never stored or transmitted.
+     */
+    setDistinctId(apiKey) {
+        _distinctId = createHash('sha256').update(apiKey).digest('hex').slice(0, 16);
+    },
+    capture(event, properties) {
+        try {
+            _provider.capture({ event, distinctId: _distinctId, properties, timestamp: new Date() });
+        }
+        catch {
+            // never let telemetry crash the app
+        }
+    },
+    async flush() {
+        try {
+            await _provider.flush();
+        }
+        catch {
+            // best-effort
+        }
+    },
+    async shutdown() {
+        try {
+            await _provider.shutdown();
+        }
+        catch {
+            // best-effort
+        }
+    },
+};
+export const TelemetryEvents = {
+    TOOL_EXECUTED: 'tool.executed',
+    TOOL_FAILED: 'tool.failed',
+    WORKFLOW_EXECUTED: 'workflow.executed',
+    TUNNEL_PROVISIONED: 'tunnel.provisioned',
+    TUNNEL_STOPPED: 'tunnel.stopped',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "1.0.32",
+  "version": "1.0.33",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {
@@ -25,8 +25,8 @@
     "version:major": "npm version major --no-git-tag-version",
     "publish:check": "npm pack --dry-run",
     "prepublishOnly": "npm test && npm run build",
-    "mcp:local": "npm run build && claude mcp remove debugg-ai 2>/dev/null; claude mcp add debugg-ai -s user -e DEBUGGAI_API_KEY=KrvXlzVFXVZO82UErXye5N7CtnmBTu1GKULrJnwXRRU -- node /Users/qosha/Repos/debugg-ai/debugg-ai-mcp/dist/index.js",
-    "mcp:npm": "claude mcp remove debugg-ai 2>/dev/null; claude mcp add debugg-ai -s user -e DEBUGGAI_API_KEY=KrvXlzVFXVZO82UErXye5N7CtnmBTu1GKULrJnwXRRU -- npx -y @debugg-ai/debugg-ai-mcp"
+    "mcp:local": "npm run build && claude mcp remove debugg-ai 2>/dev/null; claude mcp add debugg-ai -s user -e DEBUGGAI_API_KEY=KrvXlzVFXVZO82UErXye5N7CtnmBTu1GKULrJnwXRRU -e POSTHOG_API_KEY=phc_4h2Yov2P0Vc9UMqfKf3dYKSQ6THOs7N6LZR0VKYopZN -- node /Users/qosha/Repos/debugg-ai/debugg-ai-mcp/dist/index.js",
+    "mcp:npm": "claude mcp remove debugg-ai 2>/dev/null; claude mcp add debugg-ai -s user -e DEBUGGAI_API_KEY=KrvXlzVFXVZO82UErXye5N7CtnmBTu1GKULrJnwXRRU -e POSTHOG_API_KEY=phc_4h2Yov2P0Vc9UMqfKf3dYKSQ6THOs7N6LZR0VKYopZN -- npx -y @debugg-ai/debugg-ai-mcp"
   },
   "keywords": [
     "debugg",
@@ -49,6 +49,7 @@
     "axios": "^1.9.0",
     "mkdirp": "^3.0.1",
     "ngrok": "^5.0.0-beta.2",
+    "posthog-node": "^5.26.0",
     "uuid": "^11.1.0",
     "winston": "^3.15.0",
     "zod": "^3.25.32"