birdeatsbug-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,148 @@
+# birdeatsbug-mcp-server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects AI assistants to **BirdeatsBug** bug reports — extracting console logs, network logs, and video frames for deep, AI-powered root-cause analysis.
+
+## What it does
+
+- Launches headless Chromium, navigates to a BirdeatsBug report URL, and intercepts all runtime API responses
+- Extracts structured **console logs**, **network requests**, and **video recording URLs**
+- Downloads the bug recording and extracts **JPEG video frames** for visual AI analysis
+- Merges errors and network failures into a **chronological event timeline**
+- Auto-detects the likely bug moment and clusters frames around it
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `inspect_birdeatsbug_report` | Metadata, access state, artifact counts |
+| `get_birdeatsbug_console_logs` | Console entries (level, message, timestamp) |
+| `get_birdeatsbug_network_logs` | Network requests (method, URL, status, duration) |
+| `get_birdeatsbug_video_frames` | JPEG frames extracted from the bug recording for vision AI |
+| `generate_birdeatsbug_report` | All-in-one: title, description, timeline, errors, failures, and video frames |
+
+## Installation
+
+### Option A — npx (no install needed)
+
+```bash
+npx birdeatsbug-mcp-server
+```
+
+### Option B — global install
+
+```bash
+npm install -g birdeatsbug-mcp-server
+birdeatsbug-mcp-server
+```
+
+> **Note:** On first run, the postinstall script installs the Chromium browser (~200 MB). This only happens once.
+
+---
+
+## VS Code (GitHub Copilot / Continue)
+
+Add to your **global** MCP config at `~/Library/Application Support/Code/User/mcp.json` (macOS):
+
+```json
+{
+  "servers": {
+    "birdeatsbug": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "birdeatsbug-mcp-server"]
+    }
+  }
+}
+```
+
+Or add to a workspace's `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "birdeatsbug": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "birdeatsbug-mcp-server"]
+    }
+  }
+}
+```
+
+## Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "birdeatsbug": {
+      "command": "npx",
+      "args": ["-y", "birdeatsbug-mcp-server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+---
+
+## Usage
+
+Each tool accepts a `url` pointing to any `app.birdeatsbug.com/...` report URL.
+
+**Quick start — full analysis:**
+> "Use generate_birdeatsbug_report on https://app.birdeatsbug.com/sessions/YOUR_SESSION_ID"
+
+**Video frame analysis with focus on a specific moment:**
+> "Use get_birdeatsbug_video_frames on https://app.birdeatsbug.com/sessions/YOUR_SESSION_ID with focusTimeSec 8"
+
+### `generate_birdeatsbug_report` parameters
+
+| Parameter | Default | Description |
+|---|---|---|
+| `url` | required | BirdeatsBug report URL |
+| `frameCount` | 16 | Number of video frames to extract (max 30) |
+| `focusTimeSec` | auto | Timestamp (seconds) to cluster frames around. Auto-detected from first error if omitted |
+| `focusWindowSec` | 4 | Window width (seconds) around the focus timestamp |
+| `logLimit` | 100 | Max console/network log entries to include |
+
+---
+
+## Private sessions
+
+Most sessions require login. To access private reports, generate a Playwright storage state with your logged-in cookies and pass it via environment variable:
+
+```bash
+BIRDEATSBUG_STORAGE_STATE=/path/to/storageState.json npx birdeatsbug-mcp-server
+```
+
+Or in your MCP config:
+
+```json
+{
+  "servers": {
+    "birdeatsbug": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "birdeatsbug-mcp-server"],
+      "env": {
+        "BIRDEATSBUG_STORAGE_STATE": "/path/to/storageState.json"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- Chromium (installed automatically via `playwright install chromium`)
+- ffmpeg (bundled via `ffmpeg-static` — no system install needed)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "birdeatsbug-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for BirdeatsBug — extracts console logs, network logs, and video frames from bug reports for AI-powered root-cause analysis",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "birdeatsbug-mcp-server": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "postinstall": "playwright install chromium --with-deps 2>/dev/null || playwright install chromium"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "birdeatsbug",
+    "bug-report",
+    "debugging",
+    "ai",
+    "playwright",
+    "video-frames",
+    "console-logs",
+    "network-logs"
+  ],
+  "author": "BhavikaTibrewal",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BhavikaTibrewal/birdeatsbug-mcp-server.git"
+  },
+  "homepage": "https://github.com/BhavikaTibrewal/birdeatsbug-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/BhavikaTibrewal/birdeatsbug-mcp-server/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "ffmpeg-static": "^5.3.0",
+    "playwright": "^1.52.0",
+    "zod": "^3.24.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,1100 @@
+#!/usr/bin/env node
+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 { execFile } from "child_process";
+import { mkdtemp, readdir, readFile, rm, writeFile } from "fs/promises";
+import { createRequire } from "module";
+import { tmpdir } from "os";
+import { join } from "path";
+import { chromium } from "playwright";
+import { promisify } from "util";
+import { z } from "zod";
+
+const require = createRequire(import.meta.url);
+const ffmpegPath = require("ffmpeg-static");
+const execFileAsync = promisify(execFile);
+
+const URLSchema = z.object({
+  url: z
+    .string()
+    .url()
+    .refine((value) => value.includes("birdeatsbug.com"), {
+      message: "Must be a BirdeatsBug URL",
+    }),
+});
+
+const LimitedURLSchema = URLSchema.extend({
+  limit: z.number().int().positive().max(2000).optional(),
+});
+
+const VideoFramesSchema = URLSchema.extend({
+  frameCount: z.number().int().positive().max(30).optional().default(16),
+  focusTimeSec: z.number().nonnegative().optional(),
+  focusWindowSec: z.number().positive().optional().default(4),
+});
+
+const GenerateReportSchema = URLSchema.extend({
+  frameCount: z.number().int().positive().max(30).optional().default(16),
+  focusTimeSec: z.number().nonnegative().optional(),
+  focusWindowSec: z.number().positive().optional().default(4),
+  logLimit: z.number().int().positive().max(500).optional().default(100),
+});
+
+const STORAGE_STATE_PATH = process.env.BIRDEATSBUG_STORAGE_STATE;
+const NAVIGATION_TIMEOUT_MS = 45000;
+// Wait for network to go quiet after initial page load
+const NETWORK_IDLE_TIMEOUT_MS = 10000;
+// Hard cap after networkidle to let deferred API calls land
+const POST_IDLE_WAIT_MS = 2000;
+
+const unique = (values) => [...new Set(values.filter(Boolean))];
+
+const walk = (node, visitor, path = []) => {
+  if (node === null || node === undefined) {
+    return;
+  }
+
+  visitor(node, path);
+
+  if (Array.isArray(node)) {
+    node.forEach((item, index) => walk(item, visitor, [...path, index]));
+    return;
+  }
+
+  if (typeof node === "object") {
+    Object.entries(node).forEach(([key, value]) =>
+      walk(value, visitor, [...path, key]),
+    );
+  }
+};
+
+const likelyConsoleEntry = (entry) => {
+  if (typeof entry === "string") {
+    return true;
+  }
+
+  if (!entry || typeof entry !== "object") {
+    return false;
+  }
+
+  const keys = Object.keys(entry).map((key) => key.toLowerCase());
+  return keys.some((key) =>
+    [
+      "message",
+      "level",
+      "severity",
+      "stack",
+      "console",
+      "text",
+      "warn",
+      "error",
+      "log",
+    ].some((token) => key.includes(token)),
+  );
+};
+
+const likelyNetworkEntry = (entry) => {
+  if (!entry || typeof entry !== "object") {
+    return false;
+  }
+
+  const keys = Object.keys(entry).map((key) => key.toLowerCase());
+  const keyScore = [
+    "request",
+    "response",
+    "status",
+    "url",
+    "method",
+    "headers",
+    "network",
+  ].filter((token) => keys.some((key) => key.includes(token))).length;
+
+  return keyScore >= 2;
+};
+
+const normalizeConsole = (entry) => {
+  if (typeof entry === "string") {
+    return { level: "info", message: entry, timestamp: null, raw: entry };
+  }
+
+  if (!entry || typeof entry !== "object") {
+    return {
+      level: "info",
+      message: String(entry),
+      timestamp: null,
+      raw: entry,
+    };
+  }
+
+  return {
+    level: entry.level || entry.type || entry.severity || "info",
+    message:
+      entry.message ||
+      entry.text ||
+      entry.msg ||
+      entry.body ||
+      (typeof entry.error === "string" ? entry.error : JSON.stringify(entry)),
+    timestamp: entry.timestamp || entry.time || entry.createdAt || null,
+    source: entry.source || entry.origin || null,
+    raw: entry,
+  };
+};
+
+const normalizeNetwork = (entry) => {
+  if (!entry || typeof entry !== "object") {
+    return {
+      method: null,
+      url: String(entry),
+      status: null,
+      durationMs: null,
+      timestamp: null,
+      raw: entry,
+    };
+  }
+
+  const request = entry.request || {};
+  const response = entry.response || {};
+
+  return {
+    method: entry.method || request.method || null,
+    url: entry.url || request.url || entry.endpoint || null,
+    status: entry.status || response.status || null,
+    durationMs:
+      entry.duration || entry.durationMs || entry.timing?.total || null,
+    timestamp: entry.timestamp || entry.time || entry.startedDateTime || null,
+    raw: entry,
+  };
+};
+
+const extractVideoUrls = ({ apiPayloads, documentText }) => {
+  const urls = [];
+  const regex = /https?:\/\/[^\s"'<>]+\.(?:mp4|m3u8|webm)(?:\?[^\s"'<>]*)?/gi;
+
+  for (const payload of apiPayloads) {
+    walk(payload, (value, path) => {
+      if (typeof value === "string" && regex.test(value)) {
+        urls.push(value);
+        regex.lastIndex = 0;
+        return;
+      }
+
+      if (typeof value === "string" && /https?:\/\//i.test(value)) {
+        const parentPath = path.map(String).join(".").toLowerCase();
+        if (
+          (parentPath.includes("video") || parentPath.includes("record")) &&
+          /https?:\/\//i.test(value)
+        ) {
+          urls.push(value);
+        }
+      }
+    });
+  }
+
+  const textMatches = documentText.match(regex) || [];
+  urls.push(...textMatches);
+
+  return unique(urls);
+};
+
+const extractConsoleLogs = ({ apiPayloads, documentTextLines }) => {
+  const entries = [];
+
+  for (const payload of apiPayloads) {
+    walk(payload, (value, path) => {
+      if (!likelyConsoleEntry(value)) {
+        return;
+      }
+
+      const pathString = path.map(String).join(".").toLowerCase();
+      if (pathString.includes("network")) {
+        return;
+      }
+
+      entries.push(normalizeConsole(value));
+    });
+  }
+
+  const domFallback = documentTextLines
+    .filter(
+      (line) =>
+        /(^|\s)(log|warning|warn|error|info)(\s|:)/i.test(line) ||
+        line.includes("(in promise)"),
+    )
+    .map((line) => normalizeConsole(line));
+
+  return [...entries, ...domFallback].slice(0, 5000);
+};
+
+const extractNetworkLogs = ({ apiPayloads, documentTextLines }) => {
+  const entries = [];
+
+  for (const payload of apiPayloads) {
+    walk(payload, (value) => {
+      if (!likelyNetworkEntry(value)) {
+        return;
+      }
+
+      const normalized = normalizeNetwork(value);
+      if (normalized.url || normalized.status) {
+        entries.push(normalized);
+      }
+    });
+  }
+
+  const domFallback = documentTextLines
+    .filter((line) => /\b(GET|POST|PUT|PATCH|DELETE)\s+https?:\/\//i.test(line))
+    .map((line) => {
+      const match = line.match(
+        /\b(GET|POST|PUT|PATCH|DELETE)\s+(https?:\/\/\S+)(?:\s+(\d{3}))?/i,
+      );
+      return {
+        method: match?.[1] || null,
+        url: match?.[2] || null,
+        status: match?.[3] ? Number(match[3]) : null,
+        durationMs: null,
+        timestamp: null,
+        raw: line,
+      };
+    });
+
+  return [...entries, ...domFallback].slice(0, 5000);
+};
+
+// Fetch HTTP metadata (size, type, duration header, etc.) for each video URL
+// using a HEAD request so we never download the full binary.
+const fetchVideoMetadata = async (urls) => {
+  return Promise.all(
+    urls.map(async (url) => {
+      try {
+        const res = await fetch(url, { method: "HEAD" });
+        const headers = Object.fromEntries(res.headers.entries());
+        return {
+          url,
+          ok: res.ok,
+          status: res.status,
+          contentType: headers["content-type"] || null,
+          contentLength: headers["content-length"]
+            ? Number(headers["content-length"])
+            : null,
+          contentLengthHuman: headers["content-length"]
+            ? `${(Number(headers["content-length"]) / 1024 / 1024).toFixed(2)} MB`
+            : null,
+          lastModified: headers["last-modified"] || null,
+          etag: headers["etag"] || null,
+          // Some CDNs expose X-Playback-Session-Id or x-goog-* headers
+          extraHeaders: Object.fromEntries(
+            Object.entries(headers).filter(
+              ([k]) =>
+                k.startsWith("x-") ||
+                k.startsWith("cf-") ||
+                k.startsWith("x-goog"),
+            ),
+          ),
+        };
+      } catch (err) {
+        return { url, ok: false, error: err.message };
+      }
+    }),
+  );
+};
+
+// Capture any JSON-returning network response from the page.
+// Previously this was restricted to specific birdeatsbug.com subdomains which
+// caused empty results when the app fetched data from other origins (e.g.
+// Supabase, CDN presigned URLs, etc.).
+const IS_BIRDEATSBUG_API = (_responseUrl) => true;
+
+const collectRuntimeData = async (url) => {
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext(
+    STORAGE_STATE_PATH ? { storageState: STORAGE_STATE_PATH } : {},
+  );
+  const page = await context.newPage();
+
+  // Collect pending body-read promises so we can await them all before extraction.
+  const pendingBodyReads = [];
+  const apiPayloads = [];
+  const responseMeta = [];
+
+  page.on("response", (response) => {
+    const responseUrl = response.url();
+    if (!IS_BIRDEATSBUG_API(responseUrl)) {
+      return;
+    }
+
+    const status = response.status();
+    const contentType = response.headers()["content-type"] || "";
+
+    const meta = { url: responseUrl, status, contentType };
+    responseMeta.push(meta);
+
+    if (!contentType.includes("application/json")) {
+      return;
+    }
+
+    // Capture the promise — don't await inline to avoid blocking the event loop.
+    const bodyPromise = response
+      .json()
+      .then((body) => {
+        apiPayloads.push(body);
+      })
+      .catch(() => {
+        // Body already consumed or not parseable — skip silently.
+      });
+
+    pendingBodyReads.push(bodyPromise);
+  });
+
+  try {
+    await page.goto(url, {
+      waitUntil: "domcontentloaded",
+      timeout: NAVIGATION_TIMEOUT_MS,
+    });
+
+    // Wait for SPA API calls to settle (networkidle = no requests for 500ms).
+    await page
+      .waitForLoadState("networkidle", { timeout: NETWORK_IDLE_TIMEOUT_MS })
+      .catch(() => {
+        // Some pages never reach strict networkidle — continue anyway.
+      });
+
+    // Yield event-loop ticks so any trailing deferred API calls can register.
+    await page.waitForTimeout(POST_IDLE_WAIT_MS);
+
+    // Now await all enqueued body reads before we extract.
+    await Promise.allSettled(pendingBodyReads);
+
+    const documentText = await page
+      .locator("body")
+      .innerText()
+      .catch(() => "");
+    const documentTextLines = documentText
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+
+    const privateGateDetected =
+      /view this private session in your bird eats bug account/i.test(
+        documentText,
+      );
+
+    // Extract report title and description from the page DOM.
+    // BirdeatsBug renders these into visible headings / paragraphs.
+    const title = await page
+      .locator("h1")
+      .first()
+      .innerText()
+      .catch(() => null);
+
+    // Grab the first substantial paragraph that looks like a user description
+    // (longer than 30 chars, not a navigation label).
+    let description = null;
+    try {
+      const paragraphs = await page.locator("p").allInnerTexts();
+      description = paragraphs.find((t) => t.trim().length > 30) || null;
+    } catch {
+      // ignore
+    }
+
+    // Also try meta og:description / twitter:description for SPAs that set them
+    if (!description) {
+      description = await page
+        .locator('meta[property="og:description"], meta[name="description"]')
+        .first()
+        .getAttribute("content")
+        .catch(() => null);
+    }
+
+    const videoUrls = extractVideoUrls({ apiPayloads, documentText });
+    const consoleLogs = extractConsoleLogs({ apiPayloads, documentTextLines });
+    const networkLogs = extractNetworkLogs({ apiPayloads, documentTextLines });
+    const videoDetails = await fetchVideoMetadata(videoUrls);
+
+    return {
+      sourceUrl: url,
+      fetchedAt: new Date().toISOString(),
+      privateGateDetected,
+      title: title || null,
+      description: description || null,
+      apiResponseCount: responseMeta.length,
+      apiResponses: responseMeta,
+      videoUrls,
+      videoDetails,
+      consoleLogs,
+      networkLogs,
+      metadata: {
+        videoCount: videoUrls.length,
+        consoleCount: consoleLogs.length,
+        networkCount: networkLogs.length,
+        usedStorageState: Boolean(STORAGE_STATE_PATH),
+      },
+    };
+  } finally {
+    await context.close();
+    await browser.close();
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Video frame extraction
+// ---------------------------------------------------------------------------
+
+const downloadVideoBuffer = async (videoUrl) => {
+  const res = await fetch(videoUrl);
+  if (!res.ok) {
+    throw new Error(
+      `Failed to download video: ${res.status} ${res.statusText}`,
+    );
+  }
+  return Buffer.from(await res.arrayBuffer());
+};
+
+/**
+ * Probe the video duration (seconds) by parsing ffmpeg's stderr output.
+ * ffmpeg always prints "Duration: HH:MM:SS.ss" to stderr regardless of -v level.
+ */
+const probeVideoDuration = async (videoPath) => {
+  try {
+    // Run `ffmpeg -i <file>` with no output — it always exits non-zero but
+    // prints the container header (including Duration) to stderr at info level.
+    // Using -v error suppresses that line, so we omit any -v flag here.
+    const result = await execFileAsync(ffmpegPath, ["-i", videoPath], {
+      timeout: 15000,
+    }).catch((e) => e); // non-zero exit is expected — we only need stderr
+    const stderr = result.stderr || "";
+    const match = stderr.match(/Duration:\s*(\d+):(\d{2}):(\d{2}(?:\.\d+)?)/);
+    if (match) {
+      return (
+        parseInt(match[1], 10) * 3600 +
+        parseInt(match[2], 10) * 60 +
+        parseFloat(match[3])
+      );
+    }
+  } catch {
+    // ignore — callers fall back to fps=1
+  }
+  return 0;
+};
+
+/**
+ * Build an array of timestamps to capture.
+ *
+ * When `focusTimeSec` is provided:
+ *   - 40 % of frames are spread evenly across the full video (context)
+ *   - 60 % are clustered inside a window of ±(focusWindowSec/2) around the focus time
+ *
+ * Without focusTimeSec the frames are distributed uniformly.
+ */
+const buildTimestamps = (duration, count, focusTimeSec, focusWindowSec = 4) => {
+  const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+  const round1 = (v) => Math.round(v * 10) / 10;
+
+  if (focusTimeSec == null || duration <= 0) {
+    // Uniform distribution, avoid exactly 0 and duration (may be a blank frame)
+    return Array.from({ length: count }, (_, i) =>
+      round1(clamp((i / (count - 1 || 1)) * duration, 0, duration - 0.1)),
+    );
+  }
+
+  const baseCount = Math.max(1, Math.round(count * 0.4));
+  const focusCount = count - baseCount;
+
+  // Evenly spaced baseline across full video
+  const base = Array.from({ length: baseCount }, (_, i) =>
+    round1(clamp((i / (baseCount - 1 || 1)) * duration, 0, duration - 0.1)),
+  );
+
+  // Dense cluster around focus
+  const halfWin = focusWindowSec / 2;
+  const winStart = clamp(focusTimeSec - halfWin, 0, duration - 0.1);
+  const winEnd = clamp(focusTimeSec + halfWin, 0, duration - 0.1);
+  const focus = Array.from({ length: focusCount }, (_, i) =>
+    round1(winStart + (i / (focusCount - 1 || 1)) * (winEnd - winStart)),
+  );
+
+  // Merge, sort, deduplicate (drop frames within 0.15 s of each other)
+  const sorted = [...new Set([...base, ...focus])].sort((a, b) => a - b);
+  const deduped = sorted.filter((t, i) => i === 0 || t - sorted[i - 1] > 0.15);
+
+  return deduped.slice(0, count);
+};
+
+/**
+ * Extract frames at specific timestamps from a video buffer.
+ * Returns an array of { frameIndex, timestampSec, base64, mimeType }.
+ */
+const extractFrames = async (
+  videoBuffer,
+  { count = 16, focusTimeSec = undefined, focusWindowSec = 4 } = {},
+) => {
+  const tmpDir = await mkdtemp(join(tmpdir(), "birdeatsbug-frames-"));
+  const videoPath = join(tmpDir, "recording.webm");
+
+  try {
+    await writeFile(videoPath, videoBuffer);
+
+    const duration = await probeVideoDuration(videoPath);
+    const timestamps = buildTimestamps(
+      duration,
+      count,
+      focusTimeSec,
+      focusWindowSec,
+    );
+
+    // Extract each frame individually at its precise timestamp.
+    // Run in parallel for speed; ffmpeg -ss before -i is fast (keyframe seek).
+    await Promise.all(
+      timestamps.map((ts, i) => {
+        const outPath = join(
+          tmpDir,
+          `frame-${String(i + 1).padStart(3, "0")}.jpg`,
+        );
+        return execFileAsync(ffmpegPath, [
+          "-ss",
+          String(ts),
+          "-i",
+          videoPath,
+          "-vframes",
+          "1",
+          "-q:v",
+          "3",
+          "-vf",
+          "scale=1280:-2",
+          outPath,
+          "-y",
+        ]);
+      }),
+    );
+
+    const files = (await readdir(tmpDir))
+      .filter((f) => f.startsWith("frame-") && f.endsWith(".jpg"))
+      .sort();
+
+    return await Promise.all(
+      files.map(async (file, idx) => ({
+        frameIndex: idx + 1,
+        timestampSec: timestamps[idx] ?? null,
+        base64: (await readFile(join(tmpDir, file))).toString("base64"),
+        mimeType: "image/jpeg",
+      })),
+    );
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+};
+
+/**
+ * Merges console errors and network failures into a single chronological
+ * timeline, sorted by timestamp. Entries without a timestamp are appended at
+ * the end in original order.
+ *
+ * Each event: { time, kind, level?, method?, url?, status?, message?, summary }
+ */
+const buildTimeline = (consoleErrors, networkFailures) => {
+  const toMs = (ts) => {
+    if (ts == null) return null;
+    const n = Number(ts);
+    if (!Number.isNaN(n)) return n;
+    const d = Date.parse(ts);
+    return Number.isNaN(d) ? null : d;
+  };
+
+  const consoleEvents = consoleErrors.map((e) => ({
+    time: toMs(e.timestamp),
+    kind: "console",
+    level: e.level,
+    message: String(e.message ?? "").slice(0, 200),
+    summary: `[${e.level?.toUpperCase() ?? "ERROR"}] ${String(e.message ?? "").slice(0, 120)}`,
+  }));
+
+  const networkEvents = networkFailures.map((r) => ({
+    time: toMs(r.timestamp),
+    kind: "network",
+    method: r.method,
+    url: r.url,
+    status: r.status,
+    durationMs: r.durationMs,
+    summary: `${r.method ?? "?"} ${r.url} → ${r.status}`,
+  }));
+
+  const all = [...consoleEvents, ...networkEvents];
+
+  // Sort: timestamped events first (ascending), then un-timestamped
+  all.sort((a, b) => {
+    if (a.time != null && b.time != null) return a.time - b.time;
+    if (a.time != null) return -1;
+    if (b.time != null) return 1;
+    return 0;
+  });
+
+  return all;
+};
+
+/**
+ * Renders the merged timeline as a markdown table.
+ */
+const buildTimelineTable = (timeline) => {
+  if (timeline.length === 0) return "_No errors or network failures recorded._";
+
+  const header =
+    `| # | Time | Kind | Details |\n` + `|---|------|------|---------|`;
+
+  const rows = timeline
+    .map((event, i) => {
+      const time =
+        event.time != null
+          ? new Date(event.time).toISOString().replace("T", " ").slice(0, 23)
+          : "—";
+      const kind = event.kind === "console" ? "🖥 console" : "🌐 network";
+      const details =
+        event.kind === "console"
+          ? `**[${event.level?.toUpperCase() ?? "ERROR"}]** ${event.message?.slice(0, 120) ?? ""}`
+          : `\`${event.method ?? "?"} ${String(event.url ?? "").slice(0, 80)}\` → **${event.status}**${event.durationMs != null ? ` (${event.durationMs}ms)` : ""}`;
+      return `| ${i + 1} | ${time} | ${kind} | ${details} |`;
+    })
+    .join("\n");
+
+  return `${header}\n${rows}`;
+};
+
+/**
+ * Builds a markdown table summarising extracted frames.
+ * Zone is "focus" when the timestamp falls within the focus window, otherwise "context".
+ * The Description column is intentionally blank so the receiving AI fills it in
+ * by visually analysing the image that follows each row.
+ */
+const buildFrameTable = (frames, focusTimeSec, focusWindowSec = 4) => {
+  const halfWin = focusWindowSec / 2;
+  const inFocus = (ts) =>
+    focusTimeSec != null &&
+    ts != null &&
+    Math.abs(ts - focusTimeSec) <= halfWin;
+
+  const header = `| Frame | Timestamp | Zone | Description |\n|-------|-----------|------|-------------|`;
+  const rows = frames
+    .map(({ frameIndex, timestampSec }) => {
+      const ts = timestampSec != null ? `${timestampSec}s` : "—";
+      const zone =
+        focusTimeSec != null
+          ? inFocus(timestampSec)
+            ? "🔍 focus"
+            : "context"
+          : "—";
+      return `| ${frameIndex} | ${ts} | ${zone} | |`;
+    })
+    .join("\n");
+  return `${header}\n${rows}`;
+};
+
+const asTextContent = (obj) => ({
+  content: [
+    {
+      type: "text",
+      text: JSON.stringify(obj, null, 2),
+    },
+  ],
+});
+
+const server = new Server(
+  {
+    name: "birdeatsbug-live-mcp",
+    version: "0.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "inspect_birdeatsbug_report",
+      description:
+        "Fetch report page live and return extraction metadata, access state, and discovered artifact counts.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "BirdeatsBug report URL" },
+        },
+        required: ["url"],
+      },
+    },
+    {
+      name: "get_birdeatsbug_console_logs",
+      description: "Fetch console logs live from a BirdeatsBug report URL.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "BirdeatsBug report URL" },
+          limit: { type: "number", description: "Optional max logs to return" },
+        },
+        required: ["url"],
+      },
+    },
+    {
+      name: "get_birdeatsbug_network_logs",
+      description: "Fetch network logs live from a BirdeatsBug report URL.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "BirdeatsBug report URL" },
+          limit: {
+            type: "number",
+            description: "Optional max requests to return",
+          },
+        },
+        required: ["url"],
+      },
+    },
+    {
+      name: "get_birdeatsbug_video_frames",
+      description:
+        "Download the bug recording and extract frames as images for AI visual analysis. Extracts evenly-spaced frames by default. When focusTimeSec is provided, 60% of frames cluster around that timestamp (±focusWindowSec/2) and 40% spread across the full video for context — ideal for zooming in on the moment a bug occurred.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "BirdeatsBug report URL" },
+          frameCount: {
+            type: "number",
+            description: "Number of frames to extract (1-30, default 16)",
+          },
+          focusTimeSec: {
+            type: "number",
+            description:
+              "Timestamp in seconds to cluster frames around (e.g. 6 to focus on the 6s mark)",
+          },
+          focusWindowSec: {
+            type: "number",
+            description:
+              "Width in seconds of the focus window around focusTimeSec (default 4)",
+          },
+        },
+        required: ["url"],
+      },
+    },
+    {
+      name: "generate_birdeatsbug_report",
+      description:
+        "Generate a comprehensive bug report from a BirdeatsBug URL. Fetches the report title, description, console logs, network logs (errors/failures highlighted), and video frames in a single pass, then returns all data together so an AI can produce a detailed root-cause analysis.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "BirdeatsBug report URL" },
+          frameCount: {
+            type: "number",
+            description: "Number of video frames to extract (1-30, default 16)",
+          },
+          focusTimeSec: {
+            type: "number",
+            description:
+              "Timestamp in seconds to cluster frames around for closer inspection of the bug moment",
+          },
+          focusWindowSec: {
+            type: "number",
+            description:
+              "Width in seconds of the focus window around focusTimeSec (default 4)",
+          },
+          logLimit: {
+            type: "number",
+            description:
+              "Max console/network log entries to include (default 100)",
+          },
+        },
+        required: ["url"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+
+  if (name === "inspect_birdeatsbug_report") {
+    const { url } = URLSchema.parse(args);
+    const data = await collectRuntimeData(url);
+
+    return asTextContent({
+      sourceUrl: data.sourceUrl,
+      fetchedAt: data.fetchedAt,
+      privateGateDetected: data.privateGateDetected,
+      metadata: data.metadata,
+      apiResponseCount: data.apiResponseCount,
+      apiResponsesSample: data.apiResponses.slice(0, 20),
+    });
+  }
+
+  if (name === "get_birdeatsbug_console_logs") {
+    const { url, limit } = LimitedURLSchema.parse(args);
+    const data = await collectRuntimeData(url);
+
+    return asTextContent({
+      sourceUrl: data.sourceUrl,
+      fetchedAt: data.fetchedAt,
+      privateGateDetected: data.privateGateDetected,
+      count: data.consoleLogs.length,
+      logs:
+        typeof limit === "number"
+          ? data.consoleLogs.slice(0, limit)
+          : data.consoleLogs,
+    });
+  }
+
+  if (name === "get_birdeatsbug_network_logs") {
+    const { url, limit } = LimitedURLSchema.parse(args);
+    const data = await collectRuntimeData(url);
+
+    return asTextContent({
+      sourceUrl: data.sourceUrl,
+      fetchedAt: data.fetchedAt,
+      privateGateDetected: data.privateGateDetected,
+      count: data.networkLogs.length,
+      requests:
+        typeof limit === "number"
+          ? data.networkLogs.slice(0, limit)
+          : data.networkLogs,
+    });
+  }
+
+  if (name === "get_birdeatsbug_video_frames") {
+    const { url, frameCount, focusTimeSec, focusWindowSec } =
+      VideoFramesSchema.parse(args);
+
+    const data = await collectRuntimeData(url);
+
+    if (data.privateGateDetected) {
+      return asTextContent({
+        error:
+          "This is a private session — set BIRDEATSBUG_STORAGE_STATE to access it.",
+      });
+    }
+
+    if (data.videoUrls.length === 0) {
+      return asTextContent({
+        error: "No video URL found for this report.",
+        metadata: data.metadata,
+      });
+    }
+
+    const videoUrl = data.videoUrls[0];
+    const videoBuffer = await downloadVideoBuffer(videoUrl);
+    const frames = await extractFrames(videoBuffer, {
+      count: frameCount,
+      focusTimeSec,
+      focusWindowSec,
+    });
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: [
+            `## Video Frames (${frames.length} total)`,
+            focusTimeSec != null
+              ? `**Focus:** ±${focusWindowSec / 2}s around ${focusTimeSec}s — 60% of frames cluster here, 40% spread across the full recording.`
+              : "Frames distributed uniformly across the full recording.",
+            "",
+            buildFrameTable(frames, focusTimeSec, focusWindowSec),
+            "",
+            "---",
+            "```json",
+            JSON.stringify(
+              {
+                sourceUrl: data.sourceUrl,
+                fetchedAt: data.fetchedAt,
+                videoUrl,
+                totalFramesExtracted: frames.length,
+                focusTimeSec: focusTimeSec ?? null,
+                focusWindowSec: focusTimeSec != null ? focusWindowSec : null,
+              },
+              null,
+              2,
+            ),
+            "```",
+          ].join("\n"),
+        },
+        ...frames.map(({ frameIndex, timestampSec, base64, mimeType }) => ({
+          type: "image",
+          data: base64,
+          mimeType,
+          description:
+            timestampSec !== null
+              ? `Frame ${frameIndex} @ ${timestampSec}s`
+              : `Frame ${frameIndex}`,
+        })),
+      ],
+    };
+  }
+
+  if (name === "generate_birdeatsbug_report") {
+    const { url, frameCount, focusTimeSec, focusWindowSec, logLimit } =
+      GenerateReportSchema.parse(args);
+
+    const data = await collectRuntimeData(url);
+
+    if (data.privateGateDetected) {
+      return asTextContent({
+        error:
+          "This is a private session — set BIRDEATSBUG_STORAGE_STATE to access it.",
+      });
+    }
+
+    const consoleLogs = data.consoleLogs.slice(0, logLimit);
+    const networkLogs = data.networkLogs.slice(0, logLimit);
+
+    const consoleErrors = consoleLogs.filter((e) =>
+      /error|exception|uncaught|fail/i.test(
+        String(e.level) + " " + String(e.message),
+      ),
+    );
+    const networkFailures = networkLogs.filter(
+      (r) => r.status && (r.status >= 400 || r.status === 0),
+    );
+
+    // Build the merged event timeline first so we can use it for auto-focus.
+    const timeline = buildTimeline(consoleErrors, networkFailures);
+
+    // Auto-detect focusTimeSec from the first timestamped error when not provided.
+    // Timeline entries whose .time is an epoch-ms value are converted to seconds
+    // relative to the first event in the timeline.
+    let resolvedFocusTimeSec = focusTimeSec;
+    if (resolvedFocusTimeSec == null && timeline.length > 0) {
+      const firstWithTime = timeline.find((e) => e.time != null);
+      const firstConsoleWithTime = timeline.find(
+        (e) => e.kind === "console" && e.time != null,
+      );
+      const anchor = firstWithTime?.time ?? null;
+      const errorTime = firstConsoleWithTime?.time ?? null;
+      if (anchor != null && errorTime != null) {
+        // Convert absolute ms timestamps to relative seconds from session start.
+        resolvedFocusTimeSec = Math.max(0, (errorTime - anchor) / 1000);
+      }
+    }
+
+    let frames = [];
+    let videoUrl = null;
+    if (data.videoUrls.length > 0) {
+      videoUrl = data.videoUrls[0];
+      const videoBuffer = await downloadVideoBuffer(videoUrl);
+      frames = await extractFrames(videoBuffer, {
+        count: frameCount,
+        focusTimeSec: resolvedFocusTimeSec,
+        focusWindowSec,
+      });
+    }
+
+    const reportMeta = {
+      sourceUrl: data.sourceUrl,
+      fetchedAt: data.fetchedAt,
+      title: data.title,
+      description: data.description,
+      metadata: data.metadata,
+      frameStrategy:
+        resolvedFocusTimeSec != null
+          ? `60% of frames within ±${focusWindowSec / 2}s of ${resolvedFocusTimeSec}s${focusTimeSec == null ? " (auto-detected from first error)" : ""}; 40% spread across full video`
+          : "Uniform distribution across full recording",
+      summary: {
+        totalConsoleLogs: data.consoleLogs.length,
+        consoleErrorCount: consoleErrors.length,
+        totalNetworkRequests: data.networkLogs.length,
+        networkFailureCount: networkFailures.length,
+        videoFramesExtracted: frames.length,
+        autoDetectedFocusTimeSec:
+          focusTimeSec == null ? (resolvedFocusTimeSec ?? null) : null,
+      },
+      eventTimeline: timeline,
+      consoleErrors,
+      networkFailures,
+      consoleLogs,
+      networkLogs,
+      videoUrl,
+    };
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: [
+            `## Bug Report: ${data.title || data.sourceUrl}`,
+            data.description ? `> ${data.description}` : "",
+            "",
+            "### Video Frames",
+            frames.length > 0
+              ? [
+                  resolvedFocusTimeSec != null
+                    ? `**Focus:** ±${focusWindowSec / 2}s around ${resolvedFocusTimeSec}s${focusTimeSec == null ? " _(auto-detected from first error)_" : ""} — 60% cluster here, 40% spread across recording.`
+                    : "Frames distributed uniformly across the full recording.",
+                  "",
+                  buildFrameTable(frames, resolvedFocusTimeSec, focusWindowSec),
+                ].join("\n")
+              : "No video found for this report.",
+            "",
+            "### Summary",
+            `| Metric | Count |`,
+            `|--------|-------|`,
+            `| Console logs | ${data.consoleLogs.length} |`,
+            `| Console errors | ${consoleErrors.length} |`,
+            `| Network requests | ${data.networkLogs.length} |`,
+            `| Network failures | ${networkFailures.length} |`,
+            `| Video frames | ${frames.length} |`,
+            "",
+            "### Event Timeline",
+            "_Errors and network failures merged in chronological order._",
+            "",
+            buildTimelineTable(timeline),
+            "",
+            "### Console Errors",
+            consoleErrors.length > 0
+              ? consoleErrors
+                  .map((e, i) => `${i + 1}. **[${e.level}]** ${e.message}`)
+                  .join("\n")
+              : "None",
+            "",
+            "### Network Failures",
+            networkFailures.length > 0
+              ? networkFailures
+                  .map(
+                    (r, i) =>
+                      `${i + 1}. \`${r.method || "?"} ${r.url}\` → **${r.status}**`,
+                  )
+                  .join("\n")
+              : "None",
+            "",
+            "---",
+            "```json",
+            JSON.stringify(reportMeta, null, 2),
+            "```",
+          ]
+            .filter((line) => line !== null && line !== undefined)
+            .join("\n"),
+        },
+        ...frames.map(({ frameIndex, timestampSec, base64, mimeType }) => ({
+          type: "image",
+          data: base64,
+          mimeType,
+          description:
+            timestampSec !== null
+              ? `Frame ${frameIndex} @ ${timestampSec}s`
+              : `Frame ${frameIndex}`,
+        })),
+      ],
+    };
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+});
+
+const start = async () => {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+};
+
+start().catch((error) => {
+  console.error("BirdeatsBug MCP server failed to start:", error);
+  process.exit(1);
+});