mongodb-mcp-server 0.0.4 → 0.0.6

package/tests/integration/tools/mongodb/metadata/explain.test.ts

@@ -0,0 +1,171 @@
+import {
+    databaseCollectionParameters,
+    validateToolMetadata,
+    validateThrowsForInvalidArguments,
+    getResponseElements,
+} from "../../../helpers.js";
+import { describeWithMongoDB, validateAutoConnectBehavior } from "../mongodbHelpers.js";
+
+describeWithMongoDB("explain tool", (integration) => {
+    validateToolMetadata(
+        integration,
+        "explain",
+        "Returns statistics describing the execution of the winning plan chosen by the query optimizer for the evaluated method",
+        [
+            ...databaseCollectionParameters,
+
+            {
+                name: "method",
+                description: "The method and its arguments to run",
+                type: "array",
+                required: true,
+            },
+        ]
+    );
+
+    validateThrowsForInvalidArguments(integration, "explain", [
+        {},
+        { database: 123, collection: "bar", method: [{ name: "find", arguments: {} }] },
+        { database: "test", collection: true, method: [{ name: "find", arguments: {} }] },
+        { database: "test", collection: "bar", method: [{ name: "dnif", arguments: {} }] },
+        { database: "test", collection: "bar", method: "find" },
+        { database: "test", collection: "bar", method: { name: "find", arguments: {} } },
+    ]);
+
+    const testCases = [
+        {
+            method: "aggregate",
+            arguments: { pipeline: [{ $match: { name: "Peter" } }] },
+        },
+        {
+            method: "find",
+            arguments: { filter: { name: "Peter" } },
+        },
+        {
+            method: "count",
+            arguments: {
+                query: { name: "Peter" },
+            },
+        },
+    ];
+
+    for (const testType of ["database", "collection"] as const) {
+        describe(`with non-existing ${testType}`, () => {
+            for (const testCase of testCases) {
+                it(`should return the explain plan for ${testCase.method}`, async () => {
+                    if (testType === "database") {
+                        const { databases } = await integration.mongoClient().db("").admin().listDatabases();
+                        expect(databases.find((db) => db.name === integration.randomDbName())).toBeUndefined();
+                    } else if (testType === "collection") {
+                        await integration
+                            .mongoClient()
+                            .db(integration.randomDbName())
+                            .createCollection("some-collection");
+
+                        const collections = await integration
+                            .mongoClient()
+                            .db(integration.randomDbName())
+                            .listCollections()
+                            .toArray();
+
+                        expect(collections.find((collection) => collection.name === "coll1")).toBeUndefined();
+                    }
+
+                    await integration.connectMcpClient();
+
+                    const response = await integration.mcpClient().callTool({
+                        name: "explain",
+                        arguments: {
+                            database: integration.randomDbName(),
+                            collection: "coll1",
+                            method: [
+                                {
+                                    name: testCase.method,
+                                    arguments: testCase.arguments,
+                                },
+                            ],
+                        },
+                    });
+
+                    const content = getResponseElements(response.content);
+                    expect(content).toHaveLength(2);
+                    expect(content[0].text).toEqual(
+                        `Here is some information about the winning plan chosen by the query optimizer for running the given \`${testCase.method}\` operation in "${integration.randomDbName()}.coll1". This information can be used to understand how the query was executed and to optimize the query performance.`
+                    );
+
+                    expect(content[1].text).toContain("queryPlanner");
+                    expect(content[1].text).toContain("winningPlan");
+                });
+            }
+        });
+    }
+
+    describe("with existing database and collection", () => {
+        for (const indexed of [true, false] as const) {
+            describe(`with ${indexed ? "an index" : "no index"}`, () => {
+                beforeEach(async () => {
+                    await integration
+                        .mongoClient()
+                        .db(integration.randomDbName())
+                        .collection("people")
+                        .insertMany([{ name: "Alice" }, { name: "Bob" }, { name: "Charlie" }]);
+
+                    if (indexed) {
+                        await integration
+                            .mongoClient()
+                            .db(integration.randomDbName())
+                            .collection("people")
+                            .createIndex({ name: 1 });
+                    }
+                });
+
+                for (const testCase of testCases) {
+                    it(`should return the explain plan for ${testCase.method}`, async () => {
+                        await integration.connectMcpClient();
+
+                        const response = await integration.mcpClient().callTool({
+                            name: "explain",
+                            arguments: {
+                                database: integration.randomDbName(),
+                                collection: "people",
+                                method: [
+                                    {
+                                        name: testCase.method,
+                                        arguments: testCase.arguments,
+                                    },
+                                ],
+                            },
+                        });
+
+                        const content = getResponseElements(response.content);
+                        expect(content).toHaveLength(2);
+                        expect(content[0].text).toEqual(
+                            `Here is some information about the winning plan chosen by the query optimizer for running the given \`${testCase.method}\` operation in "${integration.randomDbName()}.people". This information can be used to understand how the query was executed and to optimize the query performance.`
+                        );
+
+                        expect(content[1].text).toContain("queryPlanner");
+                        expect(content[1].text).toContain("winningPlan");
+
+                        if (indexed) {
+                            if (testCase.method === "count") {
+                                expect(content[1].text).toContain("COUNT_SCAN");
+                            } else {
+                                expect(content[1].text).toContain("IXSCAN");
+                            }
+                            expect(content[1].text).toContain("name_1");
+                        } else {
+                            expect(content[1].text).toContain("COLLSCAN");
+                        }
+                    });
+                }
+            });
+        }
+    });
+
+    validateAutoConnectBehavior(integration, "explain", () => {
+        return {
+            args: { database: integration.randomDbName(), collection: "coll1", method: [] },
+            expectedResponse: "No method provided. Expected one of the following: `aggregate`, `find`, or `count`",
+        };
+    });
+});

