Merge branch 'main' of github.com:mongodb-js/mongodb-mcp-server into gagik/add-explain

Author: gagik

.github/workflows/code_health.yaml

@@ -1,35 +1,46 @@
 ---
 name: Code Health
 on:
-    push:
-        branches:
-            - main
-    pull_request:
+  push:
+    branches:
+      - main
+  pull_request:
 jobs:
-    check-style:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: GitHubSecurityLab/actions-permissions/monitor@v1
-            - uses: actions/checkout@v4
-            - uses: actions/setup-node@v4
-              with:
-                  node-version-file: package.json
-                  cache: "npm"
-            - name: Install dependencies
-              run: npm ci
-            - name: Run style check
-              run: npm run check
+  check-style:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: package.json
+          cache: "npm"
+      - name: Install dependencies
+        run: npm ci
+      - name: Run style check
+        run: npm run check
 
-    run-tests:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: GitHubSecurityLab/actions-permissions/monitor@v1
-            - uses: actions/checkout@v4
-            - uses: actions/setup-node@v4
-              with:
-                  node-version-file: package.json
-                  cache: "npm"
-            - name: Install dependencies
-              run: npm ci
-            - name: Run tests
-              run: npm test
+  run-tests:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+      fail-fast: false
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
+        if: matrix.os != 'windows-latest'
+      - name: Install keyring deps on Ubuntu
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          sudo apt update -y
+          sudo apt install -y gnome-keyring libdbus-1-dev
+
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: package.json
+          cache: "npm"
+      - name: Install dependencies
+        run: npm ci
+      - name: Run tests
+        run: npm test

.github/workflows/publish.yaml

@@ -1,29 +1,29 @@
 ---
 name: Publish
 on:
-    push:
-        tags:
-            - v*
+  push:
+    tags:
+      - v*
 jobs:
-    publish:
-        runs-on: ubuntu-latest
-        environment: Production
-        steps:
-            - uses: GitHubSecurityLab/actions-permissions/monitor@v1
-            - uses: actions/checkout@v4
-            - uses: actions/setup-node@v4
-              with:
-                  node-version-file: package.json
-                  registry-url: "https://registry.npmjs.org"
-                  cache: "npm"
-            - name: Build package
-              run: |
-                  npm ci
-                  npm run build
-            - name: Publish to NPM
-              run: npm publish
-              env:
-                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-            - name: Publish Github release
-              run: |
-                  gh release create ${{ github.ref }} --title "${{ github.ref }}" --notes "Release ${{ github.ref }}" --generate-notes
+  publish:
+    runs-on: ubuntu-latest
+    environment: Production
+    steps:
+      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: package.json
+          registry-url: "https://registry.npmjs.org"
+          cache: "npm"
+      - name: Build package
+        run: |
+          npm ci
+          npm run build
+      - name: Publish to NPM
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Publish Github release
+        run: |
+          gh release create ${{ github.ref }} --title "${{ github.ref }}" --notes "Release ${{ github.ref }}" --generate-notes

.gitignore

@@ -8,3 +8,5 @@ node_modules
 
 # Sensitive
 state.json
+
+tests/tmp

.prettierignore

@@ -1,3 +1,5 @@
 dist
 coverage
 package-lock.json
+tests/tmp
+src/common/atlas/openapi.d.ts

.prettierrc.json

@@ -5,6 +5,13 @@
   "singleQuote": false,
   "printWidth": 120,
   "overrides": [
+    {
+      "files": "*.ts",
+      "options": {
+        "insertPragma": false,
+        "proseWrap": "preserve"
+      }
+    },
     {
       "files": "*.json",
       "options": {
@@ -18,6 +25,13 @@
         "tabWidth": 2,
         "printWidth": 80
       }
+    },
+    {
+      "files": "*.yaml",
+      "options": {
+        "tabWidth": 2,
+        "printWidth": 80
+      }
     }
   ]
 }

README.md

@@ -48,13 +48,14 @@ npm run build
 
 #### MongoDB Atlas Tools
 
-- `atlas-auth` - Authenticate to MongoDB Atlas
 - `atlas-list-clusters` - Lists MongoDB Atlas clusters
 - `atlas-list-projects` - Lists MongoDB Atlas projects
 - `atlas-inspect-cluster` - Inspect a specific MongoDB Atlas cluster
 - `atlas-create-free-cluster` - Create a free MongoDB Atlas cluster
 - `atlas-create-access-list` - Configure IP/CIDR access list for MongoDB Atlas clusters
 - `atlas-inspect-access-list` - Inspect IP/CIDR ranges with access to MongoDB Atlas clusters
+- `atlas-list-db-users` - List MongoDB Atlas database users
+- `atlas-create-db-user` - List MongoDB Atlas database users
 
 #### MongoDB Database Tools
 
