mongodb-mcp-server 0.0.4

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

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+import config from "../../../config.js";
+import { MongoError as DriverError } from "mongodb";
+
+export class ConnectTool extends MongoDBToolBase {
+    protected name = "connect";
+    protected description = "Connect to a MongoDB instance";
+    protected argsShape = {
+        options: z
+            .array(
+                z
+                    .union([
+                        z.object({
+                            connectionString: z
+                                .string()
+                                .describe("MongoDB connection string (in the mongodb:// or mongodb+srv:// format)"),
+                        }),
+                        z.object({
+                            clusterName: z.string().describe("MongoDB cluster name"),
+                        }),
+                    ])
+                    .optional()
+            )
+            .optional()
+            .describe(
+                "Options for connecting to MongoDB. If not provided, the connection string from the config://connection-string resource will be used. If the user hasn't specified Atlas cluster name or a connection string explicitly and the `config://connection-string` resource is present, always invoke this with no arguments."
+            ),
+    };
+
+    protected operationType: OperationType = "metadata";
+
+    protected async execute({ options: optionsArr }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const options = optionsArr?.[0];
+        let connectionString: string;
+        if (!options && !config.connectionString) {
+            return {
+                content: [
+                    { type: "text", text: "No connection details provided." },
+                    { type: "text", text: "Please provide either a connection string or a cluster name" },
+                ],
+            };
+        }
+
+        if (!options) {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            connectionString = config.connectionString!;
+        } else if ("connectionString" in options) {
+            connectionString = options.connectionString;
+        } else {
+            // TODO: https://github.com/mongodb-js/mongodb-mcp-server/issues/19
+            // We don't support connecting via cluster name since we'd need to obtain the user credentials
+            // and fill in the connection string.
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Connecting via cluster name not supported yet. Please provide a connection string.`,
+                    },
+                ],
+            };
+        }
+
+        try {
+            await this.connectToMongoDB(connectionString);
+            return {
+                content: [{ type: "text", text: `Successfully connected to ${connectionString}.` }],
+            };
+        } catch (error) {
+            // Sometimes the model will supply an incorrect connection string. If the user has configured
+            // a different one as environment variable or a cli argument, suggest using that one instead.
+            if (
+                config.connectionString &&
+                error instanceof DriverError &&
+                config.connectionString !== connectionString
+            ) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text:
+                                `Failed to connect to MongoDB at '${connectionString}' due to error: '${error.message}.` +
+                                `Your config lists a different connection string: '${config.connectionString}' - do you want to try connecting to it instead?`,
+                        },
+                    ],
+                };
+            }
+
+            throw error;
+        }
+    }
+}

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

@@ -0,0 +1,30 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+
+export class DbStatsTool extends MongoDBToolBase {
+    protected name = "db-stats";
+    protected description = "Returns statistics that reflect the use state of a single database";
+    protected argsShape = {
+        database: DbOperationArgs.database,
+    };
+
+    protected 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}: ${JSON.stringify(result)}`,
+                    type: "text",
+                },
+            ],
+        };
+    }
+}

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

@@ -0,0 +1,90 @@
+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 {
+    protected 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.union([
+                    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"),
+    };
+
+    protected 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");
+        }
+
+        let result: Document;
+        switch (method.name) {
+            case "aggregate": {
+                const { pipeline } = method.arguments;
+                result = await provider.aggregate(database, collection, pipeline).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;
+                // This helper doesn't have explain() command but does have the argument explain
+                result = (await provider.count(database, collection, query, {
+                    explain: ExplainTool.defaultVerbosity,
+                })) as unknown as Document;
+                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

@@ -0,0 +1,38 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+
+export class ListCollectionsTool extends MongoDBToolBase {
+    protected name = "list-collections";
+    protected description = "List all collections for a given database";
+    protected argsShape = {
+        database: DbOperationArgs.database,
+    };
+
+    protected 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

@@ -0,0 +1,26 @@
+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 {
+    protected name = "list-databases";
+    protected description = "List all databases for a MongoDB connection";
+    protected argsShape = {};
+
+    protected 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/mongodbTool.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { ToolBase, ToolCategory } from "../tool.js";
+import { Session } from "../../session.js";
+import { NodeDriverServiceProvider } from "@mongosh/service-provider-node-driver";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { ErrorCodes, MongoDBError } from "../../errors.js";
+import config from "../../config.js";
+
+export const DbOperationArgs = {
+    database: z.string().describe("Database name"),
+    collection: z.string().describe("Collection name"),
+};
+
+export abstract class MongoDBToolBase extends ToolBase {
+    constructor(session: Session) {
+        super(session);
+    }
+
+    protected category: ToolCategory = "mongodb";
+
+    protected async ensureConnected(): Promise<NodeDriverServiceProvider> {
+        if (!this.session.serviceProvider && config.connectionString) {
+            await this.connectToMongoDB(config.connectionString);
+        }
+
+        if (!this.session.serviceProvider) {
+            throw new MongoDBError(ErrorCodes.NotConnectedToMongoDB, "Not connected to MongoDB");
+        }
+
+        return this.session.serviceProvider;
+    }
+
+    protected handleError(error: unknown): Promise<CallToolResult> | CallToolResult {
+        if (error instanceof MongoDBError && error.code === ErrorCodes.NotConnectedToMongoDB) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "You need to connect to a MongoDB instance before you can access its data.",
+                    },
+                    {
+                        type: "text",
+                        text: "Please use the 'connect' tool to connect to a MongoDB instance.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+
+        return super.handleError(error);
+    }
+
+    protected async connectToMongoDB(connectionString: string): Promise<void> {
+        const provider = await NodeDriverServiceProvider.connect(connectionString, {
+            productDocsLink: "https://docs.mongodb.com/todo-mcp",
+            productName: "MongoDB MCP",
+            readConcern: {
+                level: config.connectOptions.readConcern,
+            },
+            readPreference: config.connectOptions.readPreference,
+            writeConcern: {
+                w: config.connectOptions.writeConcern,
+            },
+            timeoutMS: config.connectOptions.timeoutMS,
+        });
+
+        this.session.serviceProvider = provider;
+    }
+}

package/src/tools/mongodb/read/aggregate.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+
+export const AggregateArgs = {
+    pipeline: z.array(z.object({}).passthrough()).describe("An array of aggregation stages to execute"),
+    limit: z.number().optional().default(10).describe("The maximum number of documents to return"),
+};
+
+export class AggregateTool extends MongoDBToolBase {
+    protected name = "aggregate";
+    protected description = "Run an aggregation against a MongoDB collection";
+    protected argsShape = {
+        ...DbOperationArgs,
+        ...AggregateArgs,
+    };
+    protected operationType: OperationType = "read";
+
+    protected async execute({
+        database,
+        collection,
+        pipeline,
+    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const documents = await provider.aggregate(database, collection, pipeline).toArray();
+
+        const content: Array<{ text: string; type: "text" }> = [
+            {
+                text: `Found ${documents.length} documents in the collection \`${collection}\`:`,
+                type: "text",
+            },
+            ...documents.map((doc) => {
+                return {
+                    text: JSON.stringify(doc),
+                    type: "text",
+                } as { text: string; type: "text" };
+            }),
+        ];
+
+        return {
+            content,
+        };
+    }
+}

