@runtimescope/mcp-server 0.7.1 → 0.8.0

package/dist/index.js

@@ -36,15 +36,19 @@ function registerNetworkTools(server, store) {
       since_seconds: z.number().optional().describe("Only return requests from the last N seconds"),
       url_pattern: z.string().optional().describe("Filter by URL substring match"),
       status: z.number().optional().describe("Filter by HTTP status code"),
-      method: z.string().optional().describe("Filter by HTTP method (GET, POST, etc.)")
+      method: z.string().optional().describe("Filter by HTTP method (GET, POST, etc.)"),
+      limit: z.number().optional().describe("Max results to return (default 200, max 1000)")
     },
-    async ({ since_seconds, url_pattern, status, method }) => {
-      const events = store.getNetworkRequests({
+    async ({ since_seconds, url_pattern, status, method, limit }) => {
+      const allEvents = store.getNetworkRequests({
         sinceSeconds: since_seconds,
         urlPattern: url_pattern,
         status,
         method
       });
+      const maxLimit = Math.min(limit ?? 200, 1e3);
+      const truncated = allEvents.length > maxLimit;
+      const events = truncated ? allEvents.slice(0, maxLimit) : allEvents;
       const timeRange = events.length > 0 ? { from: events[events.length - 1].timestamp, to: events[0].timestamp } : { from: 0, to: 0 };
       const sessions = store.getSessionInfo();
       const sessionId = sessions[0]?.sessionId ?? null;
@@ -72,7 +76,7 @@ function registerNetworkTools(server, store) {
         }
       }
       const response = {
-        summary: `Found ${events.length} network request(s)${since_seconds ? ` in the last ${since_seconds}s` : ""}. Average duration: ${avgDuration}ms.`,
+        summary: `Found ${events.length} network request(s)${truncated ? ` (showing ${maxLimit} of ${allEvents.length})` : ""}${since_seconds ? ` in the last ${since_seconds}s` : ""}. Average duration: ${avgDuration}ms.`,
         data: events.map((e) => ({
           url: e.url,
           method: e.method,
@@ -85,7 +89,7 @@ function registerNetworkTools(server, store) {
           timestamp: new Date(e.timestamp).toISOString()
         })),
         issues,
-        metadata: { timeRange, eventCount: events.length, sessionId }
+        metadata: { timeRange, eventCount: events.length, totalCount: allEvents.length, truncated, sessionId }
       };
       return {
         content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
@@ -103,14 +107,18 @@ function registerConsoleTools(server, store) {
     {
       level: z2.enum(["log", "warn", "error", "info", "debug", "trace"]).optional().describe("Filter by console level"),
       since_seconds: z2.number().optional().describe("Only return messages from the last N seconds"),
-      search: z2.string().optional().describe("Search message text (case-insensitive substring match)")
+      search: z2.string().optional().describe("Search message text (case-insensitive substring match)"),
+      limit: z2.number().optional().describe("Max results to return (default 200, max 1000)")
     },
-    async ({ level, since_seconds, search }) => {
-      const events = store.getConsoleMessages({
+    async ({ level, since_seconds, search, limit }) => {
+      const allEvents = store.getConsoleMessages({
         level,
         sinceSeconds: since_seconds,
         search
       });
+      const maxLimit = Math.min(limit ?? 200, 1e3);
+      const truncated = allEvents.length > maxLimit;
+      const events = truncated ? allEvents.slice(0, maxLimit) : allEvents;
       const timeRange = events.length > 0 ? { from: events[events.length - 1].timestamp, to: events[0].timestamp } : { from: 0, to: 0 };
       const sessions = store.getSessionInfo();
       const sessionId = sessions[0]?.sessionId ?? null;
@@ -135,12 +143,12 @@ function registerConsoleTools(server, store) {
       }
       for (const [msg, info] of errorMessages) {
         if (info.count > 5 && info.last - info.first < 1e4) {
-          const truncated = msg.length > 80 ? msg.slice(0, 80) + "..." : msg;
-          issues.push(`Error spam: "${truncated}" repeated ${info.count} times in ${((info.last - info.first) / 1e3).toFixed(1)}s`);
+          const truncated2 = msg.length > 80 ? msg.slice(0, 80) + "..." : msg;
+          issues.push(`Error spam: "${truncated2}" repeated ${info.count} times in ${((info.last - info.first) / 1e3).toFixed(1)}s`);
         }
       }
       const response = {
-        summary: `Found ${events.length} console message(s)${since_seconds ? ` in the last ${since_seconds}s` : ""}${levelSummary ? `. Breakdown: ${levelSummary}` : ""}.`,
+        summary: `Found ${events.length} console message(s)${truncated ? ` (showing ${maxLimit} of ${allEvents.length})` : ""}${since_seconds ? ` in the last ${since_seconds}s` : ""}${levelSummary ? `. Breakdown: ${levelSummary}` : ""}.`,
         data: events.map((e) => ({
           level: e.level,
           message: e.message,
@@ -150,7 +158,7 @@ function registerConsoleTools(server, store) {
           timestamp: new Date(e.timestamp).toISOString()
         })),
         issues,
-        metadata: { timeRange, eventCount: events.length, sessionId }
+        metadata: { timeRange, eventCount: events.length, totalCount: allEvents.length, truncated, sessionId }
       };
       return {
         content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
@@ -438,13 +446,17 @@ function registerStateTools(server, store) {
     "Get state store snapshots and diffs from Zustand or Redux stores. Shows state changes over time with action history, mutation frequency, and shallow diffs showing which keys changed.",
     {
       store_name: z5.string().optional().describe("Filter by store name/ID"),
-      since_seconds: z5.number().optional().describe("Only return events from the last N seconds")
+      since_seconds: z5.number().optional().describe("Only return events from the last N seconds"),
+      limit: z5.number().optional().describe("Max results to return (default 200, max 1000)")
     },
-    async ({ store_name, since_seconds }) => {
-      const events = store.getStateEvents({
+    async ({ store_name, since_seconds, limit }) => {
+      const allEvents = store.getStateEvents({
         storeId: store_name,
         sinceSeconds: since_seconds
       });
+      const maxLimit = Math.min(limit ?? 200, 1e3);
+      const truncated = allEvents.length > maxLimit;
+      const events = truncated ? allEvents.slice(0, maxLimit) : allEvents;
       const sessions = store.getSessionInfo();
       const sessionId = sessions[0]?.sessionId ?? null;
       const issues = [];
@@ -465,7 +477,7 @@ function registerStateTools(server, store) {
         }
       }
       const response = {
-        summary: `Found ${events.length} state event(s)${since_seconds ? ` in the last ${since_seconds}s` : ""}${store_name ? ` for store "${store_name}"` : ""}.`,
+        summary: `Found ${events.length} state event(s)${truncated ? ` (showing ${maxLimit} of ${allEvents.length})` : ""}${since_seconds ? ` in the last ${since_seconds}s` : ""}${store_name ? ` for store "${store_name}"` : ""}.`,
         data: events.map((e) => ({
           storeId: e.storeId,
           library: e.library,
@@ -483,6 +495,8 @@ function registerStateTools(server, store) {
             to: events.length > 0 ? events[events.length - 1].timestamp : 0
           },
           eventCount: events.length,
+          totalCount: allEvents.length,
+          truncated,
           sessionId
         }
       };
@@ -753,17 +767,21 @@ function registerHarTools(server, store) {
     "capture_har",
     "Export captured network requests as a HAR (HTTP Archive) 1.2 JSON file. This is the standard format used by browser DevTools, Charles Proxy, and other tools. Includes request/response headers, body content (if captureBody was enabled in the SDK), and timing data.",
     {
-      since_seconds: z9.number().optional().describe("Only include requests from the last N seconds")
+      since_seconds: z9.number().optional().describe("Only include requests from the last N seconds"),
+      limit: z9.number().optional().describe("Max entries to include (default 200, max 1000)")
     },
-    async ({ since_seconds }) => {
-      const events = store.getNetworkRequests({
+    async ({ since_seconds, limit }) => {
+      const allEvents = store.getNetworkRequests({
         sinceSeconds: since_seconds
       });
+      const maxLimit = Math.min(limit ?? 200, 1e3);
+      const truncated = allEvents.length > maxLimit;
+      const events = truncated ? allEvents.slice(0, maxLimit) : allEvents;
       const sessions = store.getSessionInfo();
       const sessionId = sessions[0]?.sessionId ?? null;
       const har = buildHar(events);
       const response = {
-        summary: `HAR export: ${events.length} request(s)${since_seconds ? ` from the last ${since_seconds}s` : ""}. Import into Chrome DevTools or any HAR viewer.`,
+        summary: `HAR export: ${events.length} request(s)${truncated ? ` (showing ${maxLimit} of ${allEvents.length})` : ""}${since_seconds ? ` from the last ${since_seconds}s` : ""}. Import into Chrome DevTools or any HAR viewer.`,
         data: har,
         issues: [],
         metadata: {
@@ -772,6 +790,8 @@ function registerHarTools(server, store) {
             to: events.length > 0 ? events[events.length - 1].timestamp : 0
           },
           eventCount: events.length,
+          totalCount: allEvents.length,
+          truncated,
           sessionId
         }
       };
@@ -4128,6 +4148,30 @@ function buildReconEvents(url, title, sessionId, techResults, tokens, layout, a1
 }
 
 // src/scanner/index.ts
+var Semaphore = class {
+  constructor(max) {
+    this.max = max;
+  }
+  queue = [];
+  active = 0;
+  async acquire() {
+    if (this.active < this.max) {
+      this.active++;
+      return;
+    }
+    return new Promise((resolve2) => {
+      this.queue.push(resolve2);
+    });
+  }
+  release() {
+    this.active--;
+    const next = this.queue.shift();
+    if (next) {
+      this.active++;
+      next();
+    }
+  }
+};
 var PlaywrightScanner = class _PlaywrightScanner {
   db = null;
   jsGlobalPaths = [];
@@ -4137,6 +4181,7 @@ var PlaywrightScanner = class _PlaywrightScanner {
   static IDLE_TIMEOUT = 6e4;
   // Close browser after 60s idle
   lastScannedUrl = null;
+  contextSemaphore = new Semaphore(2);
   /**
    * Lazily load the technology database.
    */
@@ -4201,12 +4246,14 @@ var PlaywrightScanner = class _PlaywrightScanner {
     const db = this.ensureDb();
     const { browser } = await this.ensureBrowser();
     const br = browser;
-    const context = await br.newContext({
-      viewport: { width: viewportWidth, height: viewportHeight },
-      userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
-    });
-    const page = await context.newPage();
+    await this.contextSemaphore.acquire();
+    let context = null;
     try {
+      context = await br.newContext({
+        viewport: { width: viewportWidth, height: viewportHeight },
+        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+      });
+      const page = await context.newPage();
       let mainResponse = null;
       page.on("response", (response) => {
         if (!mainResponse && response.request().resourceType() === "document") {
@@ -4267,7 +4314,9 @@ var PlaywrightScanner = class _PlaywrightScanner {
         scanDurationMs
       };
     } finally {
-      await context.close();
+      if (context) await context.close().catch(() => {
+      });
+      this.contextSemaphore.release();
     }
   }
   /**
@@ -4283,15 +4332,19 @@ var PlaywrightScanner = class _PlaywrightScanner {
   async queryComputedStyles(url, selector, propertyFilter) {
     const { browser } = await this.ensureBrowser();
     const br = browser;
-    const context = await br.newContext({
-      viewport: { width: 1280, height: 720 }
-    });
-    const page = await context.newPage();
+    await this.contextSemaphore.acquire();
+    let context = null;
     try {
+      context = await br.newContext({
+        viewport: { width: 1280, height: 720 }
+      });
+      const page = await context.newPage();
       await page.goto(url, { waitUntil: "networkidle", timeout: 6e4 });
       return await collectComputedStyles(page, selector, propertyFilter);
     } finally {
-      await context.close();
+      if (context) await context.close().catch(() => {
+      });
+      this.contextSemaphore.release();
     }
   }
   /**
@@ -4301,15 +4354,19 @@ var PlaywrightScanner = class _PlaywrightScanner {
   async queryElementSnapshot(url, selector, depth = 5) {
     const { browser } = await this.ensureBrowser();
     const br = browser;
-    const context = await br.newContext({
-      viewport: { width: 1280, height: 720 }
-    });
-    const page = await context.newPage();
+    await this.contextSemaphore.acquire();
+    let context = null;
     try {
+      context = await br.newContext({
+        viewport: { width: 1280, height: 720 }
+      });
+      const page = await context.newPage();
       await page.goto(url, { waitUntil: "networkidle", timeout: 6e4 });
       return await collectElementSnapshot(page, selector, depth);
     } finally {
-      await context.close();
+      if (context) await context.close().catch(() => {
+      });
+      this.contextSemaphore.release();
     }
   }
   /**
@@ -4341,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> -->
@@ -4359,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.",
@@ -4374,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 }
@@ -4724,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",
@@ -4764,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);
@@ -5059,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);