mongodb-mcp-server 0.1.3 → 0.3.0

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

@@ -1,96 +0,0 @@
-import { z } from "zod";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { MongoDBToolBase } from "../mongodbTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import assert from "assert";
-import { UserConfig } from "../../../config.js";
-import { Telemetry } from "../../../telemetry/telemetry.js";
-import { Session } from "../../../session.js";
-
-const disconnectedSchema = z
-    .object({
-        connectionString: z.string().describe("MongoDB connection string (in the mongodb:// or mongodb+srv:// format)"),
-    })
-    .describe("Options for connecting to MongoDB.");
-
-const connectedSchema = z
-    .object({
-        connectionString: z
-            .string()
-            .optional()
-            .describe("MongoDB connection string to switch to (in the mongodb:// or mongodb+srv:// format)"),
-    })
-    .describe(
-        "Options for switching the current MongoDB connection. If a connection string is not provided, the connection string from the config will be used."
-    );
-
-const connectedName = "switch-connection" as const;
-const disconnectedName = "connect" as const;
-
-const connectedDescription =
-    "Switch to a different MongoDB connection. If the user has configured a connection string or has previously called the connect tool, a connection is already established and there's no need to call this tool unless the user has explicitly requested to switch to a new instance.";
-const disconnectedDescription = "Connect to a MongoDB instance";
-
-export class ConnectTool extends MongoDBToolBase {
-    protected name: typeof connectedName | typeof disconnectedName = disconnectedName;
-    protected description: typeof connectedDescription | typeof disconnectedDescription = disconnectedDescription;
-
-    // Here the default is empty just to trigger registration, but we're going to override it with the correct
-    // schema in the register method.
-    protected argsShape = {
-        connectionString: z.string().optional(),
-    };
-
-    protected operationType: OperationType = "metadata";
-
-    constructor(session: Session, config: UserConfig, telemetry: Telemetry) {
-        super(session, config, telemetry);
-        session.on("close", () => {
-            this.updateMetadata();
-        });
-    }
-
-    protected async execute({ connectionString }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        switch (this.name) {
-            case disconnectedName:
-                assert(connectionString, "Connection string is required");
-                break;
-            case connectedName:
-                connectionString ??= this.config.connectionString;
-                assert(
-                    connectionString,
-                    "Cannot switch to a new connection because no connection string was provided and no default connection string is configured."
-                );
-                break;
-        }
-
-        await this.connectToMongoDB(connectionString);
-        this.updateMetadata();
-        return {
-            content: [{ type: "text", text: "Successfully connected to MongoDB." }],
-        };
-    }
-
-    public register(server: McpServer): void {
-        super.register(server);
-
-        this.updateMetadata();
-    }
-
-    private updateMetadata(): void {
-        if (this.config.connectionString || this.session.serviceProvider) {
-            this.update?.({
-                name: connectedName,
-                description: connectedDescription,
-                inputSchema: connectedSchema,
-            });
-        } else {
-            this.update?.({
-                name: disconnectedName,
-                description: disconnectedDescription,
-                inputSchema: disconnectedSchema,
-            });
-        }
-    }
-}

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 {
-    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}`,
-                    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 {
-    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. 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 {
-    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

@@ -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 {
-    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/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 {
-    protected 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."),
-    };
-
-    protected 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,100 +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 "../../errors.js";
-import logger, { LogId } from "../../logger.js";
-
-export const DbOperationArgs = {
-    database: z.string().describe("Database name"),
-    collection: z.string().describe("Collection name"),
-};
-
-export abstract class MongoDBToolBase extends ToolBase {
-    protected category: ToolCategory = "mongodb";
-
-    protected async ensureConnected(): Promise<NodeDriverServiceProvider> {
-        if (!this.session.serviceProvider && 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;
-    }
-
-    protected handleError(
-        error: unknown,
-        args: ToolArgs<typeof this.argsShape>
-    ): Promise<CallToolResult> | CallToolResult {
-        if (error instanceof MongoDBError) {
-            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: "Please use the 'connect' or 'switch-connection' tool to connect to a MongoDB instance.",
-                            },
-                        ],
-                        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. Alternatively, use the 'switch-connection' tool to connect to a different instance.",
-                            },
-                        ],
-                        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;
-    }
-}

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

@@ -1,56 +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 { EJSON } from "bson";
-import { checkIndexUsage } from "../../../helpers/indexCheck.js";
-
-export const AggregateArgs = {
-    pipeline: z.array(z.record(z.string(), z.unknown())).describe("An array of aggregation stages to execute"),
-};
-
-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();
-
-        // Check if aggregate operation uses an index if enabled
-        if (this.config.indexCheck) {
-            await checkIndexUsage(provider, database, collection, "aggregate", async () => {
-                return provider
-                    .aggregate(database, collection, pipeline, {}, { writeConcern: undefined })
-                    .explain("queryPlanner");
-            });
-        }
-
-        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: EJSON.stringify(doc),
-                    type: "text",
-                } as { text: string; type: "text" };
-            }),
-        ];
-
-        return {
-            content,
-        };
-    }
-}

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

@@ -1,48 +0,0 @@
-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: [
-                {
-                    text: `Found ${indexes.length} indexes in the collection "${collection}":`,
-                    type: "text",
-                },
-                ...(indexes.map((indexDefinition) => {
-                    return {
-                        text: `Name "${indexDefinition.name}", definition: ${JSON.stringify(indexDefinition.key)}`,
-                        type: "text",
-                    };
-                }) as { text: string; 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 indexes for "${args.database}.${args.collection}" cannot be determined because the collection does not exist.`,
-                        type: "text",
-                    },
-                ],
-            };
-        }
-
-        return super.handleError(error, args);
-    }
-}

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

@@ -1,54 +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 { checkIndexUsage } from "../../../helpers/indexCheck.js";
-
-export const CountArgs = {
-    query: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe(
-            "A filter/query parameter. Allows users to filter the documents to count. Matches the syntax of the filter argument of db.collection.count()."
-        ),
-};
-
-export class CountTool extends MongoDBToolBase {
-    protected name = "count";
-    protected description =
-        "Gets the number of documents in a MongoDB collection using db.collection.count() and query as an optional filter parameter";
-    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();
-
-        // Check if count operation uses an index if enabled
-        if (this.config.indexCheck) {
-            await checkIndexUsage(provider, database, collection, "count", async () => {
-                return provider.runCommandWithCheck(database, {
-                    explain: {
-                        count: collection,
-                        query,
-                    },
-                    verbosity: "queryPlanner",
-                });
-            });
-        }
-
-        const count = await provider.count(database, collection, query);
-
-        return {
-            content: [
-                {
-                    text: `Found ${count} documents in the collection "${collection}"`,
-                    type: "text",
-                },
-            ],
-        };
-    }
-}