Merge branch 'atlas-list-performance-advisor-tool' into atlas-list-performance-advisor-base-tool

kylelai1 · kylelai1 · commit d6b7db833871 · 2025-09-19T11:18:28.000-04:00
diff --git a/.github/copilot-instructions.md b/.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`.
diff --git a/src/server.ts b/src/server.ts
@@ -239,6 +239,13 @@ export class Server {
         // Validate API client credentials
         if (this.userConfig.apiClientId && this.userConfig.apiClientSecret) {
             try {
+                if (!this.userConfig.apiBaseUrl.startsWith("https://")) {
+                    const message =
+                        "Failed to validate MongoDB Atlas the credentials from config: apiBaseUrl must start with https://";
+                    console.error(message);
+                    throw new Error(message);
+                }
+
                 await this.session.apiClient.validateAccessToken();
             } catch (error) {
                 if (this.userConfig.connectionString === undefined) {
diff --git a/src/tools/args.ts b/src/tools/args.ts
@@ -1,4 +1,5 @@
 import { z, type ZodString } from "zod";
+import { EJSON } from "bson";
 
 const NO_UNICODE_REGEX = /^[\x20-\x7E]*$/;
 export const NO_UNICODE_ERROR = "String cannot contain special characters or Unicode symbols";
@@ -68,3 +69,15 @@ export const AtlasArgs = {
     password: (): z.ZodString =>
         z.string().min(1, "Password is required").max(100, "Password must be 100 characters or less"),
 };
+
+function toEJSON<T extends object | undefined>(value: T): T {
+    if (!value) {
+        return value;
+    }
+
+    return EJSON.deserialize(value, { relaxed: false }) as T;
+}
+
+export function zEJSON(): z.AnyZodObject {
+    return z.object({}).passthrough().transform(toEJSON) as unknown as z.AnyZodObject;
+}
diff --git a/src/tools/mongodb/create/insertMany.ts b/src/tools/mongodb/create/insertMany.ts
@@ -2,14 +2,15 @@ import { z } from "zod";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
 import type { ToolArgs, OperationType } from "../../tool.js";
+import { zEJSON } from "../../args.js";
 
 export class InsertManyTool extends MongoDBToolBase {
     public name = "insert-many";
     protected description = "Insert an array of documents into a MongoDB collection";
     protected argsShape = {
         ...DbOperationArgs,
         documents: z
-            .array(z.object({}).passthrough().describe("An individual MongoDB document"))
+            .array(zEJSON().describe("An individual MongoDB document"))
             .describe(
                 "The array of documents to insert, matching the syntax of the document argument of db.collection.insertMany()"
             ),
diff --git a/src/tools/mongodb/delete/deleteMany.ts b/src/tools/mongodb/delete/deleteMany.ts
@@ -1,18 +1,16 @@
-import { z } from "zod";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
 import type { ToolArgs, OperationType } from "../../tool.js";
 import { checkIndexUsage } from "../../../helpers/indexCheck.js";
 import { EJSON } from "bson";
+import { zEJSON } from "../../args.js";
 
 export class DeleteManyTool extends MongoDBToolBase {
     public name = "delete-many";
     protected description = "Removes all documents that match the filter from a MongoDB collection";
     protected argsShape = {
         ...DbOperationArgs,
-        filter: z
-            .object({})
-            .passthrough()
+        filter: zEJSON()
             .optional()
             .describe(
                 "The query filter, specifying the deletion criteria. Matches the syntax of the filter argument of db.collection.deleteMany()"
diff --git a/src/tools/mongodb/metadata/explain.ts b/src/tools/mongodb/metadata/explain.ts
@@ -4,7 +4,6 @@ import type { ToolArgs, OperationType } from "../../tool.js";
 import { formatUntrustedData } from "../../tool.js";
 import { z } from "zod";
 import type { Document } from "mongodb";
-import { ExplainVerbosity } from "mongodb";
 import { AggregateArgs } from "../read/aggregate.js";
 import { FindArgs } from "../read/find.js";
 import { CountArgs } from "../read/count.js";
@@ -34,16 +33,22 @@ export class ExplainTool extends MongoDBToolBase {
                 ])
             )
             .describe("The method and its arguments to run"),
+        verbosity: z
+            .enum(["queryPlanner", "queryPlannerExtended", "executionStats", "allPlansExecution"])
+            .optional()
+            .default("queryPlanner")
+            .describe(
+                "The verbosity of the explain plan, defaults to queryPlanner. If the user wants to know how fast is a query in execution time, use executionStats. It supports all verbosities as defined in the MongoDB Driver."
+            ),
     };
 
     public operationType: OperationType = "metadata";
 
-    static readonly defaultVerbosity = ExplainVerbosity.queryPlanner;
-
     protected async execute({
         database,
         collection,
         method: methods,
+        verbosity,
     }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
         const provider = await this.ensureConnected();
         const method = methods[0];
@@ -66,14 +71,12 @@ export class ExplainTool extends MongoDBToolBase {
                             writeConcern: undefined,
                         }
                     )
-                    .explain(ExplainTool.defaultVerbosity);
+                    .explain(verbosity);
                 break;
             }
             case "find": {
                 const { filter, ...rest } = method.arguments;
-                result = await provider
-                    .find(database, collection, filter as Document, { ...rest })
-                    .explain(ExplainTool.defaultVerbosity);
+                result = await provider.find(database, collection, filter as Document, { ...rest }).explain(verbosity);
                 break;
             }
             case "count": {
@@ -83,15 +86,15 @@ export class ExplainTool extends MongoDBToolBase {
                         count: collection,
                         query,
                     },
-                    verbosity: ExplainTool.defaultVerbosity,
+                    verbosity,
                 });
                 break;
             }
         }
 
         return {
             content: formatUntrustedData(
-                `Here is some information about the winning plan chosen by the query optimizer for running the given \`${method.name}\` operation in "${database}.${collection}". This information can be used to understand how the query was executed and to optimize the query performance.`,
+                `Here is some information about the winning plan chosen by the query optimizer for running the given \`${method.name}\` operation in "${database}.${collection}". The execution plan was run with the following verbosity: "${verbosity}". This information can be used to understand how the query was executed and to optimize the query performance.`,
                 JSON.stringify(result)
             ),
         };
