mongodb-mcp-server 0.1.0 → 0.1.2

package/src/helpers/EJsonTransport.ts

@@ -0,0 +1,47 @@
+import { JSONRPCMessage, JSONRPCMessageSchema } from "@modelcontextprotocol/sdk/types.js";
+import { EJSON } from "bson";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// This is almost a copy of ReadBuffer from @modelcontextprotocol/sdk
+// but it uses EJSON.parse instead of JSON.parse to handle BSON types
+export class EJsonReadBuffer {
+    private _buffer?: Buffer;
+
+    append(chunk: Buffer): void {
+        this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
+    }
+
+    readMessage(): JSONRPCMessage | null {
+        if (!this._buffer) {
+            return null;
+        }
+
+        const index = this._buffer.indexOf("\n");
+        if (index === -1) {
+            return null;
+        }
+
+        const line = this._buffer.toString("utf8", 0, index).replace(/\r$/, "");
+        this._buffer = this._buffer.subarray(index + 1);
+
+        // This is using EJSON.parse instead of JSON.parse to handle BSON types
+        return JSONRPCMessageSchema.parse(EJSON.parse(line));
+    }
+
+    clear(): void {
+        this._buffer = undefined;
+    }
+}
+
+// This is a hacky workaround for https://github.com/mongodb-js/mongodb-mcp-server/issues/211
+// The underlying issue is that StdioServerTransport uses JSON.parse to deserialize
+// messages, but that doesn't handle bson types, such as ObjectId when serialized as EJSON.
+//
+// This function creates a StdioServerTransport and replaces the internal readBuffer with EJsonReadBuffer
+// that uses EJson.parse instead.
+export function createEJsonTransport(): StdioServerTransport {
+    const server = new StdioServerTransport();
+    server["_readBuffer"] = new EJsonReadBuffer();
+
+    return server;
+}

package/src/helpers/connectionOptions.ts

@@ -0,0 +1,20 @@
+import { MongoClientOptions } from "mongodb";
+import ConnectionString from "mongodb-connection-string-url";
+
+export function setAppNameParamIfMissing({
+    connectionString,
+    defaultAppName,
+}: {
+    connectionString: string;
+    defaultAppName?: string;
+}): string {
+    const connectionStringUrl = new ConnectionString(connectionString);
+
+    const searchParams = connectionStringUrl.typedSearchParams<MongoClientOptions>();
+
+    if (!searchParams.has("appName") && defaultAppName !== undefined) {
+        searchParams.set("appName", defaultAppName);
+    }
+
+    return connectionStringUrl.toString();
+}

package/src/{packageInfo.ts → helpers/packageInfo.ts}

