mongodb-mcp-server 0.2.0 → 0.3.0

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.object({}).passthrough()).describe("An array of aggregation stages to execute"),
-};
-
-export class AggregateTool extends MongoDBToolBase {
-    public name = "aggregate";
-    protected description = "Run an aggregation against a MongoDB collection";
-    protected argsShape = {
-        ...DbOperationArgs,
-        ...AggregateArgs,
-    };
-    public 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 {
-    public name = "collection-indexes";
-    protected description = "Describe the indexes for a collection";
-    protected argsShape = DbOperationArgs;
-    public 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,55 +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
-        .object({})
-        .passthrough()
-        .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 {
-    public 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,
-    };
-
-    public 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",
-                },
-            ],
-        };
-    }
-}

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

@@ -1,75 +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 { SortDirection } from "mongodb";
-import { EJSON } from "bson";
-import { checkIndexUsage } from "../../../helpers/indexCheck.js";
-
-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
-        .object({})
-        .catchall(z.custom<SortDirection>())
-        .optional()
-        .describe(
-            "A document, describing the sort order, matching the syntax of the sort argument of cursor.sort(). The keys of the object are the fields to sort on, while the values are the sort directions (1 for ascending, -1 for descending)."
-        ),
-};
-
-export class FindTool extends MongoDBToolBase {
-    public name = "find";
-    protected description = "Run a find query against a MongoDB collection";
-    protected argsShape = {
-        ...DbOperationArgs,
-        ...FindArgs,
-    };
-    public operationType: OperationType = "read";
-
-    protected async execute({
-        database,
-        collection,
-        filter,
-        projection,
-        limit,
-        sort,
-    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-
-        // Check if find operation uses an index if enabled
-        if (this.config.indexCheck) {
-            await checkIndexUsage(provider, database, collection, "find", async () => {
-                return provider.find(database, collection, filter, { projection, limit, sort }).explain("queryPlanner");
-            });
-        }
-
-        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: EJSON.stringify(doc),
-                    type: "text",
-                } as { text: string; type: "text" };
-            }),
-        ];
-
-        return {
-            content,
-        };
-    }
-}

package/src/tools/mongodb/tools.ts

@@ -1,43 +0,0 @@
-import { ConnectTool } from "./connect/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";
-import { LogsTool } from "./metadata/logs.js";
-
-export const MongoDbTools = [
-    ConnectTool,
-    ListCollectionsTool,
-    ListDatabasesTool,
-    CollectionIndexesTool,
-    CreateIndexTool,
-    CollectionSchemaTool,
-    FindTool,
-    InsertManyTool,
-    DeleteManyTool,
-    CollectionStorageSizeTool,
-    CountTool,
-    DbStatsTool,
-    AggregateTool,
-    UpdateManyTool,
-    RenameCollectionTool,
-    DropDatabaseTool,
-    DropCollectionTool,
-    ExplainTool,
-    CreateCollectionTool,
-    LogsTool,
-];

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

@@ -1,66 +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 RenameCollectionTool extends MongoDBToolBase {
-    public name = "rename-collection";
-    protected description = "Renames a collection in a MongoDB database";
-    protected argsShape = {
-        ...DbOperationArgs,
-        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"),
-    };
-    public 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",
-                },
-            ],
-        };
-    }
-
-    protected handleError(
-        error: unknown,
-        args: ToolArgs<typeof this.argsShape>
-    ): Promise<CallToolResult> | CallToolResult {
-        if (error instanceof Error && "codeName" in error) {
-            switch (error.codeName) {
-                case "NamespaceNotFound":
-                    return {
-                        content: [
-                            {
-                                text: `Cannot rename "${args.database}.${args.collection}" because it doesn't exist.`,
-                                type: "text",
-                            },
-                        ],
-                    };
-                case "NamespaceExists":
-                    return {
-                        content: [
-                            {
-                                text: `Cannot rename "${args.database}.${args.collection}" to "${args.newName}" because the target collection already exists. If you want to overwrite it, set the "dropTarget" argument to true.`,
-                                type: "text",
-                            },
-                        ],
-                    };
-            }
-        }
-
-        return super.handleError(error, args);
-    }
-}

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

