@himanshusinghs/mongodb-mcp-server 1.8.0 → 1.11.0-prerelease.3

package/dist/esm/setup/setupTelemetry.d.ts

@@ -0,0 +1,99 @@
+import type { Keychain } from "../common/keychain.js";
+import { DeviceId } from "../helpers/deviceId.js";
+import { Telemetry } from "../telemetry/telemetry.js";
+import type { SkillsInstallOutcome } from "./installSkills.js";
+import type { SetupEventProperties, TelemetryBoolSet, TelemetryResult } from "../telemetry/types.js";
+/**
+ * Context accumulated as the user progresses through the setup wizard. Each
+ * step adds to it, and every emitted event carries the full context so each
+ * event is independently queryable downstream.
+ */
+export type SetupTelemetryContext = Omit<SetupEventProperties, "stage" | "setup_session_id" | "last_step" | "error_type" | "total_duration_ms">;
+export declare const toBoolSet: (value: boolean | undefined) => TelemetryBoolSet | undefined;
+/**
+ * Per-run helper that owns the setup telemetry session: assigns the
+ * `setup_session_id`, tracks wall-clock durations, and
+ * accumulates context so every event carries the full set of known flags.
+ *
+ * One instance is constructed per `runSetup` invocation. Callers emit typed
+ * events at each logical step and call {@link flush} before the process
+ * exits so buffered events are best-effort sent.
+ */
+export declare class SetupTelemetry {
+    private readonly telemetry;
+    private readonly deviceId;
+    private readonly setupSessionId;
+    private readonly startedAt;
+    private stepStartedAt;
+    private lastStep;
+    private context;
+    /**
+     * Builds a fully-wired {@link SetupTelemetry} for the setup CLI: a silent
+     * logger (so telemetry's internal logging doesn't leak into the
+     * interactive wizard), a fresh {@link DeviceId}, an unauthenticated
+     * {@link ApiClient}, and a {@link Telemetry} instance.
+     */
+    static create(config: {
+        apiBaseUrl: string;
+        telemetry: "enabled" | "disabled";
+    }, keychain: Keychain): SetupTelemetry;
+    /**
+     * Direct construction is primarily for tests that want to inject a mock
+     * telemetry pipeline. Production code should use {@link SetupTelemetry.create}.
+     */
+    constructor(telemetry: Telemetry, deviceId: DeviceId);
+    /**
+     * Merges new context values into the accumulated context. Subsequent
+     * events will automatically carry the updated values.
+     */
+    updateContext(patch: Partial<SetupTelemetryContext>): void;
+    /**
+     * Emits a single setup event. `duration_ms` is computed from the time
+     * elapsed since the previous step (or setup start), and `result`
+     * defaults to "success" — callers pass "failure" only when the step's
+     * own code path failed (e.g. writing the editor config threw).
+     */
+    private emit;
+    emitStarted(): void;
+    emitPrerequisitesChecked(props: {
+        nodeVersionOk: boolean;
+        hasDocker?: boolean;
+    }): void;
+    emitAiToolSelected(aiTool: string): void;
+    emitReadOnlySelected(isReadOnly: boolean): void;
+    emitConnectionStringEntered(props: {
+        provided: boolean;
+        tested: boolean;
+        attempts: number;
+        testResult?: TelemetryResult;
+    }): void;
+    emitServiceAccountIdEntered(provided: boolean): void;
+    emitServiceAccountSecretEntered(provided: boolean): void;
+    emitCredentialsValidated(): void;
+    emitEditorConfigured(props: {
+        usedDefaultConfigPath: boolean;
+        result: TelemetryResult;
+        error?: unknown;
+    }): void;
+    emitSkillsInstallPrompted(outcome: SkillsInstallOutcome): void;
+    emitOpenConfigPrompted(props: {
+        opened: boolean;
+        result: TelemetryResult;
+        error?: unknown;
+    }): void;
+    emitCompleted(): void;
+    /**
+     * Emits a cancellation event (e.g. the user hit Ctrl+C). The `result` is
+     * "success" because the cancellation itself was handled gracefully — the
+     * distinct `stage: "cancelled"` is what analytics use to separate
+     * abandoned runs from completed ones.
+     */
+    emitCancelled(): void;
+    emitFailed(error: unknown): void;
+    /**
+     * Best-effort flush of any buffered events before the process exits. Also
+     * closes the owned {@link DeviceId}.
+     */
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=setupTelemetry.d.ts.map

package/dist/esm/setup/setupTelemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupTelemetry.d.ts","sourceRoot":"","sources":["../../../src/setup/setupTelemetry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAGR,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EAClB,MAAM,uBAAuB,CAAC;AAE/B;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CACpC,oBAAoB,EACpB,OAAO,GAAG,kBAAkB,GAAG,WAAW,GAAG,YAAY,GAAG,mBAAmB,CAClF,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,GAAG,SAAS,KAAG,gBAAgB,GAAG,SAMzE,CAAC;AAEF;;;;;;;;GAQG;AACH,qBAAa,cAAc;IAmCnB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAnC7B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,OAAO,CAA6B;IAE5C;;;;;OAKG;WACW,MAAM,CAChB,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,SAAS,GAAG,UAAU,CAAA;KAAE,EACjE,QAAQ,EAAE,QAAQ,GACnB,cAAc;IAcjB;;;OAGG;gBAEkB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,QAAQ;IAGvC;;;OAGG;IACI,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,qBAAqB,CAAC,GAAG,IAAI;IAIjE;;;;;OAKG;IACH,OAAO,CAAC,IAAI;IA2BL,WAAW,IAAI,IAAI;IAInB,wBAAwB,CAAC,KAAK,EAAE;QAAE,aAAa,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAQtF,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAKxC,oBAAoB,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI;IAK/C,2BAA2B,CAAC,KAAK,EAAE;QACtC,QAAQ,EAAE,OAAO,CAAC;QAClB,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,eAAe,CAAC;KAChC,GAAG,IAAI;IAaD,2BAA2B,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAKpD,+BAA+B,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAKxD,wBAAwB,IAAI,IAAI;IAIhC,oBAAoB,CAAC,KAAK,EAAE;QAC/B,qBAAqB,EAAE,OAAO,CAAC;QAC/B,MAAM,EAAE,eAAe,CAAC;QACxB,KAAK,CAAC,EAAE,OAAO,CAAC;KACnB,GAAG,IAAI;IAOD,yBAAyB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAW9D,sBAAsB,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,eAAe,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAKlG,aAAa,IAAI,IAAI;IAI5B;;;;;OAKG;IACI,aAAa,IAAI,IAAI;IAOrB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAYvC;;;OAGG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAatC"}

package/dist/esm/setup/setupTelemetry.js

@@ -0,0 +1,197 @@
+import { randomUUID } from "crypto";
+import { ApiClient } from "../common/atlas/apiClient.js";
+import { NullLogger } from "../common/logging/index.js";
+import { DeviceId } from "../helpers/deviceId.js";
+import { Telemetry } from "../telemetry/telemetry.js";
+export const toBoolSet = (value) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    return value ? "true" : "false";
+};
+/**
+ * Per-run helper that owns the setup telemetry session: assigns the
+ * `setup_session_id`, tracks wall-clock durations, and
+ * accumulates context so every event carries the full set of known flags.
+ *
+ * One instance is constructed per `runSetup` invocation. Callers emit typed
+ * events at each logical step and call {@link flush} before the process
+ * exits so buffered events are best-effort sent.
+ */
+export class SetupTelemetry {
+    /**
+     * Builds a fully-wired {@link SetupTelemetry} for the setup CLI: a silent
+     * logger (so telemetry's internal logging doesn't leak into the
+     * interactive wizard), a fresh {@link DeviceId}, an unauthenticated
+     * {@link ApiClient}, and a {@link Telemetry} instance.
+     */
+    static create(config, keychain) {
+        const logger = new NullLogger();
+        const deviceId = DeviceId.create(logger);
+        const apiClient = new ApiClient({ baseUrl: config.apiBaseUrl }, logger);
+        const telemetry = Telemetry.create({
+            logger,
+            deviceId,
+            apiClient,
+            keychain,
+            enabled: config.telemetry === "enabled",
+        });
+        return new SetupTelemetry(telemetry, deviceId);
+    }
+    /**
+     * Direct construction is primarily for tests that want to inject a mock
+     * telemetry pipeline. Production code should use {@link SetupTelemetry.create}.
+     */
+    constructor(telemetry, deviceId) {
+        this.telemetry = telemetry;
+        this.deviceId = deviceId;
+        this.setupSessionId = randomUUID();
+        this.startedAt = Date.now();
+        this.stepStartedAt = this.startedAt;
+        this.context = {};
+    }
+    /**
+     * Merges new context values into the accumulated context. Subsequent
+     * events will automatically carry the updated values.
+     */
+    updateContext(patch) {
+        this.context = { ...this.context, ...patch };
+    }
+    /**
+     * Emits a single setup event. `duration_ms` is computed from the time
+     * elapsed since the previous step (or setup start), and `result`
+     * defaults to "success" — callers pass "failure" only when the step's
+     * own code path failed (e.g. writing the editor config threw).
+     */
+    emit(stage, extra = {}, result = "success") {
+        const now = Date.now();
+        const event = {
+            timestamp: new Date(now).toISOString(),
+            source: "mdbmcp",
+            properties: {
+                component: "setup",
+                category: "setup",
+                duration_ms: now - this.stepStartedAt,
+                result,
+                stage,
+                setup_session_id: this.setupSessionId,
+                ...this.context,
+                ...extra,
+            },
+        };
+        this.telemetry.emitEvents([event]);
+        this.stepStartedAt = now;
+        this.lastStep = stage;
+    }
+    emitStarted() {
+        this.emit("started");
+    }
+    emitPrerequisitesChecked(props) {
+        this.updateContext({
+            node_version_ok: toBoolSet(props.nodeVersionOk),
+            has_docker: toBoolSet(props.hasDocker),
+        });
+        this.emit("prerequisites_checked");
+    }
+    emitAiToolSelected(aiTool) {
+        this.updateContext({ ai_tool: aiTool });
+        this.emit("ai_tool_selected");
+    }
+    emitReadOnlySelected(isReadOnly) {
+        this.updateContext({ read_only_mode: toBoolSet(isReadOnly) });
+        this.emit("read_only_selected");
+    }
+    emitConnectionStringEntered(props) {
+        this.updateContext({
+            connection_string_provided: toBoolSet(props.provided),
+            connection_string_tested: toBoolSet(props.tested),
+            connection_test_attempts: props.attempts,
+        });
+        // If the user tested their connection string, surface the final
+        // test result on this step event (success/failure). If they skipped
+        // the test, the step itself still "succeeded" — the user chose not
+        // to validate — so we default to success.
+        this.emit("connection_string_entered", {}, props.testResult ?? "success");
+    }
+    emitServiceAccountIdEntered(provided) {
+        this.updateContext({ service_account_id_provided: toBoolSet(provided) });
+        this.emit("service_account_id_entered");
+    }
+    emitServiceAccountSecretEntered(provided) {
+        this.updateContext({ service_account_secret_provided: toBoolSet(provided) });
+        this.emit("service_account_secret_entered");
+    }
+    emitCredentialsValidated() {
+        this.emit("credentials_validated");
+    }
+    emitEditorConfigured(props) {
+        this.updateContext({
+            used_default_config_path: toBoolSet(props.usedDefaultConfigPath),
+        });
+        this.emit("editor_configured", props.error ? { error_type: errorName(props.error) } : {}, props.result);
+    }
+    emitSkillsInstallPrompted(outcome) {
+        const patch = { skills_install_status: outcome.status };
+        if (outcome.status === "skipped") {
+            patch.skills_skip_reason = outcome.reason;
+        }
+        else if (outcome.status === "failed") {
+            patch.skills_install_exit_code = outcome.exitCode;
+        }
+        this.updateContext(patch);
+        this.emit("skills_install_prompted");
+    }
+    emitOpenConfigPrompted(props) {
+        this.updateContext({ opened_config_file: toBoolSet(props.opened) });
+        this.emit("open_config_prompted", props.error ? { error_type: errorName(props.error) } : {}, props.result);
+    }
+    emitCompleted() {
+        this.emit("completed", { total_duration_ms: Date.now() - this.startedAt });
+    }
+    /**
+     * Emits a cancellation event (e.g. the user hit Ctrl+C). The `result` is
+     * "success" because the cancellation itself was handled gracefully — the
+     * distinct `stage: "cancelled"` is what analytics use to separate
+     * abandoned runs from completed ones.
+     */
+    emitCancelled() {
+        this.emit("cancelled", {
+            last_stage: this.lastStep,
+            total_duration_ms: Date.now() - this.startedAt,
+        });
+    }
+    emitFailed(error) {
+        this.emit("failed", {
+            last_stage: this.lastStep,
+            error_type: errorName(error),
+            total_duration_ms: Date.now() - this.startedAt,
+        }, "failure");
+    }
+    /**
+     * Best-effort flush of any buffered events before the process exits. Also
+     * closes the owned {@link DeviceId}.
+     */
+    async flush() {
+        try {
+            await this.telemetry.close();
+        }
+        catch {
+            // Ignore errors from telemetry.close()
+        }
+        finally {
+            try {
+                this.deviceId.close();
+            }
+            catch {
+                // Ignore errors - it's best-effort
+            }
+        }
+    }
+}
+const errorName = (error) => {
+    if (error && typeof error === "object" && "name" in error && typeof error.name === "string") {
+        return error.name;
+    }
+    return "unknown";
+};
+//# sourceMappingURL=setupTelemetry.js.map

