@spotlightjs/spotlight 4.5.0 → 4.6.0

package/dist/server/mcp/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sources":["../../../src/server/mcp/constants.ts"],"sourcesContent":["import type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\n\nexport const NO_ERRORS_CONTENT: CallToolResult = {\n  content: [\n    {\n      type: \"text\",\n      text: `**No errors detected in Spotlight**\n\n**This means:**\n- Application is currently running without runtime failures\n- No crashes, exceptions, or critical issues in the recent timeframe\n- System appears stable at the moment\n\n**Next debugging steps:**\n\n1. **If user reports a specific issue:**\n   - Ask them to reproduce the problem (click the button, submit the form, navigate to the page)\n   - Run this tool again immediately after they reproduce it\n   - Errors will appear in real-time as they happen\n\n2. **If investigating existing code:**\n   - Check application logs separately\n   - Look for TODO comments, error handling gaps, or potential edge cases in the code\n   - Consider testing error scenarios (invalid inputs, network failures, etc.)\n\n3. **Proactive error detection:**\n   - Have user interact with recently changed features\n   - Test API endpoints or database operations that might be fragile\n   - Check pages/features mentioned in recent commits\n\n** Pro tip:** Absence of errors doesn't mean absence of bugs - it just means no runtime failures occurred recently. The issue might be logical errors, UI problems, or dormant bugs waiting for specific conditions.`,\n    },\n  ],\n};\n\nexport const NO_LOGS_CONTENT: CallToolResult = {\n  content: [\n    {\n      type: \"text\",\n      text: `**No logs detected in Spotlight**\n\n**This means:**\n- Application hasn't generated any log messages in the recent timeframe\n- No debug, info, warning, or trace messages were captured\n- Application might be idle or not actively processing requests\n\n**Next debugging steps:**\n\n1. **If investigating application behavior:**\n   - Have user interact with the application (navigate pages, submit forms, trigger features)\n   - Run this tool again after user activity to capture runtime logs\n   - Logs appear in real-time as your application executes\n\n2. **If checking for specific functionality:**\n   - Trigger the feature or workflow you're investigating\n   - Look for custom logging statements in your code\n   - Consider adding more logging to critical paths if needed\n\n3. **If monitoring general health:**\n   - Check that logging is properly configured in your application\n   - Verify that Spotlight is correctly capturing your log output\n   - Test with known log-generating actions (API calls, database operations)\n\n4. **Expand search timeframe:**\n   - Use a longer duration (300+ seconds) to capture older log entries\n   - Consider that some operations might generate logs less frequently\n\n**Log Levels to expect:**\n- **INFO**: General application flow and significant events\n- **WARN**: Potential issues or important notices\n- **DEBUG**: Detailed execution information\n- **ERROR**: Failures (also check search_errors tool)\n\n**Pro tip:** Absence of logs doesn't mean your application isn't working - it might just be running quietly. Many applications only log during significant events, errors, or when explicitly configured for verbose logging.`,\n    },\n  ],\n};\n"],"names":[],"mappings":"AAEO,MAAM,oBAAoC;AAAA,EAC/C,SAAS;AAAA,IACP;AAAA,MACE,MAAM;AAAA,MACN,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAA;AAAA,EAyBR;AAEJ;AAEO,MAAM,kBAAkC;AAAA,EAC7C,SAAS;AAAA,IACP;AAAA,MACE,MAAM;AAAA,MACN,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAA;AAAA,EAmCR;AAEJ;"}

package/dist/server/mcp/mcp.d.ts

@@ -0,0 +1,31 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+declare const inputSchema: {
+    filters: z.ZodUnion<[z.ZodObject<{
+        timeWindow: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        timeWindow: number;
+    }, {
+        timeWindow: number;
+    }>, z.ZodObject<{
+        filename: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        filename: string;
+    }, {
+        filename: string;
+    }>, z.ZodOptional<z.ZodObject<{
+        limit: z.ZodNumber;
+        offset: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        limit: number;
+        offset: number;
+    }, {
+        limit: number;
+        offset?: number | undefined;
+    }>>]>;
+};
+export type InputSchema = {
+    [K in keyof typeof inputSchema]: z.infer<(typeof inputSchema)[K]>;
+};
+export declare function createMCPInstance(): McpServer;
+export {};

package/dist/server/mcp/mcp.js

@@ -0,0 +1,392 @@
+import { McpServer } from "../../node_modules/.pnpm/@modelcontextprotocol_sdk@1.16.0/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js";
+import { wrapMcpServerWithSentry, captureException } from "@sentry/node";
+import { z } from "zod";
+import { formatErrorEnvelope } from "../formatters/md/errors.js";
+import { formatLogEnvelope } from "../formatters/md/logs.js";
+import { extractTracesFromEnvelopes, formatTraceSummary, buildSpanTree, renderSpanTree } from "../formatters/md/traces.js";
+import { getBuffer } from "../utils/getBuffer.js";
+import "../parser/helpers.js";
+import "uuidv7";
+import "node:http";
+import { NO_ERRORS_CONTENT, NO_LOGS_CONTENT } from "./constants.js";
+const inputSchema = {
+  filters: z.union([
+    z.object({
+      timeWindow: z.number().describe(
+        "Number of seconds to look back from now. Examples: 60 = last minute, 300 = last 5 minutes, 3600 = last hour. Default: 60"
+      )
+    }),
+    z.object({
+      filename: z.string().describe(
+        "Exact filename to search in stack traces or logs. Examples: 'Button.tsx', 'auth.js', 'api/routes.ts'. Case-sensitive."
+      )
+    }),
+    /**
+     * TODO: Need to check, if this approach is better then a cursor based approach,
+     * where the user can pass `events since [event_id]` as "last N events" is a
+     * moving target as events keep coming in.
+     *
+     * https://github.com/getsentry/spotlight/pull/968#discussion_r2391587907
+     */
+    z.object({
+      limit: z.number().describe("Maximum number of results to return. Examples: 10, 20, 50. Default: no limit"),
+      offset: z.number().default(0).describe(
+        "Number of results to skip from the beginning. Examples: 0 = start from first, 10 = skip first 10. Default: 0"
+      )
+    }).optional().describe("Pagination: Use when timeWindow doesn't work or for browsing through many results")
+  ])
+};
+function applyPagination(envelopes, pagination) {
+  if (pagination == null || !("limit" in pagination)) {
+    return envelopes;
+  }
+  return envelopes.slice(pagination.offset, pagination.offset + pagination.limit);
+}
+function createMCPInstance() {
+  const mcp = wrapMcpServerWithSentry(
+    new McpServer({
+      name: "spotlight-mcp",
+      version: String("4.6.0")
+    })
+  );
+  mcp.registerTool(
+    "search_errors",
+    {
+      title: "Search Application Errors",
+      description: `**Purpose:** Search for runtime errors, exceptions, and crashes captured by Spotlight across your entire application stack.
+
+**CRITICAL: Call this tool IMMEDIATELY when:**
+- User says "error", "broken", "not working", "failing", "crash", "bug", "issue"
+- You encounter errors during testing or code execution
+- Before and after making code changes to verify no regressions
+- Investigating any unexpected behavior or performance problems
+- Error messages and exception details
+- Request/response context for API failures
+- Browser/device info when available
+
+**Returns:**
+• Full stack traces with exact file:line locations
+
+**When to use:**
+- User reports "error", "broken", "not working", "crash", "bug"
+- After code changes to verify no regressions
+- Investigating unexpected behavior or failures
+- Debugging specific file errors
+
+**Example calls:**
+\`\`\`json
+// Example 1: Check last minute for any errors
+search_errors({ filters: { timeWindow: 60 } })
+
+// Example 2: Find errors in specific file
+search_errors({ filters: { filename: "auth.tsx" } })
+
+// Example 3: Get last 10 errors with pagination
+search_errors({ filters: { limit: 10, offset: 0 } })
+\`\`\`
+
+**Parameter hints:**
+• filters.timeWindow: Seconds to look back (60 = 1 min, 300 = 5 min, 3600 = 1 hour)
+• filters.filename: Exact filename in stack trace (e.g., "Button.tsx", "api.js")
+• filters.limit/offset: For pagination through many errors`,
+      inputSchema
+    },
+    async (args) => {
+      const envelopes = getBuffer().read(args.filters);
+      if (envelopes.length === 0) {
+        return NO_ERRORS_CONTENT;
+      }
+      const content = [];
+      for (const envelope of envelopes) {
+        try {
+          const events = await formatErrorEnvelope(envelope);
+          if (events?.length) {
+            for (const event of events) {
+              content.push({
+                type: "text",
+                text: event
+              });
+            }
+          }
+        } catch (err) {
+          captureException(err, { extra: { context: "Error formatting error envelope in MCP" } });
+        }
+      }
+      if (content.length === 0) {
+        return NO_ERRORS_CONTENT;
+      }
+      return {
+        content: applyPagination(content, args.filters)
+      };
+    }
+  );
+  mcp.registerTool(
+    "search_logs",
+    {
+      title: "Search Application Logs",
+      description: `**Purpose:** Search for application logs to understand behavior, debug issues, and trace execution flow across your stack.
+
+**NOT for:** Error diagnostics (use search_errors for exceptions/crashes). This tool is for info, warn, debug, and trace messages.
+
+**Returns:**
+• Timestamped log entries with severity levels (info, warn, debug)
+• Custom application messages and debug output
+• API request/response logs with timing
+• Database query logs and performance metrics
+
+**When to use:**
+- Understanding application flow and behavior
+- User mentions "logs", "debugging", "trace"
+- Checking what the app is doing internally
+- Performance investigation and timing analysis
+
+**Example calls:**
+\`\`\`json
+// Example 1: Check last 5 minutes of logs
+search_logs({ filters: { timeWindow: 300 } })
+
+// Example 2: Find logs from specific file
+search_logs({ filters: { filename: "auth.ts" } })
+
+// Example 3: Get recent 20 log entries
+search_logs({ filters: { limit: 20, offset: 0 } })
+\`\`\`
+
+## Workflow Pattern:
+1. User reports behavior question → **Call search_logs** 
+2. User tests new feature → **Check logs for expected output**
+3. Performance concerns → **Look for timing patterns in logs**
+4. Debugging complex flows → **Trace execution through log timeline**
+5. **Use with search_errors** for complete debugging picture
+
+**Key trigger phrases:**
+- "How does X work?" → See runtime execution flow
+- "Is the app doing Y?" → Check for specific log patterns  
+- "Performance seems off" → Look for timing/resource logs
+- "Debug this feature" → Follow execution path through logs
+- "What's happening when..." → Real-time application behavior
+
+**Log Levels Available:**
+- **INFO**: General application flow and significant events
+- **WARN**: Potential issues that don't break functionality  
+- **DEBUG**: Detailed execution information for troubleshooting
+- **ERROR**: Actual failures (also available via search_errors)
+
+**Remember:** Logs show you what your application is actually doing, not just what the code says it should do. Use this for understanding real runtime behavior, performance patterns, and verifying that features work as intended.
+
+**Parameter hints:**
+• filters.timeWindow: Seconds to look back (60 = 1 min, 300 = 5 min, 3600 = 1 hour) 
+• filters.filename: Exact filename generating logs (e.g., "api.ts", "database.js")
+• filters.limit/offset: For pagination through many log entries`,
+      inputSchema
+    },
+    async (args) => {
+      const envelopes = getBuffer().read(args.filters);
+      if (envelopes.length === 0) {
+        return NO_LOGS_CONTENT;
+      }
+      const content = [];
+      for (const envelope of envelopes) {
+        try {
+          const events = await formatLogEnvelope(envelope);
+          if (events?.length) {
+            for (const event of events) {
+              content.push({
+                type: "text",
+                text: event
+              });
+            }
+          }
+        } catch (err) {
+          captureException(err, { extra: { context: "Error formatting log envelope in MCP" } });
+        }
+      }
+      if (content.length === 0) {
+        return NO_LOGS_CONTENT;
+      }
+      return {
+        content: applyPagination(content, args.filters)
+      };
+    }
+  );
+  mcp.registerTool(
+    "search_traces",
+    {
+      title: "Search Performance Traces",
+      description: `**Purpose:** Search for performance traces to identify slow requests, bottlenecks, and transaction patterns across your application.
+
+**USE THIS TOOL WHEN:**
+- Investigating application performance and request flows
+- User mentions "traces", "performance", "slow requests", "tracing"
+- Looking for distributed tracing data or transaction flows
+- Need to see high-level trace patterns before diving into details
+
+**Returns:**
+• List of traces with IDs, durations, and span counts
+• Root transaction names and total execution time
+• Error counts per trace for quick identification
+• Trace start timestamps for timeline analysis
+
+**When to use:**
+- Investigating performance issues or slow requests
+- User mentions "traces", "performance", "slow"
+- Finding specific transactions or requests
+- Overview of recent application activity
+
+**Example calls:**
+\`\`\`json
+// Example 1: Get traces from last 5 minutes
+search_traces({ filters: { timeWindow: 300 } })
+
+// Example 2: Get 10 most recent traces
+search_traces({ filters: { limit: 10, offset: 0 } })
+
+// Example 3: Find traces involving specific file
+search_traces({ filters: { filename: "api.ts" } })
+\`\`\`
+
+**Parameter hints:**
+• filters.timeWindow: Seconds to look back (60 = 1 min, 300 = 5 min)
+• filters.limit: Number of traces to return (e.g., 10, 20)
+• filters.offset: Skip first N traces for pagination
+**Key trigger phrases:**
+- "Show me recent traces" → Get trace overview
+- "Performance issues" → Look for slow traces
+- "Request flows" → See transaction patterns
+- "Distributed tracing" → View trace summaries
+
+**Next step:** Use get_traces with a trace ID to see detailed span breakdown`,
+      inputSchema
+    },
+    async (args) => {
+      const envelopes = getBuffer().read(args.filters);
+      if (envelopes.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No traces found in the specified time period. Make sure your application is instrumented with Sentry performance monitoring and try triggering some requests or transactions."
+            }
+          ]
+        };
+      }
+      const traces = extractTracesFromEnvelopes(envelopes);
+      if (traces.size === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No traces with trace context found. Ensure your Sentry SDK has performance monitoring enabled and is generating transaction events."
+            }
+          ]
+        };
+      }
+      let content = [];
+      const sortedTraces = Array.from(traces.values()).sort(
+        (a, b) => (b.start_timestamp || 0) - (a.start_timestamp || 0)
+      );
+      content.push({
+        type: "text",
+        text: `# Local Traces (${sortedTraces.length} found)
+
+Recent traces from your application:
+`
+      });
+      for (const trace of sortedTraces.slice(0, 20)) {
+        content.push({
+          type: "text",
+          text: formatTraceSummary(trace)
+        });
+      }
+      content = applyPagination(content, args.filters);
+      content.push({
+        type: "text",
+        text: "\n**Next Steps:**\nUse `get_traces` with a trace ID (e.g., first 8 characters shown above) to see the full span tree and detailed timing breakdown for any specific trace."
+      });
+      return { content };
+    }
+  );
+  mcp.registerTool(
+    "get_traces",
+    {
+      title: "Get Trace Details",
+      description: `**Purpose:** Get the complete span tree and timing breakdown for a specific trace ID to analyze performance bottlenecks.
+
+**USE THIS TOOL WHEN:**
+- User provides a specific trace ID from \`search_traces\`
+- Want to see detailed span hierarchy and timing for a trace
+- Investigating performance bottlenecks within a specific request flow
+- Need to understand the complete execution path of a transaction
+
+**Returns:**
+• Hierarchical span tree with parent-child relationships
+• Individual span durations and operation names
+• Database queries, API calls, and render timings
+• Error details if spans failed
+
+**When to use:**
+- After finding a trace ID with search_traces
+- Investigating specific slow request or transaction
+- Understanding detailed execution flow
+- Finding performance bottlenecks in a trace
+
+**Example calls:**
+\`\`\`json
+// Example 1: Get trace using short ID (first 8 chars)
+get_traces({ traceId: "71a8c5e4" })
+
+// Example 2: Get trace using full 32-char ID
+get_traces({ traceId: "71a8c5e41ae1044dee67f50a07538fe7" })
+\`\`\`
+
+**Parameter hints:**
+• traceId: Trace identifier from search_traces
+  - Can use first 8 characters (e.g., "71a8c5e4")
+  - Or full 32-character hex string
+  - Case-insensitive`,
+      inputSchema: {
+        traceId: z.string().describe(
+          "Trace ID to retrieve. Format: 8 or 32 hex characters. Examples: '71a8c5e4' or '71a8c5e41ae1044dee67f50a07538fe7'"
+        )
+      }
+    },
+    async (args) => {
+      const envelopes = getBuffer().read({ all: true });
+      const traces = extractTracesFromEnvelopes(envelopes);
+      let targetTrace = traces.get(args.traceId);
+      if (!targetTrace && args.traceId.length < 32) {
+        for (const [traceId, trace] of traces) {
+          if (traceId.startsWith(args.traceId)) {
+            targetTrace = trace;
+            break;
+          }
+        }
+      }
+      if (!targetTrace) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Trace \`${args.traceId}\` not found. Use \`search_traces\` to see available traces, or try expanding the time window if the trace is older.`
+            }
+          ]
+        };
+      }
+      const spanTree = buildSpanTree(targetTrace);
+      const treeLines = renderSpanTree(spanTree);
+      return {
+        content: [
+          {
+            type: "text",
+            text: treeLines.join("\n")
+          }
+        ]
+      };
+    }
+  );
+  return mcp;
+}
+export {
+  createMCPInstance
+};
+//# sourceMappingURL=mcp.js.map

