@arwars/simplebug-mcp 0.1.1

package/README.md

@@ -0,0 +1,75 @@
+# @arwars/simplebug-mcp
+
+MCP server for [SimpleBug](https://simplebug.example.com). It lets an AI agent pull
+everything captured in a bug report — reproduction steps (incl. keyboard),
+console logs, network requests (failures flagged), device info, and video frames
+— so it can diagnose and fix the reported bug.
+
+It's a standard **MCP stdio server**, so it works in any MCP client: Claude Code,
+OpenClaw, Antigravity CLI, Cursor, Windsurf, etc.
+
+## Requirements
+
+- **Node.js ≥ 20**
+- **ffmpeg** / **ffprobe** on `PATH` (only needed for the video-frame tool)
+- A **SimpleBug API key** — generate your own in the SimpleBug web app under
+  **Settings → API Keys**. Keys are per-user with per-organization permissions,
+  so you only see reports for the orgs you belong to.
+
+## Configuration
+
+| Env var | Required | Default |
+| --- | --- | --- |
+| `SIMPLEBUG_API_KEY` | yes | — |
+| `SIMPLEBUG_URL` | no | `https://simplebug.example.com` |
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add simplebug -s user \
+  --env SIMPLEBUG_API_KEY=sbk_your_key \
+  --env SIMPLEBUG_URL=https://simplebug.example.com \
+  -- npx -y @arwars/simplebug-mcp
+```
+
+### OpenClaw / Antigravity CLI / Cursor / generic MCP client
+
+Add an MCP server entry:
+
+```jsonc
+{
+  "mcpServers": {
+    "simplebug": {
+      "command": "npx",
+      "args": ["-y", "@arwars/simplebug-mcp"],
+      "env": {
+        "SIMPLEBUG_API_KEY": "sbk_your_key",
+        "SIMPLEBUG_URL": "https://simplebug.example.com"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+- **`get_bug_report(report)`** — full report: metadata, reproduction steps
+  (incl. keyboard), console logs, network requests (failures flagged), video URL,
+  device. Accepts a share link or report id.
+- **`list_bug_reports(limit?, status?)`** — browse recent reports you can access.
+- **`get_network_request(report, request_id)`** — full headers/bodies of one
+  captured request.
+- **`get_bug_report_screenshots(report, at_seconds?)`** — extract video frames to
+  local image files and return their paths + video time + nearest reproduction
+  step, so you can inspect visual bugs with your own vision tool. Targeted by
+  default (a few orientation frames); pass `at_seconds` to zoom into a moment.
+  Never decodes the whole video.
+
+## Typical flow
+
+1. `get_bug_report` to read the steps / errors and form a hypothesis.
+2. `get_bug_report_screenshots` with `at_seconds` at the suspected moment(s);
+   look at the returned frame paths with your own vision tool and compare a few.
+3. Fix the bug.

package/dist/index.js

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { execFileSync } from "node:child_process";
+import {
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createORPCClient } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+import { z } from "zod";
+var BASE_URL = (process.env.SIMPLEBUG_URL ?? "https://simplebug.example.com").replace(/\/+$/, "");
+var API_KEY = process.env.SIMPLEBUG_API_KEY ?? "";
+var link = new RPCLink({
+  url: `${BASE_URL}/rpc`,
+  headers: () => API_KEY ? { "x-api-key": API_KEY } : {}
+});
+var client = createORPCClient(link);
+function parseReportId(input) {
+  const trimmed = input.trim();
+  const slug = trimmed.match(/\/s\/([^/?#]+)/);
+  if (slug?.[1]) {
+    return slug[1];
+  }
+  try {
+    const segment = new URL(trimmed).pathname.split("/").filter(Boolean).pop();
+    if (segment) {
+      return segment;
+    }
+  } catch {}
+  return trimmed;
+}
+function asRecord(value) {
+  return value && typeof value === "object" ? value : {};
+}
+function str(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function fmtOffset(offset) {
+  if (typeof offset !== "number" || offset < 0) {
+    return "--:--";
+  }
+  const totalSeconds = Math.floor(offset / 1000);
+  const m = Math.floor(totalSeconds / 60);
+  const s = totalSeconds % 60;
+  const ms = Math.floor(offset % 1000);
+  return `${m}:${s.toString().padStart(2, "0")}.${ms.toString().padStart(3, "0")}`;
+}
+function describeAction(action) {
+  const meta = asRecord(action.metadata);
+  const target = str(action.target);
+  let detail = "";
+  switch (action.type) {
+    case "keydown": {
+      const key = str(meta.key) ?? "?";
+      const mods = str(meta.modifiers);
+      detail = `press ${mods ? `${mods}+${key}` : key}`;
+      break;
+    }
+    case "click":
+      detail = `click ${str(meta.label) ?? target ?? "element"}`;
+      break;
+    case "input":
+      detail = `type into ${target ?? "field"}`;
+      break;
+    case "change":
+      detail = `change ${target ?? "field"}`;
+      break;
+    case "navigation":
+      detail = `navigate ${str(meta.path) ?? str(meta.url) ?? ""}`.trim();
+      break;
+    default:
+      detail = `${action.type}${target ? ` on ${target}` : ""}`;
+  }
+  return `[${fmtOffset(action.offset)}] ${detail}`;
+}
+function toText(text) {
+  return { content: [{ type: "text", text }] };
+}
+function toError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const hint = /unauthorized|forbidden|not.?found|401|403|404/i.test(message) ? " (check SIMPLEBUG_API_KEY, and that the service user is a member of the report's organization)" : "";
+  return {
+    isError: true,
+    content: [{ type: "text", text: `Error: ${message}${hint}` }]
+  };
+}
+function videoDurationSeconds(videoPath) {
+  try {
+    const out = execFileSync("ffprobe", [
+      "-v",
+      "error",
+      "-select_streams",
+      "v:0",
+      "-show_entries",
+      "packet=pts_time",
+      "-of",
+      "csv=p=0",
+      videoPath
+    ], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    const times = out.trim().split(`
+`).map((line) => Number.parseFloat(line)).filter((n) => Number.isFinite(n));
+    return times.length ? Math.max(...times) : 0;
+  } catch {
+    return false;
+  }
+}
+function extractFrameJpeg(videoPath, offsetSeconds, outPath, scaleWidth = 1024) {
+  try {
+    execFileSync("ffmpeg", [
+      "-y",
+      "-ss",
+      String(Math.max(0, offsetSeconds)),
+      "-i",
+      videoPath,
+      "-frames:v",
+      "1",
+      "-vf",
+      `scale=${scaleWidth}:-1`,
+      "-q:v",
+      "4",
+      outPath
+    ], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function pickDefaultTimestamps(duration, errorTimes) {
+  const d = duration > 0 ? duration : 30;
+  const round = (n) => Math.round(n * 10) / 10;
+  const picks = new Set;
+  for (const t of errorTimes) {
+    if (picks.size >= 4) {
+      break;
+    }
+    picks.add(round(Math.max(0, Math.min(t, d))));
+  }
+  picks.add(0);
+  picks.add(round(Math.max(0, d - 0.1)));
+  if (picks.size < 3) {
+    picks.add(round(d / 2));
+  }
+  return Array.from(picks).sort((a, b) => a - b).slice(0, 5);
+}
+function nearestEventLabel(timeS, events) {
+  let bestText = null;
+  let bestDelta = Number.POSITIVE_INFINITY;
+  const consider = (offset, text2) => {
+    if (typeof offset !== "number" || offset < 0) {
+      return;
+    }
+    const delta = Math.abs(offset / 1000 - timeS);
+    if (delta < bestDelta) {
+      bestDelta = delta;
+      bestText = text2;
+    }
+  };
+  for (const action of events.actions) {
+    consider(action.offset, describeAction(action).replace(/^\[[^\]]*\]\s*/, ""));
+  }
+  for (const log of events.logs) {
+    consider(log.offset, `${log.level.toUpperCase()}: ${log.message}`);
+  }
+  if (bestText === null || bestDelta > 2.5) {
+    return "(no nearby step)";
+  }
+  const text = bestText;
+  return text.length > 90 ? `${text.slice(0, 90)}…` : text;
+}
+var FRAMES_ROOT = join(tmpdir(), "simplebug-frames");
+var FRAMES_TTL_MS = 60 * 60 * 1000;
+function reapOldFrames() {
+  try {
+    for (const name of readdirSync(FRAMES_ROOT)) {
+      const path = join(FRAMES_ROOT, name);
+      try {
+        if (Date.now() - statSync(path).mtimeMs > FRAMES_TTL_MS) {
+          rmSync(path, { recursive: true, force: true });
+        }
+      } catch {}
+    }
+  } catch {}
+}
+function imageExt(url) {
+  const lower = url.toLowerCase();
+  if (lower.includes(".png")) {
+    return "png";
+  }
+  if (lower.includes(".webp")) {
+    return "webp";
+  }
+  return "jpg";
+}
+async function renderBugReport(reportInput) {
+  const id = parseReportId(reportInput);
+  const [report, events, network] = await Promise.all([
+    client.bugReport.getById({ id }),
+    client.bugReport.getDebuggerEvents({ id }).catch(() => ({
+      actions: [],
+      logs: []
+    })),
+    client.bugReport.getNetworkRequests({ id, page: 1, perPage: 100 }).catch(() => ({ items: [], pagination: undefined }))
+  ]);
+  const device = asRecord(report.deviceInfo);
+  const lines = [];
+  lines.push(`# Bug report: ${report.title ?? "(untitled)"}`);
+  lines.push(`- id: ${report.id}`);
+  lines.push(`- link: ${BASE_URL}/s/${report.id}`);
+  lines.push(`- status: ${report.status} | priority: ${report.priority}${report.tags?.length ? ` | tags: ${report.tags.join(", ")}` : ""}`);
+  lines.push(`- organization: ${report.organization?.name ?? "?"} | reporter: ${report.reporter?.name ?? "?"} | created: ${report.createdAt}`);
+  if (report.url) {
+    lines.push(`- page url: ${report.url}`);
+  }
+  const deviceBits = [str(device.browser), str(device.os), str(device.viewport)].filter(Boolean).join(" | ");
+  if (deviceBits) {
+    lines.push(`- device: ${deviceBits}`);
+  }
+  if (report.attachmentUrl) {
+    lines.push(`- ${report.attachmentType ?? "attachment"}: ${report.attachmentUrl}`);
+  }
+  lines.push(`
+## Description`);
+  lines.push(report.description?.trim() || "(none provided)");
+  lines.push(`
+## Reproduction steps (${events.actions.length})`);
+  if (events.actions.length === 0) {
+    lines.push("(no user actions captured)");
+  } else {
+    events.actions.forEach((action, index) => {
+      lines.push(`${index + 1}. ${describeAction(action)}`);
+    });
+  }
+  const errorLogs = events.logs.filter((entry) => entry.level === "error" || entry.level === "warn");
+  lines.push(`
+## Console logs (${events.logs.length}, ${errorLogs.length} error/warn)`);
+  if (events.logs.length === 0) {
+    lines.push("(no console logs captured)");
+  } else {
+    for (const entry of events.logs) {
+      lines.push(`- [${fmtOffset(entry.offset)}] ${entry.level.toUpperCase()}: ${entry.message}`);
+    }
+  }
+  const items = network.items ?? [];
+  const failed = items.filter((req) => typeof req.status === "number" && req.status >= 400);
+  lines.push(`
+## Network requests (${items.length} shown${failed.length ? `, ${failed.length} failed` : ""})`);
+  if (items.length === 0) {
+    lines.push("(no network requests captured)");
+  } else {
+    for (const req of items) {
+      const flag = typeof req.status === "number" && req.status >= 400 ? " ⚠️" : "";
+      lines.push(`- ${req.method} ${req.status ?? "—"} ${req.url}${typeof req.duration === "number" ? ` (${req.duration}ms)` : ""}${flag}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+var server = new McpServer({ name: "simplebug", version: "0.1.0" });
+server.registerTool("get_bug_report", {
+  title: "Get SimpleBug report",
+  description: "Fetch every captured detail of a SimpleBug bug report (metadata, " + "reproduction steps including keyboard input, console logs, network " + "requests with failures highlighted, video URL, device) so you can " + "diagnose and fix the reported bug. Accepts a share link or a report id.",
+  inputSchema: {
+    report: z.string().describe("SimpleBug share link (https://simplebug.example.com/s/<id>) or the report id")
+  }
+}, async ({ report }) => {
+  try {
+    return toText(await renderBugReport(report));
+  } catch (error) {
+    return toError(error);
+  }
+});
+server.registerTool("list_bug_reports", {
+  title: "List SimpleBug reports",
+  description: "List recent bug reports the service account can access (id, title, " + "status, link), to browse before fetching one in full.",
+  inputSchema: {
+    limit: z.number().int().min(1).max(50).optional().describe("max 50"),
+    status: z.string().optional().describe("filter by status, e.g. open")
+  }
+}, async ({ limit, status }) => {
+  try {
+    const result = await client.bugReport.list({
+      perPage: limit ?? 20,
+      page: 1,
+      ...status ? { status: [status] } : {}
+    });
+    const items = result.items ?? [];
+    if (items.length === 0) {
+      return toText("No bug reports found.");
+    }
+    return toText(items.map((item) => `- ${item.status} · ${item.title ?? "(untitled)"} · ${BASE_URL}/s/${item.id}`).join(`
+`));
+  } catch (error) {
+    return toError(error);
+  }
+});
+server.registerTool("get_network_request", {
+  title: "Get a network request payload",
+  description: "Fetch the full request/response payload (headers + bodies) of one " + "captured network request in a report, for deep debugging.",
+  inputSchema: {
+    report: z.string().describe("share link or report id"),
+    request_id: z.string().describe("the network request id")
+  }
+}, async ({ report, request_id }) => {
+  try {
+    const payload = await client.bugReport.getNetworkRequestPayload({
+      id: parseReportId(report),
+      requestId: request_id
+    });
+    return toText(JSON.stringify(payload, null, 2));
+  } catch (error) {
+    return toError(error);
+  }
+});
+server.registerTool("get_bug_report_screenshots", {
+  title: "See the bug — extract report video frames / screenshot",
+  description: "Inspect a bug report's screen recording (or screenshot) visually and " + "EFFICIENTLY. Recommended workflow: first read the report (get_bug_report) " + "to see the reproduction steps and form a hypothesis about WHEN the bug " + "appears, then call this with at_seconds=[…] at those step times to extract " + "ONLY those frames. With no at_seconds it returns just a few orientation " + "frames (any error/warn moments + start/end) — it does NOT sweep the whole " + "clip, and it NEVER decodes the full video (each frame is one cheap seek). " + "Frames are written to LOCAL image files; their PATHS + video time + " + "nearest reproduction step are returned. Analyse a frame with your own " + "vision/image tool (image_source = the returned path) or open the path. " + "For focus/animation or other temporal bugs, request a few timestamps " + "around the suspected step and COMPARE them. Only widen the timestamps if " + "you cannot localise the bug from a few. NOTE: frame files are local to the " + "machine running this server (co-located vision tools only).",
+  inputSchema: {
+    report: z.string().describe("share link or report id"),
+    at_seconds: z.array(z.number().min(0)).max(8).optional().describe("video timestamps (seconds) to extract — target the suspected bug moment(s) from the steps. Default = a few orientation frames (error/warn + start/end), NOT a full sweep.")
+  }
+}, async ({ report, at_seconds }) => {
+  try {
+    const id = parseReportId(report);
+    const [meta, events] = await Promise.all([
+      client.bugReport.getById({ id }),
+      client.bugReport.getDebuggerEvents({ id }).catch(() => ({ actions: [], logs: [] }))
+    ]);
+    if (!meta.attachmentUrl) {
+      return toText("This report has no video or screenshot attachment.");
+    }
+    mkdirSync(FRAMES_ROOT, { recursive: true });
+    reapOldFrames();
+    const workDir = join(FRAMES_ROOT, id);
+    rmSync(workDir, { recursive: true, force: true });
+    mkdirSync(workDir, { recursive: true });
+    const response = await fetch(meta.attachmentUrl);
+    if (!response.ok) {
+      return toText(`Could not download attachment (HTTP ${response.status}).`);
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (meta.attachmentType === "screenshot") {
+      const shotPath = join(workDir, `screenshot.${imageExt(meta.attachmentUrl)}`);
+      writeFileSync(shotPath, bytes);
+      return toText(`Screenshot of "${meta.title ?? id}" saved locally:
+${shotPath}
+
+` + `Analyse it with your own vision/image tool (image_source=${shotPath}).`);
+    }
+    const videoPath = join(workDir, "video.webm");
+    writeFileSync(videoPath, bytes);
+    const duration = videoDurationSeconds(videoPath);
+    const errorTimes = events.logs.filter((log) => log.level === "error" || log.level === "warn").map((log) => (typeof log.offset === "number" ? log.offset : -1) / 1000).filter((t) => t >= 0);
+    const detailed = Boolean(at_seconds?.length);
+    const times = detailed ? at_seconds.slice(0, 8) : pickDefaultTimestamps(duration, errorTimes);
+    const lines = [];
+    let frameIndex = 0;
+    for (const t of times) {
+      const clamped = Math.max(0, duration ? Math.min(t, duration - 0.05) : t);
+      const outPath = join(workDir, `frame-${String(frameIndex++).padStart(2, "0")}-t${clamped.toFixed(1)}s.jpg`);
+      if (!extractFrameJpeg(videoPath, clamped, outPath, 1024)) {
+        continue;
+      }
+      lines.push(`- t=${clamped.toFixed(1)}s — ${outPath} — ${nearestEventLabel(clamped, events)}`);
+    }
+    if (lines.length === 0) {
+      return toText("Could not extract any frames (the clip may be unplayable).");
+    }
+    return toText(`Extracted ${lines.length} frames from "${meta.title ?? id}" (clip ≈ ${duration ? duration.toFixed(1) : "?"}s) to local files. ` + (detailed ? "At your requested timestamps. " : "A few orientation frames only (error/warn + start/end) — not a " + "full sweep. ") + `Each line is: video time — file path — nearest reproduction step/log.
+
+` + `${lines.join(`
+`)}
+
+` + "Analyse a frame with your own vision/image tool (image_source=<path>, " + "these are local files on this machine) or open the path directly. To " + "pinpoint the bug, call again with at_seconds=[…] at the suspected " + "step's time (and compare a few nearby frames for focus/animation bugs) " + "— extract only what you need.");
+  } catch (error) {
+    return toError(error);
+  }
+});
+await server.connect(new StdioServerTransport);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@arwars/simplebug-mcp",
+  "version": "0.1.1",
+  "description": "MCP server for SimpleBug — lets AI agents read bug reports (reproduction steps, console logs, network, video frames) to diagnose and fix bugs.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "simplebug-mcp": "dist/index.js"
+  },
+  "files": ["dist", "README.md"],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": ["mcp", "model-context-protocol", "simplebug", "bug-reports", "ai"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArWars/SimpleBug.git",
+    "directory": "apps/mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --target=node --format=esm --outfile=dist/index.js --external @modelcontextprotocol/sdk --external @orpc/client --external zod",
+    "prepublishOnly": "bun run build",
+    "start": "bun run ./src/index.ts",
+    "check-types": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.26.0",
+    "@orpc/client": "^1.12.2",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@simplebug/api": "workspace:*",
+    "typescript": "^5"
+  }
+}