package/dist/esm/setup/setupTelemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupTelemetry.js","sourceRoot":"","sources":["../../../src/setup/setupTelemetry.ts"],"names":[],"mappings":"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"}

package/dist/esm/telemetry/constants.js

@@ -5,9 +5,9 @@ import { packageInfo } from "../common/packageInfo.js";
 export const MACHINE_METADATA = {
     mcp_server_version: packageInfo.version,
     mcp_server_name: packageInfo.mcpServerName,
-    platform: process.platform,
-    arch: process.arch,
-    os_type: process.platform,
-    os_version: process.version,
+    platform: (typeof process !== "undefined" && process.platform) || "browser",
+    arch: (typeof process !== "undefined" && process.arch) || "unknown",
+    os_type: (typeof process !== "undefined" && process.platform) || "unknown",
+    os_version: (typeof process !== "undefined" && process.version) || "unknown",
 };
 //# sourceMappingURL=constants.js.map

package/dist/esm/telemetry/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/telemetry/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA2B;IACpD,kBAAkB,EAAE,WAAW,CAAC,OAAO;IACvC,eAAe,EAAE,WAAW,CAAC,aAAa;IAC1C,QAAQ,EAAE,OAAO,CAAC,QAAQ;IAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;IAClB,OAAO,EAAE,OAAO,CAAC,QAAQ;IACzB,UAAU,EAAE,OAAO,CAAC,OAAO;CACrB,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/telemetry/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA2B;IACpD,kBAAkB,EAAE,WAAW,CAAC,OAAO;IACvC,eAAe,EAAE,WAAW,CAAC,aAAa;IAC1C,QAAQ,EAAE,CAAC,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,SAAS;IAC3E,IAAI,EAAE,CAAC,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,SAAS;IACnE,OAAO,EAAE,CAAC,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,SAAS;IAC1E,UAAU,EAAE,CAAC,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,SAAS;CACtE,CAAC"}