package/tests/integration/tools/mongodb/metadata/listCollections.test.ts

@@ -1,41 +1,23 @@
-import { getResponseElements, getResponseContent, validateParameters, setupIntegrationTest } from "../../../helpers.js";
-import { toIncludeSameMembers } from "jest-extended";
-import { McpError } from "@modelcontextprotocol/sdk/types.js";
-import config from "../../../../../src/config.js";
-import { ObjectId } from "bson";
+import { describeWithMongoDB, validateAutoConnectBehavior } from "../mongodbHelpers.js";
 
-describe("listCollections tool", () => {
-    const integration = setupIntegrationTest();
+import {
+    getResponseElements,
+    getResponseContent,
+    validateToolMetadata,
+    validateThrowsForInvalidArguments,
+    databaseInvalidArgs,
+    databaseParameters,
+} from "../../../helpers.js";
 
-    it("should have correct metadata", async () => {
-        const { tools } = await integration.mcpClient().listTools();
-        const listCollections = tools.find((tool) => tool.name === "list-collections")!;
-        expect(listCollections).toBeDefined();
-        expect(listCollections.description).toBe("List all collections for a given database");
+describeWithMongoDB("listCollections tool", (integration) => {
+    validateToolMetadata(
+        integration,
+        "list-collections",
+        "List all collections for a given database",
+        databaseParameters
+    );
 
-        validateParameters(listCollections, [
-            { name: "database", description: "Database name", type: "string", required: true },
-        ]);
-    });
-
-    describe("with invalid arguments", () => {
-        const args = [{}, { database: 123 }, { foo: "bar", database: "test" }, { database: [] }];
-        for (const arg of args) {
-            it(`throws a schema error for: ${JSON.stringify(arg)}`, async () => {
-                await integration.connectMcpClient();
-                try {
-                    await integration.mcpClient().callTool({ name: "list-collections", arguments: arg });
-                    expect.fail("Expected an error to be thrown");
-                } catch (error) {
-                    expect(error).toBeInstanceOf(McpError);
-                    const mcpError = error as McpError;
-                    expect(mcpError.code).toEqual(-32602);
-                    expect(mcpError.message).toContain("Invalid arguments for tool list-collections");
-                    expect(mcpError.message).toContain('"expected": "string"');
-                }
-            });
-        }
-    });
+    validateThrowsForInvalidArguments(integration, "list-collections", databaseInvalidArgs);
 
     describe("with non-existent database", () => {
         it("returns no collections", async () => {
@@ -46,7 +28,7 @@ describe("listCollections tool", () => {
             });
             const content = getResponseContent(response.content);
             expect(content).toEqual(
-                `No collections found for database "non-existent". To create a collection, use the "create-collection" tool.`
+                'No collections found for database "non-existent". To create a collection, use the "create-collection" tool.'
             );
         });
     });
@@ -80,25 +62,15 @@ describe("listCollections tool", () => {
         });
     });
 
-    describe("when not connected", () => {
-        it("connects automatically if connection string is configured", async () => {
-            config.connectionString = integration.connectionString();
-
-            const response = await integration
-                .mcpClient()
-                .callTool({ name: "list-collections", arguments: { database: integration.randomDbName() } });
-            const content = getResponseContent(response.content);
-            expect(content).toEqual(
-                `No collections found for database "${integration.randomDbName()}". To create a collection, use the "create-collection" tool.`
-            );
-        });
+    validateAutoConnectBehavior(
+        integration,
+        "list-collections",
 
-        it("throws an error if connection string is not configured", async () => {
-            const response = await integration
-                .mcpClient()
-                .callTool({ name: "list-collections", arguments: { database: integration.randomDbName() } });
-            const content = getResponseContent(response.content);
-            expect(content).toContain("You need to connect to a MongoDB instance before you can access its data.");
-        });
-    });
+        () => {
+            return {
+                args: { database: integration.randomDbName() },
+                expectedResponse: `No collections found for database "${integration.randomDbName()}". To create a collection, use the "create-collection" tool.`,
+            };
+        }
+    );
 });

