trickle-observe 0.2.120 → 0.2.122

package/dist/mcp-observer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP tool call observer — auto-instruments MCP client and server SDKs
+ * to capture tool invocations, arguments, responses, latency, and errors.
+ *
+ * Writes to .trickle/mcp.jsonl as:
+ *   { "kind": "mcp_tool_call", "tool": "fetch", "direction": "outgoing",
+ *     "durationMs": 234.5, "args": {...}, "result": "...", ... }
+ *
+ * Zero code changes needed — intercepted via Module._load hook.
+ */
+export declare function patchMcpClient(mcpModule: any, debug: boolean): void;
+export declare function patchMcpServer(mcpModule: any, debug: boolean): void;
+export declare function initMcpObserver(): void;

package/dist/mcp-observer.js

@@ -0,0 +1,298 @@
+"use strict";
+/**
+ * MCP tool call observer — auto-instruments MCP client and server SDKs
+ * to capture tool invocations, arguments, responses, latency, and errors.
+ *
+ * Writes to .trickle/mcp.jsonl as:
+ *   { "kind": "mcp_tool_call", "tool": "fetch", "direction": "outgoing",
+ *     "durationMs": 234.5, "args": {...}, "result": "...", ... }
+ *
+ * Zero code changes needed — intercepted via Module._load hook.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchMcpClient = patchMcpClient;
+exports.patchMcpServer = patchMcpServer;
+exports.initMcpObserver = initMcpObserver;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+let mcpFile = null;
+let eventCount = 0;
+const MAX_MCP_EVENTS = 1000;
+const TRUNCATE_LEN = 500;
+function getMcpFile() {
+    if (mcpFile)
+        return mcpFile;
+    const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    mcpFile = path.join(dir, 'mcp.jsonl');
+    return mcpFile;
+}
+function writeMcpEvent(event) {
+    if (eventCount >= MAX_MCP_EVENTS)
+        return;
+    eventCount++;
+    try {
+        fs.appendFileSync(getMcpFile(), JSON.stringify(event) + '\n');
+    }
+    catch { }
+}
+function truncate(s, len = TRUNCATE_LEN) {
+    if (!s)
+        return '';
+    return s.length > len ? s.substring(0, len) + '...' : s;
+}
+function sanitizeArgs(args) {
+    if (args === null || args === undefined)
+        return null;
+    try {
+        const s = JSON.stringify(args);
+        return s.length > 1000 ? JSON.parse(s.substring(0, 1000) + '"}') : args;
+    }
+    catch {
+        return String(args).substring(0, 200);
+    }
+}
+function extractResultPreview(result) {
+    if (!result)
+        return '';
+    // MCP CallToolResult has .content array
+    if (result.content && Array.isArray(result.content)) {
+        const texts = result.content
+            .filter((c) => c.type === 'text' && c.text)
+            .map((c) => c.text);
+        return truncate(texts.join('\n'));
+    }
+    if (typeof result === 'string')
+        return truncate(result);
+    try {
+        return truncate(JSON.stringify(result));
+    }
+    catch {
+        return '';
+    }
+}
+// ────────────────────────────────────────────────────
+// Client-side: patch Client.callTool
+// ────────────────────────────────────────────────────
+function patchMcpClient(mcpModule, debug) {
+    if (!mcpModule || mcpModule.__trickle_mcp_patched)
+        return;
+    mcpModule.__trickle_mcp_patched = true;
+    // @modelcontextprotocol/sdk exports Client class
+    const ClientClass = mcpModule.Client;
+    if (!ClientClass) {
+        if (debug)
+            console.log('[trickle/mcp] Client class not found in module');
+        return;
+    }
+    // Patch callTool on the prototype
+    const proto = ClientClass.prototype;
+    if (proto.callTool && !proto.callTool.__trickle_patched) {
+        const origCallTool = proto.callTool;
+        proto.callTool = async function patchedCallTool(...args) {
+            const params = args[0] || {};
+            const toolName = typeof params === 'string' ? params : (params.name || 'unknown');
+            const toolArgs = typeof params === 'string' ? args[1] : (params.arguments || params.args);
+            const startTime = performance.now();
+            try {
+                const result = await origCallTool.apply(this, args);
+                const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+                writeMcpEvent({
+                    kind: 'mcp_tool_call', tool: toolName, direction: 'outgoing',
+                    durationMs, args: sanitizeArgs(toolArgs),
+                    resultPreview: extractResultPreview(result),
+                    isError: result?.isError || false,
+                    errorMessage: result?.isError ? extractResultPreview(result) : undefined,
+                    timestamp: Date.now(),
+                });
+                if (debug)
+                    console.log(`[trickle/mcp] callTool: ${toolName} (${durationMs}ms)`);
+                return result;
+            }
+            catch (err) {
+                const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+                writeMcpEvent({
+                    kind: 'mcp_tool_call', tool: toolName, direction: 'outgoing',
+                    durationMs, args: sanitizeArgs(toolArgs),
+                    resultPreview: '', isError: true,
+                    errorMessage: truncate(err?.message || String(err), 200),
+                    timestamp: Date.now(),
+                });
+                throw err;
+            }
+        };
+        proto.callTool.__trickle_patched = true;
+        if (debug)
+            console.log('[trickle/mcp] Patched Client.callTool');
+    }
+    // Also patch listTools for discovery
+    if (proto.listTools && !proto.listTools.__trickle_patched) {
+        const origListTools = proto.listTools;
+        proto.listTools = async function patchedListTools(...args) {
+            const startTime = performance.now();
+            const result = await origListTools.apply(this, args);
+            const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+            const toolCount = result?.tools?.length || 0;
+            writeMcpEvent({
+                kind: 'mcp_tool_call', tool: '__list_tools', direction: 'outgoing',
+                durationMs, args: null,
+                resultPreview: `${toolCount} tools available`,
+                isError: false, timestamp: Date.now(),
+            });
+            return result;
+        };
+        proto.listTools.__trickle_patched = true;
+    }
+}
+// ────────────────────────────────────────────────────
+// Server-side: patch Server to wrap tool handlers
+// ────────────────────────────────────────────────────
+function patchMcpServer(mcpModule, debug) {
+    // Server is exported from @modelcontextprotocol/sdk
+    const ServerClass = mcpModule.Server || mcpModule.McpServer;
+    if (!ServerClass || ServerClass.__trickle_mcp_server_patched)
+        return;
+    ServerClass.__trickle_mcp_server_patched = true;
+    const proto = ServerClass.prototype;
+    // Patch the .tool() registration method to wrap handlers
+    if (proto.tool && !proto.tool.__trickle_patched) {
+        const origTool = proto.tool;
+        proto.tool = function patchedTool(...args) {
+            // tool(name, schema, handler) or tool(name, handler)
+            const toolName = typeof args[0] === 'string' ? args[0] : 'unknown';
+            const lastArg = args[args.length - 1];
+            if (typeof lastArg === 'function') {
+                const originalHandler = lastArg;
+                args[args.length - 1] = async function wrappedHandler(...handlerArgs) {
+                    const startTime = performance.now();
+                    try {
+                        const result = await originalHandler.apply(this, handlerArgs);
+                        const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+                        writeMcpEvent({
+                            kind: 'mcp_tool_call', tool: toolName, direction: 'incoming',
+                            durationMs, args: sanitizeArgs(handlerArgs[0]),
+                            resultPreview: extractResultPreview(result),
+                            isError: result?.isError || false,
+                            timestamp: Date.now(),
+                        });
+                        if (debug)
+                            console.log(`[trickle/mcp] tool handler: ${toolName} (${durationMs}ms)`);
+                        return result;
+                    }
+                    catch (err) {
+                        const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+                        writeMcpEvent({
+                            kind: 'mcp_tool_call', tool: toolName, direction: 'incoming',
+                            durationMs, args: sanitizeArgs(handlerArgs[0]),
+                            resultPreview: '', isError: true,
+                            errorMessage: truncate(err?.message || String(err), 200),
+                            timestamp: Date.now(),
+                        });
+                        throw err;
+                    }
+                };
+            }
+            return origTool.apply(this, args);
+        };
+        proto.tool.__trickle_patched = true;
+        if (debug)
+            console.log('[trickle/mcp] Patched Server.tool');
+    }
+    // Patch setRequestHandler for lower-level interception
+    if (proto.setRequestHandler && !proto.setRequestHandler.__trickle_patched) {
+        const origSetHandler = proto.setRequestHandler;
+        proto.setRequestHandler = function patchedSetHandler(schema, handler) {
+            if (typeof handler === 'function') {
+                const origHandler = handler;
+                const capturedHandler = origHandler;
+                handler = async function wrappedHandler(...args) {
+                    const request = args[0];
+                    const method = request?.method || schema?.method || 'unknown';
+                    if (method === 'tools/call') {
+                        const startTime = performance.now();
+                        try {
+                            const result = await capturedHandler.apply(this, args);
+                            const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+                            writeMcpEvent({
+                                kind: 'mcp_tool_call', tool: request?.params?.name || 'unknown',
+                                direction: 'incoming', durationMs,
+                                args: sanitizeArgs(request?.params?.arguments),
+                                resultPreview: extractResultPreview(result),
+                                isError: result?.isError || false,
+                                timestamp: Date.now(),
+                            });
+                            return result;
+                        }
+                        catch (err) {
+                            const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+                            writeMcpEvent({
+                                kind: 'mcp_tool_call', tool: request?.params?.name || 'unknown',
+                                direction: 'incoming', durationMs,
+                                args: sanitizeArgs(request?.params?.arguments),
+                                resultPreview: '', isError: true,
+                                errorMessage: truncate(err?.message || String(err), 200),
+                                timestamp: Date.now(),
+                            });
+                            throw err;
+                        }
+                    }
+                    return capturedHandler.apply(this, args);
+                };
+            }
+            return origSetHandler.call(this, schema, handler);
+        };
+        proto.setRequestHandler.__trickle_patched = true;
+    }
+}
+// ────────────────────────────────────────────────────
+// Initialization
+// ────────────────────────────────────────────────────
+function initMcpObserver() {
+    const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    mcpFile = path.join(dir, 'mcp.jsonl');
+    try {
+        fs.writeFileSync(mcpFile, '');
+    }
+    catch { }
+    eventCount = 0;
+}

package/dist/observe-register.js

@@ -42,6 +42,7 @@ const express_1 = require("./express");
 const trace_var_1 = require("./trace-var");
 const call_trace_1 = require("./call-trace");
 const llm_observer_1 = require("./llm-observer");
+const mcp_observer_1 = require("./mcp-observer");
 const vite_plugin_1 = require("./vite-plugin");
 // ── Source map support ──
 // Lightweight VLQ decoder for mapping compiled JS lines back to original TS lines
@@ -1242,6 +1243,8 @@ if (enabled) {
     (0, call_trace_1.initCallTrace)();
     // ── Hook 0b3: Initialize LLM observer ──
     (0, llm_observer_1.initLlmObserver)();
+    // ── Hook 0b4: Initialize MCP observer ──
+    (0, mcp_observer_1.initMcpObserver)();
     // ── Hook 0c: Capture environment snapshot ──
     try {
         const envDir = process.env.TRICKLE_LOCAL_DIR || path_1.default.join(process.cwd(), '.trickle');
@@ -1552,6 +1555,34 @@ if (enabled) {
             }
             catch { /* not critical */ }
         }