diff --git a/src/tools/mongodb/read/aggregate.ts b/src/tools/mongodb/read/aggregate.ts
@@ -6,9 +6,10 @@ import { formatUntrustedData } from "../../tool.js";
 import { checkIndexUsage } from "../../../helpers/indexCheck.js";
 import { EJSON } from "bson";
 import { ErrorCodes, MongoDBError } from "../../../common/errors.js";
+import { zEJSON } from "../../args.js";
 
 export const AggregateArgs = {
-    pipeline: z.array(z.object({}).passthrough()).describe("An array of aggregation stages to execute"),
+    pipeline: z.array(zEJSON()).describe("An array of aggregation stages to execute"),
 };
 
 export class AggregateTool extends MongoDBToolBase {
diff --git a/src/tools/mongodb/read/count.ts b/src/tools/mongodb/read/count.ts
@@ -1,13 +1,11 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
 import type { ToolArgs, OperationType } from "../../tool.js";
-import { z } from "zod";
 import { checkIndexUsage } from "../../../helpers/indexCheck.js";
+import { zEJSON } from "../../args.js";
 
 export const CountArgs = {
-    query: z
-        .object({})
-        .passthrough()
+    query: zEJSON()
         .optional()
         .describe(
             "A filter/query parameter. Allows users to filter the documents to count. Matches the syntax of the filter argument of db.collection.count()."
diff --git a/src/tools/mongodb/read/find.ts b/src/tools/mongodb/read/find.ts
@@ -6,11 +6,10 @@ import { formatUntrustedData } from "../../tool.js";
 import type { SortDirection } from "mongodb";
 import { checkIndexUsage } from "../../../helpers/indexCheck.js";
 import { EJSON } from "bson";
+import { zEJSON } from "../../args.js";
 
 export const FindArgs = {
-    filter: z
-        .object({})
-        .passthrough()
+    filter: zEJSON()
         .optional()
         .describe("The query filter, matching the syntax of the query argument of db.collection.find()"),
     projection: z
diff --git a/src/tools/mongodb/update/updateMany.ts b/src/tools/mongodb/update/updateMany.ts
@@ -3,23 +3,21 @@ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
 import type { ToolArgs, OperationType } from "../../tool.js";
 import { checkIndexUsage } from "../../../helpers/indexCheck.js";
+import { zEJSON } from "../../args.js";
 
 export class UpdateManyTool extends MongoDBToolBase {
     public name = "update-many";
     protected description = "Updates all documents that match the specified filter for a collection";
     protected argsShape = {
         ...DbOperationArgs,
-        filter: z
-            .object({})
-            .passthrough()
+        filter: zEJSON()
             .optional()
             .describe(
                 "The selection criteria for the update, matching the syntax of the filter argument of db.collection.updateOne()"
             ),
-        update: z
-            .object({})
-            .passthrough()
-            .describe("An update document describing the modifications to apply using update operator expressions"),
+        update: zEJSON().describe(
+            "An update document describing the modifications to apply using update operator expressions"
+        ),
         upsert: z
             .boolean()
             .optional()
diff --git a/src/transports/stdio.ts b/src/transports/stdio.ts
@@ -1,55 +1,8 @@
-import { EJSON } from "bson";
-import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
-import { JSONRPCMessageSchema } from "@modelcontextprotocol/sdk/types.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { LogId } from "../common/logger.js";
 import type { Server } from "../server.js";
 import { TransportRunnerBase, type TransportRunnerConfig } from "./base.js";
 
-// This is almost a copy of ReadBuffer from @modelcontextprotocol/sdk
-// but it uses EJSON.parse instead of JSON.parse to handle BSON types
-export class EJsonReadBuffer {
-    private _buffer?: Buffer;
-
-    append(chunk: Buffer): void {
-        this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
-    }
-
-    readMessage(): JSONRPCMessage | null {
-        if (!this._buffer) {
-            return null;
-        }
-
-        const index = this._buffer.indexOf("\n");
-        if (index === -1) {
-            return null;
-        }
-
-        const line = this._buffer.toString("utf8", 0, index).replace(/\r$/, "");
-        this._buffer = this._buffer.subarray(index + 1);
-
-        // This is using EJSON.parse instead of JSON.parse to handle BSON types
-        return JSONRPCMessageSchema.parse(EJSON.parse(line));
-    }
-
-    clear(): void {
-        this._buffer = undefined;
-    }
-}
-
-// This is a hacky workaround for https://github.com/mongodb-js/mongodb-mcp-server/issues/211
-// The underlying issue is that StdioServerTransport uses JSON.parse to deserialize
-// messages, but that doesn't handle bson types, such as ObjectId when serialized as EJSON.
-//
-// This function creates a StdioServerTransport and replaces the internal readBuffer with EJsonReadBuffer
-// that uses EJson.parse instead.
-export function createStdioTransport(): StdioServerTransport {
-    const server = new StdioServerTransport();
-    server["_readBuffer"] = new EJsonReadBuffer();
-
-    return server;
-}
-
 export class StdioRunner extends TransportRunnerBase {
     private server: Server | undefined;
 
@@ -60,8 +13,7 @@ export class StdioRunner extends TransportRunnerBase {
     async start(): Promise<void> {
         try {
             this.server = await this.setupServer();
-
-            const transport = createStdioTransport();
+            const transport = new StdioServerTransport();
 
             await this.server.connect(transport);
         } catch (error: unknown) {
diff --git a/tests/integration/indexCheck.test.ts b/tests/integration/indexCheck.test.ts
@@ -80,7 +80,7 @@ describe("IndexCheck integration tests", () => {
                             arguments: {
                                 database: integration.randomDbName(),
                                 collection: "find-test-collection",
-                                filter: { _id: docs[0]?._id }, // Uses _id index (IDHACK)
+                                filter: { _id: { $oid: docs[0]?._id } }, // Uses _id index (IDHACK)
                             },
                         });
 
diff --git a/tests/integration/tools/mongodb/create/insertMany.test.ts b/tests/integration/tools/mongodb/create/insertMany.test.ts
@@ -76,7 +76,7 @@ describeWithMongoDB("insertMany tool", (integration) => {
             arguments: {
                 database: integration.randomDbName(),
                 collection: "coll1",
-                documents: [{ prop1: "value1", _id: insertedIds[0] }],
+                documents: [{ prop1: "value1", _id: { $oid: insertedIds[0] } }],
             },
         });
 
diff --git a/tests/integration/tools/mongodb/metadata/explain.test.ts b/tests/integration/tools/mongodb/metadata/explain.test.ts
diff --git a/tests/integration/tools/mongodb/mongodbHelpers.ts b/tests/integration/tools/mongodb/mongodbHelpers.ts
diff --git a/tests/integration/tools/mongodb/read/find.test.ts b/tests/integration/tools/mongodb/read/find.test.ts
diff --git a/tests/unit/transports/stdio.test.ts b/tests/unit/transports/stdio.test.ts
