mongodb-mcp-server 0.0.4 → 0.0.6

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

@@ -1,7 +1,7 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
 import { ToolArgs, OperationType } from "../../tool.js";
-import { parseSchema, SchemaField } from "mongodb-schema";
+import { getSimplifiedSchema } from "mongodb-schema";
 
 export class CollectionSchemaTool extends MongoDBToolBase {
     protected name = "collection-schema";
@@ -13,29 +13,31 @@ export class CollectionSchemaTool extends MongoDBToolBase {
     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 parseSchema(documents);
+        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 ${schema.fields.length} fields in the schema for \`${database}.${collection}\``,
+                    text: `Found ${fieldsCount} fields in the schema for "${database}.${collection}"`,
                     type: "text",
                 },
                 {
-                    text: this.formatFieldOutput(schema.fields),
+                    text: JSON.stringify(schema),
                     type: "text",
                 },
             ],
         };
     }
-
-    private formatFieldOutput(fields: SchemaField[]): string {
-        let result = "| Field | Type | Confidence |\n";
-        result += "|-------|------|-------------|\n";
-        for (const field of fields) {
-            const fieldType = Array.isArray(field.type) ? field.type.join(", ") : field.type;
-            result += `| ${field.name} | \`${fieldType}\` | ${(field.probability * 100).toFixed(0)}% |\n`;
-        }
-        return result;
-    }
 }

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