+        // MCP SDK (client + server) — match any subpath import
+        if (request.includes('@modelcontextprotocol/sdk') && !expressPatched.has('mcp-client') && exports.Client) {
+            expressPatched.add('mcp-client');
+            try {
+                const { patchMcpClient } = require(path_1.default.join(__dirname, 'mcp-observer.js'));
+                patchMcpClient(exports, debug);
+            }
+            catch { /* not critical */ }
+        }
+        if (request.includes('@modelcontextprotocol/sdk') && !expressPatched.has('mcp-server') && (exports.Server || exports.McpServer)) {
+            expressPatched.add('mcp-server');
+            try {
+                const { patchMcpServer } = require(path_1.default.join(__dirname, 'mcp-observer.js'));
+                patchMcpServer(exports, debug);
+            }
+            catch { /* not critical */ }
+        }
+        // Claude Agent SDK
+        if (request.includes('claude-agent-sdk') && !expressPatched.has('claude-agent-sdk')) {
+            expressPatched.add('claude-agent-sdk');
+            try {
+                // The Claude Agent SDK uses hooks config — we can't easily patch
+                // from Module._load since it's ESM-only. Log detection for now.
+                if (debug)
+                    console.log('[trickle] Claude Agent SDK detected — use hooks for tracing');
+            }
+            catch { /* not critical */ }
+        }
         // Google Gemini SDK
         if (request === '@google/genai' && !expressPatched.has('@google/genai')) {
             expressPatched.add('@google/genai');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "trickle-observe",
-  "version": "0.2.120",
-  "description": "Runtime type observability for JavaScript applications",
+  "version": "0.2.122",
+  "description": "Zero-code runtime observability for JavaScript/TypeScript. Auto-instruments Express, OpenAI, Anthropic, Gemini, MCP. Captures functions, variables, LLM calls, agent workflows.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

package/src/mcp-observer.ts

@@ -0,0 +1,260 @@
+/**
+ * MCP tool call observer — auto-instruments MCP client and server SDKs
+ * to capture tool invocations, arguments, responses, latency, and errors.
+ *
+ * Writes to .trickle/mcp.jsonl as:
+ *   { "kind": "mcp_tool_call", "tool": "fetch", "direction": "outgoing",
+ *     "durationMs": 234.5, "args": {...}, "result": "...", ... }
+ *
+ * Zero code changes needed — intercepted via Module._load hook.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+let mcpFile: string | null = null;
+let eventCount = 0;
+const MAX_MCP_EVENTS = 1000;
+const TRUNCATE_LEN = 500;
+
+function getMcpFile(): string {
+  if (mcpFile) return mcpFile;
+  const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  mcpFile = path.join(dir, 'mcp.jsonl');
+  return mcpFile;
+}
+
+interface McpEvent {
+  kind: 'mcp_tool_call';
+  tool: string;
+  direction: 'outgoing' | 'incoming';
+  durationMs: number;
+  args: unknown;
+  resultPreview: string;
+  isError: boolean;
+  errorMessage?: string;
+  timestamp: number;
+}
+
+function writeMcpEvent(event: McpEvent): void {
+  if (eventCount >= MAX_MCP_EVENTS) return;
+  eventCount++;
+  try {
+    fs.appendFileSync(getMcpFile(), JSON.stringify(event) + '\n');
+  } catch {}
+}
+
+function truncate(s: string, len = TRUNCATE_LEN): string {
+  if (!s) return '';
+  return s.length > len ? s.substring(0, len) + '...' : s;
+}
+
+function sanitizeArgs(args: unknown): unknown {
+  if (args === null || args === undefined) return null;
+  try {
+    const s = JSON.stringify(args);
+    return s.length > 1000 ? JSON.parse(s.substring(0, 1000) + '"}') : args;
+  } catch { return String(args).substring(0, 200); }
+}
+
+function extractResultPreview(result: any): string {
+  if (!result) return '';
+  // MCP CallToolResult has .content array
+  if (result.content && Array.isArray(result.content)) {
+    const texts = result.content
+      .filter((c: any) => c.type === 'text' && c.text)
+      .map((c: any) => c.text);
+    return truncate(texts.join('\n'));
+  }
+  if (typeof result === 'string') return truncate(result);
+  try { return truncate(JSON.stringify(result)); } catch { return ''; }
+}
+
+// ────────────────────────────────────────────────────
+// Client-side: patch Client.callTool
+// ────────────────────────────────────────────────────
+
+export function patchMcpClient(mcpModule: any, debug: boolean): void {
+  if (!mcpModule || mcpModule.__trickle_mcp_patched) return;
+  mcpModule.__trickle_mcp_patched = true;
+
+  // @modelcontextprotocol/sdk exports Client class
+  const ClientClass = mcpModule.Client;
+  if (!ClientClass) {
+    if (debug) console.log('[trickle/mcp] Client class not found in module');
+    return;
+  }
+
+  // Patch callTool on the prototype
+  const proto = ClientClass.prototype;
+  if (proto.callTool && !proto.callTool.__trickle_patched) {
+    const origCallTool = proto.callTool;
+    proto.callTool = async function patchedCallTool(this: any, ...args: any[]) {
+      const params = args[0] || {};
+      const toolName = typeof params === 'string' ? params : (params.name || 'unknown');
+      const toolArgs = typeof params === 'string' ? args[1] : (params.arguments || params.args);
+      const startTime = performance.now();
+
+      try {
+        const result = await origCallTool.apply(this, args);
+        const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+        writeMcpEvent({
+          kind: 'mcp_tool_call', tool: toolName, direction: 'outgoing',
+          durationMs, args: sanitizeArgs(toolArgs),
+          resultPreview: extractResultPreview(result),
+          isError: result?.isError || false,
+          errorMessage: result?.isError ? extractResultPreview(result) : undefined,
+          timestamp: Date.now(),
+        });
+        if (debug) console.log(`[trickle/mcp] callTool: ${toolName} (${durationMs}ms)`);
+        return result;
+      } catch (err: any) {
+        const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+        writeMcpEvent({
+          kind: 'mcp_tool_call', tool: toolName, direction: 'outgoing',
+          durationMs, args: sanitizeArgs(toolArgs),
+          resultPreview: '', isError: true,
+          errorMessage: truncate(err?.message || String(err), 200),
+          timestamp: Date.now(),
+        });
+        throw err;
+      }
+    };
+    proto.callTool.__trickle_patched = true;
+    if (debug) console.log('[trickle/mcp] Patched Client.callTool');
+  }
+
+  // Also patch listTools for discovery
+  if (proto.listTools && !proto.listTools.__trickle_patched) {
+    const origListTools = proto.listTools;
+    proto.listTools = async function patchedListTools(this: any, ...args: any[]) {
+      const startTime = performance.now();
+      const result = await origListTools.apply(this, args);
+      const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+      const toolCount = result?.tools?.length || 0;
+      writeMcpEvent({
+        kind: 'mcp_tool_call', tool: '__list_tools', direction: 'outgoing',
+        durationMs, args: null,
+        resultPreview: `${toolCount} tools available`,
+        isError: false, timestamp: Date.now(),
+      });
+      return result;
+    };
+    proto.listTools.__trickle_patched = true;
+  }
+}
+
+// ────────────────────────────────────────────────────
+// Server-side: patch Server to wrap tool handlers
+// ────────────────────────────────────────────────────
+
+export function patchMcpServer(mcpModule: any, debug: boolean): void {
+  // Server is exported from @modelcontextprotocol/sdk
+  const ServerClass = mcpModule.Server || mcpModule.McpServer;
+  if (!ServerClass || ServerClass.__trickle_mcp_server_patched) return;
+  ServerClass.__trickle_mcp_server_patched = true;
+
+  const proto = ServerClass.prototype;
+
+  // Patch the .tool() registration method to wrap handlers
+  if (proto.tool && !proto.tool.__trickle_patched) {
+    const origTool = proto.tool;
+    proto.tool = function patchedTool(this: any, ...args: any[]) {
+      // tool(name, schema, handler) or tool(name, handler)
+      const toolName = typeof args[0] === 'string' ? args[0] : 'unknown';
+      const lastArg = args[args.length - 1];
+
+      if (typeof lastArg === 'function') {
+        const originalHandler = lastArg;
+        args[args.length - 1] = async function wrappedHandler(...handlerArgs: any[]) {
+          const startTime = performance.now();
+          try {
+            const result = await originalHandler.apply(this, handlerArgs);
+            const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+            writeMcpEvent({
+              kind: 'mcp_tool_call', tool: toolName, direction: 'incoming',
+              durationMs, args: sanitizeArgs(handlerArgs[0]),
+              resultPreview: extractResultPreview(result),
+              isError: result?.isError || false,
+              timestamp: Date.now(),
+            });
+            if (debug) console.log(`[trickle/mcp] tool handler: ${toolName} (${durationMs}ms)`);
+            return result;
+          } catch (err: any) {
+            const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+            writeMcpEvent({
+              kind: 'mcp_tool_call', tool: toolName, direction: 'incoming',
+              durationMs, args: sanitizeArgs(handlerArgs[0]),
+              resultPreview: '', isError: true,
+              errorMessage: truncate(err?.message || String(err), 200),
+              timestamp: Date.now(),
+            });
+            throw err;
+          }
+        };
+      }
+
+      return origTool.apply(this, args);
+    };
+    proto.tool.__trickle_patched = true;
+    if (debug) console.log('[trickle/mcp] Patched Server.tool');
+  }
+
+  // Patch setRequestHandler for lower-level interception
+  if (proto.setRequestHandler && !proto.setRequestHandler.__trickle_patched) {
+    const origSetHandler = proto.setRequestHandler;
+    proto.setRequestHandler = function patchedSetHandler(this: any, schema: any, handler: any) {
+      if (typeof handler === 'function') {
+        const origHandler = handler;
+        const capturedHandler = origHandler;
+        handler = async function wrappedHandler(this: any, ...args: any[]) {
+          const request = args[0];
+          const method = request?.method || schema?.method || 'unknown';
+          if (method === 'tools/call') {
+            const startTime = performance.now();
+            try {
+              const result = await capturedHandler.apply(this, args);
+              const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+              writeMcpEvent({
+                kind: 'mcp_tool_call', tool: request?.params?.name || 'unknown',
+                direction: 'incoming', durationMs,
+                args: sanitizeArgs(request?.params?.arguments),
+                resultPreview: extractResultPreview(result),
+                isError: result?.isError || false,
+                timestamp: Date.now(),
+              });
+              return result;
+            } catch (err: any) {
+              const durationMs = Math.round((performance.now() - startTime) * 100) / 100;
+              writeMcpEvent({
+                kind: 'mcp_tool_call', tool: request?.params?.name || 'unknown',
+                direction: 'incoming', durationMs,
+                args: sanitizeArgs(request?.params?.arguments),
+                resultPreview: '', isError: true,
+                errorMessage: truncate(err?.message || String(err), 200),
+                timestamp: Date.now(),
+              });
+              throw err;
+            }
+          }
+          return capturedHandler.apply(this, args);
+        };
+      }
+      return origSetHandler.call(this, schema, handler);
+    };
+    proto.setRequestHandler.__trickle_patched = true;
+  }
+}
+
+// ────────────────────────────────────────────────────
+// Initialization
+// ────────────────────────────────────────────────────
+
+export function initMcpObserver(): void {
+  const dir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  mcpFile = path.join(dir, 'mcp.jsonl');
+  try { fs.writeFileSync(mcpFile, ''); } catch {}
+  eventCount = 0;
+}

package/src/observe-register.ts

@@ -39,6 +39,7 @@ import { instrumentExpress, trickleMiddleware } from './express';
 import { initVarTracer, traceVar } from './trace-var';
 import { initCallTrace } from './call-trace';
 import { initLlmObserver } from './llm-observer';
+import { initMcpObserver } from './mcp-observer';
 import {
   findReassignments,
   findForLoopVars,
@@ -1231,6 +1232,9 @@ if (enabled) {
   // ── Hook 0b3: Initialize LLM observer ──
   initLlmObserver();
 
+  // ── Hook 0b4: Initialize MCP observer ──
+  initMcpObserver();
+
   // ── Hook 0c: Capture environment snapshot ──
   try {
     const envDir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
@@ -1537,6 +1541,32 @@ if (enabled) {
       } catch { /* not critical */ }
     }
 
