mongodb-mcp-server 0.2.0 → 0.3.0

package/src/tools/mongodb/create/insertMany.ts

@@ -1,40 +0,0 @@
-import { z } from "zod";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
-import { ToolArgs, OperationType } from "../../tool.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"))
-            .describe(
-                "The array of documents to insert, matching the syntax of the document argument of db.collection.insertMany()"
-            ),
-    };
-    public operationType: OperationType = "create";
-
-    protected async execute({
-        database,
-        collection,
-        documents,
-    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-        const result = await provider.insertMany(database, collection, documents);
-
-        return {
-            content: [
-                {
-                    text: `Inserted \`${result.insertedCount}\` document(s) into collection "${collection}"`,
-                    type: "text",
-                },
-                {
-                    text: `Inserted IDs: ${Object.values(result.insertedIds).join(", ")}`,
-                    type: "text",
-                },
-            ],
-        };
-    }
-}

package/src/tools/mongodb/delete/deleteMany.ts

@@ -1,58 +0,0 @@
-import { z } from "zod";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-import { checkIndexUsage } from "../../../helpers/indexCheck.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()
-            .optional()
-            .describe(
-                "The query filter, specifying the deletion criteria. Matches the syntax of the filter argument of db.collection.deleteMany()"
-            ),
-    };
-    public operationType: OperationType = "delete";
-
-    protected async execute({
-        database,
-        collection,
-        filter,
-    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-
-        // Check if delete operation uses an index if enabled
-        if (this.config.indexCheck) {
-            await checkIndexUsage(provider, database, collection, "deleteMany", async () => {
-                return provider.runCommandWithCheck(database, {
-                    explain: {
-                        delete: collection,
-                        deletes: [
-                            {
-                                q: filter || {},
-                                limit: 0, // 0 means delete all matching documents
-                            },
-                        ],
-                    },
-                    verbosity: "queryPlanner",
-                });
-            });
-        }
-
-        const result = await provider.deleteMany(database, collection, filter);
-
-        return {
-            content: [
-                {
-                    text: `Deleted \`${result.deletedCount}\` document(s) from collection "${collection}"`,
-                    type: "text",
-                },
-            ],
-        };
-    }
-}

package/src/tools/mongodb/delete/dropCollection.ts

@@ -1,27 +0,0 @@
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-
-export class DropCollectionTool extends MongoDBToolBase {
-    public name = "drop-collection";
-    protected description =
-        "Removes a collection or view from the database. The method also removes any indexes associated with the dropped collection.";
-    protected argsShape = {
-        ...DbOperationArgs,
-    };
-    public operationType: OperationType = "delete";
-
-    protected async execute({ database, collection }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-        const result = await provider.dropCollection(database, collection);
-
-        return {
-            content: [
-                {
-                    text: `${result ? "Successfully dropped" : "Failed to drop"} collection "${collection}" from database "${database}"`,
-                    type: "text",
-                },
-            ],
-        };
-    }
-}

package/src/tools/mongodb/delete/dropDatabase.ts

@@ -1,26 +0,0 @@
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-
-export class DropDatabaseTool extends MongoDBToolBase {
-    public name = "drop-database";
-    protected description = "Removes the specified database, deleting the associated data files";
-    protected argsShape = {
-        database: DbOperationArgs.database,
-    };
-    public operationType: OperationType = "delete";
-
-    protected async execute({ database }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-        const result = await provider.dropDatabase(database);
-
-        return {
-            content: [
-                {
-                    text: `${result.ok ? "Successfully dropped" : "Failed to drop"} database "${database}"`,
-                    type: "text",
-                },
-            ],
-        };
-    }
-}

package/src/tools/mongodb/metadata/collectionSchema.ts

@@ -1,43 +0,0 @@
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-import { getSimplifiedSchema } from "mongodb-schema";
-
-export class CollectionSchemaTool extends MongoDBToolBase {
-    public name = "collection-schema";
-    protected description = "Describe the schema for a collection";
-    protected argsShape = DbOperationArgs;
-
-    public operationType: OperationType = "metadata";
-
-    protected async execute({ database, collection }: ToolArgs<typeof DbOperationArgs>): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-        const documents = await provider.find(database, collection, {}, { limit: 5 }).toArray();
-        const schema = await getSimplifiedSchema(documents);
-
-        const fieldsCount = Object.entries(schema).length;
-        if (fieldsCount === 0) {
-            return {
-                content: [
-                    {
-                        text: `Could not deduce the schema for "${database}.${collection}". This may be because it doesn't exist or is empty.`,
-                        type: "text",
-                    },
-                ],
-            };
-        }
-
-        return {
-            content: [
-                {
-                    text: `Found ${fieldsCount} fields in the schema for "${database}.${collection}"`,
-                    type: "text",
-                },
-                {
-                    text: JSON.stringify(schema),
-                    type: "text",
-                },
-            ],
-        };
-    }
-}

