Merge branch 'main' into ni/disable-tools

Author: nirinchev

.github/workflows/prepare_release.yaml

@@ -0,0 +1,45 @@
+name: Prepare release
+description: |
+  Bumps the version in package.json and creates a release PR. Once merged, the new
+  version will be published to npm.
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Exact version to bump to or one of major, minor, patch"
+        required: true
+        default: "patch"
+
+jobs:
+  create-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: mongodb-js/devtools-shared/actions/setup-bot-token@main
+        id: app-token
+        with:
+          app-id: ${{ vars.DEVTOOLS_BOT_APP_ID }}
+          private-key: ${{ secrets.DEVTOOLS_BOT_PRIVATE_KEY }}
+      - 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: Bump version
+        id: bump-version
+        run: |
+          echo "NEW_VERSION=$(npm version ${{ inputs.version }} --no-git-tag-version)" >> $GITHUB_OUTPUT
+      - name: Create release PR
+        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # 7.0.8
+        with:
+          title: "Release v${{ steps.bump-version.outputs.NEW_VERSION }}"
+          token: ${{ steps.app-token.outputs.token }}
+          commit-message: "Bump version to v${{ steps.bump-version.outputs.NEW_VERSION }}"
+          body: |
+            This PR bumps the package version to v${{ steps.bump-version.outputs.NEW_VERSION }}.
+            Once merged, the new version will be published to npm.
+          base: main
+          branch: release/v${{ steps.bump-version.outputs.NEW_VERSION }}
+          author: "${{ steps.app-token.outputs.app-slug}}[bot] <${{ steps.app-token.outputs.app-email }}>"
+          committer: "${{ steps.app-token.outputs.app-slug}}[bot] <${{ steps.app-token.outputs.app-email }}>"

.github/workflows/publish.yaml

@@ -2,12 +2,51 @@
 name: Publish
 on:
   push:
-    tags:
-      - v*
+    branches:
+      - main
+permissions:
+  contents: write
 jobs:
+  check:
+    runs-on: ubuntu-latest
+    outputs:
+      VERSION_EXISTS: ${{ steps.check-version.outputs.VERSION_EXISTS }}
+      VERSION: ${{ steps.get-version.outputs.VERSION }}
+    steps:
+      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: package.json
+          registry-url: "https://registry.npmjs.org"
+          cache: "npm"
+      - name: Get version
+        id: get-version
+        shell: bash
+        run: |
+          set +e
+
+          VERSION=v$(jq -r '.version' < package.json)
+          echo "VERSION=${VERSION}" >> "$GITHUB_OUTPUT"
+      - name: Check if version already exists
+        id: check-version
+        shell: bash
+        run: |
+          set +e
+
+          git rev-parse "${{ steps.get-version.outputs.VERSION }}" >/dev/null 2>&1
+          if [[ $? -eq 0 ]]; then
+            echo "VERSION_EXISTS=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "VERSION_EXISTS=false" >> "$GITHUB_OUTPUT"
+          fi
   publish:
     runs-on: ubuntu-latest
     environment: Production
+    needs: check
+    if: needs.check.outputs.VERSION_EXISTS == 'false'
     steps:
       - uses: GitHubSecurityLab/actions-permissions/monitor@v1
       - uses: actions/checkout@v4
@@ -24,6 +63,8 @@ jobs:
         run: npm publish
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-      - name: Publish Github release
+      - name: Publish git release
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
-          gh release create ${{ github.ref }} --title "${{ github.ref }}" --notes "Release ${{ github.ref }}" --generate-notes
+          gh release create ${{ needs.check.outputs.VERSION }} --title "${{ needs.check.outputs.VERSION }}" --generate-notes --target ${{ github.sha }}

.npmrc

@@ -0,0 +1 @@
+git-tag-version=false

CONTRIBUTING.md

@@ -141,6 +141,41 @@ When adding new tools to the MCP server:
 4. Add proper documentation for the tool
 5. Include examples of how to use the tool
 
+## Release Process
+
+Our release process is automated using GitHub Actions workflows:
+
+### Version Bumping
+
+1. To create a new version, go to the GitHub repository Actions tab
+2. Select the "Version Bump" workflow
+3. Click "Run workflow" and choose one of the following options:
+   - `patch` (e.g., 1.0.0 → 1.0.1) for backward-compatible bug fixes
+   - `minor` (e.g., 1.0.0 → 1.1.0) for backward-compatible new features
+   - `major` (e.g., 1.0.0 → 2.0.0) for breaking changes
+   - A specific version number (e.g., `1.2.3`)
+4. This creates a pull request with the version change
+5. Once approved and merged, the version is updated
+
+### Automatic Publishing
+
+When a version bump is merged to the main branch:
+
+1. The "Publish" workflow automatically runs
+2. It checks if the version already exists as a git tag
+3. If the version is new, it:
+   - Builds the package
+   - Publishes to NPM
+   - Creates a git tag for the version
+   - Creates a GitHub release with auto-generated release notes
+
+### Code Quality
+
+All pull requests automatically run through the "Code Health" workflow, which:
+
+- Verifies code style and formatting
+- Runs tests on multiple platforms (Ubuntu, macOS, Windows)
+
 ## License
 
 By contributing to this project, you agree that your contributions will be licensed under the project's license.

