feat: core telemetry functionality (#87)

Co-authored-by: Filipe Constantinov Menezes <[email protected]>

Author: blva

package-lock.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",

package.json

@@ -1,7 +1,11 @@
-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";
 import { packageInfo } from "../../packageInfo.js";
 
 const ATLAS_API_VERSION = "2025-03-12";
@@ -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/common/atlas/apiClient.ts

@@ -10,6 +10,7 @@ export interface UserConfig {
     apiBaseUrl?: string;
     apiClientId?: string;
     apiClientSecret?: string;
+    telemetry?: "enabled" | "disabled";
     logPath: string;
     connectionString?: string;
     connectOptions: {

src/config.ts

@@ -30,6 +30,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/index.ts

@@ -5,6 +5,8 @@ import { AtlasTools } from "./tools/atlas/tools.js";
 import { MongoDbTools } from "./tools/mongodb/tools.js";
 import logger, { initializeLogger } from "./logger.js";
 import { mongoLogId } from "mongodb-log-writer";
+import { ObjectId } from "mongodb";
+import { Telemetry } from "./telemetry/telemetry.js";
 import { UserConfig } from "./config.js";
 
 export interface ServerOptions {
@@ -16,25 +18,35 @@ export interface ServerOptions {
 export class Server {
     public readonly session: Session;
     private readonly mcpServer: McpServer;
+    private readonly telemetry: Telemetry;
     private readonly userConfig: UserConfig;
 
     constructor({ session, mcpServer, userConfig }: ServerOptions) {
         this.session = session;
+        this.telemetry = new Telemetry(session);
         this.mcpServer = mcpServer;
         this.userConfig = userConfig;
     }
 
     async connect(transport: Transport) {
         this.mcpServer.server.registerCapabilities({ logging: {} });
-
         this.registerTools();
         this.registerResources();
 
         await initializeLogger(this.mcpServer, this.userConfig.logPath);
 
         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> {
@@ -44,7 +56,7 @@ export class Server {
 
     private registerTools() {
         for (const tool of [...AtlasTools, ...MongoDbTools]) {
-            new tool(this.session, this.userConfig).register(this.mcpServer);
+            new tool(this.session, this.userConfig, this.telemetry).register(this.mcpServer);
         }
     }
 

src/server.ts

@@ -1,5 +1,6 @@
 import { NodeDriverServiceProvider } from "@mongosh/service-provider-node-driver";
 import { ApiClient, ApiClientCredentials } from "./common/atlas/apiClient.js";
+import { Implementation } from "@modelcontextprotocol/sdk/types.js";
 
 export interface SessionOptions {
     apiBaseUrl?: string;
@@ -8,8 +9,13 @@ export interface SessionOptions {
 }
 
 export class Session {
+    sessionId?: string;
     serviceProvider?: NodeDriverServiceProvider;
     apiClient: ApiClient;
+    agentRunner?: {
+        name: string;
+        version: string;
+    };
 
     constructor({ apiBaseUrl, apiClientId, apiClientSecret }: SessionOptions = {}) {
         const credentials: ApiClientCredentials | undefined =
@@ -26,6 +32,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/session.ts

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

src/telemetry/constants.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;
+    }
+}