Add privacy-safe telemetry to the CLI (#1951)

Author: chelojimenez

cli/README.md

@@ -28,6 +28,7 @@ Options:
   --timeout <ms>     Request timeout in milliseconds (default: 30000)
   --rpc              Include RPC logs in JSON output
   --quiet            Suppress non-result progress output
+  --no-telemetry     Disable anonymous usage telemetry
   --format <format>  Output format
   -h, --help         display help for command
 
@@ -40,6 +41,7 @@ Commands:
   oauth              Run MCP OAuth login, proxy, and conformance flows
   protocol           MCP protocol inspection and conformance checks
   inspector          Start or attach to the local MCPJam Inspector
+  telemetry          Inspect and configure anonymous CLI telemetry
 ```
 
 ## Quick start
@@ -161,6 +163,29 @@ echo '{"query":"setup guide"}' | mcpjam tools call --url $URL --access-token $TO
 
 Use `--format json|human` for the raw command result. Use `--reporter json-summary|junit-xml` on conformance and diff commands when CI needs a report artifact. `server validate` uses `--debug-out` for validation artifacts.
 
+## Telemetry
+
+`mcpjam` collects anonymous command-level telemetry so we can understand CLI usage and reliability. Events include the command/subcommand name, success/failure, exit code, duration, CLI version, Node version, OS, CPU architecture, transport type (`http` or `stdio`), `platform: "cli"`, and coarse CI metadata (`is_ci` and a provider enum such as `github_actions`).
+
+Telemetry is enabled by default. The first command invocation that is not opted out writes `telemetry.json` with `enabled: true` and a random install UUID.
+
+Telemetry uses a random install UUID stored at the same platform cache location as update checks, in `telemetry.json`. It does not collect raw argv, URLs, hostnames, ports, tokens, headers, environment values, working directories, file paths, tool/resource/prompt names, error messages, stack traces, repository names, branch names, workflow names, or CI job ids.
+
+Disable telemetry for one invocation with `--no-telemetry`, or persistently with:
+
+```bash
+mcpjam telemetry disable
+```
+
+Check or re-enable it with:
+
+```bash
+mcpjam telemetry status
+mcpjam telemetry enable
+```
+
+Set `DO_NOT_TRACK=1` or `MCPJAM_TELEMETRY_DISABLED=1` to disable telemetry through the environment. Set `MCPJAM_TELEMETRY_DEBUG=1` to print the sanitized telemetry payload to stderr instead of sending it.
+
 ## GitHub Actions
 
 ```yaml

cli/package.json

@@ -17,7 +17,8 @@
   },
   "dependencies": {
     "@mcpjam/sdk": "^1.0.0",
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "posthog-node": "^5.24.10"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

cli/src/commands/telemetry.ts

@@ -0,0 +1,83 @@
+import { Command } from "commander";
+import { writeResult, type OutputFormat } from "../lib/output.js";
+import { getGlobalOptions } from "../lib/server-config.js";
+import {
+  formatTelemetryStatusHuman,
+  getTelemetryStatus,
+  setTelemetryEnabled,
+  type TelemetryOptions,
+} from "../lib/telemetry.js";
+
+interface TelemetryCommandOptions {
+  telemetry?: boolean;
+}
+
+export function registerTelemetryCommands(
+  program: Command,
+  telemetryOptions: TelemetryOptions = {},
+): void {
+  const telemetry = program
+    .command("telemetry")
+    .description("Inspect and configure anonymous CLI telemetry");
+
+  telemetry
+    .command("status")
+    .description("Show the current telemetry status")
+    .action((_options, command) => {
+      writeTelemetryStatus(
+        resolveTelemetryStatus(command, telemetryOptions),
+        getGlobalOptions(command).format,
+      );
+    });
+
+  telemetry
+    .command("disable")
+    .description("Disable anonymous CLI telemetry")
+    .action((_options, command) => {
+      setTelemetryEnabled(false, telemetryOptions);
+      writeTelemetryStatus(
+        resolveTelemetryStatus(command, telemetryOptions),
+        getGlobalOptions(command).format,
+      );
+    });
+
+  telemetry
+    .command("enable")
+    .description("Enable anonymous CLI telemetry")
+    .action((_options, command) => {
+      setTelemetryEnabled(true, telemetryOptions);
+      writeTelemetryStatus(
+        resolveTelemetryStatus(command, telemetryOptions),
+        getGlobalOptions(command).format,
+      );
+    });
+}
+
+function resolveTelemetryStatus(
+  command: Command,
+  telemetryOptions: TelemetryOptions,
+) {
+  const options = command.optsWithGlobals() as TelemetryCommandOptions;
+  return getTelemetryStatus({
+    ...telemetryOptions,
+    commandOptOut: options.telemetry === false,
+  });
+}
+
+function writeTelemetryStatus(
+  status: ReturnType<typeof getTelemetryStatus>,
+  format: OutputFormat,
+): void {
+  if (format === "human") {
+    process.stdout.write(formatTelemetryStatusHuman(status));
+    return;
+  }
+
+  writeResult(
+    {
+      success: true,
+      telemetry: status,
+    },
+    format,
+  );
+}

cli/src/index.ts

@@ -8,6 +8,7 @@ import { registerOAuthCommands } from "./commands/oauth.js";
 import { registerPromptCommands } from "./commands/prompts.js";
 import { registerResourcesCommands } from "./commands/resources.js";
 import { registerServerCommands } from "./commands/server.js";
+import { registerTelemetryCommands } from "./commands/telemetry.js";
 import { registerToolsCommands } from "./commands/tools.js";
 import { registerInspectorCommands } from "./commands/inspector.js";
 import {
@@ -17,6 +18,11 @@ import {
   writeError,
 } from "./lib/output.js";
 import { addGlobalOptions } from "./lib/server-config.js";
+import {
+  captureCommandEvent,
+  initTelemetry,
+  type TelemetryOptions,
+} from "./lib/telemetry.js";
 import { checkForUpdates } from "./lib/update-notifier.js";
 
 const pkgVersion = packageJson.version;
@@ -26,12 +32,17 @@ export interface CliMainResult {
   shouldCheckForUpdates: boolean;
 }
 
-export interface CliEntrypointDependencies {
+export interface CliMainDependencies {
+  telemetry?: TelemetryOptions;
+}
+
+export interface CliEntrypointDependencies extends CliMainDependencies {
   checkForUpdates?: (currentVersion: string) => void;
 }
 
 export async function main(
   argv: readonly string[] = process.argv,
+  dependencies: CliMainDependencies = {},
 ): Promise<CliMainResult> {
   const program = addGlobalOptions(
     new Command()
@@ -49,6 +60,7 @@ export async function main(
         },
       }),
   );
+  const telemetry = initTelemetry(program, pkgVersion, dependencies.telemetry);
 
   registerServerCommands(program);
   registerToolsCommands(program);
@@ -58,6 +70,7 @@ export async function main(
   registerOAuthCommands(program);
   registerProtocolCommands(program);
   registerInspectorCommands(program);
+  registerTelemetryCommands(program, dependencies.telemetry);
 
   if (argv.length <= 2) {
     program.outputHelp();
@@ -69,16 +82,15 @@ export async function main(
 
   try {
     await program.parseAsync(argv as string[]);
-    const exitCode = process.exitCode;
-    if (typeof exitCode === "number") {
-      return {
-        exitCode,
-        shouldCheckForUpdates: true,
-      };
-    }
-
+    const normalizedExitCode =
+      typeof process.exitCode === "number" ? process.exitCode : 0;
+    captureCommandEvent(
+      normalizedExitCode,
+      normalizedExitCode === 0 ? undefined : "UNKNOWN_ERROR",
+    );
+    await telemetry.flush();
     return {
-      exitCode: Number(exitCode ?? 0) || 0,
+      exitCode: normalizedExitCode,
       shouldCheckForUpdates: true,
     };
   } catch (error) {
@@ -89,13 +101,16 @@ export async function main(
         error.code === "commander.helpDisplayed" ||
         error.code === "commander.version"
       ) {
+        await telemetry.flush();
         return {
           exitCode: 0,
           shouldCheckForUpdates: false,
         };
       }
 
       writeError(usageError(error.message), format);
+      captureCommandEvent(2, "USAGE_ERROR");
+      await telemetry.flush();
       return {
         exitCode: 2,
         shouldCheckForUpdates: false,
@@ -104,6 +119,8 @@ export async function main(
 
     const normalizedError = normalizeCliError(error);
     writeError(normalizedError, format);
+    captureCommandEvent(normalizedError.exitCode, normalizedError.code);
+    await telemetry.flush();
     return {
       exitCode: normalizedError.exitCode,
       shouldCheckForUpdates: false,
@@ -115,7 +132,7 @@ export async function runCliEntrypoint(
   argv: readonly string[] = process.argv,
   dependencies: CliEntrypointDependencies = {},
 ): Promise<CliMainResult> {
-  const result = await main(argv);
+  const result = await main(argv, dependencies);
   process.exitCode = result.exitCode;
 
   if (result.exitCode === 0 && result.shouldCheckForUpdates) {

cli/src/lib/server-config.ts

@@ -16,6 +16,7 @@ export interface GlobalOptions {
   timeout: number;
   rpc: boolean;
   quiet: boolean;
+  telemetry: boolean;
 }
 
 type TransportType = "http" | "stdio";
@@ -109,6 +110,7 @@ export function getGlobalOptions(command: Command): GlobalOptions {
     timeout: options.timeout ?? 30_000,
     rpc: options.rpc ?? false,
     quiet: options.quiet ?? false,
+    telemetry: options.telemetry ?? true,
   };
 }
 
@@ -370,6 +372,7 @@ export function addGlobalOptions(program: Command): Command {
     )
     .option("--rpc", "Include RPC logs in JSON output")
     .option("--quiet", "Suppress non-result progress output")
+    .option("--no-telemetry", "Disable anonymous usage telemetry")
     .option("--format <format>", "Output format");
 }