Merge branch 'main' into ni/create-user

Author: nirinchev

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",
@@ -69,7 +69,7 @@
     "mongodb-log-writer": "^2.4.1",
     "mongodb-redact": "^1.1.6",
     "mongodb-schema": "^12.6.2",
-    "native-machine-id": "^0.1.0",
+    "node-machine-id": "^1.1.12",
     "openapi-fetch": "^0.13.5",
     "simple-oauth2": "^5.1.0",
     "yargs-parser": "^21.1.1",

package.json

@@ -12,12 +12,14 @@ 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),
     telemetryEmitStart: mongoLogId(1_002_003),
     telemetryEmitSuccess: mongoLogId(1_002_004),
     telemetryMetadataError: mongoLogId(1_002_005),
+    telemetryDeviceIdFailure: mongoLogId(1_002_006),
 
     toolExecute: mongoLogId(1_003_001),
     toolExecuteFailure: mongoLogId(1_003_002),