Merge branch 'main' into dependabot/npm_and_yarn/mongosh/arg-parser-3.16.0

Author: kmruiz

src/common/atlas/accessListUtils.ts

@@ -22,8 +22,9 @@ export async function makeCurrentIpAccessListEntry(
  * If the IP is already present, this is a no-op.
  * @param apiClient The Atlas API client instance
  * @param projectId The Atlas project ID
+ * @returns Promise<boolean> - true if a new IP access list entry was created, false if it already existed
  */
-export async function ensureCurrentIpInAccessList(apiClient: ApiClient, projectId: string): Promise<void> {
+export async function ensureCurrentIpInAccessList(apiClient: ApiClient, projectId: string): Promise<boolean> {
     const entry = await makeCurrentIpAccessListEntry(apiClient, projectId, DEFAULT_ACCESS_LIST_COMMENT);
     try {
         await apiClient.createProjectIpAccessList({
@@ -35,6 +36,7 @@ export async function ensureCurrentIpInAccessList(apiClient: ApiClient, projectI
             context: "accessListUtils",
             message: `IP access list created: ${JSON.stringify(entry)}`,
         });
+        return true;
     } catch (err) {
         if (err instanceof ApiClientError && err.response?.status === 409) {
             // 409 Conflict: entry already exists, log info
@@ -43,12 +45,13 @@ export async function ensureCurrentIpInAccessList(apiClient: ApiClient, projectI
                 context: "accessListUtils",
                 message: `IP address ${entry.ipAddress} is already present in the access list for project ${projectId}.`,
             });
-            return;
+            return false;
         }
         apiClient.logger.warning({
             id: LogId.atlasIpAccessListAddFailure,
             context: "accessListUtils",
             message: `Error adding IP access list: ${err instanceof Error ? err.message : String(err)}`,
         });
     }
+    return false;
 }

src/common/connectionErrorHandler.ts

@@ -0,0 +1,82 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { ErrorCodes, type MongoDBError } from "./errors.js";
+import type { AnyConnectionState } from "./connectionManager.js";
+import type { ToolBase } from "../tools/tool.js";
+
+export type ConnectionErrorHandler = (
+    error: MongoDBError<ErrorCodes.NotConnectedToMongoDB | ErrorCodes.MisconfiguredConnectionString>,
+    additionalContext: ConnectionErrorHandlerContext
+) => ConnectionErrorUnhandled | ConnectionErrorHandled;
+
+export type ConnectionErrorHandlerContext = { availableTools: ToolBase[]; connectionState: AnyConnectionState };
+export type ConnectionErrorUnhandled = { errorHandled: false };
+export type ConnectionErrorHandled = { errorHandled: true; result: CallToolResult };
+
+export const connectionErrorHandler: ConnectionErrorHandler = (error, { availableTools, connectionState }) => {
+    const connectTools = availableTools
+        .filter((t) => t.operationType === "connect")
+        .sort((a, b) => a.category.localeCompare(b.category)); // Sort Atlas tools before MongoDB tools
+
+    // Find the first Atlas connect tool if available and suggest to the LLM to use it.
+    // Note: if we ever have multiple Atlas connect tools, we may want to refine this logic to select the most appropriate one.
+    const atlasConnectTool = connectTools?.find((t) => t.category === "atlas");
+    const llmConnectHint = atlasConnectTool
+        ? `Note to LLM: prefer using the "${atlasConnectTool.name}" tool to connect to an Atlas cluster over using a connection string. Make sure to ask the user to specify a cluster name they want to connect to or ask them if they want to use the "list-clusters" tool to list all their clusters. Do not invent cluster names or connection strings unless the user has explicitly specified them. If they've previously connected to MongoDB using MCP, you can ask them if they want to reconnect using the same cluster/connection.`
+        : "Note to LLM: do not invent connection strings and explicitly ask the user to provide one. If they have previously connected to MongoDB using MCP, you can ask them if they want to reconnect using the same connection string.";
+
+    const connectToolsNames = connectTools?.map((t) => `"${t.name}"`).join(", ");
+    const additionalPromptForConnectivity: { type: "text"; text: string }[] = [];
+
+    if (connectionState.tag === "connecting" && connectionState.oidcConnectionType) {
+        additionalPromptForConnectivity.push({
+            type: "text",
+            text: `The user needs to finish their OIDC connection by opening '${connectionState.oidcLoginUrl}' in the browser and use the following user code: '${connectionState.oidcUserCode}'`,
+        });
+    } else {
+        additionalPromptForConnectivity.push({
+            type: "text",
+            text: connectToolsNames
+                ? `Please use one of the following tools: ${connectToolsNames} to connect to a MongoDB instance or update the MCP server configuration to include a connection string. ${llmConnectHint}`
+                : "There are no tools available to connect. Please update the configuration to include a connection string and restart the server.",
+        });
+    }
+
+    switch (error.code) {
+        case ErrorCodes.NotConnectedToMongoDB:
+            return {
+                errorHandled: true,
+                result: {
+                    content: [
+                        {
+                            type: "text",
+                            text: "You need to connect to a MongoDB instance before you can access its data.",
+                        },
+                        ...additionalPromptForConnectivity,
+                    ],
+                    isError: true,
+                },
+            };
+        case ErrorCodes.MisconfiguredConnectionString:
+            return {
+                errorHandled: true,
+                result: {
+                    content: [
+                        {
+                            type: "text",
+                            text: "The configured connection string is not valid. Please check the connection string and confirm it points to a valid MongoDB instance.",
+                        },
+                        {
+                            type: "text",
+                            text: connectTools
+                                ? `Alternatively, you can use one of the following tools: ${connectToolsNames} to connect to a MongoDB instance. ${llmConnectHint}`
+                                : "Please update the configuration to use a valid connection string and restart the server.",
+                        },
+                    ],
+                    isError: true,
+                },
+            };
+
+        default:
+            return { errorHandled: false };
+    }
+};

src/common/errors.ts

@@ -4,9 +4,9 @@ export enum ErrorCodes {
     ForbiddenCollscan = 1_000_002,
 }
 
-export class MongoDBError extends Error {
+export class MongoDBError<ErrorCode extends ErrorCodes = ErrorCodes> extends Error {
     constructor(
-        public code: ErrorCodes,
+        public code: ErrorCode,
         message: string
     ) {
         super(message);

src/common/logger.ts

@@ -41,6 +41,7 @@ export const LogId = {
 
     mongodbConnectFailure: mongoLogId(1_004_001),
     mongodbDisconnectFailure: mongoLogId(1_004_002),
+    mongodbConnectTry: mongoLogId(1_004_003),
 
     toolUpdateFailure: mongoLogId(1_005_001),
     resourceUpdateFailure: mongoLogId(1_005_002),

src/index.ts

@@ -49,7 +49,14 @@ async function main(): Promise<void> {
     assertHelpMode();
     assertVersionMode();
 
-    const transportRunner = config.transport === "stdio" ? new StdioRunner(config) : new StreamableHttpRunner(config);
+    const transportRunner =
+        config.transport === "stdio"
+            ? new StdioRunner({
+                  userConfig: config,
+              })
+            : new StreamableHttpRunner({
+                  userConfig: config,
+              });
     const shutdown = (): void => {
         transportRunner.logger.info({
             id: LogId.serverCloseRequested,

src/lib.ts

@@ -11,4 +11,11 @@ export {
     type ConnectionStateErrored,
     type ConnectionManagerFactoryFn,
 } from "./common/connectionManager.js";
+export type {
+    ConnectionErrorHandler,
+    ConnectionErrorHandled,
+    ConnectionErrorUnhandled,
+    ConnectionErrorHandlerContext,
+} from "./common/connectionErrorHandler.js";
+export { ErrorCodes } from "./common/errors.js";
 export { Telemetry } from "./telemetry/telemetry.js";

src/server.ts

@@ -20,12 +20,15 @@ import {
 import assert from "assert";
 import type { ToolBase } from "./tools/tool.js";
 import { validateConnectionString } from "./helpers/connectionOptions.js";
+import { packageInfo } from "./common/packageInfo.js";
+import { type ConnectionErrorHandler } from "./common/connectionErrorHandler.js";
 
 export interface ServerOptions {
     session: Session;
     userConfig: UserConfig;
     mcpServer: McpServer;
     telemetry: Telemetry;
+    connectionErrorHandler: ConnectionErrorHandler;
 }
 
 export class Server {
@@ -34,6 +37,7 @@ export class Server {
     private readonly telemetry: Telemetry;
     public readonly userConfig: UserConfig;
     public readonly tools: ToolBase[] = [];
+    public readonly connectionErrorHandler: ConnectionErrorHandler;
 
     private _mcpLogLevel: LogLevel = "debug";
 
@@ -44,12 +48,13 @@ export class Server {
     private readonly startTime: number;
     private readonly subscriptions = new Set<string>();
 
-    constructor({ session, mcpServer, userConfig, telemetry }: ServerOptions) {
+    constructor({ session, mcpServer, userConfig, telemetry, connectionErrorHandler }: ServerOptions) {
         this.startTime = Date.now();
         this.session = session;
         this.telemetry = telemetry;
         this.mcpServer = mcpServer;
         this.userConfig = userConfig;
+        this.connectionErrorHandler = connectionErrorHandler;
     }
 
     async connect(transport: Transport): Promise<void> {
@@ -119,11 +124,10 @@ export class Server {
             this.session.setMcpClient(this.mcpServer.server.getClientVersion());
             // Placed here to start the connection to the config connection string as soon as the server is initialized.
             void this.connectToConfigConnectionString();
-
             this.session.logger.info({
                 id: LogId.serverInitialized,
                 context: "server",
-                message: `Server started with transport ${transport.constructor.name} and agent runner ${this.session.mcpClient?.name}`,
+                message: `Server with version ${packageInfo.version} started with transport ${transport.constructor.name} and agent runner ${JSON.stringify(this.session.mcpClient)}`,
             });
 
             this.emitServerEvent("start", Date.now() - this.startTime);
@@ -244,15 +248,21 @@ export class Server {
     private async connectToConfigConnectionString(): Promise<void> {
         if (this.userConfig.connectionString) {
             try {
+                this.session.logger.info({
+                    id: LogId.mongodbConnectTry,
+                    context: "server",
+                    message: `Detected a MongoDB connection string in the configuration, trying to connect...`,
+                });
                 await this.session.connectToMongoDB({
                     connectionString: this.userConfig.connectionString,
                 });
             } catch (error) {
-                console.error(
-                    "Failed to connect to MongoDB instance using the connection string from the config: ",
-                    error
-                );
-                throw new Error("Failed to connect to MongoDB instance using the connection string from the config");
+                // We don't throw an error here because we want to allow the server to start even if the connection string is invalid.
+                this.session.logger.error({
+                    id: LogId.mongodbConnectFailure,
+                    context: "server",
+                    message: `Failed to connect to MongoDB instance using the connection string from the config: ${error instanceof Error ? error.message : String(error)}`,
+                });
             }
         }
     }

src/tools/atlas/connect/connectCluster.ts

@@ -10,6 +10,11 @@ import type { AtlasClusterConnectionInfo } from "../../../common/connectionManag
 import { getDefaultRoleFromConfig } from "../../../common/atlas/roles.js";
 
 const EXPIRY_MS = 1000 * 60 * 60 * 12; // 12 hours
+const addedIpAccessListMessage =
+    "Note: Your current IP address has been added to the Atlas project's IP access list to enable secure connection.";
+
+const createdUserMessage =
+    "Note: A temporary user has been created to enable secure connection to the cluster. For more information, see https://dochub.mongodb.org/core/mongodb-mcp-server-tools-considerations\n\nNote to LLM Agent: it is important to include the following link in your response to the user in case they want to get more information about the temporary user created: https://dochub.mongodb.org/core/mongodb-mcp-server-tools-considerations";
 
 function sleep(ms: number): Promise<void> {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -190,19 +195,35 @@ export class ConnectClusterTool extends AtlasToolBase {
     }
 
     protected async execute({ projectId, clusterName }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        await ensureCurrentIpInAccessList(this.session.apiClient, projectId);
+        const ipAccessListUpdated = await ensureCurrentIpInAccessList(this.session.apiClient, projectId);
+        let createdUser = false;
+
         for (let i = 0; i < 60; i++) {
             const state = this.queryConnection(projectId, clusterName);
             switch (state) {
                 case "connected": {
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: `Connected to cluster "${clusterName}".`,
-                            },
-                        ],
-                    };
+                    const content: CallToolResult["content"] = [
+                        {
+                            type: "text",
+                            text: `Connected to cluster "${clusterName}".`,
+                        },
+                    ];
+
+                    if (ipAccessListUpdated) {
+                        content.push({
+                            type: "text",
+                            text: addedIpAccessListMessage,
+                        });
+                    }
+
+                    if (createdUser) {
+                        content.push({
+                            type: "text",
+                            text: createdUserMessage,
+                        });
+                    }
+
+                    return { content };
                 }
                 case "connecting":
                 case "unknown": {
@@ -214,6 +235,7 @@ export class ConnectClusterTool extends AtlasToolBase {
                     await this.session.disconnect();
                     const { connectionString, atlas } = await this.prepareClusterConnection(projectId, clusterName);
 
+                    createdUser = true;
                     // try to connect for about 5 minutes asynchronously
                     void this.connectToCluster(connectionString, atlas).catch((err: unknown) => {
                         const error = err instanceof Error ? err : new Error(String(err));
@@ -230,21 +252,31 @@ export class ConnectClusterTool extends AtlasToolBase {
             await sleep(500);
         }
 
-        return {
-            content: [
-                {
-                    type: "text" as const,
-                    text: `Attempting to connect to cluster "${clusterName}"...`,
-                },
-                {
-                    type: "text" as const,
-                    text: `Warning: Provisioning a user and connecting to the cluster may take more time, please check again in a few seconds.`,
-                },
-                {
-                    type: "text" as const,
-                    text: `Warning: Make sure your IP address was enabled in the allow list setting of the Atlas cluster.`,
-                },
-            ],
-        };
+        const content: CallToolResult["content"] = [
+            {
+                type: "text" as const,
+                text: `Attempting to connect to cluster "${clusterName}"...`,
+            },
+            {
+                type: "text" as const,
+                text: `Warning: Provisioning a user and connecting to the cluster may take more time, please check again in a few seconds.`,
+            },
+        ];
+
+        if (ipAccessListUpdated) {
+            content.push({
+                type: "text" as const,
+                text: addedIpAccessListMessage,
+            });
+        }
+
+        if (createdUser) {
+            content.push({
+                type: "text" as const,
+                text: createdUserMessage,
+            });
+        }
+
+        return { content };
     }
 }