package/dist/server/mcp/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sources":["../../../src/server/mcp/mcp.ts"],"sourcesContent":["import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { TextContent } from \"@modelcontextprotocol/sdk/types.js\";\nimport { captureException, wrapMcpServerWithSentry } from \"@sentry/node\";\nimport { z } from \"zod\";\nimport { formatErrorEnvelope } from \"../formatters/md/errors.ts\";\nimport { formatLogEnvelope } from \"../formatters/md/logs.ts\";\nimport {\n  buildSpanTree,\n  extractTracesFromEnvelopes,\n  formatTraceSummary,\n  renderSpanTree,\n} from \"../formatters/md/traces.ts\";\nimport { getBuffer } from \"../utils/index.ts\";\nimport { NO_ERRORS_CONTENT, NO_LOGS_CONTENT } from \"./constants.ts\";\n\nconst inputSchema = {\n  filters: z.union([\n    z.object({\n      timeWindow: z\n        .number()\n        .describe(\n          \"Number of seconds to look back from now. Examples: 60 = last minute, 300 = last 5 minutes, 3600 = last hour. Default: 60\",\n        ),\n    }),\n    z.object({\n      filename: z\n        .string()\n        .describe(\n          \"Exact filename to search in stack traces or logs. Examples: 'Button.tsx', 'auth.js', 'api/routes.ts'. Case-sensitive.\",\n        ),\n    }),\n    /**\n     * TODO: Need to check, if this approach is better then a cursor based approach,\n     * where the user can pass `events since [event_id]` as \"last N events\" is a\n     * moving target as events keep coming in.\n     *\n     * https://github.com/getsentry/spotlight/pull/968#discussion_r2391587907\n     */\n    z\n      .object({\n        limit: z.number().describe(\"Maximum number of results to return. Examples: 10, 20, 50. Default: no limit\"),\n        offset: z\n          .number()\n          .default(0)\n          .describe(\n            \"Number of results to skip from the beginning. Examples: 0 = start from first, 10 = skip first 10. Default: 0\",\n          ),\n      })\n      .optional()\n      .describe(\"Pagination: Use when timeWindow doesn't work or for browsing through many results\"),\n  ]),\n};\n\nexport type InputSchema = { [K in keyof typeof inputSchema]: z.infer<(typeof inputSchema)[K]> };\n\nfunction applyPagination<T>(envelopes: T[], pagination: InputSchema[\"filters\"]) {\n  if (pagination == null || !(\"limit\" in pagination)) {\n    return envelopes;\n  }\n\n  return envelopes.slice(pagination.offset, pagination.offset + pagination.limit);\n}\n\nexport function createMCPInstance() {\n  const mcp = wrapMcpServerWithSentry(\n    new McpServer({\n      name: \"spotlight-mcp\",\n      version: String(process.env.npm_package_version),\n    }),\n  );\n\n  mcp.registerTool(\n    \"search_errors\",\n    {\n      title: \"Search Application Errors\",\n      description: `**Purpose:** Search for runtime errors, exceptions, and crashes captured by Spotlight across your entire application stack.\n\n**CRITICAL: Call this tool IMMEDIATELY when:**\n- User says \"error\", \"broken\", \"not working\", \"failing\", \"crash\", \"bug\", \"issue\"\n- You encounter errors during testing or code execution\n- Before and after making code changes to verify no regressions\n- Investigating any unexpected behavior or performance problems\n- Error messages and exception details\n- Request/response context for API failures\n- Browser/device info when available\n\n**Returns:**\n• Full stack traces with exact file:line locations\n\n**When to use:**\n- User reports \"error\", \"broken\", \"not working\", \"crash\", \"bug\"\n- After code changes to verify no regressions\n- Investigating unexpected behavior or failures\n- Debugging specific file errors\n\n**Example calls:**\n\\`\\`\\`json\n// Example 1: Check last minute for any errors\nsearch_errors({ filters: { timeWindow: 60 } })\n\n// Example 2: Find errors in specific file\nsearch_errors({ filters: { filename: \"auth.tsx\" } })\n\n// Example 3: Get last 10 errors with pagination\nsearch_errors({ filters: { limit: 10, offset: 0 } })\n\\`\\`\\`\n\n**Parameter hints:**\n• filters.timeWindow: Seconds to look back (60 = 1 min, 300 = 5 min, 3600 = 1 hour)\n• filters.filename: Exact filename in stack trace (e.g., \"Button.tsx\", \"api.js\")\n• filters.limit/offset: For pagination through many errors`,\n      inputSchema,\n    },\n    async args => {\n      const envelopes = getBuffer().read(args.filters);\n\n      if (envelopes.length === 0) {\n        return NO_ERRORS_CONTENT;\n      }\n\n      const content: TextContent[] = [];\n      for (const envelope of envelopes) {\n        try {\n          const events = await formatErrorEnvelope(envelope);\n\n          if (events?.length) {\n            for (const event of events) {\n              content.push({\n                type: \"text\",\n                text: event,\n              });\n            }\n          }\n        } catch (err) {\n          captureException(err, { extra: { context: \"Error formatting error envelope in MCP\" } });\n        }\n      }\n\n      if (content.length === 0) {\n        return NO_ERRORS_CONTENT;\n      }\n\n      return {\n        content: applyPagination(content, args.filters),\n      };\n    },\n  );\n\n  mcp.registerTool(\n    \"search_logs\",\n    {\n      title: \"Search Application Logs\",\n      description: `**Purpose:** Search for application logs to understand behavior, debug issues, and trace execution flow across your stack.\n\n**NOT for:** Error diagnostics (use search_errors for exceptions/crashes). This tool is for info, warn, debug, and trace messages.\n\n**Returns:**\n• Timestamped log entries with severity levels (info, warn, debug)\n• Custom application messages and debug output\n• API request/response logs with timing\n• Database query logs and performance metrics\n\n**When to use:**\n- Understanding application flow and behavior\n- User mentions \"logs\", \"debugging\", \"trace\"\n- Checking what the app is doing internally\n- Performance investigation and timing analysis\n\n**Example calls:**\n\\`\\`\\`json\n// Example 1: Check last 5 minutes of logs\nsearch_logs({ filters: { timeWindow: 300 } })\n\n// Example 2: Find logs from specific file\nsearch_logs({ filters: { filename: \"auth.ts\" } })\n\n// Example 3: Get recent 20 log entries\nsearch_logs({ filters: { limit: 20, offset: 0 } })\n\\`\\`\\`\n\n## Workflow Pattern:\n1. User reports behavior question → **Call search_logs** \n2. User tests new feature → **Check logs for expected output**\n3. Performance concerns → **Look for timing patterns in logs**\n4. Debugging complex flows → **Trace execution through log timeline**\n5. **Use with search_errors** for complete debugging picture\n\n**Key trigger phrases:**\n- \"How does X work?\" → See runtime execution flow\n- \"Is the app doing Y?\" → Check for specific log patterns  \n- \"Performance seems off\" → Look for timing/resource logs\n- \"Debug this feature\" → Follow execution path through logs\n- \"What's happening when...\" → Real-time application behavior\n\n**Log Levels Available:**\n- **INFO**: General application flow and significant events\n- **WARN**: Potential issues that don't break functionality  \n- **DEBUG**: Detailed execution information for troubleshooting\n- **ERROR**: Actual failures (also available via search_errors)\n\n**Remember:** Logs show you what your application is actually doing, not just what the code says it should do. Use this for understanding real runtime behavior, performance patterns, and verifying that features work as intended.\n\n**Parameter hints:**\n• filters.timeWindow: Seconds to look back (60 = 1 min, 300 = 5 min, 3600 = 1 hour) \n• filters.filename: Exact filename generating logs (e.g., \"api.ts\", \"database.js\")\n• filters.limit/offset: For pagination through many log entries`,\n      inputSchema,\n    },\n    async args => {\n      const envelopes = getBuffer().read(args.filters);\n\n      if (envelopes.length === 0) {\n        return NO_LOGS_CONTENT;\n      }\n\n      const content: TextContent[] = [];\n      for (const envelope of envelopes) {\n        try {\n          const events = await formatLogEnvelope(envelope);\n\n          if (events?.length) {\n            for (const event of events) {\n              content.push({\n                type: \"text\",\n                text: event,\n              });\n            }\n          }\n        } catch (err) {\n          captureException(err, { extra: { context: \"Error formatting log envelope in MCP\" } });\n        }\n      }\n\n      if (content.length === 0) {\n        return NO_LOGS_CONTENT;\n      }\n\n      return {\n        content: applyPagination(content, args.filters),\n      };\n    },\n  );\n\n  mcp.registerTool(\n    \"search_traces\",\n    {\n      title: \"Search Performance Traces\",\n      description: `**Purpose:** Search for performance traces to identify slow requests, bottlenecks, and transaction patterns across your application.\n\n**USE THIS TOOL WHEN:**\n- Investigating application performance and request flows\n- User mentions \"traces\", \"performance\", \"slow requests\", \"tracing\"\n- Looking for distributed tracing data or transaction flows\n- Need to see high-level trace patterns before diving into details\n\n**Returns:**\n• List of traces with IDs, durations, and span counts\n• Root transaction names and total execution time\n• Error counts per trace for quick identification\n• Trace start timestamps for timeline analysis\n\n**When to use:**\n- Investigating performance issues or slow requests\n- User mentions \"traces\", \"performance\", \"slow\"\n- Finding specific transactions or requests\n- Overview of recent application activity\n\n**Example calls:**\n\\`\\`\\`json\n// Example 1: Get traces from last 5 minutes\nsearch_traces({ filters: { timeWindow: 300 } })\n\n// Example 2: Get 10 most recent traces\nsearch_traces({ filters: { limit: 10, offset: 0 } })\n\n// Example 3: Find traces involving specific file\nsearch_traces({ filters: { filename: \"api.ts\" } })\n\\`\\`\\`\n\n**Parameter hints:**\n• filters.timeWindow: Seconds to look back (60 = 1 min, 300 = 5 min)\n• filters.limit: Number of traces to return (e.g., 10, 20)\n• filters.offset: Skip first N traces for pagination\n**Key trigger phrases:**\n- \"Show me recent traces\" → Get trace overview\n- \"Performance issues\" → Look for slow traces\n- \"Request flows\" → See transaction patterns\n- \"Distributed tracing\" → View trace summaries\n\n**Next step:** Use get_traces with a trace ID to see detailed span breakdown`,\n      inputSchema,\n    },\n    async args => {\n      const envelopes = getBuffer().read(args.filters);\n\n      if (envelopes.length === 0) {\n        return {\n          content: [\n            {\n              type: \"text\",\n              text: \"No traces found in the specified time period. Make sure your application is instrumented with Sentry performance monitoring and try triggering some requests or transactions.\",\n            },\n          ],\n        };\n      }\n\n      const traces = extractTracesFromEnvelopes(envelopes);\n\n      if (traces.size === 0) {\n        return {\n          content: [\n            {\n              type: \"text\",\n              text: \"No traces with trace context found. Ensure your Sentry SDK has performance monitoring enabled and is generating transaction events.\",\n            },\n          ],\n        };\n      }\n\n      let content: TextContent[] = [];\n\n      // Sort traces by start time (most recent first)\n      const sortedTraces = Array.from(traces.values()).sort(\n        (a, b) => (b.start_timestamp || 0) - (a.start_timestamp || 0),\n      );\n\n      content.push({\n        type: \"text\",\n        text: `# Local Traces (${sortedTraces.length} found)\\n\\nRecent traces from your application:\\n`,\n      });\n\n      for (const trace of sortedTraces.slice(0, 20)) {\n        // Limit to 20 most recent\n        content.push({\n          type: \"text\",\n          text: formatTraceSummary(trace),\n        });\n      }\n\n      content = applyPagination(content, args.filters);\n\n      content.push({\n        type: \"text\",\n        text: \"\\n**Next Steps:**\\nUse `get_traces` with a trace ID (e.g., first 8 characters shown above) to see the full span tree and detailed timing breakdown for any specific trace.\",\n      });\n\n      return { content };\n    },\n  );\n\n  mcp.registerTool(\n    \"get_traces\",\n    {\n      title: \"Get Trace Details\",\n      description: `**Purpose:** Get the complete span tree and timing breakdown for a specific trace ID to analyze performance bottlenecks.\n\n**USE THIS TOOL WHEN:**\n- User provides a specific trace ID from \\`search_traces\\`\n- Want to see detailed span hierarchy and timing for a trace\n- Investigating performance bottlenecks within a specific request flow\n- Need to understand the complete execution path of a transaction\n\n**Returns:**\n• Hierarchical span tree with parent-child relationships\n• Individual span durations and operation names\n• Database queries, API calls, and render timings\n• Error details if spans failed\n\n**When to use:**\n- After finding a trace ID with search_traces\n- Investigating specific slow request or transaction\n- Understanding detailed execution flow\n- Finding performance bottlenecks in a trace\n\n**Example calls:**\n\\`\\`\\`json\n// Example 1: Get trace using short ID (first 8 chars)\nget_traces({ traceId: \"71a8c5e4\" })\n\n// Example 2: Get trace using full 32-char ID\nget_traces({ traceId: \"71a8c5e41ae1044dee67f50a07538fe7\" })\n\\`\\`\\`\n\n**Parameter hints:**\n• traceId: Trace identifier from search_traces\n  - Can use first 8 characters (e.g., \"71a8c5e4\")\n  - Or full 32-character hex string\n  - Case-insensitive`,\n      inputSchema: {\n        traceId: z\n          .string()\n          .describe(\n            \"Trace ID to retrieve. Format: 8 or 32 hex characters. Examples: '71a8c5e4' or '71a8c5e41ae1044dee67f50a07538fe7'\",\n          ),\n      },\n    },\n    async args => {\n      // Getting all the envelopes\n      const envelopes = getBuffer().read({ all: true });\n      const traces = extractTracesFromEnvelopes(envelopes);\n\n      // Find trace by full ID or partial ID match\n      let targetTrace = traces.get(args.traceId);\n\n      if (!targetTrace && args.traceId.length < 32) {\n        // Try to find by partial ID\n        for (const [traceId, trace] of traces) {\n          if (traceId.startsWith(args.traceId)) {\n            targetTrace = trace;\n            break;\n          }\n        }\n      }\n\n      if (!targetTrace) {\n        return {\n          content: [\n            {\n              type: \"text\",\n              text: `Trace \\`${args.traceId}\\` not found. Use \\`search_traces\\` to see available traces, or try expanding the time window if the trace is older.`,\n            },\n          ],\n        };\n      }\n\n      const spanTree = buildSpanTree(targetTrace);\n\n      // Just render the full span tree\n      const treeLines = renderSpanTree(spanTree);\n\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: treeLines.join(\"\\n\"),\n          },\n        ],\n      };\n    },\n  );\n\n  return mcp;\n}\n"],"names":[],"mappings":"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"}