package/tests/integration/tools/mongodb/metadata/listDatabases.test.ts

@@ -1,44 +1,26 @@
-import config from "../../../../../src/config.js";
-import { getResponseElements, getParameters, setupIntegrationTest, getResponseContent } from "../../../helpers.js";
-import { toIncludeSameMembers } from "jest-extended";
+import { describeWithMongoDB, validateAutoConnectBehavior } from "../mongodbHelpers.js";
+import { getResponseElements, getParameters, expectDefined } from "../../../helpers.js";
 
-describe("listDatabases tool", () => {
-    const integration = setupIntegrationTest();
+describeWithMongoDB("listDatabases tool", (integration) => {
+    const defaultDatabases = ["admin", "config", "local"];
 
     it("should have correct metadata", async () => {
         const { tools } = await integration.mcpClient().listTools();
-        const listDatabases = tools.find((tool) => tool.name === "list-databases")!;
-        expect(listDatabases).toBeDefined();
+        const listDatabases = tools.find((tool) => tool.name === "list-databases");
+        expectDefined(listDatabases);
         expect(listDatabases.description).toBe("List all databases for a MongoDB connection");
 
         const parameters = getParameters(listDatabases);
         expect(parameters).toHaveLength(0);
     });
 
-    describe("when not connected", () => {
-        it("connects automatically if connection string is configured", async () => {
-            config.connectionString = integration.connectionString();
-
-            const response = await integration.mcpClient().callTool({ name: "list-databases", arguments: {} });
-            const dbNames = getDbNames(response.content);
-
-            expect(dbNames).toIncludeSameMembers(["admin", "config", "local"]);
-        });
-
-        it("throws an error if connection string is not configured", async () => {
-            const response = await integration.mcpClient().callTool({ name: "list-databases", arguments: {} });
-            const content = getResponseContent(response.content);
-            expect(content).toContain("You need to connect to a MongoDB instance before you can access its data.");
-        });
-    });
-
     describe("with no preexisting databases", () => {
         it("returns only the system databases", async () => {
             await integration.connectMcpClient();
             const response = await integration.mcpClient().callTool({ name: "list-databases", arguments: {} });
             const dbNames = getDbNames(response.content);
 
-            expect(dbNames).toIncludeSameMembers(["admin", "config", "local"]);
+            expect(defaultDatabases).toIncludeAllMembers(dbNames);
         });
     });
 
@@ -52,9 +34,33 @@ describe("listDatabases tool", () => {
 
             const response = await integration.mcpClient().callTool({ name: "list-databases", arguments: {} });
             const dbNames = getDbNames(response.content);
-            expect(dbNames).toIncludeSameMembers(["admin", "config", "local", "foo", "baz"]);
+            expect(dbNames).toIncludeSameMembers([...defaultDatabases, "foo", "baz"]);
         });
     });
+
+    validateAutoConnectBehavior(
+        integration,
+        "list-databases",
+        () => {
+            return {
+                args: {},
+                validate: (content) => {
+                    const dbNames = getDbNames(content);
+
+                    expect(defaultDatabases).toIncludeAllMembers(dbNames);
+                },
+            };
+        },
+        async () => {
+            const mongoClient = integration.mongoClient();
+            const { databases } = await mongoClient.db("admin").command({ listDatabases: 1, nameOnly: true });
+            for (const db of databases as { name: string }[]) {
+                if (!defaultDatabases.includes(db.name)) {
+                    await mongoClient.db(db.name).dropDatabase();
+                }
+            }
+        }
+    );
 });
 
 function getDbNames(content: unknown): (string | null)[] {

package/tests/integration/tools/mongodb/metadata/logs.test.ts

@@ -0,0 +1,83 @@
+import { validateToolMetadata, validateThrowsForInvalidArguments, getResponseElements } from "../../../helpers.js";
+import { describeWithMongoDB, validateAutoConnectBehavior } from "../mongodbHelpers.js";
+
+describeWithMongoDB("logs tool", (integration) => {
+    validateToolMetadata(integration, "mongodb-logs", "Returns the most recent logged mongod events", [
+        {
+            type: "string",
+            name: "type",
+            description:
+                "The type of logs to return. Global returns all recent log entries, while startupWarnings returns only warnings and errors from when the process started.",
+            required: false,
+        },
+        {
+            type: "integer",
+            name: "limit",
+            description: "The maximum number of log entries to return.",
+            required: false,
+        },
+    ]);
+
+    validateThrowsForInvalidArguments(integration, "mongodb-logs", [
+        { type: 123 },
+        { type: "something" },
+        { limit: 0 },
+        { limit: true },
+        { limit: 1025 },
+    ]);
+
+    it("should return global logs", async () => {
+        await integration.connectMcpClient();
+        const response = await integration.mcpClient().callTool({
+            name: "mongodb-logs",
+            arguments: {},
+        });
+
+        const elements = getResponseElements(response);
+
+        // Default limit is 50
+        expect(elements.length).toBeLessThanOrEqual(51);
+        expect(elements[0].text).toMatch(/Found: \d+ messages/);
+
+        for (let i = 1; i < elements.length; i++) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            const log = JSON.parse(elements[i].text);
+            expect(log).toHaveProperty("t");
+            expect(log).toHaveProperty("msg");
+        }
+    });
+
+    it("should return startupWarnings logs", async () => {
+        await integration.connectMcpClient();
+        const response = await integration.mcpClient().callTool({
+            name: "mongodb-logs",
+            arguments: {
+                type: "startupWarnings",
+            },
+        });
+
+        const elements = getResponseElements(response);
+        expect(elements.length).toBeLessThanOrEqual(51);
+        for (let i = 1; i < elements.length; i++) {
+            const log = JSON.parse(elements[i].text) as { tags: string[] };
+            expect(log).toHaveProperty("t");
+            expect(log).toHaveProperty("msg");
+            expect(log).toHaveProperty("tags");
+            expect(log.tags).toContain("startupWarnings");
+        }
+    });
+
+    validateAutoConnectBehavior(integration, "mongodb-logs", () => {
+        return {
+            args: {
+                database: integration.randomDbName(),
+                collection: "foo",
+            },
+            validate: (content) => {
+                const elements = getResponseElements(content);
+                expect(elements.length).toBeLessThanOrEqual(51);
+                expect(elements[0].text).toMatch(/Found: \d+ messages/);
+            },
+        };
+    });
+});