README.md

@@ -10,38 +10,88 @@ A Model Context Protocol server for interacting with MongoDB Atlas. This project
 - [🚀 Getting Started](#getting-started)
   - [Prerequisites](#prerequisites)
   - [Installation](#installation)
-  - [Running the MCP Server](#running-the-mcp-server)
+    - [VSCode](#vscode)
+    - [Claude Desktop](#claude)
 - [🛠️ Supported Tools](#supported-tools)
   - [Tool List](#tool-list)
+- [⚙️ Configuration](#configuration)
+  - [Configuration Options](#configuration-options)
+  - [Atlas API Access](#atlas-api-access)
+  - [Configuration Methods](#configuration-methods)
 - [👩‍💻 Client Integration](#client-integration)
   - [VSCode](#vscode)
   - [Claude](#claude)
 - [🤝 Contributing](#contributing)
 
-## 🚀 Getting Started
-
-### Prerequisites
+## Prerequisites
 
 - Node.js (v20 or later)
 - MongoDB Atlas account
 
-### Installation
+## Installation
 
-```shell
-# Clone the repository
-git clone https://github.com/mongodb-labs/mongodb-mcp-server.git
-cd mongodb-mcp-server
+### VSCode
+
+Prerequisites:
+
+- Node.js v20.x
+
+Step 1: Add the mcp server to VSCode configuration
+
+- Press `Cmd + Shift + P` and type `MCP: Add MCP Server` and select it.
+- Select command (Stdio).
+- Input command `npx -y @mongodb-js/mongodb-mcp-server`.
+- Choose between user / workspace
+- Add arguments to the file
+
+Note: the file should look like:
 
-# Install dependencies
-npm install
 ```
+{
+    "servers": {
+        "MongoDB": {
+            "type": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "@mongodb-js/mongodb-mcp-server"
+            ]
+        }
+    }
+}
+```
+
+Notes: You can configure the server with atlas access, make sure to follow configuration section for more details.
 
-### Running the MCP Server
+Step 2: Try talking to github copilot
 
-```shell
-npm run build
+- 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
+
+Paste the mcp server configuration into the file
+
+```json
+{
+  "mcpServers": {
+    "MongoDB": {
+      "command": "npx",
+      "args": ["-y", "@mongodb-js/mongodb-mcp-server"]
+    }
+  }
+}
 ```
 
+Step 3: Close and Relaunch Claude Desktop and click on the hammer icon, the MongoDB MCP server should be detected.
+
+You may experiment asking `Can you connect to my mongodb instance?`.
+
 ## 🛠️ Supported Tools
 
 ### Tool List
@@ -80,77 +130,6 @@ npm run build
 - `collection-storage-size` - Get the size of a collection in MB
 - `db-stats` - Return statistics about a MongoDB database
 
-## 👩‍💻 Client Integration (Use the server!)
-
-### VSCode
-
-Prerequisites:
-
-- Use VSCode Insiders (https://code.visualstudio.com/insiders/)
-- Setup copilot in VSCode Insiders
-
-Step 1: Add the mcp server to VSCode configuration
-
-- Press `Cmd + Shift + P` and type `MCP: Add MCP Server` and select it.
-- Select the first option for a local MCP server.
-- Add the path to dist/index.js in the prompt
-
-Step 2: Verify the created mcp file
-
-It should look like this
-
-```json
-{
-  "servers": {
-    "mongodb-mcp-server": {
-      "type": "stdio",
-      "command": "/Users/<user>/workplace/atlas-mcp-server/dist/index.js",
-      "args": []
-    }
-  }
-}
-```
-
-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
-
-- Can you list my clusters?
-
-### Claude
-
-Step 1: Install claude and login
-
-```shell
-brew install claude
-```
-
-Step 2: Create a configuration file for your MCP server
-
-Open the file
-
-```shell
-code ~/Library/Application\ Support/Claude/claude_desktop_config.json
-```
-
-Paste the mcp server configuration into the file
-
-```json
-{
-  "mcpServers": {
-    "Demo": {
-      "command": "path/to/this/repo/atlas-mc-server/dist/index.js"
-    }
-  }
-}
-```
-
-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.
-
-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):
@@ -240,7 +219,7 @@ export MDB_MCP_LOG_PATH="/path/to/logs"
 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:password@cluster.mongodb.net/myDatabase" --logPath=/path/to/logs
+npx -y @mongodb-js/mongodb-mcp-server --apiClientId="your-atlas-client-id" --apiClientSecret="your-atlas-client-secret" --connectionString="mongodb+srv://username:password@cluster.mongodb.net/myDatabase" --logPath=/path/to/logs
 ```
 
 ## 🤝 Contributing

jest.config.js

@@ -16,4 +16,5 @@ export default {
         ],
     },
     moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
+    setupFilesAfterEnv: ["jest-extended/all"],
 };