feat: core telemetry functionality

package.json

@@ -47,6 +47,7 @@
     "jest-environment-node": "^29.7.0",
     "jest-extended": "^4.0.2",
     "mongodb-runner": "^5.8.2",
+    "native-machine-id": "^0.0.8",
     "openapi-types": "^12.1.3",
     "openapi-typescript": "^7.6.1",
     "prettier": "^3.5.3",

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 listClustersForAllProjects(options?: FetchOptions<operations["listClustersForAllProjects"]>) {
         const { data } = await this.client.GET("/api/atlas/v2/clusters", options);

src/config.ts

@@ -5,12 +5,16 @@ import argv from "yargs-parser";
 import packageJson from "../package.json" with { type: "json" };
 import { ReadConcernLevel, ReadPreferenceMode, W } from "mongodb";
 
+export const SERVER_NAME = "MdbMcpServer";
+export const SERVER_VERSION = packageJson.version;
+
 // If we decide to support non-string config options, we'll need to extend the mechanism for parsing
 // env variables.
 interface UserConfig {
     apiBaseUrl?: string;
     apiClientId?: string;
     apiClientSecret?: string;
+    telemetry?: "enabled" | "disabled";
     logPath: string;
     connectionString?: string;
     connectOptions: {
@@ -41,7 +45,8 @@ const mergedUserConfig = {
 
 const config = {
     ...mergedUserConfig,
-    version: packageJson.version,
+    version: SERVER_VERSION,
+    mcpServerName: SERVER_NAME,
 };
 
 export default config;

src/index.ts

@@ -25,6 +25,5 @@ try {
     await server.connect(transport);
 } catch (error: unknown) {
     logger.emergency(mongoLogId(1_000_004), "server", `Fatal error running server: ${error as string}`);
-
     process.exit(1);
 }

src/server.ts

@@ -18,15 +18,21 @@ export class Server {
 
     async connect(transport: Transport) {
         this.mcpServer.server.registerCapabilities({ logging: {} });
-
         this.registerTools();
         this.registerResources();
 
         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.setAgentRunner(this.mcpServer.server.getClientVersion());
+            logger.info(
+                mongoLogId(1_000_004),
+                "server",
+                `Server started with transport ${transport.constructor.name} and agent runner ${this.session.agentRunner?.name}`
+            );
+        };
     }
 
     async close(): Promise<void> {

src/session.ts

@@ -1,25 +1,73 @@
 import { NodeDriverServiceProvider } from "@mongosh/service-provider-node-driver";
 import { ApiClient } from "./common/atlas/apiClient.js";
-import config from "./config.js";
+import defaultConfig from "./config.js";
+import { Implementation } from "@modelcontextprotocol/sdk/types.js";
+
+// Define the type for configuration used by Session
+interface SessionConfig {
+    apiBaseUrl?: string;
+    apiClientId?: string;
+    apiClientSecret?: string;
+    [key: string]: unknown;
+}
 
 export class Session {
+    sessionId?: string;
     serviceProvider?: NodeDriverServiceProvider;
-    apiClient?: ApiClient;
+    apiClient: ApiClient;
+    agentRunner?: {
+        name: string;
+        version: string;
+    };
+    private credentials?: { clientId: string; clientSecret: string };
+    private baseUrl: string;
+    private readonly config: SessionConfig;
+
+    constructor(config: SessionConfig = defaultConfig as SessionConfig) {
+        this.config = config;
+        this.baseUrl = this.config.apiBaseUrl ?? "https://cloud.mongodb.com/";
+
+        // Store credentials if available
+        if (this.config.apiClientId && this.config.apiClientSecret) {
+            this.credentials = {
+                clientId: this.config.apiClientId,
+                clientSecret: this.config.apiClientSecret,
+            };
+
+            // Initialize API client with credentials
+            this.apiClient = new ApiClient({
+                baseUrl: this.baseUrl,
+                credentials: this.credentials,
+            });
+            return;
+        }
+
+        // Initialize API client without credentials
+        this.apiClient = new ApiClient({ baseUrl: this.baseUrl });
+    }
+
+    setAgentRunner(agentClient: Implementation | undefined) {
+        if (agentClient?.name && agentClient?.version) {
+            this.agentRunner = {
+                name: agentClient.name,
+                version: agentClient.version,
+            };
+        }
+    }
 
     ensureAuthenticated(): asserts this is { apiClient: ApiClient } {
-        if (!this.apiClient) {
-            if (!config.apiClientId || !config.apiClientSecret) {
+        if (!this.apiClient.hasCredentials()) {
+            if (!this.credentials) {
                 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."
                 );
             }
 
+            // Reinitialize API client with the stored credentials
+            // This can happen if the server was configured without credentials but the env variables are later set
             this.apiClient = new ApiClient({
-                baseUrl: config.apiBaseUrl,
-                credentials: {
-                    clientId: config.apiClientId,
-                    clientSecret: config.apiClientSecret,
-                },
+                baseUrl: this.baseUrl,
+                credentials: this.credentials,
             });
         }
     }

src/telemetry/constants.ts

@@ -0,0 +1,16 @@
+import pkg from "../../package.json" with { type: "json" };
+import config from "../config.js";
+import { getMachineIdSync } from "native-machine-id";
+
+/**
+ * Machine-specific metadata formatted for telemetry
+ */
+export const MACHINE_METADATA = {
+    device_id: getMachineIdSync(),
+    mcp_server_version: pkg.version,
+    mcp_server_name: config.mcpServerName,
+    platform: process.platform,
+    arch: process.arch,
+    os_type: process.platform,
+    os_version: process.version,
+} as const;

src/telemetry/eventCache.ts

@@ -0,0 +1,46 @@
+import { BaseEvent } from "./types.js";
+
+/**
+ * Singleton class for in-memory telemetry event caching
+ * Provides a central storage for telemetry events that couldn't be sent
+ */
+export class EventCache {
+    private static instance: EventCache;
+    private events: BaseEvent[] = [];
+
+    private constructor() {}
+
+    /**
+     * Gets the singleton instance of EventCache
+     * @returns The EventCache instance
+     */
+    public static getInstance(): EventCache {
+        if (!EventCache.instance) {
+            EventCache.instance = new EventCache();
+        }
+        return EventCache.instance;
+    }
+
+    /**
+     * Gets a copy of the currently cached events
+     * @returns Array of cached BaseEvent objects
+     */
+    public getEvents(): BaseEvent[] {
+        return [...this.events];
+    }
+
+    /**
+     * Sets the cached events, replacing any existing events
+     * @param events - The events to cache
+     */
+    public setEvents(events: BaseEvent[]): void {
+        this.events = [...events];
+    }
+
+    /**
+     * Clears all cached events
+     */
+    public clearEvents(): void {
+        this.events = [];
+    }
+}