@runtimescope/mcp-server 0.7.2 → 0.8.0

package/dist/index.js

@@ -4398,7 +4398,7 @@ function registerScannerTools(server, store, scanner) {
     "Generate a ready-to-paste code snippet to connect any web application to RuntimeScope for live runtime monitoring. Works with ANY tech stack \u2014 React, Vue, Angular, Svelte, plain HTML, Flask/Django templates, Rails ERB, PHP, WordPress, etc. Returns the appropriate installation method based on the project type.",
     {
       app_name: z25.string().optional().default("my-app").describe('Name for the app in RuntimeScope (e.g., "echo-frontend", "dashboard")'),
-      framework: z25.enum(["html", "react", "vue", "angular", "svelte", "nextjs", "nuxt", "flask", "django", "rails", "php", "wordpress", "other"]).optional().default("html").describe('The framework/tech stack of the project. Use "html" for any plain HTML or server-rendered pages.')
+      framework: z25.enum(["html", "react", "vue", "angular", "svelte", "nextjs", "nuxt", "flask", "django", "rails", "php", "wordpress", "workers", "other"]).optional().default("html").describe('The framework/tech stack of the project. Use "html" for any plain HTML or server-rendered pages. Use "workers" for Cloudflare Workers.')
     },
     async ({ app_name, framework }) => {
       const scriptTagSnippet = `<!-- RuntimeScope \u2014 paste before </body> -->
@@ -4416,8 +4416,34 @@ RuntimeScope.init({
   appName: '${app_name}',
   endpoint: 'ws://localhost:${COLLECTOR_PORT}',
 });`;
-      const usesNpm = ["react", "vue", "angular", "svelte", "nextjs", "nuxt"].includes(framework);
-      const primarySnippet = usesNpm ? npmSnippet : scriptTagSnippet;
+      const workersSnippet = `// npm install @runtimescope/workers-sdk
+import { withRuntimeScope, scopeD1, scopeKV, scopeR2, track, addBreadcrumb } from '@runtimescope/workers-sdk';
+
+export default withRuntimeScope({
+  async fetch(request, env, ctx) {
+    // Instrument bindings (optional \u2014 use the ones you have)
+    // const db = scopeD1(env.DB);
+    // const kv = scopeKV(env.KV);
+    // const bucket = scopeR2(env.BUCKET);
+
+    // Track custom events
+    // track('request.processed', { path: new URL(request.url).pathname });
+
+    // Add breadcrumbs for debugging
+    // addBreadcrumb('handler started', { method: request.method });
+
+    return new Response('Hello!');
+  },
+}, {
+  appName: '${app_name}',
+  httpEndpoint: 'http://localhost:${HTTP_PORT}/api/events',
+  // captureConsole: true,    // Capture console.log/warn/error (default: true)
+  // captureHeaders: false,   // Include request/response headers (default: false)
+  // sampleRate: 1.0,         // 0.0-1.0 probabilistic sampling (default: 1.0)
+});`;
+      const isWorkers = framework === "workers";
+      const usesNpm = isWorkers || ["react", "vue", "angular", "svelte", "nextjs", "nuxt"].includes(framework);
+      const primarySnippet = isWorkers ? workersSnippet : usesNpm ? npmSnippet : scriptTagSnippet;
       const placementHints = {
         html: "Paste the <script> tags before </body> in your HTML file(s).",
         react: "Add the import to your entry file (src/index.tsx or src/main.tsx), before ReactDOM.render/createRoot.",
@@ -4431,28 +4457,44 @@ RuntimeScope.init({
         rails: "Add the <script> tags to your application layout (app/views/layouts/application.html.erb) before </body>.",
         php: "Add the <script> tags to your layout/footer file before </body>.",
         wordpress: "Add the <script> tags to your theme's footer.php before </body>, or use a custom HTML plugin.",
+        workers: "Wrap your default export with withRuntimeScope in your Worker entry file (src/index.ts). Enable nodejs_compat in wrangler.toml.",
         other: "Add the <script> tags to your HTML template before </body>. Works in any HTML page."
       };
+      const workersCaptures = [
+        "Incoming HTTP requests with timing, status, and Cloudflare properties",
+        "Console logs, warnings, and errors with stack traces",
+        "D1 database queries with SQL parsing, timing, and N+1 detection",
+        "KV namespace operations (get/put/delete/list) with timing",
+        "R2 bucket operations (get/put/delete/list/head) with size tracking",
+        "Custom business events via track()",
+        "Request breadcrumbs via addBreadcrumb()"
+      ];
+      const browserCaptures = [
+        "Network requests (fetch/XHR) with timing and headers",
+        "Console logs, warnings, and errors with stack traces",
+        "React/Vue/Svelte component renders (if applicable)",
+        "State store changes (Redux, Zustand, Pinia)",
+        "Web Vitals (LCP, FCP, CLS, TTFB, INP)",
+        "Unhandled errors and promise rejections"
+      ];
       const response = {
-        summary: `SDK snippet for ${framework} project "${app_name}". ${usesNpm ? "Uses npm import." : "Uses <script> tag \u2014 no build system required."}`,
+        summary: isWorkers ? `Workers SDK snippet for Cloudflare Worker "${app_name}". Captures requests, D1/KV/R2 operations, console, custom events, and breadcrumbs.` : `SDK snippet for ${framework} project "${app_name}". ${usesNpm ? "Uses npm import." : "Uses <script> tag \u2014 no build system required."}`,
         data: {
           snippet: primarySnippet,
           placement: placementHints[framework] || placementHints.other,
-          alternativeSnippet: usesNpm ? scriptTagSnippet : npmSnippet,
-          alternativeNote: usesNpm ? "If you prefer, you can also use a <script> tag instead of npm:" : "If the project uses npm/Node.js, you can also install via:",
-          requirements: [
+          alternativeSnippet: isWorkers ? void 0 : usesNpm ? scriptTagSnippet : npmSnippet,
+          alternativeNote: isWorkers ? void 0 : usesNpm ? "If you prefer, you can also use a <script> tag instead of npm:" : "If the project uses npm/Node.js, you can also install via:",
+          requirements: isWorkers ? [
+            "RuntimeScope collector must be reachable from your Worker",
+            `HTTP collector endpoint at http://localhost:${HTTP_PORT}/api/events`,
+            "Add nodejs_compat to compatibility_flags in wrangler.toml",
+            "For production: set httpEndpoint to your hosted collector URL"
+          ] : [
             "RuntimeScope MCP server must be running (it starts automatically with Claude Code)",
             `SDK bundle served at http://localhost:${HTTP_PORT}/runtimescope.js`,
             `WebSocket collector at ws://localhost:${COLLECTOR_PORT}`
           ],
-          whatItCaptures: [
-            "Network requests (fetch/XHR) with timing and headers",
-            "Console logs, warnings, and errors with stack traces",
-            "React/Vue/Svelte component renders (if applicable)",
-            "State store changes (Redux, Zustand, Pinia)",
-            "Web Vitals (LCP, FCP, CLS, TTFB, INP)",
-            "Unhandled errors and promise rejections"
-          ]
+          whatItCaptures: isWorkers ? workersCaptures : browserCaptures
         },
         issues: [],
         metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId: null }
@@ -4781,8 +4823,167 @@ function dedup(arr, limit) {
   return result;
 }
 
-// src/tools/history.ts
+// src/tools/breadcrumbs.ts
 import { z as z27 } from "zod";
+function eventToBreadcrumb(event, anchorTs) {
+  const base = {
+    timestamp: new Date(event.timestamp).toISOString(),
+    relativeMs: event.timestamp - anchorTs
+  };
+  switch (event.eventType) {
+    case "navigation": {
+      const nav = event;
+      return {
+        ...base,
+        category: "navigation",
+        level: "info",
+        message: `${nav.trigger}: ${nav.to}`,
+        data: { from: nav.from }
+      };
+    }
+    case "ui": {
+      const ui = event;
+      if (ui.action === "click") {
+        return {
+          ...base,
+          category: "ui.click",
+          level: "info",
+          message: ui.text ? `Click: ${ui.text}` : `Click: ${ui.target}`,
+          data: { target: ui.target }
+        };
+      }
+      return {
+        ...base,
+        category: "breadcrumb",
+        level: "info",
+        message: ui.text ?? ui.target,
+        ...ui.data && { data: ui.data }
+      };
+    }
+    case "console": {
+      const con = event;
+      const level = con.level === "error" ? "error" : con.level === "warn" ? "warning" : con.level === "debug" || con.level === "trace" ? "debug" : "info";
+      return {
+        ...base,
+        category: `console.${con.level}`,
+        level,
+        message: con.message.slice(0, 200),
+        ...con.stackTrace && { data: { hasStack: true } }
+      };
+    }
+    case "network": {
+      const net = event;
+      const level = net.errorPhase ? "error" : net.status >= 400 ? "warning" : "info";
+      const url = new URL(net.url, "http://localhost").pathname;
+      return {
+        ...base,
+        category: "http",
+        level,
+        message: `${net.method} ${url} \u2192 ${net.status || net.errorPhase || "pending"}`,
+        data: { duration: net.duration, status: net.status }
+      };
+    }
+    case "state": {
+      const st = event;
+      if (st.phase === "init") return null;
+      const changedKeys = st.diff ? Object.keys(st.diff).join(", ") : "unknown";
+      return {
+        ...base,
+        category: "state",
+        level: "debug",
+        message: `${st.storeId}: ${changedKeys}`,
+        data: { library: st.library }
+      };
+    }
+    case "custom": {
+      const cust = event;
+      return {
+        ...base,
+        category: `custom.${cust.name}`,
+        level: "info",
+        message: cust.name,
+        ...cust.properties && { data: cust.properties }
+      };
+    }
+    default:
+      return null;
+  }
+}
+var MAX_BREADCRUMBS = 200;
+function registerBreadcrumbTools(server, store) {
+  server.tool(
+    "get_breadcrumbs",
+    "Get the chronological trail of user actions, navigation, clicks, console logs, network requests, and state changes leading up to a point in time (or an error). This is the primary debugging context tool \u2014 use it when investigating errors, unexpected behavior, or user-reported issues.",
+    {
+      since_seconds: z27.number().optional().describe("How far back to look (default: 60 seconds)"),
+      session_id: z27.string().optional().describe("Filter to a specific session"),
+      before_timestamp: z27.number().optional().describe('Only show breadcrumbs before this Unix ms timestamp (useful for "what happened before this error")'),
+      categories: z27.array(z27.string()).optional().describe("Filter to specific categories: navigation, ui.click, breadcrumb, console.error, console.warn, console.log, http, state, custom.*"),
+      level: z27.enum(["debug", "info", "warning", "error"]).optional().describe("Minimum breadcrumb level to include (default: debug = show all)"),
+      limit: z27.number().optional().describe(`Max breadcrumbs to return (default/max: ${MAX_BREADCRUMBS})`)
+    },
+    async ({ since_seconds, session_id, before_timestamp, categories, level, limit }) => {
+      const sinceSeconds = since_seconds ?? 60;
+      const maxItems = Math.min(limit ?? MAX_BREADCRUMBS, MAX_BREADCRUMBS);
+      const allEvents = store.getEventTimeline({
+        sinceSeconds,
+        sessionId: session_id,
+        eventTypes: ["navigation", "ui", "console", "network", "state", "custom"]
+      });
+      const anchor = before_timestamp ?? (allEvents.length > 0 ? allEvents[allEvents.length - 1].timestamp : Date.now());
+      const filtered = before_timestamp ? allEvents.filter((e) => e.timestamp <= before_timestamp) : allEvents;
+      let breadcrumbs = [];
+      for (const event of filtered) {
+        const bc = eventToBreadcrumb(event, anchor);
+        if (bc) breadcrumbs.push(bc);
+      }
+      if (categories && categories.length > 0) {
+        const catSet = new Set(categories);
+        breadcrumbs = breadcrumbs.filter((bc) => {
+          return catSet.has(bc.category) || Array.from(catSet).some((cat) => bc.category.startsWith(cat + "."));
+        });
+      }
+      if (level) {
+        const levelOrder = { debug: 0, info: 1, warning: 2, error: 3 };
+        const minLevel = levelOrder[level];
+        breadcrumbs = breadcrumbs.filter((bc) => levelOrder[bc.level] >= minLevel);
+      }
+      if (breadcrumbs.length > maxItems) {
+        breadcrumbs = breadcrumbs.slice(-maxItems);
+      }
+      const lastError = breadcrumbs.findLast((bc) => bc.level === "error");
+      const sessions = store.getSessionInfo();
+      const sessionId = session_id ?? sessions[0]?.sessionId ?? null;
+      const response = {
+        summary: `${breadcrumbs.length} breadcrumbs over the last ${sinceSeconds}s${lastError ? ` \u2014 last error: "${lastError.message.slice(0, 80)}"` : ""}`,
+        data: breadcrumbs,
+        metadata: {
+          timeRange: {
+            from: breadcrumbs.length > 0 ? breadcrumbs[0].relativeMs : 0,
+            to: breadcrumbs.length > 0 ? breadcrumbs[breadcrumbs.length - 1].relativeMs : 0
+          },
+          eventCount: breadcrumbs.length,
+          sessionId,
+          anchor: new Date(anchor).toISOString(),
+          categoryCounts: countCategories(breadcrumbs)
+        }
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+      };
+    }
+  );
+}
+function countCategories(breadcrumbs) {
+  const counts = {};
+  for (const bc of breadcrumbs) {
+    counts[bc.category] = (counts[bc.category] ?? 0) + 1;
+  }
+  return counts;
+}
+
+// src/tools/history.ts
+import { z as z28 } from "zod";
 var EVENT_TYPES = [
   "network",
   "console",
@@ -4821,13 +5022,13 @@ function registerHistoryTools(server, collector, projectManager) {
     "get_historical_events",
     "Query past events from persistent SQLite storage. Use this to access events beyond the in-memory buffer (last 10K events). Events persist across Claude Code restarts. Filter by project, event type, time range, and session.",
     {
-      project: z27.string().describe("Project/app name (the appName used in SDK init)"),
-      event_types: z27.array(z27.enum(EVENT_TYPES)).optional().describe('Filter by event types (e.g., ["network", "console"])'),
-      since: z27.string().optional().describe('Start time \u2014 relative ("2h", "7d", "30m") or ISO date string'),
-      until: z27.string().optional().describe("End time \u2014 relative or ISO date string"),
-      session_id: z27.string().optional().describe("Filter by specific session ID"),
-      limit: z27.number().optional().default(200).describe("Max events to return (default 200, max 1000)"),
-      offset: z27.number().optional().default(0).describe("Pagination offset")
+      project: z28.string().describe("Project/app name (the appName used in SDK init)"),
+      event_types: z28.array(z28.enum(EVENT_TYPES)).optional().describe('Filter by event types (e.g., ["network", "console"])'),
+      since: z28.string().optional().describe('Start time \u2014 relative ("2h", "7d", "30m") or ISO date string'),
+      until: z28.string().optional().describe("End time \u2014 relative or ISO date string"),
+      session_id: z28.string().optional().describe("Filter by specific session ID"),
+      limit: z28.number().optional().default(200).describe("Max events to return (default 200, max 1000)"),
+      offset: z28.number().optional().default(0).describe("Pagination offset")
     },
     async ({ project, event_types, since, until, session_id, limit, offset }) => {
       const sqliteStore = collector.getSqliteStore(project);
@@ -5116,6 +5317,7 @@ async function main() {
   registerReconStyleDiffTools(mcp, store);
   registerScannerTools(mcp, store, scanner);
   registerCustomEventTools(mcp, store);
+  registerBreadcrumbTools(mcp, store);
   registerHistoryTools(mcp, collector, projectManager);
   const transport = new StdioServerTransport();
   await mcp.connect(transport);