feat(server): add protocol logger and session lifecycle instrumentation

Author: rahmanunver

packages/pluggable-widgets-mcp/src/server/protocol-logger.ts

@@ -0,0 +1,98 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+export interface ProtocolLogEntry {
+    timestamp: string;
+    sessionId: string;
+    direction: "incoming" | "outgoing";
+    method?: string;
+    id?: string | number | null;
+    params?: unknown;
+    result?: unknown;
+    error?: unknown;
+    duration?: number;
+    clientCapabilities?: unknown;
+    clientInfo?: unknown;
+    protocolVersion?: string;
+}
+
+const LOG_DIR = join(process.cwd(), "mcp-session-logs");
+let logDirCreated = false;
+
+function ensureLogDir(): void {
+    if (!logDirCreated) {
+        mkdirSync(LOG_DIR, { recursive: true });
+        logDirCreated = true;
+    }
+}
+
+/**
+ * Appends a JSON-lines log entry for the given session.
+ * Writes to mcp-session-logs/<sessionId>.jsonl.
+ * Uses synchronous I/O to keep the MCP stdio channel clean.
+ */
+export function logProtocolMessage(sessionId: string, entry: ProtocolLogEntry): void {
+    try {
+        ensureLogDir();
+        const line = JSON.stringify(entry) + "\n";
+        appendFileSync(join(LOG_DIR, `${sessionId}.jsonl`), line, "utf-8");
+    } catch {
+        // Never crash the server over a logging failure
+    }
+}
+
+/**
+ * Extracts a structured log entry from an incoming JSON-RPC request body.
+ * Special-cases initialize requests to surface ClientCapabilities at the top level.
+ */
+export function buildIncomingLogEntry(sessionId: string, body: Record<string, unknown>): ProtocolLogEntry {
+    const entry: ProtocolLogEntry = {
+        timestamp: new Date().toISOString(),
+        sessionId,
+        direction: "incoming",
+        method: typeof body.method === "string" ? body.method : undefined,
+        id: (body.id as string | number | null | undefined) ?? undefined
+    };
+
+    const method = entry.method;
+
+    if (method === "initialize") {
+        const params = body.params as Record<string, unknown> | undefined;
+        if (params) {
+            entry.protocolVersion = params.protocolVersion as string | undefined;
+            entry.clientInfo = params.clientInfo;
+            entry.clientCapabilities = params.capabilities;
+        }
+    } else if (method === "tools/call") {
+        const params = body.params as Record<string, unknown> | undefined;
+        entry.params = params ? { name: params.name, arguments: params.arguments } : undefined;
+    } else {
+        // For other methods log params as-is (but omit large payloads)
+        entry.params = body.params;
+    }
+
+    return entry;
+}
+
+/**
+ * Builds a log entry for an outgoing response.
+ */
+export function buildOutgoingLogEntry(
+    sessionId: string,
+    method: string | undefined,
+    id: string | number | null | undefined,
+    result: unknown,
+    error: unknown,
+    duration: number
+): ProtocolLogEntry {
+    return {
+        timestamp: new Date().toISOString(),
+        sessionId,
+        direction: "outgoing",
+        method,
+        id,
+        result: error ? undefined : result,
+        error,
+        duration
+    };
+}

packages/pluggable-widgets-mcp/src/server/routes.ts

@@ -1,6 +1,7 @@
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import type { Express, Request, Response } from "express";
 import { MENDIX_PROJECT_DIR, SERVER_NAME, SERVER_VERSION } from "@/config";
+import { buildIncomingLogEntry, logProtocolMessage } from "./protocol-logger";
 import { createMcpServer } from "./server";
 import { sessionManager } from "./session";
 
@@ -40,27 +41,41 @@ function setupMcpRoute(app: Express): void {
 
     app.all("/mcp", async (req: Request, res: Response) => {
         const sessionId = req.headers["mcp-session-id"] as string | undefined;
+        const requestStart = Date.now();
 
         try {
             // Case 1: Existing session - reuse transport
             if (sessionId && sessionManager.hasSession(sessionId)) {
+                const body = req.body as Record<string, unknown>;
+                logProtocolMessage(sessionId, buildIncomingLogEntry(sessionId, body));
+                console.error(
+                    `[MCP] ${body.method ?? "request"} session=${sessionId} elapsed=${Date.now() - requestStart}ms`
+                );
                 const transport = sessionManager.getTransport(sessionId)!;
-                await transport.handleRequest(req, res, req.body);
+                await transport.handleRequest(req, res, body);
                 return;
             }
 
             // Case 2: New session via POST with initialize request
             if (req.method === "POST" && !sessionId && isInitializeRequest(req.body)) {
+                const body = req.body as Record<string, unknown>;
+                const pendingSessionId = "pending-" + Date.now();
+                const logEntry = buildIncomingLogEntry(pendingSessionId, body);
+                console.error(
+                    `[MCP] initialize (new session) protocolVersion=${logEntry.protocolVersion} clientInfo=${JSON.stringify(logEntry.clientInfo)}`
+                );
+                logProtocolMessage(pendingSessionId, logEntry);
                 const transport = sessionManager.createTransport();
                 const server = createMcpServer();
                 await server.connect(transport);
-                await transport.handleRequest(req, res, req.body);
+                await transport.handleRequest(req, res, body);
                 return;
             }
 
             // Case 3: GET request for SSE - create new session
             // StreamableHTTP uses GET for server-to-client event streams
             if (req.method === "GET") {
+                console.error(`[MCP] SSE GET — creating new session`);
                 const transport = sessionManager.createTransport();
                 const server = createMcpServer();
                 await server.connect(transport);

packages/pluggable-widgets-mcp/src/server/session.ts

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 export interface Session {
     transport: StreamableHTTPServerTransport;
     createdAt: Date;
+    toolCallCount: number;
 }
 
 /**
@@ -20,15 +21,23 @@ export class SessionManager {
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: () => randomUUID(),
             onsessioninitialized: sessionId => {
+                const createdAt = new Date();
                 this.sessions.set(sessionId, {
                     transport,
-                    createdAt: new Date()
+                    createdAt,
+                    toolCallCount: 0
                 });
-                console.log(`[MCP] Session initialized: ${sessionId}`);
+                console.error(`[MCP] Session initialized: ${sessionId} at=${createdAt.toISOString()}`);
             },
             onsessionclosed: sessionId => {
+                const session = this.sessions.get(sessionId);
+                if (session) {
+                    const durationMs = Date.now() - session.createdAt.getTime();
+                    console.error(
+                        `[MCP] Session closed: ${sessionId} duration=${durationMs}ms toolCalls=${session.toolCallCount}`
+                    );
+                }
                 this.sessions.delete(sessionId);
-                console.log(`[MCP] Session closed: ${sessionId}`);
             }
         });