feat: core telemetry functionality

src/common/atlas/apiClient.ts

@@ -1,8 +1,12 @@
 import config from "../../config.js";
-import createClient, { Client, FetchOptions, Middleware } from "openapi-fetch";
+import createClient, { Client, Middleware } from "openapi-fetch";
+import type { FetchOptions } from "openapi-fetch";
 import { AccessToken, ClientCredentials } from "simple-oauth2";
 import { ApiClientError } from "./apiClientError.js";
 import { paths, operations } from "./openapi.js";
+import { BaseEvent } from "../../telemetry/types.js";
+import { mongoLogId } from "mongodb-log-writer";
+import logger from "../../logger.js";
 
 const ATLAS_API_VERSION = "2025-03-12";
 
@@ -62,10 +66,10 @@ export class ApiClient {
     constructor(options?: ApiClientOptions) {
         this.options = {
             ...options,
-            baseUrl: options?.baseUrl || "https://cloud.mongodb.com/",
+            baseUrl: options?.baseUrl || "https://cloud-dev.mongodb.com/",
             userAgent:
                 options?.userAgent ||
-                `AtlasMCP/${config.version} (${process.platform}; ${process.arch}; ${process.env.HOSTNAME || "unknown"})`,
+                `${config.mcpServerName}/${config.version} (${process.platform}; ${process.arch}; ${process.env.HOSTNAME || "unknown"})`,
         };
 
         this.client = createClient<paths>({
@@ -91,6 +95,15 @@ export class ApiClient {
         this.client.use(this.errorMiddleware);
     }
 
+    public hasCredentials(): boolean {
+        logger.info(
+            mongoLogId(1_000_000),
+            "api-client",
+            `Checking if API client has credentials: ${!!(this.oauth2Client && this.accessToken)}`
+        );
+        return !!(this.oauth2Client && this.accessToken);
+    }
+
     public async getIpInfo(): Promise<{
         currentIpv4Address: string;
     }> {
@@ -116,6 +129,32 @@ export class ApiClient {
         }>;
     }
 
+    async sendEvents(events: BaseEvent[]): Promise<void> {
+        let endpoint = "api/private/unauth/telemetry/events";
+        const headers: Record<string, string> = {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": this.options.userAgent,
+        };
+
+        const accessToken = await this.getAccessToken();
+        if (accessToken) {
+            endpoint = "api/private/v1.0/telemetry/events";
+            headers["Authorization"] = `Bearer ${accessToken}`;
+        }
+
+        const url = new URL(endpoint, this.options.baseUrl);
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(events),
+        });
+
+        if (!response.ok) {
+            throw await ApiClientError.fromResponse(response);
+        }
+    }
+
     // DO NOT EDIT. This is auto-generated code.
     async listOrganizations(options?: FetchOptions<operations["listOrganizations"]>) {
         const { data } = await this.client.GET("/api/atlas/v2/orgs", options);

src/config.ts

@@ -11,6 +11,7 @@ interface UserConfig {
     apiBaseUrl?: string;
     apiClientId?: string;
     apiClientSecret?: string;
+    telemetry?: "enabled" | "disabled";
     logPath: string;
     connectionString?: string;
     connectOptions: {
@@ -39,9 +40,20 @@ const mergedUserConfig = {
     ...getCliConfig(),
 };
 
+const machineMetadata = {
+    device_id: "id", // TODO: use @mongodb-js/machine-id
+    platform: process.platform,
+    arch: process.arch,
+    os_type: process.platform,
+    os_version: process.version,
+};
+
 const config = {
     ...mergedUserConfig,
+    ...machineMetadata,
     version: packageJson.version,
+    mcpServerName: "MdbMcpServer",
+    isTelemetryEnabled: true,
 };
 
 export default config;

src/index.ts

@@ -8,7 +8,7 @@ import config from "./config.js";
 import { Session } from "./session.js";
 import { Server } from "./server.js";
 
-try {
+async function main() {
     const session = new Session();
     const mcpServer = new McpServer({
         name: "MongoDB Atlas",
@@ -23,8 +23,12 @@ try {
     const transport = new StdioServerTransport();
 
     await server.connect(transport);
+}
+
+// Start the server
+try {
+    await main();
 } catch (error: unknown) {
     logger.emergency(mongoLogId(1_000_004), "server", `Fatal error running server: ${error as string}`);
-
     process.exit(1);
 }

src/server.ts

@@ -17,14 +17,16 @@ export class Server {
 
     async connect(transport: Transport) {
         this.mcpServer.server.registerCapabilities({ logging: {} });
-
         this.registerTools();
 
         await initializeLogger(this.mcpServer);
 
         await this.mcpServer.connect(transport);
 
-        logger.info(mongoLogId(1_000_004), "server", `Server started with transport ${transport.constructor.name}`);
+        this.mcpServer.server.oninitialized = () => {
+            this.session.setAgentClientData(this.mcpServer.server.getClientVersion());
+            logger.info(mongoLogId(1_000_004), "server", `Server started with transport ${transport.constructor.name}`);
+        };
     }
 
     async close(): Promise<void> {

src/session.ts

@@ -1,19 +1,46 @@
 import { NodeDriverServiceProvider } from "@mongosh/service-provider-node-driver";
 import { ApiClient } from "./common/atlas/apiClient.js";
 import config from "./config.js";
+import { Implementation } from "@modelcontextprotocol/sdk/types.js";
 
 export class Session {
+    sessionId?: string;
     serviceProvider?: NodeDriverServiceProvider;
-    apiClient?: ApiClient;
+    apiClient: ApiClient;
+    agentClientName?: string;
+    agentClientVersion?: string;
+
+    constructor() {
+        // Initialize API client with credentials if available
+        if (config.apiClientId && config.apiClientSecret) {
+            this.apiClient = new ApiClient({
+                baseUrl: config.apiBaseUrl,
+                credentials: {
+                    clientId: config.apiClientId,
+                    clientSecret: config.apiClientSecret,
+                },
+            });
+            return;
+        }
+
+        // Initialize API client without credentials
+        this.apiClient = new ApiClient({ baseUrl: config.apiBaseUrl });
+    }
+
+    setAgentClientData(agentClient: Implementation | undefined) {
+        this.agentClientName = agentClient?.name;
+        this.agentClientVersion = agentClient?.version;
+    }
 
     ensureAuthenticated(): asserts this is { apiClient: ApiClient } {
-        if (!this.apiClient) {
+        if (!this.apiClient || !this.apiClient.hasCredentials()) {
             if (!config.apiClientId || !config.apiClientSecret) {
                 throw new Error(
                     "Not authenticated make sure to configure MCP server with MDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET environment variables."
                 );
             }
 
+            // Initialize or reinitialize API client with credentials
             this.apiClient = new ApiClient({
                 baseUrl: config.apiBaseUrl,
                 credentials: {

src/telemetry/telemetry.ts

@@ -0,0 +1,203 @@
+import { Session } from "../session.js";
+import { BaseEvent, type ToolEvent } from "./types.js";
+import pkg from "../../package.json" with { type: "json" };
+import config from "../config.js";
+import logger from "../logger.js";
+import { mongoLogId } from "mongodb-log-writer";
+import { ApiClient } from "../common/atlas/apiClient.js";
+import fs from "fs/promises";
+import path from "path";
+
+const TELEMETRY_ENABLED = config.telemetry !== "disabled";
+const CACHE_FILE = path.join(process.cwd(), ".telemetry-cache.json");
+
+interface TelemetryError extends Error {
+    code?: string;
+}
+
+type EventResult = {
+    success: boolean;
+    error?: Error;
+};
+
+type CommonProperties = {
+    device_id: string;
+    mcp_server_version: string;
+    mcp_server_name: string;
+    mcp_client_version?: string;
+    mcp_client_name?: string;
+    platform: string;
+    arch: string;
+    os_type: string;
+    os_version?: string;
+    session_id?: string;
+};
+
+export class Telemetry {
+    private readonly commonProperties: CommonProperties;
+
+    constructor(private readonly session: Session) {
+        // Ensure all required properties are present
+        this.commonProperties = Object.freeze({
+            device_id: config.device_id,
+            mcp_server_version: pkg.version,
+            mcp_server_name: config.mcpServerName,
+            mcp_client_version: this.session.agentClientVersion,
+            mcp_client_name: this.session.agentClientName,
+            platform: config.platform,
+            arch: config.arch,
+            os_type: config.os_type,
+            os_version: config.os_version,
+        });
+    }
+
+    /**
+     * Emits a tool event with timing and error information
+     * @param command - The command being executed
+     * @param category - Category of the command
+     * @param startTime - Start time in milliseconds
+     * @param result - Whether the command succeeded or failed
+     * @param error - Optional error if the command failed
+     */
+    public async emitToolEvent(
+        command: string,
+        category: string,
+        startTime: number,
+        result: "success" | "failure",
+        error?: Error
+    ): Promise<void> {
+        if (!TELEMETRY_ENABLED) {
+            logger.debug(mongoLogId(1_000_000), "telemetry", "Telemetry is disabled, skipping event.");
+            return;
+        }
+
+        const event = this.createToolEvent(command, category, startTime, result, error);
+        await this.emit([event]);
+    }
+
+    /**
+     * Creates a tool event with common properties and timing information
+     */
+    private createToolEvent(
+        command: string,
+        category: string,
+        startTime: number,
+        result: "success" | "failure",
+        error?: Error
+    ): ToolEvent {
+        const duration = Date.now() - startTime;
+
+        const event: ToolEvent = {
+            timestamp: new Date().toISOString(),
+            source: "mdbmcp",
+            properties: {
+                ...this.commonProperties,
+                command,
+                category,
+                duration_ms: duration,
+                session_id: this.session.sessionId,
+                result,
+                ...(error && {
+                    error_type: error.name,
+                    error_code: error.message,
+                }),
+            },
+        };
+
+        return event;
+    }
+
+    /**
+     * Attempts to emit events through authenticated and unauthenticated clients
+     * Falls back to caching if both attempts fail
+     */
+    private async emit(events: BaseEvent[]): Promise<void> {
+        const cachedEvents = await this.readCache();
+        const allEvents = [...cachedEvents, ...events];
+
+        logger.debug(
+            mongoLogId(1_000_000),
+            "telemetry",
+            `Attempting to send ${allEvents.length} events (${cachedEvents.length} cached)`
+        );
+
+        const result = await this.sendEvents(this.session.apiClient, allEvents);
+        if (result.success) {
+            await this.clearCache();
+            return;
+        }
+
+        logger.warning(mongoLogId(1_000_000), "telemetry", `Error sending event to client: ${result.error}`);
+        await this.cacheEvents(allEvents);
+    }
+
+    /**
+     * Attempts to send events through the provided API client
+     */
+    private async sendEvents(client: ApiClient, events: BaseEvent[]): Promise<EventResult> {
+        try {
+            await client.sendEvents(events);
+            return { success: true };
+        } catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+        }
+    }
+
+    /**
+     * Reads cached events from disk
+     * Returns empty array if no cache exists or on read error
+     */
+    private async readCache(): Promise<BaseEvent[]> {
+        try {
+            const data = await fs.readFile(CACHE_FILE, "utf-8");
+            return JSON.parse(data) as BaseEvent[];
+        } catch (error) {
+            const typedError = error as TelemetryError;
+            if (typedError.code !== "ENOENT") {
+                logger.warning(
+                    mongoLogId(1_000_000),
+                    "telemetry",
+                    `Error reading telemetry cache: ${typedError.message}`
+                );
+            }
+            return [];
+        }
+    }
+
+    /**
+     * Caches events to disk for later sending
+     */
+    private async cacheEvents(events: BaseEvent[]): Promise<void> {
+        try {
+            await fs.writeFile(CACHE_FILE, JSON.stringify(events, null, 2));
+            logger.debug(mongoLogId(1_000_000), "telemetry", `Cached ${events.length} events for later sending`);
+        } catch (error) {
+            logger.warning(
+                mongoLogId(1_000_000),
+                "telemetry",
+                `Failed to cache telemetry events: ${error instanceof Error ? error.message : String(error)}`
+            );
+        }
+    }
+
+    /**
+     * Clears the event cache after successful sending
+     */
+    private async clearCache(): Promise<void> {
+        try {
+            await fs.unlink(CACHE_FILE);
+        } catch (error) {
+            const typedError = error as TelemetryError;
+            if (typedError.code !== "ENOENT") {
+                logger.warning(
+                    mongoLogId(1_000_000),
+                    "telemetry",
+                    `Error clearing telemetry cache: ${typedError.message}`
+                );
+            }
+        }
+    }
+}