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",
@@ -61,6 +62,7 @@
     "@mongodb-js/devtools-connect": "^3.7.2",
     "@mongosh/service-provider-node-driver": "^3.6.0",
     "bson": "^6.10.3",
+    "lru-cache": "^11.1.0",
     "mongodb": "^6.15.0",
     "mongodb-log-writer": "^2.4.1",
     "mongodb-redact": "^1.1.6",

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";
 
@@ -67,7 +71,7 @@ export class ApiClient {
             baseUrl: options?.baseUrl || "https://cloud.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>({
@@ -93,6 +97,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;
     }> {
@@ -118,6 +131,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

@@ -6,6 +6,7 @@ import { MongoDbTools } from "./tools/mongodb/tools.js";
 import logger, { initializeLogger } from "./logger.js";
 import { mongoLogId } from "mongodb-log-writer";
 import config from "./config.js";
+import { ObjectId } from "mongodb";
 
 export class Server {
     public readonly session: Session;
@@ -18,15 +19,23 @@ 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());
+            this.session.sessionId = new ObjectId().toString();
+
+            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,10 +1,16 @@
 import { NodeDriverServiceProvider } from "@mongosh/service-provider-node-driver";
 import { ApiClient, ApiClientCredentials } from "./common/atlas/apiClient.js";
+import { Implementation } from "@modelcontextprotocol/sdk/types.js";
 import config from "./config.js";
 
 export class Session {
+    sessionId?: string;
     serviceProvider?: NodeDriverServiceProvider;
     apiClient: ApiClient;
+    agentRunner?: {
+        name: string;
+        version: string;
+    };
 
     constructor() {
         const credentials: ApiClientCredentials | undefined =
@@ -21,6 +27,15 @@ export class Session {
         });
     }
 
+    setAgentRunner(agentRunner: Implementation | undefined) {
+        if (agentRunner?.name && agentRunner?.version) {
+            this.agentRunner = {
+                name: agentRunner.name,
+                version: agentRunner.version,
+            };
+        }
+    }
+
     async close(): Promise<void> {
         if (this.serviceProvider) {
             try {

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,62 @@
+import { BaseEvent } from "./types.js";
+import { LRUCache } from "lru-cache";
+
+/**
+ * Singleton class for in-memory telemetry event caching
+ * Provides a central storage for telemetry events that couldn't be sent
+ * Uses LRU cache to automatically drop oldest events when limit is exceeded
+ */
+export class EventCache {
+    private static instance: EventCache;
+    private static readonly MAX_EVENTS = 1000;
+
+    private cache: LRUCache<number, BaseEvent>;
+    private nextId = 0;
+
+    private constructor() {
+        this.cache = new LRUCache({
+            max: EventCache.MAX_EVENTS,
+            // Using FIFO eviction strategy for events
+            allowStale: false,
+            updateAgeOnGet: false,
+        });
+    }
+
+    /**
+     * 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 Array.from(this.cache.values());
+    }
+
+    /**
+     * Appends new events to the cached events
+     * LRU cache automatically handles dropping oldest events when limit is exceeded
+     * @param events - The events to append
+     */
+    public appendEvents(events: BaseEvent[]): void {
+        for (const event of events) {
+            this.cache.set(this.nextId++, event);
+        }
+    }
+
+    /**
+     * Clears all cached events
+     */
+    public clearEvents(): void {
+        this.cache.clear();
+        this.nextId = 0;
+    }
+}