package/tests/integration/tools/mongodb/mongodbHelpers.ts

@@ -0,0 +1,176 @@
+import { MongoCluster } from "mongodb-runner";
+import path from "path";
+import fs from "fs/promises";
+import { MongoClient, ObjectId } from "mongodb";
+import { getResponseContent, IntegrationTest, setupIntegrationTest } from "../../helpers.js";
+import { config, UserConfig } from "../../../../src/config.js";
+
+interface MongoDBIntegrationTest {
+    mongoClient: () => MongoClient;
+    connectionString: () => string;
+    randomDbName: () => string;
+}
+
+export function describeWithMongoDB(
+    name: string,
+    fn: (integration: IntegrationTest & MongoDBIntegrationTest & { connectMcpClient: () => Promise<void> }) => void,
+    getUserConfig: (mdbIntegration: MongoDBIntegrationTest) => UserConfig = () => config,
+    describeFn = describe
+) {
+    describeFn(name, () => {
+        const mdbIntegration = setupMongoDBIntegrationTest();
+        const integration = setupIntegrationTest(() => ({
+            ...getUserConfig(mdbIntegration),
+            connectionString: mdbIntegration.connectionString(),
+        }));
+
+        beforeEach(() => {
+            integration.mcpServer().userConfig.connectionString = mdbIntegration.connectionString();
+        });
+
+        fn({
+            ...integration,
+            ...mdbIntegration,
+            connectMcpClient: async () => {
+                // TODO: https://github.com/mongodb-js/mongodb-mcp-server/issues/141 - reenable when
+                // the connect tool is reenabled
+                // await integration.mcpClient().callTool({
+                //     name: "connect",
+                //     arguments: { connectionString: mdbIntegration.connectionString() },
+                // });
+            },
+        });
+    });
+}
+
+export function setupMongoDBIntegrationTest(): MongoDBIntegrationTest {
+    let mongoCluster: // TODO: Fix this type once mongodb-runner is updated.
+    | {
+              connectionString: string;
+              close: () => Promise<void>;
+          }
+        | undefined;
+    let mongoClient: MongoClient | undefined;
+    let randomDbName: string;
+
+    beforeEach(() => {
+        randomDbName = new ObjectId().toString();
+    });
+
+    afterEach(async () => {
+        await mongoClient?.close();
+        mongoClient = undefined;
+    });
+
+    beforeAll(async function () {
+        // Downloading Windows executables in CI takes a long time because
+        // they include debug symbols...
+        const tmpDir = path.join(__dirname, "..", "..", "..", "tmp");
+        await fs.mkdir(tmpDir, { recursive: true });
+
+        // On Windows, we may have a situation where mongod.exe is not fully released by the OS
+        // before we attempt to run it again, so we add a retry.
+        let dbsDir = path.join(tmpDir, "mongodb-runner", "dbs");
+        for (let i = 0; i < 10; i++) {
+            try {
+                // TODO: Fix this type once mongodb-runner is updated.
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+                mongoCluster = await MongoCluster.start({
+                    tmpDir: dbsDir,
+                    logDir: path.join(tmpDir, "mongodb-runner", "logs"),
+                    topology: "standalone",
+                });
+
+                return;
+            } catch (err) {
+                if (i < 5) {
+                    // Just wait a little bit and retry
+                    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+                    console.error(`Failed to start cluster in ${dbsDir}, attempt ${i}: ${err}`);
+                    await new Promise((resolve) => setTimeout(resolve, 1000));
+                } else {
+                    // If we still fail after 5 seconds, try another db dir
+                    console.error(
+                        // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+                        `Failed to start cluster in ${dbsDir}, attempt ${i}: ${err}. Retrying with a new db dir.`
+                    );
+                    dbsDir = path.join(tmpDir, "mongodb-runner", `dbs${i - 5}`);
+                }
+            }
+        }
+
+        throw new Error("Failed to start cluster after 10 attempts");
+    }, 120_000);
+
+    afterAll(async function () {
+        await mongoCluster?.close();
+        mongoCluster = undefined;
+    });
+
+    const getConnectionString = () => {
+        if (!mongoCluster) {
+            throw new Error("beforeAll() hook not ran yet");
+        }
+
+        return mongoCluster.connectionString;
+    };
+
+    return {
+        mongoClient: () => {
+            if (!mongoClient) {
+                mongoClient = new MongoClient(getConnectionString());
+            }
+            return mongoClient;
+        },
+        connectionString: getConnectionString,
+
+        randomDbName: () => randomDbName,
+    };
+}
+
+export function validateAutoConnectBehavior(
+    integration: IntegrationTest & MongoDBIntegrationTest,
+    name: string,
+    validation: () => {
+        args: { [x: string]: unknown };
+        expectedResponse?: string;
+        validate?: (content: unknown) => void;
+    },
+    beforeEachImpl?: () => Promise<void>
+): void {
+    // TODO: https://github.com/mongodb-js/mongodb-mcp-server/issues/141 - reenable when the connect tool is reenabled
+    describe.skip("when not connected", () => {
+        if (beforeEachImpl) {
+            beforeEach(() => beforeEachImpl());
+        }
+
+        it("connects automatically if connection string is configured", async () => {
+            integration.mcpServer().userConfig.connectionString = integration.connectionString();
+
+            const validationInfo = validation();
+
+            const response = await integration.mcpClient().callTool({
+                name,
+                arguments: validationInfo.args,
+            });
+
+            if (validationInfo.expectedResponse) {
+                const content = getResponseContent(response.content);
+                expect(content).toContain(validationInfo.expectedResponse);
+            }
+
+            if (validationInfo.validate) {
+                validationInfo.validate(response.content);
+            }
+        });
+
+        it("throws an error if connection string is not configured", async () => {
+            const response = await integration.mcpClient().callTool({
+                name,
+                arguments: validation().args,
+            });
+            const content = getResponseContent(response.content);
+            expect(content).toContain("You need to connect to a MongoDB instance before you can access its data.");
+        });
+    });
+}