@@ -1,85 +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 UpdateManyTool extends MongoDBToolBase {
-    public name = "update-many";
-    protected description = "Updates all documents that match the specified filter for a collection";
-    protected argsShape = {
-        ...DbOperationArgs,
-        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()
-            .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"),
-    };
-    public operationType: OperationType = "update";
-
-    protected async execute({
-        database,
-        collection,
-        filter,
-        update,
-        upsert,
-    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        const provider = await this.ensureConnected();
-
-        // Check if update operation uses an index if enabled
-        if (this.config.indexCheck) {
-            await checkIndexUsage(provider, database, collection, "updateMany", async () => {
-                return provider.runCommandWithCheck(database, {
-                    explain: {
-                        update: collection,
-                        updates: [
-                            {
-                                q: filter || {},
-                                u: update,
-                                upsert: upsert || false,
-                                multi: true,
-                            },
-                        ],
-                    },
-                    verbosity: "queryPlanner",
-                });
-            });
-        }
-
-        const result = await provider.updateMany(database, collection, filter, update, {
-            upsert,
-        });
-
-        let message = "";
-        if (result.matchedCount === 0 && result.modifiedCount === 0 && result.upsertedCount === 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 with id: ${result.upsertedId?.toString()}.`;
-            }
-        }
-
-        return {
-            content: [
-                {
-                    text: message,
-                    type: "text",
-                },
-            ],
-        };
-    }
-}

package/src/tools/tool.ts

@@ -1,219 +0,0 @@
-import { z, type ZodRawShape, type ZodNever, AnyZodObject } from "zod";
-import type { RegisteredTool, ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
-import { Session } from "../common/session.js";
-import logger, { LogId } from "../common/logger.js";
-import { Telemetry } from "../telemetry/telemetry.js";
-import { type ToolEvent } from "../telemetry/types.js";
-import { UserConfig } from "../common/config.js";
-import { Server } from "../server.js";
-
-export type ToolArgs<Args extends ZodRawShape> = z.objectOutputType<Args, ZodNever>;
-
-export type OperationType = "metadata" | "read" | "create" | "delete" | "update" | "connect";
-export type ToolCategory = "mongodb" | "atlas";
-export type TelemetryToolMetadata = {
-    projectId?: string;
-    orgId?: string;
-};
-
-export abstract class ToolBase {
-    public abstract name: string;
-
-    public abstract category: ToolCategory;
-
-    public abstract operationType: OperationType;
-
-    protected abstract description: string;
-
-    protected abstract argsShape: ZodRawShape;
-
-    protected get annotations(): ToolAnnotations {
-        const annotations: ToolAnnotations = {
-            title: this.name,
-            description: this.description,
-        };
-
-        switch (this.operationType) {
-            case "read":
-            case "metadata":
-            case "connect":
-                annotations.readOnlyHint = true;
-                annotations.destructiveHint = false;
-                break;
-            case "delete":
-                annotations.readOnlyHint = false;
-                annotations.destructiveHint = true;
-                break;
-            case "create":
-            case "update":
-                annotations.destructiveHint = false;
-                annotations.readOnlyHint = false;
-                break;
-            default:
-                break;
-        }
-
-        return annotations;
-    }
-
-    protected abstract execute(...args: Parameters<ToolCallback<typeof this.argsShape>>): Promise<CallToolResult>;
-
-    constructor(
-        protected readonly session: Session,
-        protected readonly config: UserConfig,
-        protected readonly telemetry: Telemetry
-    ) {}
-
-    public register(server: Server): boolean {
-        if (!this.verifyAllowed()) {
-            return false;
-        }
-
-        const callback: ToolCallback<typeof this.argsShape> = async (...args) => {
-            const startTime = Date.now();
-            try {
-                logger.debug(LogId.toolExecute, "tool", `Executing tool ${this.name}`);
-
-                const result = await this.execute(...args);
-                await this.emitToolEvent(startTime, result, ...args).catch(() => {});
-                return result;
-            } catch (error: unknown) {
-                logger.error(LogId.toolExecuteFailure, "tool", `Error executing ${this.name}: ${error as string}`);
-                const toolResult = await this.handleError(error, args[0] as ToolArgs<typeof this.argsShape>);
-                await this.emitToolEvent(startTime, toolResult, ...args).catch(() => {});
-                return toolResult;
-            }
-        };
-
-        server.mcpServer.tool(this.name, this.description, this.argsShape, this.annotations, callback);
-
-        // This is very similar to RegisteredTool.update, but without the bugs around the name.
-        // In the upstream update method, the name is captured in the closure and not updated when
-        // the tool name changes. This means that you only get one name update before things end up
-        // in a broken state.
-        // See https://github.com/modelcontextprotocol/typescript-sdk/issues/414 for more details.
-        this.update = (updates: { name?: string; description?: string; inputSchema?: AnyZodObject }) => {
-            const tools = server.mcpServer["_registeredTools"] as { [toolName: string]: RegisteredTool };
-            const existingTool = tools[this.name];
-
-            if (!existingTool) {
-                logger.warning(LogId.toolUpdateFailure, "tool", `Tool ${this.name} not found in update`);
-                return;
-            }
-
-            existingTool.annotations = this.annotations;
-
-            if (updates.name && updates.name !== this.name) {
-                existingTool.annotations.title = updates.name;
-                delete tools[this.name];
-                this.name = updates.name;
-                tools[this.name] = existingTool;
-            }
-
-            if (updates.description) {
-                existingTool.annotations.description = updates.description;
-                existingTool.description = updates.description;
-                this.description = updates.description;
-            }
-
-            if (updates.inputSchema) {
-                existingTool.inputSchema = updates.inputSchema;
-            }
-
-            server.mcpServer.sendToolListChanged();
-        };
-
-        return true;
-    }
-
-    protected update?: (updates: { name?: string; description?: string; inputSchema?: AnyZodObject }) => void;
-
-    // Checks if a tool is allowed to run based on the config
-    protected verifyAllowed(): boolean {
-        let errorClarification: string | undefined;
-
-        // Check read-only mode first
-        if (this.config.readOnly && !["read", "metadata"].includes(this.operationType)) {
-            errorClarification = `read-only mode is enabled, its operation type, \`${this.operationType}\`,`;
-        } else if (this.config.disabledTools.includes(this.category)) {
-            errorClarification = `its category, \`${this.category}\`,`;
-        } else if (this.config.disabledTools.includes(this.operationType)) {
-            errorClarification = `its operation type, \`${this.operationType}\`,`;
-        } else if (this.config.disabledTools.includes(this.name)) {
-            errorClarification = `it`;
-        }
-
-        if (errorClarification) {
-            logger.debug(
-                LogId.toolDisabled,
-                "tool",
-                `Prevented registration of ${this.name} because ${errorClarification} is disabled in the config`
-            );
-
-            return false;
-        }
-
-        return true;
-    }
-
-    // This method is intended to be overridden by subclasses to handle errors
-    protected handleError(
-        error: unknown,
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        args: ToolArgs<typeof this.argsShape>
-    ): Promise<CallToolResult> | CallToolResult {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Error running ${this.name}: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-
-    protected abstract resolveTelemetryMetadata(
-        ...args: Parameters<ToolCallback<typeof this.argsShape>>
-    ): TelemetryToolMetadata;
-
-    /**
-     * Creates and emits a tool telemetry event
-     * @param startTime - Start time in milliseconds
-     * @param result - Whether the command succeeded or failed
-     * @param args - The arguments passed to the tool
-     */
-    private async emitToolEvent(
-        startTime: number,
-        result: CallToolResult,
-        ...args: Parameters<ToolCallback<typeof this.argsShape>>
-    ): Promise<void> {
-        if (!this.telemetry.isTelemetryEnabled()) {
-            return;
-        }
-        const duration = Date.now() - startTime;
-        const metadata = this.resolveTelemetryMetadata(...args);
-        const event: ToolEvent = {
-            timestamp: new Date().toISOString(),
-            source: "mdbmcp",
-            properties: {
-                command: this.name,
-                category: this.category,
-                component: "tool",
-                duration_ms: duration,
-                result: result.isError ? "failure" : "success",
-            },
-        };
-
-        if (metadata?.orgId) {
-            event.properties.org_id = metadata.orgId;
-        }
-
-        if (metadata?.projectId) {
-            event.properties.project_id = metadata.projectId;
-        }
-
-        await this.telemetry.emitEvents([event]);
-    }
-}

package/src/transports/base.ts

@@ -1,34 +0,0 @@
-import { UserConfig } from "../common/config.js";
-import { packageInfo } from "../common/packageInfo.js";
-import { Server } from "../server.js";
-import { Session } from "../common/session.js";
-import { Telemetry } from "../telemetry/telemetry.js";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-
-export abstract class TransportRunnerBase {
-    protected setupServer(userConfig: UserConfig): Server {
-        const session = new Session({
-            apiBaseUrl: userConfig.apiBaseUrl,
-            apiClientId: userConfig.apiClientId,
-            apiClientSecret: userConfig.apiClientSecret,
-        });
-
-        const telemetry = Telemetry.create(session, userConfig);
-
-        const mcpServer = new McpServer({
-            name: packageInfo.mcpServerName,
-            version: packageInfo.version,
-        });
-
-        return new Server({
-            mcpServer,
-            session,
-            telemetry,
-            userConfig,
-        });
-    }
-
-    abstract start(): Promise<void>;
-
-    abstract close(): Promise<void>;
-}