Merge pull request #8 from vercel/log_v1

feat: new onEvent callback for user land logging of server calls

Author: quuu

src/lib/event-emitter.ts

@@ -0,0 +1,120 @@
+import { ServerResponse, type IncomingMessage } from "node:http";
+import {
+  type McpErrorEvent,
+  type McpEvent,
+  type McpRequestEvent,
+  type McpSessionEvent,
+  createEvent,
+} from "./log-helper";
+
+export class EventEmittingResponse extends ServerResponse {
+  private onEvent?: (event: McpEvent) => void;
+  private sessionId?: string;
+  private requestId: string;
+  private startTime: number;
+
+  constructor(
+    req: IncomingMessage,
+    onEvent?: (event: McpEvent) => void,
+    sessionId?: string
+  ) {
+    super(req);
+    this.onEvent = onEvent;
+    this.sessionId = sessionId;
+    this.requestId = crypto.randomUUID();
+    this.startTime = Date.now();
+  }
+
+  emitEvent(event: Omit<McpEvent, "timestamp" | "sessionId" | "requestId">) {
+    if (this.onEvent) {
+      this.onEvent(
+        createEvent({
+          ...event,
+          sessionId: this.sessionId,
+          requestId: this.requestId,
+        } as Omit<McpEvent, "timestamp">)
+      );
+    }
+  }
+
+  startSession(
+    transport: "SSE" | "HTTP",
+    clientInfo?: { userAgent?: string; ip?: string }
+  ) {
+    this.emitEvent({
+      type: "SESSION_STARTED",
+      transport,
+      clientInfo,
+    } as Omit<McpSessionEvent, "timestamp" | "sessionId" | "requestId">);
+  }
+
+  endSession(transport: "SSE" | "HTTP") {
+    this.emitEvent({
+      type: "SESSION_ENDED",
+      transport,
+    } as Omit<McpSessionEvent, "timestamp" | "sessionId" | "requestId">);
+  }
+
+  requestReceived(method: string, parameters?: unknown) {
+    this.emitEvent({
+      type: "REQUEST_RECEIVED",
+      method,
+      parameters,
+      status: "success",
+    } as Omit<McpRequestEvent, "timestamp" | "sessionId" | "requestId">);
+  }
+
+  requestCompleted(method: string, result?: unknown, error?: Error | string) {
+    this.emitEvent({
+      type: "REQUEST_COMPLETED",
+      method,
+      result,
+      duration: Date.now() - this.startTime,
+      status: error ? "error" : "success",
+    } as Omit<McpRequestEvent, "timestamp" | "sessionId" | "requestId">);
+
+    if (error) {
+      this.error(error, `Error executing request ${method}`, "request");
+    }
+  }
+
+  error(
+    error: Error | string,
+    context?: string,
+    source: McpErrorEvent["source"] = "system",
+    severity: McpErrorEvent["severity"] = "error"
+  ) {
+    this.emitEvent({
+      type: "ERROR",
+      error,
+      context,
+      source,
+      severity,
+    } as Omit<McpErrorEvent, "timestamp" | "sessionId" | "requestId">);
+  }
+
+  end(
+    chunk?: unknown,
+    encoding?: BufferEncoding | (() => void),
+    cb?: () => void
+  ): this {
+    let finalChunk = chunk;
+    let finalEncoding = encoding;
+    let finalCallback = cb;
+
+    if (typeof chunk === "function") {
+      finalCallback = chunk as () => void;
+      finalChunk = undefined;
+      finalEncoding = undefined;
+    } else if (typeof encoding === "function") {
+      finalCallback = encoding as () => void;
+      finalEncoding = undefined;
+    }
+
+    return super.end(
+      finalChunk as string | Buffer,
+      finalEncoding as BufferEncoding,
+      finalCallback
+    );
+  }
+}

src/lib/log-helper.ts

@@ -0,0 +1,50 @@
+export type McpEventType =
+  | "SESSION_STARTED" // When a new client session begins (either HTTP or SSE)
+  | "SESSION_ENDED" // When a client session ends (SSE disconnection)
+  | "REQUEST_RECEIVED" // When a request is received from the client
+  | "REQUEST_COMPLETED" // When a request completes
+  | "ERROR"; // When an error occurs during any operation
+
+export interface McpEventBase {
+  type: McpEventType;
+  timestamp: number;
+  sessionId?: string;
+  requestId?: string; // To track individual requests within a session
+}
+
+export interface McpSessionEvent extends McpEventBase {
+  type: "SESSION_STARTED" | "SESSION_ENDED";
+  transport: "SSE" | "HTTP";
+  clientInfo?: {
+    userAgent?: string;
+    ip?: string;
+  };
+}
+
+export interface McpRequestEvent extends McpEventBase {
+  type: "REQUEST_RECEIVED" | "REQUEST_COMPLETED";
+  method: string;
+  parameters?: unknown;
+  result?: unknown;
+  duration?: number; // For REQUEST_COMPLETED events
+  status: "success" | "error";
+}
+
+export interface McpErrorEvent extends McpEventBase {
+  type: "ERROR";
+  error: Error | string;
+  context?: string;
+  source: "request" | "session" | "system";
+  severity: "warning" | "error" | "fatal";
+}
+
+export type McpEvent = McpSessionEvent | McpRequestEvent | McpErrorEvent;
+
+export function createEvent<T extends McpEvent>(
+  event: Omit<T, "timestamp">
+): T {
+  return {
+    ...event,
+    timestamp: Date.now(),
+  } as T;
+}