package/src/tools/mongodb/metadata/collectionStorageSize.ts

@@ -1,68 +0,0 @@
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-
-export class CollectionStorageSizeTool extends MongoDBToolBase {
-    public name = "collection-storage-size";
-    protected description = "Gets the size of the collection";
-    protected argsShape = DbOperationArgs;
-
-    public operationType: OperationType = "metadata";
-
-    protected async execute({ database, collection }: ToolArgs<typeof DbOperationArgs>): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-        const [{ value }] = (await provider
-            .aggregate(database, collection, [
-                { $collStats: { storageStats: {} } },
-                { $group: { _id: null, value: { $sum: "$storageStats.size" } } },
-            ])
-            .toArray()) as [{ value: number }];
-
-        const { units, value: scaledValue } = CollectionStorageSizeTool.getStats(value);
-
-        return {
-            content: [
-                {
-                    text: `The size of "${database}.${collection}" is \`${scaledValue.toFixed(2)} ${units}\``,
-                    type: "text",
-                },
-            ],
-        };
-    }
-
-    protected handleError(
-        error: unknown,
-        args: ToolArgs<typeof this.argsShape>
-    ): Promise<CallToolResult> | CallToolResult {
-        if (error instanceof Error && "codeName" in error && error.codeName === "NamespaceNotFound") {
-            return {
-                content: [
-                    {
-                        text: `The size of "${args.database}.${args.collection}" cannot be determined because the collection does not exist.`,
-                        type: "text",
-                    },
-                ],
-            };
-        }
-
-        return super.handleError(error, args);
-    }
-
-    private static getStats(value: number): { value: number; units: string } {
-        const kb = 1024;
-        const mb = kb * 1024;
-        const gb = mb * 1024;
-
-        if (value > gb) {
-            return { value: value / gb, units: "GB" };
-        }
-
-        if (value > mb) {
-            return { value: value / mb, units: "MB" };
-        }
-        if (value > kb) {
-            return { value: value / kb, units: "KB" };
-        }
-        return { value, units: "bytes" };
-    }
-}

package/src/tools/mongodb/metadata/dbStats.ts

@@ -1,35 +0,0 @@
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-import { EJSON } from "bson";
-
-export class DbStatsTool extends MongoDBToolBase {
-    public name = "db-stats";
-    protected description = "Returns statistics that reflect the use state of a single database";
-    protected argsShape = {
-        database: DbOperationArgs.database,
-    };
-
-    public operationType: OperationType = "metadata";
-
-    protected async execute({ database }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-        const result = await provider.runCommandWithCheck(database, {
-            dbStats: 1,
-            scale: 1,
-        });
-
-        return {
-            content: [
-                {
-                    text: `Statistics for database ${database}`,
-                    type: "text",
-                },
-                {
-                    text: EJSON.stringify(result),
-                    type: "text",
-                },
-            ],
-        };
-    }
-}

package/src/tools/mongodb/metadata/explain.ts

