mongodb-mcp-server 0.2.0 → 0.3.0

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

@@ -1,172 +0,0 @@
-import {
-    databaseCollectionParameters,
-    validateToolMetadata,
-    validateThrowsForInvalidArguments,
-    getResponseElements,
-} from "../../../helpers.js";
-import { describeWithMongoDB, validateAutoConnectBehavior } from "../mongodbHelpers.js";
-import { beforeEach, describe, expect, it } from "vitest";
-
-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,77 +0,0 @@
-import { describeWithMongoDB, validateAutoConnectBehavior } from "../mongodbHelpers.js";
-
-import {
-    getResponseElements,
-    getResponseContent,
-    validateToolMetadata,
-    validateThrowsForInvalidArguments,
-    databaseInvalidArgs,
-    databaseParameters,
-} from "../../../helpers.js";
-import { describe, expect, it } from "vitest";
-
-describeWithMongoDB("listCollections tool", (integration) => {
-    validateToolMetadata(
-        integration,
-        "list-collections",
-        "List all collections for a given database",
-        databaseParameters
-    );
-
-    validateThrowsForInvalidArguments(integration, "list-collections", databaseInvalidArgs);
-
-    describe("with non-existent database", () => {
-        it("returns no collections", async () => {
-            await integration.connectMcpClient();
-            const response = await integration.mcpClient().callTool({
-                name: "list-collections",
-                arguments: { database: "non-existent" },
-            });
-            const content = getResponseContent(response.content);
-            expect(content).toEqual(
-                'No collections found for database "non-existent". To create a collection, use the "create-collection" tool.'
-            );
-        });
-    });
-
-    describe("with existing database", () => {
-        it("returns collections", async () => {
-            const mongoClient = integration.mongoClient();
-            await mongoClient.db(integration.randomDbName()).createCollection("collection-1");
-
-            await integration.connectMcpClient();
-            const response = await integration.mcpClient().callTool({
-                name: "list-collections",
-                arguments: { database: integration.randomDbName() },
-            });
-            const items = getResponseElements(response.content);
-            expect(items).toHaveLength(1);
-            expect(items[0]?.text).toContain('Name: "collection-1"');
-
-            await mongoClient.db(integration.randomDbName()).createCollection("collection-2");
-
-            const response2 = await integration.mcpClient().callTool({
-                name: "list-collections",
-                arguments: { database: integration.randomDbName() },
-            });
-            const items2 = getResponseElements(response2.content);
-            expect(items2).toHaveLength(2);
-            expect(items2.map((item) => item.text)).toIncludeSameMembers([
-                'Name: "collection-1"',
-                'Name: "collection-2"',
-            ]);
-        });
-    });
-
-    validateAutoConnectBehavior(
-        integration,
-        "list-collections",
-
-        () => {
-            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,78 +0,0 @@
-import { describeWithMongoDB, validateAutoConnectBehavior } from "../mongodbHelpers.js";
-import { getResponseElements, getParameters, expectDefined } from "../../../helpers.js";
-import { describe, expect, it } from "vitest";
-
-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");
-        expectDefined(listDatabases);
-        expect(listDatabases.description).toBe("List all databases for a MongoDB connection");
-
-        const parameters = getParameters(listDatabases);
-        expect(parameters).toHaveLength(0);
-    });
-
-    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(defaultDatabases).toStrictEqual(dbNames);
-        });
-    });
-
-    describe("with preexisting databases", () => {
-        it("returns their names and sizes", async () => {
-            const mongoClient = integration.mongoClient();
-            await mongoClient.db("foo").collection("bar").insertOne({ test: "test" });
-            await mongoClient.db("baz").collection("qux").insertOne({ test: "test" });
-
-            await integration.connectMcpClient();
-
-            const response = await integration.mcpClient().callTool({ name: "list-databases", arguments: {} });
-            const dbNames = getDbNames(response.content);
-            expect(dbNames).toIncludeSameMembers([...defaultDatabases, "foo", "baz"]);
-        });
-    });
-
-    validateAutoConnectBehavior(
-        integration,
-        "list-databases",
-        () => {
-            return {
-                args: {},
-                validate: (content) => {
-                    const dbNames = getDbNames(content);
-
-                    expect(defaultDatabases).toStrictEqual(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)[] {
-    const responseItems = getResponseElements(content);
-    return responseItems
-        .map((item) => {
-            if (item && typeof item.text === "string") {
-                const match = item.text.match(/Name: ([^,]+), Size: \d+ bytes/);
-                return match ? match[1] : null;
-            }
-            return null;
-        })
-        .filter((item): item is string | null => item !== undefined);
-}

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

@@ -1,84 +0,0 @@
-import { expect, it } from "vitest";
-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

@@ -1,235 +0,0 @@
-import { MongoCluster } from "mongodb-runner";
-import path from "path";
-import { fileURLToPath } from "url";
-import fs from "fs/promises";
-import { Document, MongoClient, ObjectId } from "mongodb";
-import { getResponseContent, IntegrationTest, setupIntegrationTest, defaultTestConfig } from "../../helpers.js";
-import { UserConfig } from "../../../../src/common/config.js";
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-const testDataDumpPath = path.join(__dirname, "..", "..", "..", "accuracy", "test-data-dumps");
-
-const testDataPaths = [
-    {
-        db: "comics",
-        collection: "books",
-        path: path.join(testDataDumpPath, "comics.books.json"),
-    },
-    {
-        db: "comics",
-        collection: "characters",
-        path: path.join(testDataDumpPath, "comics.characters.json"),
-    },
-    {
-        db: "mflix",
-        collection: "movies",
-        path: path.join(testDataDumpPath, "mflix.movies.json"),
-    },
-    {
-        db: "mflix",
-        collection: "shows",
-        path: path.join(testDataDumpPath, "mflix.shows.json"),
-    },
-];
-
-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 = () => defaultTestConfig
-) {
-    describe(name, () => {
-        const mdbIntegration = setupMongoDBIntegrationTest();
-        const integration = setupIntegrationTest(() => ({
-            ...getUserConfig(mdbIntegration),
-        }));
-
-        fn({
-            ...integration,
-            ...mdbIntegration,
-            connectMcpClient: async () => {
-                const { tools } = await integration.mcpClient().listTools();
-                if (tools.find((tool) => tool.name === "connect")) {
-                    await integration.mcpClient().callTool({
-                        name: "connect",
-                        arguments: { connectionString: mdbIntegration.connectionString() },
-                    });
-                }
-            },
-        });
-    });
-}
-
-export function setupMongoDBIntegrationTest(): MongoDBIntegrationTest {
-    let mongoCluster: MongoCluster | 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 {
-                mongoCluster = await MongoCluster.start({
-                    tmpDir: dbsDir,
-                    logDir: path.join(tmpDir, "mongodb-runner", "logs"),
-                    topology: "standalone",
-                    version: "8.0.10",
-                });
-
-                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 {
-    describe("when not connected", () => {
-        if (beforeEachImpl) {
-            beforeEach(() => beforeEachImpl());
-        }
-
-        afterEach(() => {
-            integration.mcpServer().userConfig.connectionString = undefined;
-        });
-
-        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.");
-        });
-    });
-}
-
-export function prepareTestData(integration: MongoDBIntegrationTest) {
-    const NON_TEST_DBS = ["admin", "config", "local"];
-    const testData: {
-        db: string;
-        collection: string;
-        data: Document[];
-    }[] = [];
-
-    beforeAll(async () => {
-        for (const { db, collection, path } of testDataPaths) {
-            testData.push({
-                db,
-                collection,
-                data: JSON.parse(await fs.readFile(path, "utf8")) as Document[],
-            });
-        }
-    });
-
-    return {
-        async populateTestData(this: void) {
-            const client = integration.mongoClient();
-            for (const { db, collection, data } of testData) {
-                await client.db(db).collection(collection).insertMany(data);
-            }
-        },
-        async cleanupTestDatabases(this: void, integration: MongoDBIntegrationTest) {
-            const client = integration.mongoClient();
-            const admin = client.db().admin();
-            const databases = await admin.listDatabases();
-            await Promise.all(
-                databases.databases
-                    .filter(({ name }) => !NON_TEST_DBS.includes(name))
-                    .map(({ name }) => client.db(name).dropDatabase())
-            );
-        },
-    };
-}