@@ -1,4 +1,4 @@
-import packageJson from "../package.json" with { type: "json" };
+import packageJson from "../../package.json" with { type: "json" };
 
 export const packageInfo = {
     version: packageJson.version,

package/src/index.ts

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import logger, { LogId } from "./logger.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { config } from "./config.js";
 import { Session } from "./session.js";
 import { Server } from "./server.js";
-import { packageInfo } from "./packageInfo.js";
+import { packageInfo } from "./helpers/packageInfo.js";
+import { Telemetry } from "./telemetry/telemetry.js";
+import { createEJsonTransport } from "./helpers/EJsonTransport.js";
 
 try {
     const session = new Session({
@@ -19,13 +20,36 @@ try {
         version: packageInfo.version,
     });
 
+    const telemetry = Telemetry.create(session, config);
+
     const server = new Server({
         mcpServer,
         session,
+        telemetry,
         userConfig: config,
     });
 
-    const transport = new StdioServerTransport();
+    const transport = createEJsonTransport();
+
+    const shutdown = () => {
+        logger.info(LogId.serverCloseRequested, "server", `Server close requested`);
+
+        server
+            .close()
+            .then(() => {
+                logger.info(LogId.serverClosed, "server", `Server closed successfully`);
+                process.exit(0);
+            })
+            .catch((err: unknown) => {
+                const error = err instanceof Error ? err : new Error(String(err));
+                logger.error(LogId.serverCloseFailure, "server", `Error closing server: ${error.message}`);
+                process.exit(1);
+            });
+    };
+
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    process.once("SIGQUIT", shutdown);
 
     await server.connect(transport);
 } catch (error: unknown) {

package/src/logger.ts

@@ -9,10 +9,14 @@ export type LogLevel = LoggingMessageNotification["params"]["level"];
 export const LogId = {
     serverStartFailure: mongoLogId(1_000_001),
     serverInitialized: mongoLogId(1_000_002),
+    serverCloseRequested: mongoLogId(1_000_003),
+    serverClosed: mongoLogId(1_000_004),
+    serverCloseFailure: mongoLogId(1_000_005),
 
     atlasCheckCredentials: mongoLogId(1_001_001),
     atlasDeleteDatabaseUserFailure: mongoLogId(1_001_002),
     atlasConnectFailure: mongoLogId(1_001_003),
+    atlasInspectFailure: mongoLogId(1_001_004),
 
     telemetryDisabled: mongoLogId(1_002_001),
     telemetryEmitFailure: mongoLogId(1_002_002),
@@ -20,6 +24,8 @@ export const LogId = {
     telemetryEmitSuccess: mongoLogId(1_002_004),
     telemetryMetadataError: mongoLogId(1_002_005),
     telemetryDeviceIdFailure: mongoLogId(1_002_006),
+    telemetryDeviceIdTimeout: mongoLogId(1_002_007),
+    telemetryContainerEnvFailure: mongoLogId(1_002_008),
 
     toolExecute: mongoLogId(1_003_001),
     toolExecuteFailure: mongoLogId(1_003_002),
@@ -27,6 +33,8 @@ export const LogId = {
 
     mongodbConnectFailure: mongoLogId(1_004_001),
     mongodbDisconnectFailure: mongoLogId(1_004_002),
+
+    toolUpdateFailure: mongoLogId(1_005_001),
 } as const;
 
 abstract class LoggerBase {

package/src/server.ts

@@ -16,6 +16,7 @@ export interface ServerOptions {
     session: Session;
     userConfig: UserConfig;
     mcpServer: McpServer;
+    telemetry: Telemetry;
 }
 
 export class Server {
@@ -25,10 +26,10 @@ export class Server {
     public readonly userConfig: UserConfig;
     private readonly startTime: number;
 
-    constructor({ session, mcpServer, userConfig }: ServerOptions) {
+    constructor({ session, mcpServer, userConfig, telemetry }: ServerOptions) {
         this.startTime = Date.now();
         this.session = session;
-        this.telemetry = new Telemetry(session, userConfig);
+        this.telemetry = telemetry;
         this.mcpServer = mcpServer;
         this.userConfig = userConfig;
     }
@@ -93,6 +94,7 @@ export class Server {
     }
 
     async close(): Promise<void> {
+        await this.telemetry.close();
         await this.session.close();
         await this.mcpServer.close();
     }
@@ -102,7 +104,7 @@ export class Server {
      * @param command - The server command (e.g., "start", "stop", "register", "deregister")
      * @param additionalProperties - Additional properties specific to the event
      */
-    emitServerEvent(command: ServerCommand, commandDuration: number, error?: Error) {
+    private emitServerEvent(command: ServerCommand, commandDuration: number, error?: Error) {
         const event: ServerEvent = {
             timestamp: new Date().toISOString(),
             source: "mdbmcp",
@@ -128,7 +130,7 @@ export class Server {
             }
         }
 
-        this.telemetry.emitEvents([event]).catch(() => {});
+        this.telemetry.emitEvents([event]);
     }
 
     private registerTools() {
@@ -172,17 +174,6 @@ export class Server {
     }
 
     private async validateConfig(): Promise<void> {
-        const isAtlasConfigured = this.userConfig.apiClientId && this.userConfig.apiClientSecret;
-        const isMongoDbConfigured = this.userConfig.connectionString;
-        if (!isAtlasConfigured && !isMongoDbConfigured) {
-            console.error(
-                "Either Atlas Client Id or a MongoDB connection string must be configured - you can provide them as environment variables or as startup arguments. \n" +
-                    "Provide the Atlas credentials as `MDB_MCP_API_CLIENT_ID` and `MDB_MCP_API_CLIENT_SECRET` environment variables or as `--apiClientId` and `--apiClientSecret` startup arguments. \n" +
-                    "Provide the MongoDB connection string as `MDB_MCP_CONNECTION_STRING` environment variable or as `--connectionString` startup argument."
-            );
-            throw new Error("Either Atlas Client Id or a MongoDB connection string must be configured");
-        }
-
         if (this.userConfig.connectionString) {
             try {
                 await this.session.connectToMongoDB(this.userConfig.connectionString, this.userConfig.connectOptions);
@@ -194,5 +185,22 @@ export class Server {
                 throw new Error("Failed to connect to MongoDB instance using the connection string from the config");
             }
         }
+
+        if (this.userConfig.apiClientId && this.userConfig.apiClientSecret) {
+            try {
+                await this.session.apiClient.validateAccessToken();
+            } catch (error) {
+                if (this.userConfig.connectionString === undefined) {
+                    console.error("Failed to validate MongoDB Atlas the credentials from the config: ", error);
+
+                    throw new Error(
+                        "Failed to connect to MongoDB Atlas instance using the credentials from the config"
+                    );
+                }
+                console.error(
+                    "Failed to validate MongoDB Atlas the credentials from the config, but validated the connection string."
+                );
+            }
+        }
     }
 }

package/src/session.ts

@@ -4,6 +4,8 @@ import { Implementation } from "@modelcontextprotocol/sdk/types.js";
 import logger, { LogId } from "./logger.js";
 import EventEmitter from "events";
 import { ConnectOptions } from "./config.js";
+import { setAppNameParamIfMissing } from "./helpers/connectionOptions.js";
+import { packageInfo } from "./helpers/packageInfo.js";
 
 export interface SessionOptions {
     apiBaseUrl: string;
@@ -98,8 +100,12 @@ export class Session extends EventEmitter<{
     }
 
     async connectToMongoDB(connectionString: string, connectOptions: ConnectOptions): Promise<void> {
-        const provider = await NodeDriverServiceProvider.connect(connectionString, {
-            productDocsLink: "https://docs.mongodb.com/todo-mcp",
+        connectionString = setAppNameParamIfMissing({
+            connectionString,
+            defaultAppName: `${packageInfo.mcpServerName} ${packageInfo.version}`,
+        });
+        this.serviceProvider = await NodeDriverServiceProvider.connect(connectionString, {
+            productDocsLink: "https://github.com/mongodb-js/mongodb-mcp-server/",
             productName: "MongoDB MCP",
             readConcern: {
                 level: connectOptions.readConcern,
@@ -110,7 +116,5 @@ export class Session extends EventEmitter<{
             },
             timeoutMS: connectOptions.timeoutMS,
         });
-
-        this.serviceProvider = provider;
     }
 }

package/src/telemetry/constants.ts

@@ -1,11 +1,10 @@
-import { packageInfo } from "../packageInfo.js";
+import { packageInfo } from "../helpers/packageInfo.js";
 import { type CommonStaticProperties } from "./types.js";
-import { getDeviceId } from "./device-id.js";
+
 /**
  * Machine-specific metadata formatted for telemetry
  */
 export const MACHINE_METADATA: CommonStaticProperties = {
-    device_id: getDeviceId(),
     mcp_server_version: packageInfo.version,
     mcp_server_name: packageInfo.mcpServerName,
     platform: process.platform,

package/src/telemetry/eventCache.ts

@@ -1,5 +1,5 @@
-import { BaseEvent } from "./types.js";
 import { LRUCache } from "lru-cache";
+import { BaseEvent } from "./types.js";
 
 /**
  * Singleton class for in-memory telemetry event caching

package/src/telemetry/telemetry.ts

@@ -5,55 +5,154 @@ import logger, { LogId } from "../logger.js";
 import { ApiClient } from "../common/atlas/apiClient.js";
 import { MACHINE_METADATA } from "./constants.js";
 import { EventCache } from "./eventCache.js";
+import nodeMachineId from "node-machine-id";
+import { getDeviceId } from "@mongodb-js/device-id";
+import fs from "fs/promises";
 
-type EventResult = {
-    success: boolean;
-    error?: Error;
-};
+async function fileExists(filePath: string): Promise<boolean> {
+    try {
+        await fs.access(filePath, fs.constants.F_OK);
+        return true; // File exists
+    } catch (e: unknown) {
+        if (
+            e instanceof Error &&
+            (
+                e as Error & {
+                    code: string;
+                }
+            ).code === "ENOENT"
+        ) {
+            return false; // File does not exist
+        }
+        throw e; // Re-throw unexpected errors
+    }
+}
+
+async function isContainerized(): Promise<boolean> {
+    if (process.env.container) {
+        return true;
+    }
+
+    const exists = await Promise.all(["/.dockerenv", "/run/.containerenv", "/var/run/.containerenv"].map(fileExists));
+
+    return exists.includes(true);
+}
 
 export class Telemetry {
-    private readonly commonProperties: CommonProperties;
+    private deviceIdAbortController = new AbortController();
+    private eventCache: EventCache;
+    private getRawMachineId: () => Promise<string>;
+    private getContainerEnv: () => Promise<boolean>;
+    private cachedCommonProperties?: CommonProperties;
+    private flushing: boolean = false;
 
-    constructor(
+    private constructor(
         private readonly session: Session,
         private readonly userConfig: UserConfig,
-        private readonly eventCache: EventCache = EventCache.getInstance()
+        {
+            eventCache,
+            getRawMachineId,
+            getContainerEnv,
+        }: {
+            eventCache: EventCache;
+            getRawMachineId: () => Promise<string>;
+            getContainerEnv: () => Promise<boolean>;
+        }
     ) {
-        this.commonProperties = {
-            ...MACHINE_METADATA,
-        };
+        this.eventCache = eventCache;
+        this.getRawMachineId = getRawMachineId;
+        this.getContainerEnv = getContainerEnv;
+    }
+
+    static create(
+        session: Session,
+        userConfig: UserConfig,
+        {
+            eventCache = EventCache.getInstance(),
+            getRawMachineId = () => nodeMachineId.machineId(true),
+            getContainerEnv = isContainerized,
+        }: {
+            eventCache?: EventCache;
+            getRawMachineId?: () => Promise<string>;
+            getContainerEnv?: () => Promise<boolean>;
+        } = {}
+    ): Telemetry {
+        const instance = new Telemetry(session, userConfig, {
+            eventCache,
+            getRawMachineId,
+            getContainerEnv,
+        });
+
+        return instance;
+    }
+
+    public async close(): Promise<void> {
+        this.deviceIdAbortController.abort();
+        await this.flush();
     }
 
     /**
      * Emits events through the telemetry pipeline
      * @param events - The events to emit
      */
-    public async emitEvents(events: BaseEvent[]): Promise<void> {
-        try {
-            if (!this.isTelemetryEnabled()) {
-                logger.info(LogId.telemetryEmitFailure, "telemetry", `Telemetry is disabled.`);
-                return;
-            }
-
-            await this.emit(events);
-        } catch {
-            logger.debug(LogId.telemetryEmitFailure, "telemetry", `Error emitting telemetry events.`);
-        }
+    public emitEvents(events: BaseEvent[]): void {
+        void this.flush(events);
     }
 
     /**
      * Gets the common properties for events
      * @returns Object containing common properties for all events
      */
-    public getCommonProperties(): CommonProperties {
-        return {
-            ...this.commonProperties,
-            mcp_client_version: this.session.agentRunner?.version,
-            mcp_client_name: this.session.agentRunner?.name,
-            session_id: this.session.sessionId,
-            config_atlas_auth: this.session.apiClient.hasCredentials() ? "true" : "false",
-            config_connection_string: this.userConfig.connectionString ? "true" : "false",
-        };
+    private async getCommonProperties(): Promise<CommonProperties> {
+        if (!this.cachedCommonProperties) {
+            let deviceId: string | undefined;
+            let containerEnv: boolean | undefined;
+            try {
+                await Promise.all([
+                    getDeviceId({
+                        getMachineId: () => this.getRawMachineId(),
+                        onError: (reason, error) => {
+                            switch (reason) {
+                                case "resolutionError":
+                                    logger.debug(LogId.telemetryDeviceIdFailure, "telemetry", String(error));
+                                    break;
+                                case "timeout":
+                                    logger.debug(
+                                        LogId.telemetryDeviceIdTimeout,
+                                        "telemetry",
+                                        "Device ID retrieval timed out"
+                                    );
+                                    break;
+                                case "abort":
+                                    // No need to log in the case of aborts
+                                    break;
+                            }
+                        },
+                        abortSignal: this.deviceIdAbortController.signal,
+                    }).then((id) => {
+                        deviceId = id;
+                    }),
+                    this.getContainerEnv().then((env) => {
+                        containerEnv = env;
+                    }),
+                ]);
+            } catch (error: unknown) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                logger.debug(LogId.telemetryDeviceIdFailure, "telemetry", err.message);
+            }
+            this.cachedCommonProperties = {
+                ...MACHINE_METADATA,
+                mcp_client_version: this.session.agentRunner?.version,
+                mcp_client_name: this.session.agentRunner?.name,
+                session_id: this.session.sessionId,
+                config_atlas_auth: this.session.apiClient.hasCredentials() ? "true" : "false",
+                config_connection_string: this.userConfig.connectionString ? "true" : "false",
+                is_container_env: containerEnv ? "true" : "false",
+                device_id: deviceId,
+            };
+        }
+
+        return this.cachedCommonProperties;
     }
 
     /**
@@ -74,55 +173,74 @@ export class Telemetry {
     }
 
     /**
-     * Attempts to emit events through authenticated and unauthenticated clients
+     * Attempts to flush events through authenticated and unauthenticated clients
      * Falls back to caching if both attempts fail
      */
-    private async emit(events: BaseEvent[]): Promise<void> {
-        const cachedEvents = this.eventCache.getEvents();
-        const allEvents = [...cachedEvents, ...events];
-
-        logger.debug(
-            LogId.telemetryEmitStart,
-            "telemetry",
-            `Attempting to send ${allEvents.length} events (${cachedEvents.length} cached)`
-        );
+    public async flush(events?: BaseEvent[]): Promise<void> {
+        if (!this.isTelemetryEnabled()) {
+            logger.info(LogId.telemetryEmitFailure, "telemetry", `Telemetry is disabled.`);
+            return;
+        }
+
+        if (this.flushing) {
+            this.eventCache.appendEvents(events ?? []);
+            process.nextTick(async () => {
+                // try again if in the middle of a flush
+                await this.flush();
+            });
+            return;
+        }
+
+        this.flushing = true;
+
+        try {
+            const cachedEvents = this.eventCache.getEvents();
+            const allEvents = [...cachedEvents, ...(events ?? [])];
+            if (allEvents.length <= 0) {
+                this.flushing = false;
+                return;
+            }
+
+            logger.debug(
+                LogId.telemetryEmitStart,
+                "telemetry",
+                `Attempting to send ${allEvents.length} events (${cachedEvents.length} cached)`
+            );
 
-        const result = await this.sendEvents(this.session.apiClient, allEvents);
-        if (result.success) {
+            await this.sendEvents(this.session.apiClient, allEvents);
             this.eventCache.clearEvents();
             logger.debug(
                 LogId.telemetryEmitSuccess,
                 "telemetry",
                 `Sent ${allEvents.length} events successfully: ${JSON.stringify(allEvents, null, 2)}`
             );
-            return;
+        } catch (error: unknown) {
+            logger.debug(
+                LogId.telemetryEmitFailure,
+                "telemetry",
+                `Error sending event to client: ${error instanceof Error ? error.message : String(error)}`
+            );
+            this.eventCache.appendEvents(events ?? []);
+            process.nextTick(async () => {
+                // try again
+                await this.flush();
+            });
         }
 
-        logger.debug(
-            LogId.telemetryEmitFailure,
-            "telemetry",
-            `Error sending event to client: ${result.error instanceof Error ? result.error.message : String(result.error)}`
-        );
-        this.eventCache.appendEvents(events);
+        this.flushing = false;
     }
 
     /**
      * Attempts to send events through the provided API client
      */
-    private async sendEvents(client: ApiClient, events: BaseEvent[]): Promise<EventResult> {
-        try {
-            await client.sendEvents(
-                events.map((event) => ({
-                    ...event,
-                    properties: { ...this.getCommonProperties(), ...event.properties },
-                }))
-            );
-            return { success: true };
-        } catch (error) {
-            return {
-                success: false,
-                error: error instanceof Error ? error : new Error(String(error)),
-            };
-        }
+    private async sendEvents(client: ApiClient, events: BaseEvent[]): Promise<void> {
+        const commonProperties = await this.getCommonProperties();
+
+        await client.sendEvents(
+            events.map((event) => ({
+                ...event,
+                properties: { ...commonProperties, ...event.properties },
+            }))
+        );
     }
 }

package/src/telemetry/types.ts

@@ -53,7 +53,6 @@ export type ServerEvent = TelemetryEvent<ServerEventProperties>;
  * Interface for static properties, they can be fetched once and reused.
  */
 export type CommonStaticProperties = {
-    device_id?: string;
     mcp_server_version: string;
     mcp_server_name: string;
     platform: string;
@@ -72,4 +71,5 @@ export type CommonProperties = {
     config_atlas_auth?: TelemetryBoolSet;
     config_connection_string?: TelemetryBoolSet;
     session_id?: string;
+    is_container_env?: TelemetryBoolSet;
 } & CommonStaticProperties;

package/src/tools/atlas/atlasTool.ts

@@ -1,7 +1,9 @@
-import { ToolBase, ToolCategory, TelemetryToolMetadata } from "../tool.js";
+import { ToolBase, ToolCategory, TelemetryToolMetadata, ToolArgs } from "../tool.js";
 import { ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import logger, { LogId } from "../../logger.js";
 import { z } from "zod";
+import { ApiClientError } from "../../common/atlas/apiClientError.js";
 
 export abstract class AtlasToolBase extends ToolBase {
     protected category: ToolCategory = "atlas";
@@ -13,6 +15,50 @@ export abstract class AtlasToolBase extends ToolBase {
         return super.verifyAllowed();
     }
 
+    protected handleError(
+        error: unknown,
+        args: ToolArgs<typeof this.argsShape>
+    ): Promise<CallToolResult> | CallToolResult {
+        if (error instanceof ApiClientError) {
+            const statusCode = error.response.status;
+
+            if (statusCode === 401) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unable to authenticate with MongoDB Atlas, API error: ${error.message}
+
+Hint: Your API credentials may be invalid, expired or lack permissions. 
+Please check your Atlas API credentials and ensure they have the appropriate permissions.
+For more information on setting up API keys, visit: https://www.mongodb.com/docs/atlas/configure-api-access/`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+
+            if (statusCode === 403) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Received a Forbidden API Error: ${error.message}
+                            
+You don't have sufficient permissions to perform this action in MongoDB Atlas
+Please ensure your API key has the necessary roles assigned.
+For more information on Atlas API access roles, visit: https://www.mongodb.com/docs/atlas/api/service-accounts-overview/`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+
+        // For other types of errors, use the default error handling from the base class
+        return super.handleError(error, args);
+    }
+
     /**
      *
      * Resolves the tool metadata from the arguments passed to the tool