package/src/tools/mongodb/read/collectionIndexes.ts

@@ -0,0 +1,24 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+
+export class CollectionIndexesTool extends MongoDBToolBase {
+    protected name = "collection-indexes";
+    protected description = "Describe the indexes for a collection";
+    protected argsShape = DbOperationArgs;
+    protected operationType: OperationType = "read";
+
+    protected async execute({ database, collection }: ToolArgs<typeof DbOperationArgs>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const indexes = await provider.getIndexes(database, collection);
+
+        return {
+            content: indexes.map((indexDefinition) => {
+                return {
+                    text: `Field: ${indexDefinition.name}: ${JSON.stringify(indexDefinition.key)}`,
+                    type: "text",
+                };
+            }),
+        };
+    }
+}

package/src/tools/mongodb/read/count.ts

@@ -0,0 +1,39 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+import { z } from "zod";
+
+export const CountArgs = {
+    query: z
+        .object({})
+        .passthrough()
+        .optional()
+        .describe(
+            "The query filter to count documents. Matches the syntax of the filter argument of db.collection.count()"
+        ),
+};
+
+export class CountTool extends MongoDBToolBase {
+    protected name = "count";
+    protected description = "Gets the number of documents in a MongoDB collection";
+    protected argsShape = {
+        ...DbOperationArgs,
+        ...CountArgs,
+    };
+
+    protected operationType: OperationType = "read";
+
+    protected async execute({ database, collection, query }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const count = await provider.count(database, collection, query);
+
+        return {
+            content: [
+                {
+                    text: `Found ${count} documents in the collection "${collection}"`,
+                    type: "text",
+                },
+            ],
+        };
+    }
+}

