Merge branch 'main' into feat-MCP-40

Author: Luke-Sanderson

.github/copilot-instructions.md

@@ -0,0 +1,71 @@
+# Project Overview
+
+This project is a server implementing the MCP (Model Context Protocol) that allows users to interact with their MongoDB clusters
+and MongoDB Atlas accounts. It is built using TypeScript, Node.js and the official Anthropic
+@modelcontextprotocol/sdk SDK.
+
+## Folder Structure
+
+- `/src`: Contains the source code of the MCP Server.
+- `/src/tools`: Contains the implementation of MCP tools.
+- `/src/tools/atlas/`: Contains the implementation of MCP tools that are specific to MongoDB Atlas.
+- `/src/tools/mongodb/`: Contains the implementation of MCP tools that are specific to MongoDB clusters.
+- `/src/resources`: Contains the implementation of MCP Resources.
+- `/tests`: Contains the test code for the MCP Server.
+- `/tests/accuracy`: Contains the test code for the accuracy tests, that use different models to ensure that tools have reliable descriptions.
+- `/tests/integration`: Contains tests that start the MCP Server and interact with it to ensure that functionality is correct.
+- `/tests/unit`: Contains simple unit tests to cover specific functionality of the MCP Server.
+
+## Libraries and Frameworks
+
+- Zod for message and schema validation.
+- Express for the HTTP Transport implementation.
+- mongosh NodeDriverServiceProvider for connecting to MongoDB.
+- vitest for testing.
+- @modelcontextprotocol/sdk for the protocol implementation.
+
+## Coding Standards
+
+- For declarations, use types. For usage, rely on type inference unless it is not clear enough.
+- Always follow the eslint and prettier rule formats specified in `.eslint.config.js` and `.prettierrc.json`.
+- Use classes for stateful components and functions for stateless pure logic.
+- Use dependency injection to provide dependencies between components.
+- Avoid using global variables as much as possible.
+- New functionality MUST be under test.
+  - Tools MUST HAVE integration tests.
+  - Tools MUST HAVE unit tests.
+  - Tools MAY HAVE accuracy tests.
+
+## Architectural Guidelines and Best Practices
+
+Every agent connected to the MCP Server has a Session object attached to it. The Session is the main entrypoint for
+dependencies to other components. Any component that MUST be used by either a tool or a resource MUST be provided
+through the Session.
+
+### Guidelines for All Tools
+
+- The name of the tool should describe an action: `create-collection`, `insert-many`.
+- The description MUST be a simple and accurate prompt that defines what the tool does in an unambiguous way.
+- All tools MUST provide a Zod schema that clearly specifies the API of the tool.
+- The Operation type MUST be clear:
+  - `metadata`: Reads metadata for an entity (for example, a cluster). Example: CollectionSchema.
+  - `read`: Reads information from a cluster or Atlas.
+  - `create`: Creates resources, like a collection or a cluster.
+  - `delete`: Deletes resources or documents, like collections, documents or clusters.
+  - `update`: Modifies resources or documents, like collections, documents or clusters.
+  - `connects`: Connects to a MongoDB cluster.
+- If a new tool is added, or the tool description is modified, the accuracy tests MUST be updated too.
+
+### Guidelines for MongoDB Tools
+
+- The tool category MUST be `mongodb`.
+- They MUST call `this.ensureConnected()` before attempting to query MongoDB.
+- They MUST return content sanitized using `formatUntrustedData`.
+- Documents should be serialized with `EJSON.stringify`.
+- Ensure there are proper timeout mechanisms to avoid long-running queries that can affect the server.
+- Tools that require elicitation MUST implement `getConfirmationMessage` and provide an easy-to-understand message for a human running the operation.
+  - If a tool requires elicitation, it must be added to `src/common/config.ts` in the `confirmationRequiredTools` list in the defaultUserConfig.
+
+### Guidelines for Atlas Tools
+
+- The tool category MUST be `atlas`.

.github/dependabot.yml

@@ -4,6 +4,22 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    ignore:
+      # We are ignoring major updates on yargs-parser because yargs-parser@22
+      # does not play nicely when bundled using webpack. Our VSCode extension
+      # bundles MCP server with the extension code and yargs-parser from MCP
+      # server ends up on the final bundle which leads to issues such as -
+      # https://github.com/mongodb-js/vscode/issues/1149.
+      #
+      # This was reported to yargs-parser as well -
+      # https://github.com/yargs/yargs-parser/issues/517 and we already tried
+      # their suggestion about disabling the meta resolution in webpack,
+      # alongside others (dependency overrides, disabling the bundling of
+      # yargs-parser), and none of the solutions yield a working extension. So
+      # until we figure out a fix for this we need to keep mongodb-mcp-server
+      # working with v21 of yargs-parser.
+      - dependency-name: "yargs-parser"
+        update-types: ["version-update:semver-major"]
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