@@ -4,7 +4,7 @@ import { ToolArgs, OperationType } from "../../tool.js";
 
 export class CollectionStorageSizeTool extends MongoDBToolBase {
     protected name = "collection-storage-size";
-    protected description = "Gets the size of the collection in MB";
+    protected description = "Gets the size of the collection";
     protected argsShape = DbOperationArgs;
 
     protected operationType: OperationType = "metadata";
@@ -14,17 +14,55 @@ export class CollectionStorageSizeTool extends MongoDBToolBase {
         const [{ value }] = (await provider
             .aggregate(database, collection, [
                 { $collStats: { storageStats: {} } },
-                { $group: { _id: null, value: { $sum: "$storageStats.storageSize" } } },
+                { $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 \`${(value / 1024 / 1024).toFixed(2)} MB\``,
+                    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/connect.ts

@@ -2,93 +2,95 @@ 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";
+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 = "connect";
-    protected description = "Connect to a MongoDB instance";
+    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 = {
-        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."
-            ),
+        connectionString: z.string().optional(),
     };
 
     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" },
-                ],
-            };
-        }
+    constructor(session: Session, config: UserConfig, telemetry: Telemetry) {
+        super(session, config, telemetry);
+        session.on("close", () => {
+            this.updateMetadata();
+        });
+    }
 
-        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.`,
-                    },
-                ],
-            };
+    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;
         }
 
-        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?`,
-                        },
-                    ],
-                };
-            }
+        await this.connectToMongoDB(connectionString);
+        this.updateMetadata();
+        return {
+            content: [{ type: "text", text: "Successfully connected to MongoDB." }],
+        };
+    }
+
+    public register(server: McpServer): void {
+        super.register(server);
 
-            throw error;
+        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,6 +1,7 @@
 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";
@@ -21,7 +22,11 @@ export class DbStatsTool extends MongoDBToolBase {
         return {
             content: [
                 {
-                    text: `Statistics for database ${database}: ${JSON.stringify(result)}`,
+                    text: `Statistics for database ${database}`,
+                    type: "text",
+                },
+                {
+                    text: EJSON.stringify(result),
                     type: "text",
                 },
             ],

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

@@ -47,14 +47,24 @@ export class ExplainTool extends MongoDBToolBase {
         const method = methods[0];
 
         if (!method) {
-            throw new Error("No method provided");
+            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).explain(ExplainTool.defaultVerbosity);
+                result = await provider
+                    .aggregate(
+                        database,
+                        collection,
+                        pipeline,
+                        {},
+                        {
+                            writeConcern: undefined,
+                        }
+                    )
+                    .explain(ExplainTool.defaultVerbosity);
                 break;
             }
             case "find": {
@@ -66,10 +76,13 @@ export class ExplainTool extends MongoDBToolBase {
             }
             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;
+                result = await provider.mongoClient.db(database).command({
+                    explain: {
+                        count: collection,
+                        query,
+                    },
+                    verbosity: ExplainTool.defaultVerbosity,
+                });
                 break;
             }
         }
@@ -77,7 +90,7 @@ export class ExplainTool extends MongoDBToolBase {
         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.`,
+                    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",
                 },
                 {

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

@@ -0,0 +1,55 @@
+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,10 +1,9 @@
 import { z } from "zod";
-import { ToolBase, ToolCategory } from "../tool.js";
-import { Session } from "../../session.js";
+import { ToolArgs, ToolBase, ToolCategory } 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 config from "../../config.js";
+import logger, { LogId } from "../../logger.js";
 
 export const DbOperationArgs = {
     database: z.string().describe("Database name"),
@@ -12,15 +11,20 @@ export const DbOperationArgs = {
 };
 
 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 && 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) {
@@ -30,40 +34,43 @@ export abstract class MongoDBToolBase extends ToolBase {
         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,
-            };
+    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,
+                    };
+            }
         }
 
-        return super.handleError(error);
+        return super.handleError(error, args);
     }
 
-    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;
+    protected connectToMongoDB(connectionString: string): Promise<void> {
+        return this.session.connectToMongoDB(connectionString, this.config.connectOptions);
     }
 }

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

@@ -2,10 +2,10 @@ 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";
 
 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"),
+    pipeline: z.array(z.record(z.string(), z.unknown())).describe("An array of aggregation stages to execute"),
 };
 
 export class AggregateTool extends MongoDBToolBase {
@@ -27,12 +27,12 @@ export class AggregateTool extends MongoDBToolBase {
 
         const content: Array<{ text: string; type: "text" }> = [
             {
-                text: `Found ${documents.length} documents in the collection \`${collection}\`:`,
+                text: `Found ${documents.length} documents in the collection "${collection}":`,
                 type: "text",
             },
             ...documents.map((doc) => {
                 return {
-                    text: JSON.stringify(doc),
+                    text: EJSON.stringify(doc),
                     type: "text",
                 } as { text: string; type: "text" };
             }),

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

@@ -13,12 +13,36 @@ export class CollectionIndexesTool extends MongoDBToolBase {
         const indexes = await provider.getIndexes(database, collection);
 
         return {
-            content: indexes.map((indexDefinition) => {
-                return {
-                    text: `Field: ${indexDefinition.name}: ${JSON.stringify(indexDefinition.key)}`,
+            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

@@ -5,8 +5,7 @@ import { z } from "zod";
 
 export const CountArgs = {
     query: z
-        .object({})
-        .passthrough()
+        .record(z.string(), z.unknown())
         .optional()
         .describe(
             "The query filter to count documents. Matches the syntax of the filter argument of db.collection.count()"

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

@@ -3,16 +3,15 @@ import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
 import { ToolArgs, OperationType } from "../../tool.js";
 import { SortDirection } from "mongodb";
+import { EJSON } from "bson";
 
 export const FindArgs = {
     filter: z
-        .object({})
-        .passthrough()
+        .record(z.string(), z.unknown())
         .optional()
         .describe("The query filter, matching the syntax of the query argument of db.collection.find()"),
     projection: z
-        .object({})
-        .passthrough()
+        .record(z.string(), z.unknown())
         .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"),
@@ -44,12 +43,12 @@ export class FindTool extends MongoDBToolBase {
 
         const content: Array<{ text: string; type: "text" }> = [
             {
-                text: `Found ${documents.length} documents in the collection \`${collection}\`:`,
+                text: `Found ${documents.length} documents in the collection "${collection}":`,
                 type: "text",
             },
             ...documents.map((doc) => {
                 return {
-                    text: JSON.stringify(doc),
+                    text: EJSON.stringify(doc),
                     type: "text",
                 } as { text: string; type: "text" };
             }),