feat: MCP (#864)

Author: MathurAditya724

packages/sidecar/package.json

@@ -27,12 +27,14 @@
       "types": "./dist/src/vite-plugin.d.ts"
     },
     "./constants": {
-      "import": "./src/constants.js",
-      "types": "./dist/constants.d.ts"
+      "import": "./dist/src/constants.js",
+      "types": "./dist/src/constants.d.ts"
     }
   },
   "dependencies": {
     "@jridgewell/trace-mapping": "^0.3.25",
+    "@modelcontextprotocol/sdk": "^1.16.0",
+    "@sentry/core": "^9.22.0",
     "@sentry/node": "^8.49.0",
     "kleur": "^4.1.5",
     "launch-editor": "^2.9.1"

packages/sidecar/src/main.ts

@@ -2,14 +2,15 @@ import { createWriteStream, readFileSync } from "node:fs";
 import { type IncomingMessage, type Server, type ServerResponse, createServer, get } from "node:http";
 import { extname, join, resolve } from "node:path";
 import { createGunzip, createInflate } from "node:zlib";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { addEventProcessor, captureException, getTraceData, startSpan } from "@sentry/node";
 import launchEditor from "launch-editor";
 import { CONTEXT_LINES_ENDPOINT, DEFAULT_PORT, SERVER_IDENTIFIER } from "./constants.js";
 import { contextLinesHandler } from "./contextlines.js";
 import { type SidecarLogger, activateLogger, enableDebugLogging, logger } from "./logger.js";
+import { createMcpInstance } from "./mcp/index.js";
 import { MessageBuffer } from "./messageBuffer.js";
-
-type Payload = [string, Buffer];
+import type { Payload } from "./utils.js";
 
 type IncomingPayloadCallback = (body: string) => void;
 
@@ -74,7 +75,7 @@ const SPOTLIGHT_HEADERS = {
 
 const enableCORS = (handler: RequestHandler): RequestHandler =>
   withTracing(
-    (req: IncomingMessage, res: ServerResponse, pathname?: string, searchParams?: URLSearchParams) => {
+    async (req: IncomingMessage, res: ServerResponse, pathname?: string, searchParams?: URLSearchParams) => {
       const headers = {
         ...CORS_HEADERS,
         ...SPOTLIGHT_HEADERS,
@@ -316,21 +317,30 @@ function logSpotlightUrl(port: number): void {
   logger.info(`You can open: http://localhost:${port} to see the Spotlight overlay directly`);
 }
 
-function startServer(
+async function startServer(
   buffer: MessageBuffer<Payload>,
   port: number,
   basePath?: string,
   filesToServe?: Record<string, Buffer>,
   incomingPayload?: IncomingPayloadCallback,
-): Server {
+): Promise<Server> {
   if (basePath && !filesToServe) {
     filesToServe = {
       "/src/index.html": readFileSync(join(basePath, "src/index.html")),
       "/assets/main.js": readFileSync(join(basePath, "assets/main.js")),
     };
   }
+
+  // MCP Setup
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+  });
+  const mcp = createMcpInstance(buffer);
+  await mcp.connect(transport);
+
   const ROUTES: [RegExp, RequestHandler][] = [
     [/^\/health$/, handleHealthRequest],
+    [/^\/mcp$/, enableCORS((req, res) => transport.handleRequest(req, res))],
     [/^\/clear$/, enableCORS(handleClearRequest)],
     [/^\/stream$|^\/api\/\d+\/envelope\/?$/, enableCORS(streamRequestHandler(buffer, incomingPayload))],
     [/^\/open$/, enableCORS(openRequestHandler(basePath))],
@@ -494,15 +504,15 @@ export function setupSidecar({
     sidecarPort = typeof port === "string" ? Number(port) : port;
   }
 
-  isSidecarRunning(sidecarPort).then((isRunning: boolean) => {
+  isSidecarRunning(sidecarPort).then(async (isRunning: boolean) => {
     if (isRunning) {
       logger.info(`Sidecar is already running on port ${sidecarPort}`);
       const hasSpotlightUI = (filesToServe && "/src/index.html" in filesToServe) || (!filesToServe && basePath);
       if (hasSpotlightUI) {
         logSpotlightUrl(sidecarPort);
       }
     } else if (!serverInstance) {
-      serverInstance = startServer(buffer, sidecarPort, basePath, filesToServe, incomingPayload);
+      serverInstance = await startServer(buffer, sidecarPort, basePath, filesToServe, incomingPayload);
     }
   });
 }

packages/sidecar/src/mcp/index.ts

@@ -0,0 +1,79 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TextContent } from "@modelcontextprotocol/sdk/types.js";
+import type { ErrorEvent } from "@sentry/core";
+import { MessageBuffer } from "../messageBuffer.js";
+import type { Payload } from "../utils.js";
+import { processEnvelope } from "./parsing.js";
+
+export function createMcpInstance(buffer: MessageBuffer<Payload>) {
+  const mcp = new McpServer({
+    name: "spotlight-mcp",
+    version: String(process.env.npm_package_version),
+  });
+
+  const errorsBuffer = new MessageBuffer<Payload>(10);
+  buffer.subscribe((item: Payload) => {
+    errorsBuffer.put(item);
+  });
+
+  mcp.tool(
+    "get_errors",
+    "Fetches the most recent errors from Spotlight debugger. Returns error details, stack traces, and request details for immediate debugging context.",
+    async () => {
+      const envelopes = errorsBuffer.read();
+      errorsBuffer.clear();
+
+      if (envelopes.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No recent errors found in Spotlight. This might be because the application started successfully, but runtime issues only appear when you interact with specific pages or features.\n\nAsk the user to navigate to the page where they're experiencing the issue to reproduce it, that way we can get that in the Spotlight debugger. So if you want to check for errors again, just ask me to do that.",
+            },
+          ],
+        };
+      }
+
+      const errors = envelopes
+        .map(([contentType, data]) => processEnvelope({ contentType, data }))
+        .sort((a, b) => {
+          const a_sent_at = a.envelope[0].sent_at as string;
+          const b_sent_at = b.envelope[0].sent_at as string;
+          if (a_sent_at < b_sent_at) return 1;
+          if (a_sent_at > b_sent_at) return -1;
+          return 0;
+        });
+
+      const content: TextContent[] = [];
+      for (const error of errors) {
+        const {
+          envelope: [, [[{ type }, payload]]],
+        } = error;
+
+        if (type === "event" && isErrorEvent(payload)) {
+          content.push({
+            type: "text",
+            text: JSON.stringify({
+              exception: payload.exception,
+              level: payload.level,
+              request: payload.request,
+            }),
+          });
+        }
+      }
+
+      return {
+        content,
+      };
+    },
+  );
+
+  // TODO: Add tool for performance tracing
+  // TODO: Add tool for profiling data
+
+  return mcp;
+}
+
+function isErrorEvent(payload: unknown): payload is ErrorEvent {
+  return typeof payload === "object" && payload !== null && "exception" in payload;
+}

packages/sidecar/src/mcp/parsing.ts

@@ -0,0 +1,66 @@
+// This file is a copy of utils from @spotlightjs/overlay to parse envelopes from Buffer
+import type { Envelope, EnvelopeItem } from "@sentry/core";
+
+type RawEventContext = {
+  contentType: string;
+  data: string | Uint8Array;
+};
+
+export function processEnvelope(rawEvent: RawEventContext) {
+  let buffer = typeof rawEvent.data === "string" ? Uint8Array.from(rawEvent.data, c => c.charCodeAt(0)) : rawEvent.data;
+
+  function readLine(length?: number) {
+    const cursor = length ?? getLineEnd(buffer);
+    const line = buffer.subarray(0, cursor);
+    buffer = buffer.subarray(cursor + 1);
+    return line;
+  }
+
+  const envelopeHeader = parseJSONFromBuffer(readLine()) as Envelope[0];
+
+  const items: EnvelopeItem[] = [];
+  while (buffer.length) {
+    const itemHeader = parseJSONFromBuffer(readLine()) as EnvelopeItem[0];
+    const payloadLength = itemHeader.length;
+    const itemPayloadRaw = readLine(payloadLength);
+
+    let itemPayload: EnvelopeItem[1];
+    try {
+      itemPayload = parseJSONFromBuffer(itemPayloadRaw);
+      // data sanitization
+      if (itemHeader.type) {
+        // @ts-expect-error ts(2339) -- We should really stop adding type to payloads
+        itemPayload.type = itemHeader.type;
+      }
+    } catch (err) {
+      itemPayload = itemPayloadRaw;
+      console.error(err);
+    }
+
+    items.push([itemHeader, itemPayload] as EnvelopeItem);
+  }
+
+  const envelope = [envelopeHeader, items] as Envelope;
+
+  return {
+    envelope,
+  };
+}
+
+function getLineEnd(data: Uint8Array): number {
+  let end = data.indexOf(0xa);
+  if (end === -1) {
+    end = data.length;
+  }
+
+  return end;
+}
+
+export function parseJSONFromBuffer<T = unknown>(data: Uint8Array): T {
+  try {
+    return JSON.parse(new TextDecoder().decode(data)) as T;
+  } catch (err) {
+    console.error(err);
+    return {} as T;
+  }
+}

packages/sidecar/src/messageBuffer.ts

@@ -66,6 +66,19 @@ export class MessageBuffer<T> {
     this.head = 0;
     this.readers = new Map<string, (item: T) => void>();
   }
+
+  read(): T[] {
+    const result: T[] = [];
+    const start = this.head;
+    const end = this.writePos;
+    for (let i = start; i < end; i++) {
+      const item = this.items[i % this.size];
+      if (item !== undefined) {
+        result.push(item[1]);
+      }
+    }
+    return result;
+  }
 }
 
 function generateUuidv4(): string {

packages/sidecar/src/utils.ts

@@ -0,0 +1 @@
+export type Payload = [string, Buffer];

packages/sidecar/tsdown.config.ts

@@ -1,14 +1,6 @@
-import { builtinModules } from "node:module";
 import { defineConfig } from "tsdown";
-import packageJson from "./package.json";
-
-const dependencies = Object.keys({
-  ...packageJson.dependencies,
-  ...packageJson.devDependencies,
-});
 
 export default defineConfig({
   entry: ["./src/main.ts", "./src/vite-plugin.ts", "./src/constants.ts", "./server.ts"],
   sourcemap: true,
-  external: [...dependencies, ...builtinModules.map(x => `node:${x}`)],
 });