package/dist/esm/telemetry/eventCache.d.ts

@@ -9,6 +9,8 @@ export declare class EventCache {
     private static readonly MAX_EVENTS;
     private cache;
     private nextId;
+    /** Current exclusive operation, if any. The next caller awaits this before starting. */
+    private currentOperation;
     constructor();
     /**
      * Gets the singleton instance of EventCache
@@ -19,6 +21,21 @@ export declare class EventCache {
      * Gets the number of currently cached events
      */
     get size(): number;
+    /**
+     * Runs a callback with exclusive access to the cache so operations
+     * are serialized across all callers (e.g. multiple Telemetry instances / sessions).
+     */
+    private runExclusive;
+    /**
+     * Under exclusive access: takes up to `batchSize` oldest events and passes them
+     * to the processor. If the processor signals `removeProcessed: true`, those events
+     * are removed from the cache; otherwise they remain untouched.
+     * Returns the `result` from the processor, or `undefined` if the cache was empty.
+     */
+    processOldestBatch<T>(batchSize: number, processor: (events: BaseEvent[]) => Promise<{
+        removeProcessed: boolean;
+        result: T;
+    }>): Promise<T | undefined>;
     /**
      * Gets a copy of the currently cached events along with their ids
      * @returns Array of cached BaseEvent objects
@@ -28,9 +45,8 @@ export declare class EventCache {
         event: BaseEvent;
     }[];
     /**
-     * Appends new events to the cached events
-     * LRU cache automatically handles dropping oldest events when limit is exceeded
-     * @param events - The events to append
+     * Appends new events to the cache.
+     * LRU cache automatically handles dropping oldest events when limit is exceeded.
      */
     appendEvents(events: BaseEvent[]): void;
     /**

package/dist/esm/telemetry/eventCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eventCache.d.ts","sourceRoot":"","sources":["../../../src/telemetry/eventCache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;GAIG;AACH,qBAAa,UAAU;IACnB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAa;IACpC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAQ;IAE1C,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,MAAM,CAAK;;IAWnB;;;OAGG;WACW,WAAW,IAAI,UAAU;IAOvC;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;OAGG;IACI,SAAS,IAAI;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,EAAE;IAItD;;;;OAIG;IACI,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI;IAM9C;;OAEG;IACI,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;CAK3C"}
+{"version":3,"file":"eventCache.d.ts","sourceRoot":"","sources":["../../../src/telemetry/eventCache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;GAIG;AACH,qBAAa,UAAU;IACnB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAa;IACpC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAQ;IAE1C,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,MAAM,CAAK;IACnB,wFAAwF;IACxF,OAAO,CAAC,gBAAgB,CAA8D;;IAWtF;;;OAGG;WACW,WAAW,IAAI,UAAU;IAOvC;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;OAGG;YACW,YAAY;IAoB1B;;;;;OAKG;IACU,kBAAkB,CAAC,CAAC,EAC7B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,OAAO,CAAC;QAAE,eAAe,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC,GACrF,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAmBzB;;;OAGG;IACI,SAAS,IAAI;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,EAAE;IAItD;;;OAGG;IACI,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI;IAM9C;;OAEG;IACI,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;CAK3C"}

package/dist/esm/telemetry/eventCache.js

@@ -30,6 +30,52 @@ export class EventCache {
     get size() {
         return this.cache.size;
     }
+    /**
+     * Runs a callback with exclusive access to the cache so operations
+     * are serialized across all callers (e.g. multiple Telemetry instances / sessions).
+     */
+    async runExclusive(fn) {
+        const prevOperation = this.currentOperation;
+        let resolve;
+        const promise = new Promise((res) => {
+            resolve = res;
+        });
+        // resolve is guaranteed to be assigned by the Promise constructor
+        const release = resolve;
+        this.currentOperation = { promise, resolve: release };
+        await prevOperation?.promise;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Under exclusive access: takes up to `batchSize` oldest events and passes them
+     * to the processor. If the processor signals `removeProcessed: true`, those events
+     * are removed from the cache; otherwise they remain untouched.
+     * Returns the `result` from the processor, or `undefined` if the cache was empty.
+     */
+    async processOldestBatch(batchSize, processor) {
+        return this.runExclusive(async () => {
+            const allEvents = this.getEvents();
+            const batch = allEvents.slice(0, batchSize);
+            if (batch.length === 0)
+                return undefined;
+            try {
+                const { removeProcessed, result } = await processor(batch.map((e) => e.event));
+                if (removeProcessed) {
+                    this.removeEvents(batch.map((e) => e.id));
+                }
+                return result;
+            }
+            catch {
+                // Processor threw — leave events in cache for retry
+                return undefined;
+            }
+        });
+    }
     /**
      * Gets a copy of the currently cached events along with their ids
      * @returns Array of cached BaseEvent objects
@@ -38,9 +84,8 @@ export class EventCache {
         return Array.from(this.cache.entries()).map(([id, event]) => ({ id, event }));
     }
     /**
-     * Appends new events to the cached events
-     * LRU cache automatically handles dropping oldest events when limit is exceeded
-     * @param events - The events to append
+     * Appends new events to the cache.
+     * LRU cache automatically handles dropping oldest events when limit is exceeded.
      */
     appendEvents(events) {
         for (const event of events) {

package/dist/esm/telemetry/eventCache.js.map

@@ -1 +1 @@
-{"version":3,"file":"eventCache.js","sourceRoot":"","sources":["../../../src/telemetry/eventCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGrC;;;;GAIG;AACH,MAAM,OAAO,UAAU;IAOnB;QAFQ,WAAM,GAAG,CAAC,CAAC;QAGf,IAAI,CAAC,KAAK,GAAG,IAAI,QAAQ,CAAC;YACtB,GAAG,EAAE,UAAU,CAAC,UAAU;YAC1B,0CAA0C;YAC1C,UAAU,EAAE,KAAK;YACjB,cAAc,EAAE,KAAK;SACxB,CAAC,CAAC;IACP,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,WAAW;QACrB,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;YACvB,UAAU,CAAC,QAAQ,GAAG,IAAI,UAAU,EAAE,CAAC;QAC3C,CAAC;QACD,OAAO,UAAU,CAAC,QAAQ,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,IAAW,IAAI;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACI,SAAS;QACZ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAClF,CAAC;IAED;;;;OAIG;IACI,YAAY,CAAC,MAAmB;QACnC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,KAAK,CAAC,CAAC;QACzC,CAAC;IACL,CAAC;IAED;;OAEG;IACI,YAAY,CAAC,GAAa;QAC7B,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACnB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC;IACL,CAAC;;AA1DuB,qBAAU,GAAG,IAAI,AAAP,CAAQ"}
+{"version":3,"file":"eventCache.js","sourceRoot":"","sources":["../../../src/telemetry/eventCache.ts"],"names":[],"mappings":"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"}

package/dist/esm/telemetry/telemetry.d.ts

@@ -1,57 +1,138 @@
-import type { Session } from "../common/session.js";
 import type { BaseEvent, CommonProperties } from "./types.js";
-import type { UserConfig } from "../common/config/userConfig.js";
+import type { LoggerBase } from "../common/logging/index.js";
+import type { ApiClient } from "../common/atlas/apiClient.js";
 import { EventCache } from "./eventCache.js";
 import type { DeviceId } from "../helpers/deviceId.js";
+import type { Keychain } from "../common/keychain.js";
+import type { Session } from "../common/session.js";
+import type { UserConfig } from "../common/config/userConfig.js";
 import { EventEmitter } from "events";
-export interface TelemetryEvents {
-    "events-emitted": [];
-    "events-send-failed": [];
-    "events-skipped": [];
+import type { TelemetryEvents } from "@mongodb-js/mcp-types";
+export type { TelemetryEvents };
+/**
+ * Configuration for the {@link Telemetry} pipeline.
+ */
+export interface TelemetryConfig {
+    /** Logger used by the telemetry pipeline for its own diagnostics. */
+    logger: LoggerBase;
+    /** Device id source, resolved asynchronously during setup. */
+    deviceId: DeviceId;
+    /**
+     * API client used to send events. Always required — the pipeline would
+     * otherwise buffer events in the cache forever. When no Atlas credentials
+     * are configured, callers should still pass an unauthenticated
+     * {@link ApiClient}; it will route telemetry through the unauth endpoint.
+     */
+    apiClient: ApiClient;
+    /** Secrets source used when redacting events prior to sending. */
+    keychain?: Keychain;
+    /**
+     * The user's telemetry preference. When set to `false`, no events are
+     * cached or sent. The DO_NOT_TRACK environment variable is always honored
+     * on top of this setting, so callers don't need to check it themselves.
+     */
+    enabled: boolean;
+    /**
+     * Returns the host-supplied common properties merged onto every event
+     * (e.g. hosting mode, MCP client identity, transport). Invoked on every
+     * send so values resolved after construction — like the client name/
+     * version exchanged during handshake — are captured. Static properties
+     * can simply be returned as constants from this callback.
+     *
+     * Machine metadata, device id, and container environment are provided by
+     * the pipeline itself and don't need to be returned here.
+     */
+    getCommonProperties?: () => Partial<CommonProperties>;
+    /**
+     * Optional override for the underlying event cache. Defaults to the
+     * process-wide singleton returned by {@link EventCache.getInstance}.
+     * Mostly useful for tests or callers that need to isolate caching.
+     */
+    eventCache?: EventCache;
 }
+/** Maximum number of events sent per batch. */
+export declare const BATCH_SIZE = 32;
+/** Delay between send attempts under normal conditions. */
+export declare const SEND_INTERVAL_MS = 30000;
+/** Initial backoff delay after a 429 response. */
+export declare const INITIAL_BACKOFF_MS = 60000;
+/** Maximum backoff delay (1 hour). */
+export declare const MAX_BACKOFF_MS = 3600000;
+/**
+ * Calculates the next backoff duration, doubling the current value up to MAX_BACKOFF_MS.
+ */
+export declare function nextBackoffMs(currentMs: number): number;
 export declare class Telemetry {
-    private readonly session;
-    private readonly userConfig;
-    private readonly commonProperties;
-    private isBufferingEvents;
     /** Resolves when the setup is complete or a timeout occurs */
     setupPromise: Promise<[string, boolean]> | undefined;
     readonly events: EventEmitter<TelemetryEvents>;
-    private eventCache;
-    private deviceId;
+    private readonly logger;
+    private readonly apiClient;
+    private readonly keychain?;
+    private readonly enabled;
+    private readonly getHostCommonProperties;
+    /**
+     * Machine metadata plus device_id / is_container_env, which the pipeline
+     * resolves itself during setup. Host-supplied properties are merged on
+     * top of this at send time.
+     */
+    private readonly pipelineCommonProperties;
+    private readonly eventCache;
+    private readonly deviceId;
+    private backoffMs;
+    private readonly timer;
     private constructor();
-    static create(session: Session, userConfig: UserConfig, deviceId: DeviceId, { commonProperties, eventCache, }?: {
+    /**
+     * @deprecated Pass a {@link TelemetryConfig} object instead. This
+     * positional-argument overload is preserved for backward compatibility
+     * and will be removed in the next major version.
+     */
+    static create(session: Session, userConfig: UserConfig, deviceId: DeviceId, options?: {
         commonProperties?: Partial<CommonProperties>;
         eventCache?: EventCache;
     }): Telemetry;
+    static create(config: TelemetryConfig): Telemetry;
     private setup;
     close(): Promise<void>;
     /**
-     * Emits events through the telemetry pipeline
-     * @param events - The events to emit
+     * Caches events for sending via the background timer.
      */
     emitEvents(events: BaseEvent[]): void;
     /**
      * Gets the common properties for events
-     * @returns Object containing common properties for all events
      */
     getCommonProperties(): CommonProperties;
     /**
-     * Checks if telemetry is currently enabled
-     * This is a method rather than a constant to capture runtime config changes
+     * Checks if telemetry is currently enabled.
      *
-     * Follows the Console Do Not Track standard (https://consoledonottrack.com/)
-     * by respecting the DO_NOT_TRACK environment variable
+     * Follows the Console Do Not Track standard
+     * by respecting the DO_NOT_TRACK environment variable. The env check is
+     * done on every call so an operator can opt out mid-process.
      */
     isTelemetryEnabled(): boolean;
     /**
-     * Attempts to emit events through authenticated and unauthenticated clients
-     * Falls back to caching if both attempts fail
+     * Schedules the next send attempt. Replaces any previously scheduled send.
+     */
+    private scheduleSend;
+    /**
+     * Sends a batch and reschedules the next attempt based on the result.
+     */
+    private sendBatchAndReschedule;
+    /**
+     * Determines the next send delay based on the result of the last batch.
+     * On rate-limit: uses and advances exponential backoff.
+     * On success: resets backoff and returns the normal interval.
+     * On error/empty: returns the normal interval without changing backoff state.
+     */
+    private getNextDelay;
+    /**
+     * Sends up to BATCH_SIZE oldest events from the cache.
+     * On success the sent events are removed; on failure they stay in the cache.
+     * Does not reschedule — the caller decides what to do next.
      */
-    private emit;
+    private sendBatch;
     /**
-     * Attempts to send events through the provided API client.
-     * Events are redacted before being sent to ensure no sensitive data is transmitted
+     * Sends events through the API client after redacting sensitive data.
      */
     private sendEvents;
 }

package/dist/esm/telemetry/telemetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../../src/telemetry/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAIjE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAQtC,MAAM,WAAW,eAAe;IAC5B,gBAAgB,EAAE,EAAE,CAAC;IACrB,oBAAoB,EAAE,EAAE,CAAC;IACzB,gBAAgB,EAAE,EAAE,CAAC;CACxB;AAED,qBAAa,SAAS;IAUd,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAXrC,OAAO,CAAC,iBAAiB,CAAiB;IAC1C,8DAA8D;IACvD,YAAY,EAAE,OAAO,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAC5D,SAAgB,MAAM,EAAE,YAAY,CAAC,eAAe,CAAC,CAAsB;IAE3E,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,QAAQ,CAAW;IAE3B,OAAO;IAUP,MAAM,CAAC,MAAM,CACT,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,QAAQ,EAClB,EACI,gBAAqB,EACrB,UAAqC,GACxC,GAAE;QACC,gBAAgB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;QAC7C,UAAU,CAAC,EAAE,UAAU,CAAC;KACtB,GACP,SAAS;YAcE,KAAK;IAoBN,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiCnC;;;OAGG;IACI,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI;IAU5C;;;OAGG;IACI,mBAAmB,IAAI,gBAAgB;IAY9C;;;;;;OAMG;IACI,kBAAkB,IAAI,OAAO;IAUpC;;;OAGG;YACW,IAAI;IAoDlB;;;OAGG;YACW,UAAU;CAmB3B"}
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../../src/telemetry/telemetry.ts"],"names":[],"mappings":"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"}