+    // MCP SDK (client + server) — match any subpath import
+    if (request.includes('@modelcontextprotocol/sdk') && !expressPatched.has('mcp-client') && exports.Client) {
+      expressPatched.add('mcp-client');
+      try {
+        const { patchMcpClient } = require(path.join(__dirname, 'mcp-observer.js'));
+        patchMcpClient(exports, debug);
+      } catch { /* not critical */ }
+    }
+    if (request.includes('@modelcontextprotocol/sdk') && !expressPatched.has('mcp-server') && (exports.Server || exports.McpServer)) {
+      expressPatched.add('mcp-server');
+      try {
+        const { patchMcpServer } = require(path.join(__dirname, 'mcp-observer.js'));
+        patchMcpServer(exports, debug);
+      } catch { /* not critical */ }
+    }
+
+    // Claude Agent SDK
+    if (request.includes('claude-agent-sdk') && !expressPatched.has('claude-agent-sdk')) {
+      expressPatched.add('claude-agent-sdk');
+      try {
+        // The Claude Agent SDK uses hooks config — we can't easily patch
+        // from Module._load since it's ESM-only. Log detection for now.
+        if (debug) console.log('[trickle] Claude Agent SDK detected — use hooks for tracing');
+      } catch { /* not critical */ }
+    }
+
     // Google Gemini SDK
     if (request === '@google/genai' && !expressPatched.has('@google/genai')) {
       expressPatched.add('@google/genai');