.github/workflows/accuracy-tests.yml

@@ -29,7 +29,7 @@ jobs:
     steps:
       - uses: GitHubSecurityLab/actions-permissions/monitor@v1
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version-file: package.json
           cache: "npm"

.github/workflows/check.yml

@@ -17,7 +17,7 @@ jobs:
     steps:
       - uses: GitHubSecurityLab/actions-permissions/monitor@v1
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version-file: package.json
           cache: "npm"
@@ -31,7 +31,7 @@ jobs:
     steps:
       - uses: GitHubSecurityLab/actions-permissions/monitor@v1
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version-file: package.json
           cache: "npm"
@@ -45,7 +45,7 @@ jobs:
     steps:
       - uses: GitHubSecurityLab/actions-permissions/monitor@v1
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version-file: package.json
           cache: "npm"

.github/workflows/cleanup-atlas-env.yml

@@ -0,0 +1,27 @@
+---
+name: "Cleanup stale Atlas test environments"
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * *"
+
+permissions: {}
+
+jobs:
+  cleanup-envs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: GitHubSecurityLab/actions-permissions/monitor@v1
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version-file: package.json
+          cache: "npm"
+      - name: Install dependencies
+        run: npm ci
+      - name: Run cleanup script
+        env:
+          MDB_MCP_API_CLIENT_ID: ${{ secrets.TEST_ATLAS_CLIENT_ID }}
+          MDB_MCP_API_CLIENT_SECRET: ${{ secrets.TEST_ATLAS_CLIENT_SECRET }}
+          MDB_MCP_API_BASE_URL: ${{ vars.TEST_ATLAS_BASE_URL }}
+        run: npm run atlas:cleanup

.github/workflows/code_health_fork.yaml renamed to .github/workflows/code-health-fork.yml

@@ -20,7 +20,12 @@ jobs:
       - uses: GitHubSecurityLab/actions-permissions/monitor@v1
         if: matrix.os == 'ubuntu-latest'
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v4
+      - uses: docker/setup-docker-action@v4
+        if: matrix.os == 'ubuntu-latest'
+        name: Setup Docker Environment
+        with:
+          set-host: true
+      - uses: actions/setup-node@v5
         with:
           node-version-file: package.json
           cache: "npm"

.github/workflows/code_health.yaml renamed to .github/workflows/code-health.yml

@@ -21,7 +21,12 @@ jobs:
       - uses: GitHubSecurityLab/actions-permissions/monitor@v1
         if: matrix.os == 'ubuntu-latest'
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v4
+      - uses: docker/setup-docker-action@v4
+        if: matrix.os == 'ubuntu-latest'
+        name: Setup Docker Environment
+        with:
+          set-host: true
+      - uses: actions/setup-node@v5
         with:
           node-version-file: package.json
           cache: "npm"
@@ -45,7 +50,7 @@ jobs:
     steps:
       - uses: GitHubSecurityLab/actions-permissions/monitor@v1
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version-file: package.json
           cache: "npm"
@@ -93,7 +98,7 @@ jobs:
     needs: [run-tests, run-atlas-tests, run-atlas-local-tests]
     steps:
       - uses: actions/checkout@v5
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version-file: package.json
           cache: "npm"

.github/workflows/dependabot_pr.yaml renamed to .github/workflows/dependabot-pr.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435
       - name: Login to Docker Hub
-        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef
         with:
           username: "${{ secrets.DOCKERHUB_USERNAME }}"
           password: "${{ secrets.DOCKERHUB_PASSWORD }}"

.github/workflows/docker.yaml renamed to .github/workflows/docker.yml

@@ -54,15 +54,15 @@ jobs:
 
       - name: Add comment
         if: steps.create.outputs.issue-key
-        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043
+        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9
         with:
           issue-number: ${{ github.event.issue.number }}
           body: |
             Thanks for opening this issue. The ticket [${{ steps.create.outputs.issue-key }}](https://jira.mongodb.org/browse/${{ steps.create.outputs.issue-key }}) was created for internal tracking.
 
       - name: Remove create-jira label
         if: github.event.action == 'labeled' && github.event.label.name == 'create-jira'
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             try {
@@ -104,7 +104,7 @@ jobs:
           transition-id: 61
       - name: Add closure comment
         if: steps.close_jira_ticket.outcome == 'success'
-        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043
+        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9
         with:
           issue-number: ${{ github.event.issue.number }}
           body: |