@@ -110,6 +111,8 @@ It should look like this
 }
 ```
 
+Notes: You can configure the server with atlas access, make sure to follow configuration section for more details.
+
 Step 3: Open the copilot chat and check that the toolbox icon is visible and has the mcp server listed.
 
 Step 4: Try running a command
@@ -146,10 +149,79 @@ Paste the mcp server configuration into the file
 
 Step 3: Launch Claude Desktop and click on the hammer icon, the Demo MCP server should be detected. Type in the chat "show me a demo of MCP" and allow the tool to get access.
 
-- Detailed instructions with screenshots can be found in this [document](https://docs.google.com/document/d/1_C8QBMZ5rwImV_9v4G96661OqcBk1n1SfEgKyNalv9c/edit?tab=t.2hhewstzj7ck#bookmark=id.nktw0lg0fn7t).
-
 Note: If you make changes to your MCP server code, rebuild the project with `npm run build` and restart the server and Claude Desktop.
 
+## Configuration
+
+The MongoDB MCP Server can be configured using multiple methods, with the following precedence (highest to lowest):
+
+1. Command-line arguments
+2. Environment variables
+
+### Configuration Options
+
+| Option             | Description                                                                                                           |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `apiClientId`      | Atlas API client ID for authentication                                                                                |
+| `apiClientSecret`  | Atlas API client secret for authentication                                                                            |
+| `connectionString` | MongoDB connection string for direct database connections (optional users may choose to inform it on every tool call) |
+| `logPath`          | Folder to store logs                                                                                                  |
+
+**Default Log Path:**
+
+- Windows: `%LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs`
+- macOS/Linux: `~/.mongodb/mongodb-mcp/.app-logs`
+
+### Atlas API Access
+
+To use the Atlas API tools, you'll need to create a service account in MongoDB Atlas:
+
+1. **Create a Service Account:**
+
+   - Log in to MongoDB Atlas at [cloud.mongodb.com](https://cloud.mongodb.com)
+   - Navigate to Access Manager > Organization Access
+   - Click Add New > Applications > Service Accounts
+   - Enter name, description and expiration for your service account (e.g., "MCP, MCP Server Access, 7 days")
+   - Select appropriate permissions (for full access, use Organization Owner)
+   - Click "Create"
+
+2. **Save Client Credentials:**
+
+   - After creation, you'll be shown the Client ID and Client Secret
+   - **Important:** Copy and save the Client Secret immediately as it won't be displayed again
+
+3. **Add Access List Entry (Optional but recommended):**
+
+   - Add your IP address to the API access list
+
+4. **Configure the MCP Server:**
+   - Use one of the configuration methods below to set your `apiClientId` and `apiClientSecret`
+
+### Configuration Methods
+
+#### Environment Variables
+
+Set environment variables with the prefix `MDB_MCP_` followed by the option name in uppercase with underscores:
+
+```shell
+# Set Atlas API credentials
+export MDB_MCP_API_CLIENT_ID="your-atlas-client-id"
+export MDB_MCP_API_CLIENT_SECRET="your-atlas-client-secret"
+
+# Set a custom MongoDB connection string
+export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:[email protected]/myDatabase"
+
+export MDB_MCP_LOG_PATH="/path/to/logs"
+```
+
+#### Command-Line Arguments
+
+Pass configuration options as command-line arguments when starting the server:
+
+```shell
+node dist/index.js --apiClientId="your-atlas-client-id" --apiClientSecret="your-atlas-client-secret" --connectionString="mongodb+srv://username:[email protected]/myDatabase" --logPath=/path/to/logs
+```
+
 ## 🤝 Contributing
 
 Interested in contributing? Great! Please check our [Contributing Guide](CONTRIBUTING.md) for guidelines on code contributions, standards, adding new tools, and troubleshooting information.

eslint.config.js

@@ -4,16 +4,32 @@ import globals from "globals";
 import tseslint from "typescript-eslint";
 import eslintConfigPrettier from "eslint-config-prettier/flat";
 
+const files = ["src/**/*.ts", "scripts/**/*.ts", "tests/**/*.test.ts", "eslint.config.js", "jest.config.js"];
+
 export default defineConfig([
-    { files: ["src/**/*.ts"], plugins: { js }, extends: ["js/recommended"] },
-    { files: ["src/**/*.ts"], languageOptions: { globals: globals.node } },
-    tseslint.configs.recommended,
-    eslintConfigPrettier,
+    { files, plugins: { js }, extends: ["js/recommended"] },
+    { files, languageOptions: { globals: globals.node } },
+    tseslint.configs.recommendedTypeChecked,
+    {
+        languageOptions: {
+            parserOptions: {
+                projectService: true,
+                tsconfigRootDir: import.meta.dirname,
+            },
+        },
+    },
     {
-        files: ["src/**/*.ts"],
+        files,
         rules: {
+            "@typescript-eslint/switch-exhaustiveness-check": "error",
             "@typescript-eslint/no-non-null-assertion": "error",
         },
     },
-    globalIgnores(["node_modules", "dist"]),
+    // Ignore features specific to TypeScript resolved rules
+    tseslint.config({
+        // TODO: Configure tests and scripts to work with this.
+        ignores: ["eslint.config.js", "jest.config.js", "tests/**/*.ts", "scripts/**/*.ts"],
+    }),
+    globalIgnores(["node_modules", "dist", "src/common/atlas/openapi.d.ts"]),
+    eslintConfigPrettier,
 ]);