mongodb-mcp-server 0.0.8 → 0.1.1

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,16 @@ 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();
 
     await server.connect(transport);
 } catch (error: unknown) {

package/src/logger.ts

@@ -13,6 +13,7 @@ export const LogId = {
     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 +21,7 @@ export const LogId = {
     telemetryEmitSuccess: mongoLogId(1_002_004),
     telemetryMetadataError: mongoLogId(1_002_005),
     telemetryDeviceIdFailure: mongoLogId(1_002_006),
+    telemetryDeviceIdTimeout: mongoLogId(1_002_007),
 
     toolExecute: mongoLogId(1_003_001),
     toolExecuteFailure: mongoLogId(1_003_002),

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",
@@ -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,23 +5,84 @@ 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";
 
 type EventResult = {
     success: boolean;
     error?: Error;
 };
 
+export const DEVICE_ID_TIMEOUT = 3000;
+
 export class Telemetry {
-    private readonly commonProperties: CommonProperties;
+    private isBufferingEvents: boolean = true;
+    /** Resolves when the device ID is retrieved or timeout occurs */
+    public deviceIdPromise: Promise<string> | undefined;
+    private deviceIdAbortController = new AbortController();
+    private eventCache: EventCache;
+    private getRawMachineId: () => Promise<string>;
 
-    constructor(
+    private constructor(
         private readonly session: Session,
         private readonly userConfig: UserConfig,
-        private readonly eventCache: EventCache = EventCache.getInstance()
+        private readonly commonProperties: CommonProperties,
+        { eventCache, getRawMachineId }: { eventCache: EventCache; getRawMachineId: () => Promise<string> }
     ) {
-        this.commonProperties = {
-            ...MACHINE_METADATA,
-        };
+        this.eventCache = eventCache;
+        this.getRawMachineId = getRawMachineId;
+    }
+
+    static create(
+        session: Session,
+        userConfig: UserConfig,
+        {
+            commonProperties = { ...MACHINE_METADATA },
+            eventCache = EventCache.getInstance(),
+            getRawMachineId = () => nodeMachineId.machineId(true),
+        }: {
+            eventCache?: EventCache;
+            getRawMachineId?: () => Promise<string>;
+            commonProperties?: CommonProperties;
+        } = {}
+    ): Telemetry {
+        const instance = new Telemetry(session, userConfig, commonProperties, { eventCache, getRawMachineId });
+
+        void instance.start();
+        return instance;
+    }
+
+    private async start(): Promise<void> {
+        if (!this.isTelemetryEnabled()) {
+            return;
+        }
+        this.deviceIdPromise = 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,
+        });
+
+        this.commonProperties.device_id = await this.deviceIdPromise;
+
+        this.isBufferingEvents = false;
+    }
+
+    public async close(): Promise<void> {
+        this.deviceIdAbortController.abort();
+        this.isBufferingEvents = false;
+        await this.emitEvents(this.eventCache.getEvents());
     }
 
     /**
@@ -78,6 +139,11 @@ export class Telemetry {
      * Falls back to caching if both attempts fail
      */
     private async emit(events: BaseEvent[]): Promise<void> {
+        if (this.isBufferingEvents) {
+            this.eventCache.appendEvents(events);
+            return;
+        }
+
         const cachedEvents = this.eventCache.getEvents();
         const allEvents = [...cachedEvents, ...events];
 

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;

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

package/src/tools/atlas/create/createDBUser.ts

@@ -3,6 +3,7 @@ import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { AtlasToolBase } from "../atlasTool.js";
 import { ToolArgs, OperationType } from "../../tool.js";
 import { CloudDatabaseUser, DatabaseUserRole } from "../../../common/atlas/openapi.js";
+import { generateSecurePassword } from "../../../common/atlas/generatePassword.js";
 
 export class CreateDBUserTool extends AtlasToolBase {
     protected name = "atlas-create-db-user";
@@ -11,7 +12,16 @@ export class CreateDBUserTool extends AtlasToolBase {
     protected argsShape = {
         projectId: z.string().describe("Atlas project ID"),
         username: z.string().describe("Username for the new user"),
-        password: z.string().describe("Password for the new user"),
+        // Models will generate overly simplistic passwords like SecurePassword123 or
+        // AtlasPassword123, which are easily guessable and exploitable. We're instructing
+        // the model not to try and generate anything and instead leave the field unset.
+        password: z
+            .string()
+            .optional()
+            .nullable()
+            .describe(
+                "Password for the new user. If the user hasn't supplied an explicit password, leave it unset and under no circumstances try to generate a random one. A secure password will be generated by the MCP server if necessary."
+            ),
         roles: z
             .array(
                 z.object({
@@ -34,6 +44,11 @@ export class CreateDBUserTool extends AtlasToolBase {
         roles,
         clusters,
     }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const shouldGeneratePassword = !password;
+        if (shouldGeneratePassword) {
+            password = await generateSecurePassword();
+        }
+
         const input = {
             groupId: projectId,
             awsIAMType: "NONE",
@@ -62,7 +77,12 @@ export class CreateDBUserTool extends AtlasToolBase {
         });
 
         return {
-            content: [{ type: "text", text: `User "${username}" created sucessfully.` }],
+            content: [
+                {
+                    type: "text",
+                    text: `User "${username}" created successfully${shouldGeneratePassword ? ` with password: \`${password}\`` : ""}.`,
+                },
+            ],
         };
     }
 }

package/src/tools/atlas/metadata/connectCluster.ts

@@ -2,24 +2,15 @@ import { z } from "zod";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { AtlasToolBase } from "../atlasTool.js";
 import { ToolArgs, OperationType } from "../../tool.js";
-import { randomBytes } from "crypto";
-import { promisify } from "util";
+import { generateSecurePassword } from "../../../common/atlas/generatePassword.js";
 import logger, { LogId } from "../../../logger.js";
+import { inspectCluster } from "../../../common/atlas/cluster.js";
 
 const EXPIRY_MS = 1000 * 60 * 60 * 12; // 12 hours
 
-const randomBytesAsync = promisify(randomBytes);
-
-async function generateSecurePassword(): Promise<string> {
-    const buf = await randomBytesAsync(16);
-    const pass = buf.toString("base64url");
-    return pass;
-}
-
 function sleep(ms: number): Promise<void> {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-
 export class ConnectClusterTool extends AtlasToolBase {
     protected name = "atlas-connect-cluster";
     protected description = "Connect to MongoDB Atlas cluster";
@@ -32,22 +23,9 @@ export class ConnectClusterTool extends AtlasToolBase {
     protected async execute({ projectId, clusterName }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
         await this.session.disconnect();
 
-        const cluster = await this.session.apiClient.getCluster({
-            params: {
-                path: {
-                    groupId: projectId,
-                    clusterName,
-                },
-            },
-        });
-
-        if (!cluster) {
-            throw new Error("Cluster not found");
-        }
-
-        const baseConnectionString = cluster.connectionStrings?.standardSrv || cluster.connectionStrings?.standard;
+        const cluster = await inspectCluster(this.session.apiClient, projectId, clusterName);
 
-        if (!baseConnectionString) {
+        if (!cluster.connectionString) {
             throw new Error("Connection string not available");
         }
 
@@ -99,7 +77,7 @@ export class ConnectClusterTool extends AtlasToolBase {
             expiryDate,
         };
 
-        const cn = new URL(baseConnectionString);
+        const cn = new URL(cluster.connectionString);
         cn.username = username;
         cn.password = password;
         cn.searchParams.set("authSource", "admin");

package/src/tools/atlas/read/inspectCluster.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { AtlasToolBase } from "../atlasTool.js";
 import { ToolArgs, OperationType } from "../../tool.js";
-import { ClusterDescription20240805 } from "../../../common/atlas/openapi.js";
+import { Cluster, inspectCluster } from "../../../common/atlas/cluster.js";
 
 export class InspectClusterTool extends AtlasToolBase {
     protected name = "atlas-inspect-cluster";
@@ -14,55 +14,19 @@ export class InspectClusterTool extends AtlasToolBase {
     };
 
     protected async execute({ projectId, clusterName }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        const cluster = await this.session.apiClient.getCluster({
-            params: {
-                path: {
-                    groupId: projectId,
-                    clusterName,
-                },
-            },
-        });
+        const cluster = await inspectCluster(this.session.apiClient, projectId, clusterName);
 
         return this.formatOutput(cluster);
     }
 
-    private formatOutput(cluster?: ClusterDescription20240805): CallToolResult {
-        if (!cluster) {
-            throw new Error("Cluster not found");
-        }
-
-        const regionConfigs = (cluster.replicationSpecs || [])
-            .map(
-                (replicationSpec) =>
-                    (replicationSpec.regionConfigs || []) as {
-                        providerName: string;
-                        electableSpecs?: {
-                            instanceSize: string;
-                        };
-                        readOnlySpecs?: {
-                            instanceSize: string;
-                        };
-                    }[]
-            )
-            .flat()
-            .map((regionConfig) => {
-                return {
-                    providerName: regionConfig.providerName,
-                    instanceSize: regionConfig.electableSpecs?.instanceSize || regionConfig.readOnlySpecs?.instanceSize,
-                };
-            });
-
-        const instanceSize = (regionConfigs.length <= 0 ? undefined : regionConfigs[0].instanceSize) || "UNKNOWN";
-
-        const clusterInstanceType = instanceSize == "M0" ? "FREE" : "DEDICATED";
-
+    private formatOutput(formattedCluster: Cluster): CallToolResult {
         return {
             content: [
                 {
                     type: "text",
                     text: `Cluster Name | Cluster Type | Tier | State | MongoDB Version | Connection String
 ----------------|----------------|----------------|----------------|----------------|----------------
-${cluster.name} | ${clusterInstanceType} | ${clusterInstanceType == "DEDICATED" ? instanceSize : "N/A"} | ${cluster.stateName} | ${cluster.mongoDBVersion || "N/A"} | ${cluster.connectionStrings?.standardSrv || cluster.connectionStrings?.standard || "N/A"}`,
+${formattedCluster.name || "Unknown"} | ${formattedCluster.instanceType} | ${formattedCluster.instanceSize || "N/A"} | ${formattedCluster.state || "UNKNOWN"} | ${formattedCluster.mongoDBVersion || "N/A"} | ${formattedCluster.connectionString || "N/A"}`,
                 },
             ],
         };