wip

Author: blva

package-lock.json

@@ -64,6 +64,7 @@
     "mongodb-log-writer": "^2.4.1",
     "mongodb-redact": "^1.1.6",
     "mongodb-schema": "^12.6.2",
+    "node-machine-id": "^1.1.12",
     "openapi-fetch": "^0.13.5",
     "simple-oauth2": "^5.1.0",
     "yargs-parser": "^21.1.1",

package.json

@@ -4,6 +4,7 @@ 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";
 
 const ATLAS_API_VERSION = "2025-03-12";
 
@@ -63,10 +64,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 ||
-                `${config.mcp_server_name}/${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>({
@@ -117,6 +118,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

@@ -11,6 +11,7 @@ interface UserConfig {
     apiBaseUrl?: string;
     apiClientId?: string;
     apiClientSecret?: string;
+    telemetry?: 'enabled' | 'disabled';
     logPath: string;
     connectionString?: string;
     connectOptions: {
@@ -52,7 +53,8 @@ const config = {
     ...mergedUserConfig,
     ...machineMetadata,
     version: packageJson.version,
-    mcp_server_name: "MdbMcpServer"
+    mcpServerName: "MdbMcpServer",
+    isTelemetryEnabled: true
 };
 
 export default config;

src/config.ts

@@ -25,11 +25,8 @@ export class Server {
         await this.mcpServer.connect(transport);
 
         this.mcpServer.server.oninitialized = () =>  {
-            const client = this.mcpServer.server.getClientVersion();
-            this.session.clientName = client?.name;
-            this.session.clientVersion = client?.version;
-
-            logger.info(mongoLogId(1_000_004), "server", `Server started with transport ${transport.constructor.name}`);        
+            this.session.setAgentClientData(this.mcpServer.server.getClientVersion());
+            logger.info(mongoLogId(1_000_004), "server", `Server started with transport ${transport.constructor.name}`);
         };
     }
 

src/server.ts

@@ -3,13 +3,32 @@ import { ApiClient } from "./common/atlas/apiClient.js";
 import config from "./config.js";
 import logger from "./logger.js";
 import { mongoLogId } from "mongodb-log-writer";
+import { Implementation } from "@modelcontextprotocol/sdk/types.js";
 
 export class Session {
     sessionId?: string;
     serviceProvider?: NodeDriverServiceProvider;
     apiClient?: ApiClient;
-    clientName?: string;
-    clientVersion?: string;  
+    agentClientName?: string;
+    agentClientVersion?: string; 
+
+    constructor() {
+        // configure api client if credentials are set
+        if (config.apiClientId && config.apiClientSecret) {
+            this.apiClient = new ApiClient({
+                baseUrl: config.apiBaseUrl,
+                credentials: {
+                    clientId: config.apiClientId,
+                    clientSecret: config.apiClientSecret,
+                },
+            });
+        }
+    }
+    
+    setAgentClientData(agentClient: Implementation | undefined) {
+        this.agentClientName = agentClient?.name;
+        this.agentClientVersion = agentClient?.version;
+    }
 
     ensureAuthenticated(): asserts this is { apiClient: ApiClient } {
         if (!this.apiClient) {
@@ -39,12 +58,4 @@ export class Session {
             this.serviceProvider = undefined;
         }
     }
-
-    async emitTelemetry(todo: unknown): Promise<void> {
-        logger.info(
-            mongoLogId(1_000_001),
-            "telemetry",
-            `Telemetry event: ${JSON.stringify(todo)}`
-        );
-    }
 }

src/session.ts

@@ -0,0 +1,75 @@
+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 { ApiClientError } from '../common/atlas/apiClientError.js';
+
+export class Telemetry {
+    constructor(private readonly session: Session) {}
+
+    private readonly commonProperties = {
+            mcp_server_version: pkg.version,
+            mcp_server_name: config.mcpServerName,
+            mcp_client_version: this.session.agentClientVersion,
+            mcp_client_name: this.session.agentClientName,
+            session_id: this.session.sessionId,
+            device_id: config.device_id,
+            platform: config.platform,
+            arch: config.arch,
+            os_type: config.os_type,
+            os_version: config.os_version,
+        };
+
+    private readonly isTelemetryEnabled = config.telemetry === 'enabled';
+
+    async emitToolEvent(command: string, category: string, startTime: number, result: 'success' | 'failure', error?: Error): Promise<void> {
+        if (!this.isTelemetryEnabled) {
+            logger.debug(mongoLogId(1_000_000), "telemetry", `Telemetry is disabled, skipping event.`);
+            return;
+        }
+
+        const duration = Date.now() - startTime;
+
+        const event: ToolEvent = {
+            timestamp: new Date().toISOString(),
+            source: 'mdbmcp',
+            properties: {
+                ...this.commonProperties,
+                command: command,
+                category: category,
+                duration_ms: duration,
+                result: result
+            }
+        };
+
+        if (result === 'failure') {
+            event.properties.error_type = error?.name;
+            event.properties.error_code = error?.message;
+        }
+
+        await this.emit(event);
+    }
+
+    private async emit(event: BaseEvent): Promise<void> {
+        try {
+            if (this.session.apiClient) {
+                await this.session.apiClient.sendEvents([event]);
+            }
+        } catch (error) {
+            logger.warning(mongoLogId(1_000_000), "telemetry", `Error sending event to authenticated client: ${error}`);
+        }
+
+        // if it is unauthenticated, send to temp client
+        try {
+            const tempApiClient = new ApiClient({
+                baseUrl: config.apiBaseUrl,
+            });
+            await tempApiClient.sendEvents([event]);
+        } catch (error) {
+            logger.warning(mongoLogId(1_000_000), "telemetry", `Error sending event to unauthenticated client: ${error}`);
+        }
+    }
+}

src/telemetry/telemetry.ts

@@ -0,0 +1,41 @@
+/**
+ * Base interface for all events
+ */
+export interface Event {
+    timestamp: string;
+    source: 'mdbmcp';
+    properties: Record<string, unknown>;
+}
+
+export interface BaseEvent extends Event {
+    properties: {
+        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;
+    } & Event['properties'];
+}
+
+/**
+ * Interface for tool events
+ */
+export interface ToolEvent extends BaseEvent {
+    properties: {
+        command: string;
+        category: string;
+        duration_ms: number;
+        result: 'success' | 'failure';
+        error_code?: string;
+        error_type?: string;
+        project_id?: string;
+        org_id?: string;
+        cluster_name?: string;
+        is_atlas?: boolean;
+    } & BaseEvent['properties'];
+}

src/telemetry/types.ts

@@ -1,17 +1,22 @@
-import { McpServer, ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z, ZodNever, ZodRawShape } from "zod";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z, type ZodRawShape, type ZodNever } from "zod";
+import type { McpServer, ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { Session } from "../session.js";
 import logger from "../logger.js";
 import { mongoLogId } from "mongodb-log-writer";
+<<<<<<< HEAD
 import config from "../config.js";
+=======
+import { Telemetry } from "../telemetry/telemetry.js";
+>>>>>>> 61e295a (wip)
 
 export type ToolArgs<Args extends ZodRawShape> = z.objectOutputType<Args, ZodNever>;
 
 export type OperationType = "metadata" | "read" | "create" | "delete" | "update" | "cluster";
 export type ToolCategory = "mongodb" | "atlas";
 
 export abstract class ToolBase {
+<<<<<<< HEAD
     protected abstract name: string;
 
     protected abstract category: ToolCategory;
@@ -21,37 +26,57 @@ export abstract class ToolBase {
     protected abstract description: string;
 
     protected abstract argsShape: ZodRawShape;
+=======
+    protected abstract readonly name: string;
+    protected abstract readonly description: string;
+    protected abstract readonly argsShape: ZodRawShape;
+>>>>>>> 61e295a (wip)
 
     protected abstract category: string;
+    private readonly telemetry: Telemetry;
 
     protected abstract execute(...args: Parameters<ToolCallback<typeof this.argsShape>>): Promise<CallToolResult>;
 
-    protected constructor(protected session: Session) {}
+    protected constructor(protected session: Session) {
+        this.telemetry = new Telemetry(session);
+    }
 
     public register(server: McpServer): void {
         if (!this.verifyAllowed()) {
             return;
         }
 
         const callback: ToolCallback<typeof this.argsShape> = async (...args) => {
+            const startTime = Date.now();
             try {
                 logger.debug(
                     mongoLogId(1_000_006),
                     "tool",
                     `Executing ${this.name} with args: ${JSON.stringify(args)}`
                 );
 
-                return await this.execute(...args);
+                const result = await this.execute(...args);
+                await this.telemetry.emitToolEvent(this.name, this.category, startTime, "success");
+                return result;
             } catch (error: unknown) {
                 logger.error(mongoLogId(1_000_000), "tool", `Error executing ${this.name}: ${error as string}`);
 
+                await this.telemetry.emitToolEvent(
+                    this.name,
+                    this.category,
+                    startTime,
+                    "failure",
+                    error instanceof Error ? error : new Error(String(error))
+                );
+
                 return await this.handleError(error);
             }
         };
 
         server.tool(this.name, this.description, this.argsShape, callback);
     }
 
+<<<<<<< HEAD
     // Checks if a tool is allowed to run based on the config
     private verifyAllowed(): boolean {
         let errorClarification: string | undefined;
@@ -76,6 +101,8 @@ export abstract class ToolBase {
         return true;
     }
 
+=======
+>>>>>>> 61e295a (wip)
     // This method is intended to be overridden by subclasses to handle errors
     protected handleError(error: unknown): Promise<CallToolResult> | CallToolResult {
         return {