@@ -1,103 +0,0 @@
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-import { z } from "zod";
-import { ExplainVerbosity, Document } from "mongodb";
-import { AggregateArgs } from "../read/aggregate.js";
-import { FindArgs } from "../read/find.js";
-import { CountArgs } from "../read/count.js";
-
-export class ExplainTool extends MongoDBToolBase {
-    public name = "explain";
-    protected description =
-        "Returns statistics describing the execution of the winning plan chosen by the query optimizer for the evaluated method";
-
-    protected argsShape = {
-        ...DbOperationArgs,
-        method: z
-            .array(
-                z.discriminatedUnion("name", [
-                    z.object({
-                        name: z.literal("aggregate"),
-                        arguments: z.object(AggregateArgs),
-                    }),
-                    z.object({
-                        name: z.literal("find"),
-                        arguments: z.object(FindArgs),
-                    }),
-                    z.object({
-                        name: z.literal("count"),
-                        arguments: z.object(CountArgs),
-                    }),
-                ])
-            )
-            .describe("The method and its arguments to run"),
-    };
-
-    public operationType: OperationType = "metadata";
-
-    static readonly defaultVerbosity = ExplainVerbosity.queryPlanner;
-
-    protected async execute({
-        database,
-        collection,
-        method: methods,
-    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-        const method = methods[0];
-
-        if (!method) {
-            throw new Error("No method provided. Expected one of the following: `aggregate`, `find`, or `count`");
-        }
-
-        let result: Document;
-        switch (method.name) {
-            case "aggregate": {
-                const { pipeline } = method.arguments;
-                result = await provider
-                    .aggregate(
-                        database,
-                        collection,
-                        pipeline,
-                        {},
-                        {
-                            writeConcern: undefined,
-                        }
-                    )
-                    .explain(ExplainTool.defaultVerbosity);
-                break;
-            }
-            case "find": {
-                const { filter, ...rest } = method.arguments;
-                result = await provider
-                    .find(database, collection, filter as Document, { ...rest })
-                    .explain(ExplainTool.defaultVerbosity);
-                break;
-            }
-            case "count": {
-                const { query } = method.arguments;
-                result = await provider.runCommandWithCheck(database, {
-                    explain: {
-                        count: collection,
-                        query,
-                    },
-                    verbosity: ExplainTool.defaultVerbosity,
-                });
-                break;
-            }
-        }
-
-        return {
-            content: [
-                {
-                    text: `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.`,
-                    type: "text",
-                },
-                {
-                    text: JSON.stringify(result),
-                    type: "text",
-                },
-            ],
-        };
-    }
-}

package/src/tools/mongodb/metadata/listCollections.ts

@@ -1,38 +0,0 @@
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-
-export class ListCollectionsTool extends MongoDBToolBase {
-    public name = "list-collections";
-    protected description = "List all collections for a given database";
-    protected argsShape = {
-        database: DbOperationArgs.database,
-    };
-
-    public operationType: OperationType = "metadata";
-
-    protected async execute({ database }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-        const collections = await provider.listCollections(database);
-
-        if (collections.length === 0) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `No collections found for database "${database}". To create a collection, use the "create-collection" tool.`,
-                    },
-                ],
-            };
-        }
-
-        return {
-            content: collections.map((collection) => {
-                return {
-                    text: `Name: "${collection.name}"`,
-                    type: "text",
-                };
-            }),
-        };
-    }
-}

package/src/tools/mongodb/metadata/listDatabases.ts

@@ -1,25 +0,0 @@
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { MongoDBToolBase } from "../mongodbTool.js";
-import * as bson from "bson";
-import { OperationType } from "../../tool.js";
-
-export class ListDatabasesTool extends MongoDBToolBase {
-    public name = "list-databases";
-    protected description = "List all databases for a MongoDB connection";
-    protected argsShape = {};
-    public operationType: OperationType = "metadata";
-
-    protected async execute(): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-        const dbs = (await provider.listDatabases("")).databases as { name: string; sizeOnDisk: bson.Long }[];
-
-        return {
-            content: dbs.map((db) => {
-                return {
-                    text: `Name: ${db.name}, Size: ${db.sizeOnDisk.toString()} bytes`,
-                    type: "text",
-                };
-            }),
-        };
-    }
-}

package/src/tools/mongodb/metadata/logs.ts

@@ -1,55 +0,0 @@
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { MongoDBToolBase } from "../mongodbTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-import { z } from "zod";
-
-export class LogsTool extends MongoDBToolBase {
-    public name = "mongodb-logs";
-    protected description = "Returns the most recent logged mongod events";
-    protected argsShape = {
-        type: z
-            .enum(["global", "startupWarnings"])
-            .optional()
-            .default("global")
-            .describe(
-                "The type of logs to return. Global returns all recent log entries, while startupWarnings returns only warnings and errors from when the process started."
-            ),
-        limit: z
-            .number()
-            .int()
-            .max(1024)
-            .min(1)
-            .optional()
-            .default(50)
-            .describe("The maximum number of log entries to return."),
-    };
-
-    public operationType: OperationType = "metadata";
-
-    protected async execute({ type, limit }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-
-        const result = await provider.runCommandWithCheck("admin", {
-            getLog: type,
-        });
-
-        const logs = (result.log as string[]).slice(0, limit);
-
-        return {
-            content: [
-                {
-                    text: `Found: ${result.totalLinesWritten} messages`,
-                    type: "text",
-                },
-
-                ...logs.map(
-                    (log) =>
-                        ({
-                            text: log,
-                            type: "text",
-                        }) as const
-                ),
-            ],
-        };
-    }
-}

package/src/tools/mongodb/mongodbTool.ts

