feat: segment telemetry (apify#329)

* feat: implement segment telemetry

---------

Co-authored-by: Jiří Spilka <[email protected]>
Co-authored-by: Tomas Katz <[email protected]>
Co-authored-by: Jiří Moravčík <[email protected]>

Author: 4 people

README.md

@@ -34,6 +34,7 @@ The Apify Model Context Protocol (MCP) server at [**mcp.apify.com**](https://mcp
 - [🤖 MCP clients and examples](#-mcp-clients-and-examples)
 - [🪄 Try Apify MCP instantly](#-try-apify-mcp-instantly)
 - [🛠️ Tools, resources, and prompts](#-tools-resources-and-prompts)
+- [📊 Telemetry](#telemetry)
 - [🐛 Troubleshooting (local MCP server)](#-troubleshooting-local-mcp-server)
 - [⚙️ Development](#-development)
 - [🤝 Contributing](#-contributing)
@@ -266,13 +267,32 @@ The server provides a set of predefined example prompts to help you get started
 
 The server does not yet provide any resources.
 
-### Debugging the NPM package
+## 📡 Telemetry
 
-To debug the server, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) tool:
+The Apify MCP Server collects telemetry data about tool calls to help Apify understand usage patterns and improve the service.
+By default, telemetry is **enabled** for all tool calls.
 
-```shell
-export APIFY_TOKEN="your-apify-token"
-npx @modelcontextprotocol/inspector npx -y @apify/actors-mcp-server
+### Opting out of telemetry
+
+You can opt out of telemetry by setting the `--telemetry-enabled` CLI flag to `false` or the `TELEMETRY_ENABLED` environment variable to `false`.
+CLI flags take precedence over environment variables.
+
+#### Examples
+
+**For the remote server (mcp.apify.com)**:
+```text
+# Disable via URL parameter
+https://mcp.apify.com?telemetry-enabled=false
+```
+
+**For the local stdio server**:
+```bash
+# Disable via CLI flag
+npx @apify/actors-mcp-server --telemetry-enabled=false
+
+# Or set environment variable
+export TELEMETRY_ENABLED=false
+npx @apify/actors-mcp-server
 ```
 
 # ⚙️ Development
@@ -333,6 +353,15 @@ The Apify MCP Server is also available on [Docker Hub](https://hub.docker.com/mc
 - Make sure the `APIFY_TOKEN` environment variable is set.
 - Always use the latest version of the MCP server by using `@apify/actors-mcp-server@latest`.
 
+### Debugging the NPM package
+
+To debug the server, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) tool:
+
+```shell
+export APIFY_TOKEN="your-apify-token"
+npx @modelcontextprotocol/inspector npx -y @apify/actors-mcp-server
+```
+
 ## 💡 Limitations
 
 The Actor input schema is processed to be compatible with most MCP clients while adhering to [JSON Schema](https://json-schema.org/) standards. The processing includes:

package-lock.json

@@ -20,6 +20,7 @@
   "files": [
     "dist",
     "LICENSE",
+    "package.json",
     "server.json",
     "manifest.json"
   ],
@@ -42,6 +43,7 @@
     "@apify/datastructures": "^2.0.3",
     "@apify/log": "^2.5.16",
     "@modelcontextprotocol/sdk": "^1.18.1",
+    "@segment/analytics-node": "^2.3.0",
     "@types/cheerio": "^0.22.35",
     "@types/turndown": "^5.0.5",
     "ajv": "^8.17.1",

package.json

@@ -14,6 +14,7 @@ import log from '@apify/log';
 
 import { ApifyClient } from '../apify-client.js';
 import { ActorsMcpServer } from '../mcp/server.js';
+import { parseBooleanFromString } from '../utils/generic.js';
 import { getHelpMessage, HEADER_READINESS_PROBE, Routes, TransportType } from './const.js';
 import { getActorRunData } from './utils.js';
 
@@ -78,7 +79,21 @@ export function createExpressApp(
                 rt: Routes.SSE,
                 tr: TransportType.SSE,
             });
-            const mcpServer = new ActorsMcpServer({ setupSigintHandler: false });
+            // Extract telemetry query parameters
+            const urlParams = new URL(req.url, `http://${req.headers.host}`).searchParams;
+            const telemetryEnabledParam = urlParams.get('telemetry-enabled');
+            // URL param > env var > default (true)
+            const telemetryEnabled = parseBooleanFromString(telemetryEnabledParam)
+                ?? parseBooleanFromString(process.env.TELEMETRY_ENABLED)
+                ?? true;
+
+            const mcpServer = new ActorsMcpServer({
+                setupSigintHandler: false,
+                transportType: 'sse',
+                telemetry: {
+                    enabled: telemetryEnabled,
+                },
+            });
             const transport = new SSEServerTransport(Routes.MESSAGE, res);
 
             // Load MCP server tools
@@ -157,12 +172,27 @@ export function createExpressApp(
             // Reuse existing transport
                 transport = transports[sessionId];
             } else if (!sessionId && isInitializeRequest(req.body)) {
-            // New initialization request - use JSON response mode
+            // New initialization request
                 transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: () => randomUUID(),
                     enableJsonResponse: false, // Use SSE response mode
                 });
-                const mcpServer = new ActorsMcpServer({ setupSigintHandler: false, initializeRequestData: req.body as InitializeRequest });
+                // Extract telemetry query parameters
+                const urlParams = new URL(req.url, `http://${req.headers.host}`).searchParams;
+                const telemetryEnabledParam = urlParams.get('telemetry-enabled');
+                // URL param > env var > default (true)
+                const telemetryEnabled = parseBooleanFromString(telemetryEnabledParam)
+                    ?? parseBooleanFromString(process.env.TELEMETRY_ENABLED)
+                    ?? true;
+
+                const mcpServer = new ActorsMcpServer({
+                    setupSigintHandler: false,
+                    initializeRequestData: req.body as InitializeRequest,
+                    transportType: 'http',
+                    telemetry: {
+                        enabled: telemetryEnabled,
+                    },
+                });
 
                 // Load MCP server tools
                 const apifyToken = process.env.APIFY_TOKEN as string;

src/actor/server.ts

@@ -76,6 +76,8 @@ export const GET_HTML_SKELETON_CACHE_TTL_SECS = 5 * 60; // 5 minutes
 export const GET_HTML_SKELETON_CACHE_MAX_SIZE = 200;
 export const MCP_SERVER_CACHE_MAX_SIZE = 500;
 export const MCP_SERVER_CACHE_TTL_SECS = 30 * 60; // 30 minutes
+export const USER_CACHE_MAX_SIZE = 200;
+export const USER_CACHE_TTL_SECS = 60 * 60; // 1 hour
 
 export const ACTOR_PRICING_MODEL = {
     /** Rental Actors */
@@ -104,3 +106,21 @@ export const ALGOLIA = {
 export const PROGRESS_NOTIFICATION_INTERVAL_MS = 5_000; // 5 seconds
 
 export const APIFY_STORE_URL = 'https://apify.com';
+
+// Telemetry
+export const TELEMETRY_ENV = {
+    DEV: 'DEV',
+    PROD: 'PROD',
+} as const;
+export type TelemetryEnv = (typeof TELEMETRY_ENV)[keyof typeof TELEMETRY_ENV];
+
+export const DEFAULT_TELEMETRY_ENABLED = true;
+export const DEFAULT_TELEMETRY_ENV: TelemetryEnv = TELEMETRY_ENV.PROD;
+
+// We are using the same values as apify-core for consistency (despite that we ship events of different types).
+// https://github.com/apify/apify-core/blob/2284766c122c6ac5bc4f27ec28051f4057d6f9c0/src/packages/analytics/src/server/segment.ts#L28
+// Reasoning from the apify-core:
+// Flush at 50 events to avoid sending too many small requests (default is 15)
+export const SEGMENT_FLUSH_AT_EVENTS = 50;
+// Flush interval in milliseconds (default is 10000)
+export const SEGMENT_FLUSH_INTERVAL_MS = 5_000;