feat: add telemetry exporters for observability (#2)

* feat: add telemetry exporters for observability

- Add TelemetryManager to coordinate multiple exporters
- Implement OTLP exporter for OpenTelemetry compatibility
- Implement Datadog exporter with StatsD metrics and APM tracing
- Implement Sentry exporter for error tracking and performance monitoring
- Support telemetry-only mode with null projectId
- Enable dual mode to send events to both MCPCat and telemetry exporters
- Update eventQueue to support telemetry manager integration

Author: kashishhora

README.md

@@ -58,10 +58,10 @@ import * as mcpcat from "mcpcat";
 
 const mcpServer = new Server({ name: "echo-mcp", version: "0.1.0" });
 
-// Register tools
-
-// NOTE: track() must be called *after* tools are setup
+// Track the server with MCPCat
 mcpcat.track(mcpServer, "proj_0000000");
+
+// Register your tools
 ```
 
 ### Identifying users

package.json

@@ -72,6 +72,7 @@
     "@modelcontextprotocol/sdk": ">=1.3.1"
   },
   "dependencies": {
+    "@opentelemetry/otlp-transformer": "^0.203.0",
     "mcpcat-api": "0.1.3",
     "redact-pii": "3.4.0",
     "zod": "3.25.30"

pnpm-lock.yaml

@@ -18,25 +18,28 @@ import { setupToolCallTracing } from "./modules/tracing.js";
 import { getSessionInfo, newSessionId } from "./modules/session.js";
 import { setServerTrackingData } from "./modules/internal.js";
 import { setupTracking } from "./modules/tracingV2.js";
+import { TelemetryManager } from "./modules/telemetry.js";
+import { setTelemetryManager } from "./modules/eventQueue.js";
 
 /**
  * Integrates MCPCat analytics into an MCP server to track tool usage patterns and user interactions.
  *
  * @param server - The MCP server instance to track. Must be a compatible MCP server implementation.
- * @param projectId - Your MCPCat project ID obtained from mcpcat.io when creating an account.
+ * @param projectId - Your MCPCat project ID obtained from mcpcat.io when creating an account. Pass null for telemetry-only mode.
  * @param options - Optional configuration to customize tracking behavior.
  * @param options.enableReportMissing - Adds a "get_more_tools" tool that allows LLMs to automatically report missing functionality.
  * @param options.enableTracing - Enables tracking of tool calls and usage patterns.
  * @param options.enableToolCallContext - Injects a "context" parameter to existing tools to capture user intent.
  * @param options.identify - Async function to identify users and attach custom data to their sessions.
  * @param options.redactSensitiveInformation - Function to redact sensitive data before sending to MCPCat.
+ * @param options.exporters - Configure telemetry exporters to send events to external systems. Available exporters:
+ *   - `otlp`: OpenTelemetry Protocol exporter (see {@link ../modules/exporters/otlp.OTLPExporter})
+ *   - `datadog`: Datadog APM exporter (see {@link ../modules/exporters/datadog.DatadogExporter})
+ *   - `sentry`: Sentry Monitoring exporter (see {@link ../modules/exporters/sentry.SentryExporter})
  *
  * @returns The tracked server instance.
  *
  * @remarks
- * **IMPORTANT**: The `track()` function must be called AFTER all tools have been registered on the server.
- * Calling it before tool registration will result in those tools not being tracked.
- *
  * Analytics data and debug information are logged to `~/mcpcat.log` since console logs interfere
  * with STDIO-based MCP servers.
  *
@@ -48,13 +51,13 @@ import { setupTracking } from "./modules/tracingV2.js";
  *
  * const mcpServer = new Server({ name: "my-mcp-server", version: "1.0.0" });
  *
- * // Register your tools first
+ * // Track the server with MCPCat
+ * mcpcat.track(mcpServer, "proj_abc123xyz");
+ *
+ * // Register your tools
  * mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
  *   tools: [{ name: "my_tool", description: "Does something useful" }]
  * }));
- *
- * // Then call track() after all tools are registered
- * mcpcat.track(mcpServer, "proj_abc123xyz");
  * ```
  *
  * @example
@@ -80,23 +83,68 @@ import { setupTracking } from "./modules/tracingV2.js";
  *   }
  * });
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Telemetry-only mode (no MCPCat account required)
+ * mcpcat.track(mcpServer, null, {
+ *   exporters: {
+ *     otlp: {
+ *       type: "otlp",
+ *       endpoint: "http://localhost:4318/v1/traces"
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Dual mode - send to both MCPCat and telemetry exporters
+ * mcpcat.track(mcpServer, "proj_abc123xyz", {
+ *   exporters: {
+ *     datadog: {
+ *       type: "datadog",
+ *       apiKey: process.env.DD_API_KEY,
+ *       site: "datadoghq.com"
+ *     }
+ *   }
+ * });
+ * ```
  */
 function track(
   server: any,
-  projectId: string,
+  projectId: string | null,
   options: MCPCatOptions = {},
 ): any {
   try {
     const validatedServer = isCompatibleServerType(server);
+
     // For high-level servers, we need to pass the underlying server to some functions
     const lowLevelServer = (
       isHighLevelServer(validatedServer)
         ? (validatedServer as any).server
         : validatedServer
     ) as MCPServerLike;
+
+    // Initialize telemetry if exporters are configured
+    if (options.exporters) {
+      const telemetryManager = new TelemetryManager(options.exporters);
+      setTelemetryManager(telemetryManager);
+      writeToLog(
+        `Initialized telemetry with ${Object.keys(options.exporters).length} exporters`,
+      );
+    }
+
+    // If projectId is null and no exporters, warn the user
+    if (!projectId && !options.exporters) {
+      writeToLog(
+        "Warning: No projectId provided and no exporters configured. Events will not be sent anywhere.",
+      );
+    }
+
     const sessionInfo = getSessionInfo(lowLevelServer, undefined);
     const mcpcatData: MCPCatData = {
-      projectId,
+      projectId: projectId || "", // Use empty string for null projectId
       sessionId: newSessionId(),
       lastActivity: new Date(),
       identifiedSessions: new Map<string, UserIdentity>(),
@@ -140,7 +188,13 @@ function track(
   }
 }
 
-export type { MCPCatOptions, UserIdentity, RedactFunction } from "./types.js";
+export type {
+  MCPCatOptions,
+  UserIdentity,
+  RedactFunction,
+  ExporterConfig,
+  Exporter,
+} from "./types.js";
 
 export type IdentifyFunction = MCPCatOptions["identify"];