@@ -1,136 +0,0 @@
-import { z } from "zod";
-import { ToolArgs, ToolBase, ToolCategory, TelemetryToolMetadata } from "../tool.js";
-import { NodeDriverServiceProvider } from "@mongosh/service-provider-node-driver";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { ErrorCodes, MongoDBError } from "../../common/errors.js";
-import logger, { LogId } from "../../common/logger.js";
-import { Server } from "../../server.js";
-
-export const DbOperationArgs = {
-    database: z.string().describe("Database name"),
-    collection: z.string().describe("Collection name"),
-};
-
-export abstract class MongoDBToolBase extends ToolBase {
-    private server?: Server;
-    public category: ToolCategory = "mongodb";
-
-    protected async ensureConnected(): Promise<NodeDriverServiceProvider> {
-        if (!this.session.serviceProvider) {
-            if (this.session.connectedAtlasCluster) {
-                throw new MongoDBError(
-                    ErrorCodes.NotConnectedToMongoDB,
-                    `Attempting to connect to Atlas cluster "${this.session.connectedAtlasCluster.clusterName}", try again in a few seconds.`
-                );
-            }
-
-            if (this.config.connectionString) {
-                try {
-                    await this.connectToMongoDB(this.config.connectionString);
-                } catch (error) {
-                    logger.error(
-                        LogId.mongodbConnectFailure,
-                        "mongodbTool",
-                        `Failed to connect to MongoDB instance using the connection string from the config: ${error as string}`
-                    );
-                    throw new MongoDBError(ErrorCodes.MisconfiguredConnectionString, "Not connected to MongoDB.");
-                }
-            }
-        }
-
-        if (!this.session.serviceProvider) {
-            throw new MongoDBError(ErrorCodes.NotConnectedToMongoDB, "Not connected to MongoDB");
-        }
-
-        return this.session.serviceProvider;
-    }
-
-    public register(server: Server): boolean {
-        this.server = server;
-        return super.register(server);
-    }
-
-    protected handleError(
-        error: unknown,
-        args: ToolArgs<typeof this.argsShape>
-    ): Promise<CallToolResult> | CallToolResult {
-        if (error instanceof MongoDBError) {
-            const connectTools = this.server?.tools
-                .filter((t) => t.operationType === "connect")
-                .sort((a, b) => a.category.localeCompare(b.category)); // Sort Altas tools before MongoDB tools
-
-            // Find the first Atlas connect tool if available and suggest to the LLM to use it.
-            // Note: if we ever have multiple Atlas connect tools, we may want to refine this logic to select the most appropriate one.
-            const atlasConnectTool = connectTools?.find((t) => t.category === "atlas");
-            const llmConnectHint = atlasConnectTool
-                ? `Note to LLM: prefer using the "${atlasConnectTool.name}" tool to connect to an Atlas cluster over using a connection string. Make sure to ask the user to specify a cluster name they want to connect to or ask them if they want to use the "list-clusters" tool to list all their clusters. Do not invent cluster names or connection strings unless the user has explicitly specified them. If they've previously connected to MongoDB using MCP, you can ask them if they want to reconnect using the same cluster/connection.`
-                : "Note to LLM: do not invent connection strings and explicitly ask the user to provide one. If they have previously connected to MongoDB using MCP, you can ask them if they want to reconnect using the same connection string.";
-
-            const connectToolsNames = connectTools?.map((t) => `"${t.name}"`).join(", ");
-            switch (error.code) {
-                case ErrorCodes.NotConnectedToMongoDB:
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: "You need to connect to a MongoDB instance before you can access its data.",
-                            },
-                            {
-                                type: "text",
-                                text: connectToolsNames
-                                    ? `Please use one of the following tools: ${connectToolsNames} to connect to a MongoDB instance or update the MCP server configuration to include a connection string. ${llmConnectHint}`
-                                    : "There are no tools available to connect. Please update the configuration to include a connection string and restart the server.",
-                            },
-                        ],
-                        isError: true,
-                    };
-                case ErrorCodes.MisconfiguredConnectionString:
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: "The configured connection string is not valid. Please check the connection string and confirm it points to a valid MongoDB instance.",
-                            },
-                            {
-                                type: "text",
-                                text: connectTools
-                                    ? `Alternatively, you can use one of the following tools: ${connectToolsNames} to connect to a MongoDB instance. ${llmConnectHint}`
-                                    : "Please update the configuration to use a valid connection string and restart the server.",
-                            },
-                        ],
-                        isError: true,
-                    };
-                case ErrorCodes.ForbiddenCollscan:
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: error.message,
-                            },
-                        ],
-                        isError: true,
-                    };
-            }
-        }
-
-        return super.handleError(error, args);
-    }
-
-    protected connectToMongoDB(connectionString: string): Promise<void> {
-        return this.session.connectToMongoDB(connectionString, this.config.connectOptions);
-    }
-
-    protected resolveTelemetryMetadata(
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        args: ToolArgs<typeof this.argsShape>
-    ): TelemetryToolMetadata {
-        const metadata: TelemetryToolMetadata = {};
-
-        // Add projectId to the metadata if running a MongoDB operation to an Atlas cluster
-        if (this.session.connectedAtlasCluster?.projectId) {
-            metadata.projectId = this.session.connectedAtlasCluster.projectId;
-        }
-
-        return metadata;
-    }
-}