fix: Segment requires either userId OR anonymousId, but not both When userId is available, use it; otherwise use anonymousId

Author: jirispilka

src/mcp/server.ts

@@ -2,8 +2,6 @@
  * Model Context Protocol (MCP) server for Apify Actors
  */
 
-import * as crypto from 'node:crypto';
-
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
@@ -761,13 +759,13 @@ Please verify the tool name and ensure the tool is properly registered.`;
      * Calculates execution time, sets final status, and sends the telemetry event.
      *
      * @param telemetryData - Telemetry data to finalize and track (null if telemetry is disabled)
-     * @param userId - Apify user ID
+     * @param userId - Apify user ID (string or null if not available)
      * @param startTime - Timestamp when the tool call started
      * @param toolStatus - Final status of the tool call ('succeeded', 'failed', or 'aborted')
      */
     private finalizeAndTrackTelemetry(
         telemetryData: ToolCallTelemetryProperties | null,
-        userId: string,
+        userId: string | null,
         startTime: number,
         toolStatus: 'succeeded' | 'failed' | 'aborted',
     ): void {
@@ -789,9 +787,9 @@ Please verify the tool name and ensure the tool is properly registered.`;
     */
     private async prepareTelemetryData(
         tool: HelperTool | ActorTool | ActorMcpTool, mcpSessionId: string | undefined, apifyToken: string,
-    ): Promise<{ telemetryData: ToolCallTelemetryProperties | null; userId: string }> {
+    ): Promise<{ telemetryData: ToolCallTelemetryProperties | null; userId: string | null }> {
         if (this.options.telemetry?.enabled !== true) {
-            return { telemetryData: null, userId: crypto.randomUUID() };
+            return { telemetryData: null, userId: null };
         }
 
         const toolFullName = tool.type === 'actor' ? tool.actorFullName : tool.name;
@@ -813,11 +811,6 @@ Please verify the tool name and ensure the tool is properly registered.`;
             userId = await getUserIdFromTokenCached(apifyToken, apifyClient);
             log.debug('Telemetry: fetched userId', { userId });
         }
-        if (!userId) {
-            userId = crypto.randomUUID();
-            log.debug('Telemetry: using random userId', { userId });
-        }
-
         const capabilities = this.options.initializeRequestData?.params?.capabilities;
         const params = this.options.initializeRequestData?.params as InitializeRequest['params'];
         const telemetryData: ToolCallTelemetryProperties = {

src/telemetry.ts

@@ -1,3 +1,5 @@
+import * as crypto from 'node:crypto';
+
 import { Analytics } from '@segment/analytics-node';
 
 import log from '@apify/log';
@@ -57,12 +59,14 @@ export function getOrInitAnalyticsClient(): Analytics | null {
 
 /**
  * Tracks a tool call event to Segment.
+ * Segment requires either userId OR anonymousId, but not both
+ * When userId is available, use it; otherwise use anonymousId
  *
  * @param userId - Apify user ID (null if not available)
  * @param properties - Event properties for the tool call
  */
 export function trackToolCall(
-    userId: string,
+    userId: string | null,
     properties: ToolCallTelemetryProperties,
 ): void {
     const client = getOrInitAnalyticsClient();
@@ -73,7 +77,7 @@ export function trackToolCall(
 
     try {
         client.track({
-            userId,
+            ...(userId ? { userId } : { anonymousId: crypto.randomUUID() }),
             event: SEGMENT_EVENTS.TOOL_CALL,
             properties,
         });

tests/unit/telemetry.test.ts

@@ -15,7 +15,7 @@ describe('telemetry', () => {
         vi.clearAllMocks();
     });
 
-    it('should send correct payload structure to Segment', () => {
+    it('should send correct payload structure to Segment with userId', () => {
         const userId = 'test-user-123';
         const properties = {
             app: 'mcp' as const,
@@ -53,4 +53,35 @@ describe('telemetry', () => {
             },
         });
     });
+
+    it('should use anonymousId when userId is null', () => {
+        const properties = {
+            app: 'mcp' as const,
+            app_version: '0.5.6',
+            mcp_client_name: 'test-client',
+            mcp_client_version: '1.0.0',
+            mcp_protocol_version: '2024-11-05',
+            mcp_client_capabilities: '{}',
+            mcp_session_id: 'session-123',
+            transport_type: 'stdio',
+            tool_name: 'test-tool',
+            tool_status: 'succeeded' as const,
+            tool_exec_time_ms: 100,
+            tool_call_number: 1,
+        };
+
+        trackToolCall(null, properties);
+
+        expect(mockTrack).toHaveBeenCalledTimes(1);
+        const callArgs = mockTrack.mock.calls[0][0];
+
+        // Should have anonymousId but not userId
+        expect(callArgs).toHaveProperty('anonymousId');
+        expect(callArgs.anonymousId).toBeDefined();
+        expect(typeof callArgs.anonymousId).toBe('string');
+        expect(callArgs.anonymousId.length).toBeGreaterThan(0);
+        expect(callArgs).not.toHaveProperty('userId');
+        expect(callArgs.event).toBe('MCP Tool Call');
+        expect(callArgs.properties).toEqual(properties);
+    });
 });