package/src/tools/mongodb/read/find.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+import { SortDirection } from "mongodb";
+
+export const FindArgs = {
+    filter: z
+        .object({})
+        .passthrough()
+        .optional()
+        .describe("The query filter, matching the syntax of the query argument of db.collection.find()"),
+    projection: z
+        .object({})
+        .passthrough()
+        .optional()
+        .describe("The projection, matching the syntax of the projection argument of db.collection.find()"),
+    limit: z.number().optional().default(10).describe("The maximum number of documents to return"),
+    sort: z
+        .record(z.string(), z.custom<SortDirection>())
+        .optional()
+        .describe("A document, describing the sort order, matching the syntax of the sort argument of cursor.sort()"),
+};
+
+export class FindTool extends MongoDBToolBase {
+    protected name = "find";
+    protected description = "Run a find query against a MongoDB collection";
+    protected argsShape = {
+        ...DbOperationArgs,
+        ...FindArgs,
+    };
+    protected operationType: OperationType = "read";
+
+    protected async execute({
+        database,
+        collection,
+        filter,
+        projection,
+        limit,
+        sort,
+    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const documents = await provider.find(database, collection, filter, { projection, limit, sort }).toArray();
+
+        const content: Array<{ text: string; type: "text" }> = [
+            {
+                text: `Found ${documents.length} documents in the collection \`${collection}\`:`,
+                type: "text",
+            },
+            ...documents.map((doc) => {
+                return {
+                    text: JSON.stringify(doc),
+                    type: "text",
+                } as { text: string; type: "text" };
+            }),
+        ];
+
+        return {
+            content,
+        };
+    }
+}

package/src/tools/mongodb/tools.ts

@@ -0,0 +1,41 @@
+import { ConnectTool } from "./metadata/connect.js";
+import { ListCollectionsTool } from "./metadata/listCollections.js";
+import { CollectionIndexesTool } from "./read/collectionIndexes.js";
+import { ListDatabasesTool } from "./metadata/listDatabases.js";
+import { CreateIndexTool } from "./create/createIndex.js";
+import { CollectionSchemaTool } from "./metadata/collectionSchema.js";
+import { FindTool } from "./read/find.js";
+import { InsertManyTool } from "./create/insertMany.js";
+import { DeleteManyTool } from "./delete/deleteMany.js";
+import { CollectionStorageSizeTool } from "./metadata/collectionStorageSize.js";
+import { CountTool } from "./read/count.js";
+import { DbStatsTool } from "./metadata/dbStats.js";
+import { AggregateTool } from "./read/aggregate.js";
+import { UpdateManyTool } from "./update/updateMany.js";
+import { RenameCollectionTool } from "./update/renameCollection.js";
+import { DropDatabaseTool } from "./delete/dropDatabase.js";
+import { DropCollectionTool } from "./delete/dropCollection.js";
+import { ExplainTool } from "./metadata/explain.js";
+import { CreateCollectionTool } from "./create/createCollection.js";
+
+export const MongoDbTools = [
+    ConnectTool,
+    ListCollectionsTool,
+    ListDatabasesTool,
+    CollectionIndexesTool,
+    CreateIndexTool,
+    CollectionSchemaTool,
+    FindTool,
+    InsertManyTool,
+    DeleteManyTool,
+    CollectionStorageSizeTool,
+    CountTool,
+    DbStatsTool,
+    AggregateTool,
+    UpdateManyTool,
+    RenameCollectionTool,
+    DropDatabaseTool,
+    DropCollectionTool,
+    ExplainTool,
+    CreateCollectionTool,
+];

package/src/tools/mongodb/update/renameCollection.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+
+export class RenameCollectionTool extends MongoDBToolBase {
+    protected name = "rename-collection";
+    protected description = "Renames a collection in a MongoDB database";
+    protected argsShape = {
+        collection: z.string().describe("Collection name"),
+        database: z.string().describe("Database name"),
+        newName: z.string().describe("The new name for the collection"),
+        dropTarget: z.boolean().optional().default(false).describe("If true, drops the target collection if it exists"),
+    };
+    protected operationType: OperationType = "update";
+
+    protected async execute({
+        database,
+        collection,
+        newName,
+        dropTarget,
+    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const result = await provider.renameCollection(database, collection, newName, {
+            dropTarget,
+        });
+
+        return {
+            content: [
+                {
+                    text: `Collection \`${collection}\` renamed to \`${result.collectionName}\` in database \`${database}\`.`,
+                    type: "text",
+                },
+            ],
+        };
+    }
+}

package/src/tools/mongodb/update/updateMany.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { MongoDBToolBase } from "../mongodbTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+
+export class UpdateManyTool extends MongoDBToolBase {
+    protected name = "update-many";
+    protected description = "Updates all documents that match the specified filter for a collection";
+    protected argsShape = {
+        collection: z.string().describe("Collection name"),
+        database: z.string().describe("Database name"),
+        filter: z
+            .object({})
+            .passthrough()
+            .optional()
+            .describe(
+                "The selection criteria for the update, matching the syntax of the filter argument of db.collection.updateOne()"
+            ),
+        update: z
+            .object({})
+            .passthrough()
+            .optional()
+            .describe("An update document describing the modifications to apply using update operator expressions"),
+        upsert: z
+            .boolean()
+            .optional()
+            .describe("Controls whether to insert a new document if no documents match the filter"),
+    };
+    protected operationType: OperationType = "update";
+
+    protected async execute({
+        database,
+        collection,
+        filter,
+        update,
+        upsert,
+    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const provider = await this.ensureConnected();
+        const result = await provider.updateMany(database, collection, filter, update, {
+            upsert,
+        });
+
+        let message = "";
+        if (result.matchedCount === 0) {
+            message = `No documents matched the filter.`;
+        } else {
+            message = `Matched ${result.matchedCount} document(s).`;
+            if (result.modifiedCount > 0) {
+                message += ` Modified ${result.modifiedCount} document(s).`;
+            }
+            if (result.upsertedCount > 0) {
+                message += ` Upserted ${result.upsertedCount} document(s) (with id: ${result.upsertedId?.toString()}).`;
+            }
+        }
+
+        return {
+            content: [
+                {
+                    text: message,
+                    type: "text",
+                },
+            ],
+        };
+    }
+}