package/dist/server/messageBuffer.d.ts

@@ -0,0 +1,40 @@
+import { InputSchema } from './mcp/mcp.ts';
+export declare class MessageBuffer<T> {
+    private size;
+    private items;
+    private writePos;
+    private head;
+    private readers;
+    private filenameCache;
+    constructor(size?: number);
+    /**
+     * Binary search for an event by its envelope ID (UUIDv7).
+     * Returns the position of the event, or -1 if not found.
+     * Takes advantage of UUIDv7's time-ordered property.
+     */
+    private binarySearchEventId;
+    put(item: T): void;
+    subscribe(callback: (item: T) => void, lastEventId?: string): string;
+    unsubscribe(readerId: string): void;
+    stream(readerId: string): void;
+    /**
+     * hard reset: drops items and resets cursors.
+     */
+    clear(): void;
+    /**
+     * soft reset: clears buffered items but preserves subscribers
+     * do not set head or writePos to `0` as subscribers retain their
+     * readPos which would mess things up if we suddenly reset everything
+     * to 0.
+     */
+    reset(): void;
+    read(filters?: ReadFilter): T[];
+    filterHandlers: Record<keyof ReadFilter | string, (item: [number, T], value: NonNullable<ReadFilter>, ctx: {
+        filenameCache: Map<string, Set<string>>;
+    }) => boolean>;
+}
+export type ReadFilter = InputSchema["filters"] | {
+    envelopeId: string;
+} | {
+    all: true;
+};