Merge branch 'main' into gagik/use-machine-id

Author: gagik

README.md

@@ -1,96 +1,96 @@
 # MongoDB MCP Server
 
-A Model Context Protocol server for interacting with MongoDB Atlas. This project implements a Model Context Protocol (MCP) server enabling AI assistants to interact with MongoDB Atlas resources through natural language.
-
-> [!CAUTION]
-> Do not use this in production. This is a work in progress and is not intended for production use. It is meant for demonstration purposes only.
+A Model Context Protocol server for interacting with MongoDB Databases and MongoDB Atlas.
 
 ## 📚 Table of Contents
 
 - [🚀 Getting Started](#getting-started)
   - [Prerequisites](#prerequisites)
-  - [Installation](#installation)
-    - [VSCode](#vscode)
-    - [Claude Desktop](#claude)
+  - [Setup](#setup)
+    - [Quick Start](#quick-start)
 - [🛠️ Supported Tools](#supported-tools)
-  - [Tool List](#tool-list)
+  - [MongoDB Atlas Tools](#mongodb-atlas-tools)
+  - [MongoDB Database Tools](#mongodb-database-tools)
 - [⚙️ Configuration](#configuration)
   - [Configuration Options](#configuration-options)
   - [Atlas API Access](#atlas-api-access)
   - [Configuration Methods](#configuration-methods)
-- [👩‍💻 Client Integration](#client-integration)
-  - [VSCode](#vscode)
-  - [Claude](#claude)
+    - [Environment Variables](#environment-variables)
+    - [Command-Line Arguments](#command-line-arguments)
+    - [MCP Client Configuration](#mcp-configuration-file-examples)
 - [🤝 Contributing](#contributing)
 
 ## Prerequisites
 
 - Node.js (v20 or later)
-- MongoDB Atlas account
 
-## Installation
+```shell
+node -v
+```
 
-### VSCode
+- A MongoDB connection string or Atlas API credentials, **_the Server will not start unless configured_**.
+  - **_Atlas API credentials_** are required to use the Atlas tools. You can create a service account in MongoDB Atlas and use its credentials for authentication. See [Atlas API Access](#atlas-api-access) for more details.
+  - If you have a MongoDB connection string, you can use it directly to connect to your MongoDB instance.
 
-Prerequisites:
+## Setup
 
-- Node.js v20.x
+### Quick Start
 
-Step 1: Add the mcp server to VSCode configuration
+Most MCP clients require a configuration file to be created or modified to add the MCP server.
 
-- Press `Cmd + Shift + P` and type `MCP: Add MCP Server` and select it.
-- Select command (Stdio).
-- Input command `npx -y mongodb-mcp-server`.
-- Choose between user / workspace
-- Add arguments to the file
+- **Windsurf**:https://docs.windsurf.com/windsurf/mcp
+- **VSCode**: https://docs.codeium.com/docs/mcp
+- **Claude Desktop**: https://modelcontextprotocol.io/quickstart/user
+- **Cursor**: https://docs.cursor.com/context/model-context-protocol
 
-Note: the file should look like:
+#### Option 1: Connection String args
 
-```
+You can pass your connection string via args, make sure to use a valid username and password.
+
+```json
 {
-    "servers": {
-        "MongoDB": {
-            "type": "stdio",
-            "command": "npx",
-            "args": [
-                "-y",
-                "mongodb-mcp-server"
-            ]
-        }
+  "servers": {
+    "MongoDB": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mongodb-mcp-server",
+        "--connectionString",
+        "mongodb+srv://username:[email protected]/myDatabase"
+      ]
     }
+  }
 }
 ```
 
-Notes: You can configure the server with atlas access, make sure to follow configuration section for more details.
-
-Step 2: Try talking to github copilot
-
-- Can you connect to my mongodb instance?
-
-### Claude Desktop
-
-Step 1: Install claude and login
-
-Note: follow instructions at https://claude.ai/download
-
-Step 2: Launch Claude Settings -> Developer -> Edit Config
+#### Option 2: Atlas API credentials args
 
-Paste the mcp server configuration into the file
+Use your Atlas API Service Account credentials. More details in the [Atlas API Access](#atlas-api-access) section.
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "MongoDB": {
       "command": "npx",
-      "args": ["-y", "mongodb-mcp-server"]
+      "args": [
+        "-y",
+        "mongodb-mcp-server",
+        "--apiClientId",
+        "your-atlas-client-id",
+        "--apiClientSecret",
+        "your-atlas-client-secret"
+      ]
     }
   }
 }
 ```
 
-Step 3: Close and Relaunch Claude Desktop and click on the hammer icon, the MongoDB MCP server should be detected.
+#### Other options
 
-You may experiment asking `Can you connect to my mongodb instance?`.
+Alternatively you can use environment variables in the config file or set them and run the server via npx.
+
+- Connection String via environment variables in the MCP file [example](#connection-string-with-environment-variables)
+- Atlas API credentials via environment variables in the MCP file [example](#atlas-api-credentials-with-environment-variables)
 
 ## 🛠️ Supported Tools
 
@@ -154,7 +154,7 @@ The MongoDB MCP Server can be configured using multiple methods, with the follow
 | `readOnly`         | When set to true, only allows read and metadata operation types, disabling create/update/delete operations            |
 | `telemetry`        | When set to disabled, disables telemetry collection                                                                   |
 
-#### `logPath`
+#### Log Path
 
 Default log location is as follows:
 
@@ -220,6 +220,8 @@ To use the Atlas API tools, you'll need to create a service account in MongoDB A
    - Select appropriate permissions (for full access, use Organization Owner)
    - Click "Create"
 
+To learn more about Service Accounts, check the [MongoDB Atlas documentation](https://www.mongodb.com/docs/atlas/api/service-accounts-overview/).
+
 2. **Save Client Credentials:**
 
    - After creation, you'll be shown the Client ID and Client Secret
@@ -250,6 +252,41 @@ export MDB_MCP_LOG_PATH="/path/to/logs"
 
 ```
 
+#### MCP configuration file examples
+
+##### Connection String with environment variables
+
+```json
+{
+  "servers": {
+    "MongoDB": {
+      "command": "npx",
+      "args": ["-y", "mongodb-mcp-server"],
+      "env": {
+        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:[email protected]/myDatabase"
+      }
+    }
+  }
+}
+```
+
+##### Atlas API credentials with environment variables
+
+```json
+{
+  "servers": {
+    "MongoDB": {
+      "command": "npx",
+      "args": ["-y", "mongodb-mcp-server"],
+      "env": {
+        "MDB_MCP_API_CLIENT_ID": "your-atlas-client-id",
+        "MDB_MCP_API_CLIENT_SECRET": "your-atlas-client-secret"
+      }
+    }
+  }
+}
+```
+
 #### Command-Line Arguments
 
 Pass configuration options as command-line arguments when starting the server:
@@ -258,6 +295,46 @@ Pass configuration options as command-line arguments when starting the server:
 npx -y mongodb-mcp-server --apiClientId="your-atlas-client-id" --apiClientSecret="your-atlas-client-secret" --connectionString="mongodb+srv://username:[email protected]/myDatabase" --logPath=/path/to/logs
 ```
 
+#### MCP configuration file examples
+
+##### Connection String with command-line arguments
+
+```json
+{
+  "servers": {
+    "MongoDB": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mongodb-mcp-server",
+        "--connectionString",
+        "mongodb+srv://username:[email protected]/myDatabase"
+      ]
+    }
+  }
+}
+```
+
+##### Atlas API credentials with command-line arguments
+
+```json
+{
+  "servers": {
+    "MongoDB": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mongodb-mcp-server",
+        "--apiClientId",
+        "your-atlas-client-id",
+        "--apiClientSecret",
+        "your-atlas-client-secret"
+      ]
+    }
+  }
+}
+```
+
 ## 🤝 Contributing
 
 Interested in contributing? Great! Please check our [Contributing Guide](CONTRIBUTING.md) for guidelines on code contributions, standards, adding new tools, and troubleshooting information.

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "mongodb-mcp-server",
   "description": "MongoDB Model Context Protocol Server",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "main": "dist/index.js",
   "author": "MongoDB <[email protected]>",
   "homepage": "https://github.com/mongodb-js/mongodb-mcp-server",

package.json

@@ -0,0 +1,10 @@
+import { randomBytes } from "crypto";
+import { promisify } from "util";
+
+const randomBytesAsync = promisify(randomBytes);
+
+export async function generateSecurePassword(): Promise<string> {
+    const buf = await randomBytesAsync(16);
+    const pass = buf.toString("base64url");
+    return pass;
+}

src/common/atlas/generatePassword.ts

@@ -12,6 +12,7 @@ export const LogId = {
 
     atlasCheckCredentials: mongoLogId(1_001_001),
     atlasDeleteDatabaseUserFailure: mongoLogId(1_001_002),
+    atlasConnectFailure: mongoLogId(1_001_003),
 
     telemetryDisabled: mongoLogId(1_002_001),
     telemetryEmitFailure: mongoLogId(1_002_002),

src/logger.ts

@@ -69,25 +69,24 @@ export class Session extends EventEmitter<{
             this.emit("disconnect");
             return;
         }
-        try {
-            await this.apiClient.deleteDatabaseUser({
+        void this.apiClient
+            .deleteDatabaseUser({
                 params: {
                     path: {
                         groupId: this.connectedAtlasCluster.projectId,
                         username: this.connectedAtlasCluster.username,
                         databaseName: "admin",
                     },
                 },
+            })
+            .catch((err: unknown) => {
+                const error = err instanceof Error ? err : new Error(String(err));
+                logger.error(
+                    LogId.atlasDeleteDatabaseUserFailure,
+                    "atlas-connect-cluster",
+                    `Error deleting previous database user: ${error.message}`
+                );
             });
-        } catch (err: unknown) {
-            const error = err instanceof Error ? err : new Error(String(err));
-
-            logger.error(
-                LogId.atlasDeleteDatabaseUserFailure,
-                "atlas-connect-cluster",
-                `Error deleting previous database user: ${error.message}`
-            );
-        }
         this.connectedAtlasCluster = undefined;
 
         this.emit("disconnect");

src/session.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}\`` : ""}.`,
+                },
+            ],
         };
     }
 }