mongodb-mcp-server 0.2.0 → 0.3.0

package/src/telemetry/types.ts

@@ -1,76 +0,0 @@
-/**
- * Result type constants for telemetry events
- */
-export type TelemetryResult = "success" | "failure";
-export type ServerCommand = "start" | "stop";
-export type TelemetryBoolSet = "true" | "false";
-
-/**
- * Base interface for all events
- */
-export type TelemetryEvent<T> = {
-    timestamp: string;
-    source: "mdbmcp";
-    properties: T & {
-        component: string;
-        duration_ms: number;
-        result: TelemetryResult;
-        category: string;
-    };
-};
-
-export type BaseEvent = TelemetryEvent<unknown>;
-
-/**
- * Interface for tool events
- */
-export type ToolEventProperties = {
-    command: string;
-    error_code?: string;
-    error_type?: string;
-    project_id?: string;
-    org_id?: string;
-    cluster_name?: string;
-    is_atlas?: boolean;
-};
-
-export type ToolEvent = TelemetryEvent<ToolEventProperties>;
-/**
- * Interface for server events
- */
-export type ServerEventProperties = {
-    command: ServerCommand;
-    reason?: string;
-    startup_time_ms?: number;
-    runtime_duration_ms?: number;
-    read_only_mode?: boolean;
-    disabled_tools?: string[];
-};
-
-export type ServerEvent = TelemetryEvent<ServerEventProperties>;
-
-/**
- * Interface for static properties, they can be fetched once and reused.
- */
-export type CommonStaticProperties = {
-    mcp_server_version: string;
-    mcp_server_name: string;
-    platform: string;
-    arch: string;
-    os_type: string;
-    os_version?: string;
-};
-
-/**
- * Common properties for all events that might change.
- */
-export type CommonProperties = {
-    device_id?: string;
-    is_container_env?: boolean;
-    mcp_client_version?: string;
-    mcp_client_name?: string;
-    transport?: "stdio" | "http";
-    config_atlas_auth?: TelemetryBoolSet;
-    config_connection_string?: TelemetryBoolSet;
-    session_id?: string;
-} & CommonStaticProperties;

package/src/tools/atlas/atlasTool.ts

@@ -1,103 +0,0 @@
-import { ToolBase, ToolCategory, TelemetryToolMetadata, ToolArgs } from "../tool.js";
-import { ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import logger, { LogId } from "../../common/logger.js";
-import { z } from "zod";
-import { ApiClientError } from "../../common/atlas/apiClientError.js";
-
-export abstract class AtlasToolBase extends ToolBase {
-    public category: ToolCategory = "atlas";
-
-    protected verifyAllowed(): boolean {
-        if (!this.config.apiClientId || !this.config.apiClientSecret) {
-            return false;
-        }
-        return super.verifyAllowed();
-    }
-
-    protected handleError(
-        error: unknown,
-        args: ToolArgs<typeof this.argsShape>
-    ): Promise<CallToolResult> | CallToolResult {
-        if (error instanceof ApiClientError) {
-            const statusCode = error.response.status;
-
-            if (statusCode === 401) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Unable to authenticate with MongoDB Atlas, API error: ${error.message}
-
-Hint: Your API credentials may be invalid, expired or lack permissions.
-Please check your Atlas API credentials and ensure they have the appropriate permissions.
-For more information on setting up API keys, visit: https://www.mongodb.com/docs/atlas/configure-api-access/`,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-
-            if (statusCode === 403) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Received a Forbidden API Error: ${error.message}
-
-You don't have sufficient permissions to perform this action in MongoDB Atlas
-Please ensure your API key has the necessary roles assigned.
-For more information on Atlas API access roles, visit: https://www.mongodb.com/docs/atlas/api/service-accounts-overview/`,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-        }
-
-        // For other types of errors, use the default error handling from the base class
-        return super.handleError(error, args);
-    }
-
-    /**
-     *
-     * Resolves the tool metadata from the arguments passed to the tool
-     *
-     * @param args - The arguments passed to the tool
-     * @returns The tool metadata
-     */
-    protected resolveTelemetryMetadata(
-        ...args: Parameters<ToolCallback<typeof this.argsShape>>
-    ): TelemetryToolMetadata {
-        const toolMetadata: TelemetryToolMetadata = {};
-        if (!args.length) {
-            return toolMetadata;
-        }
-
-        // Create a typed parser for the exact shape we expect
-        const argsShape = z.object(this.argsShape);
-        const parsedResult = argsShape.safeParse(args[0]);
-
-        if (!parsedResult.success) {
-            logger.debug(
-                LogId.telemetryMetadataError,
-                "tool",
-                `Error parsing tool arguments: ${parsedResult.error.message}`
-            );
-            return toolMetadata;
-        }
-
-        const data = parsedResult.data;
-
-        // Extract projectId using type guard
-        if ("projectId" in data && typeof data.projectId === "string" && data.projectId.trim() !== "") {
-            toolMetadata.projectId = data.projectId;
-        }
-
-        // Extract orgId using type guard
-        if ("orgId" in data && typeof data.orgId === "string" && data.orgId.trim() !== "") {
-            toolMetadata.orgId = data.orgId;
-        }
-        return toolMetadata;
-    }
-}

package/src/tools/atlas/connect/connectCluster.ts

@@ -1,259 +0,0 @@
-import { z } from "zod";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { AtlasToolBase } from "../atlasTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-import { generateSecurePassword } from "../../../helpers/generatePassword.js";
-import logger, { LogId } from "../../../common/logger.js";
-import { inspectCluster } from "../../../common/atlas/cluster.js";
-import { ensureCurrentIpInAccessList } from "../../../common/atlas/accessListUtils.js";
-
-const EXPIRY_MS = 1000 * 60 * 60 * 12; // 12 hours
-
-function sleep(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-export class ConnectClusterTool extends AtlasToolBase {
-    public name = "atlas-connect-cluster";
-    protected description = "Connect to MongoDB Atlas cluster";
-    public operationType: OperationType = "connect";
-    protected argsShape = {
-        projectId: z.string().describe("Atlas project ID"),
-        clusterName: z.string().describe("Atlas cluster name"),
-    };
-
-    private async queryConnection(
-        projectId: string,
-        clusterName: string
-    ): Promise<"connected" | "disconnected" | "connecting" | "connected-to-other-cluster" | "unknown"> {
-        if (!this.session.connectedAtlasCluster) {
-            if (this.session.serviceProvider) {
-                return "connected-to-other-cluster";
-            }
-            return "disconnected";
-        }
-
-        if (
-            this.session.connectedAtlasCluster.projectId !== projectId ||
-            this.session.connectedAtlasCluster.clusterName !== clusterName
-        ) {
-            return "connected-to-other-cluster";
-        }
-
-        if (!this.session.serviceProvider) {
-            return "connecting";
-        }
-
-        try {
-            await this.session.serviceProvider.runCommand("admin", {
-                ping: 1,
-            });
-
-            return "connected";
-        } catch (err: unknown) {
-            const error = err instanceof Error ? err : new Error(String(err));
-            logger.debug(
-                LogId.atlasConnectFailure,
-                "atlas-connect-cluster",
-                `error querying cluster: ${error.message}`
-            );
-            return "unknown";
-        }
-    }
-
-    private async prepareClusterConnection(projectId: string, clusterName: string): Promise<string> {
-        const cluster = await inspectCluster(this.session.apiClient, projectId, clusterName);
-
-        if (!cluster.connectionString) {
-            throw new Error("Connection string not available");
-        }
-
-        const username = `mcpUser${Math.floor(Math.random() * 100000)}`;
-        const password = await generateSecurePassword();
-
-        const expiryDate = new Date(Date.now() + EXPIRY_MS);
-
-        const readOnly =
-            this.config.readOnly ||
-            (this.config.disabledTools?.includes("create") &&
-                this.config.disabledTools?.includes("update") &&
-                this.config.disabledTools?.includes("delete") &&
-                !this.config.disabledTools?.includes("read") &&
-                !this.config.disabledTools?.includes("metadata"));
-
-        const roleName = readOnly ? "readAnyDatabase" : "readWriteAnyDatabase";
-
-        await this.session.apiClient.createDatabaseUser({
-            params: {
-                path: {
-                    groupId: projectId,
-                },
-            },
-            body: {
-                databaseName: "admin",
-                groupId: projectId,
-                roles: [
-                    {
-                        roleName,
-                        databaseName: "admin",
-                    },
-                ],
-                scopes: [{ type: "CLUSTER", name: clusterName }],
-                username,
-                password,
-                awsIAMType: "NONE",
-                ldapAuthType: "NONE",
-                oidcAuthType: "NONE",
-                x509Type: "NONE",
-                deleteAfterDate: expiryDate.toISOString(),
-            },
-        });
-
-        this.session.connectedAtlasCluster = {
-            username,
-            projectId,
-            clusterName,
-            expiryDate,
-        };
-
-        const cn = new URL(cluster.connectionString);
-        cn.username = username;
-        cn.password = password;
-        cn.searchParams.set("authSource", "admin");
-        return cn.toString();
-    }
-
-    private async connectToCluster(projectId: string, clusterName: string, connectionString: string): Promise<void> {
-        let lastError: Error | undefined = undefined;
-
-        logger.debug(
-            LogId.atlasConnectAttempt,
-            "atlas-connect-cluster",
-            `attempting to connect to cluster: ${this.session.connectedAtlasCluster?.clusterName}`
-        );
-
-        // try to connect for about 5 minutes
-        for (let i = 0; i < 600; i++) {
-            if (
-                !this.session.connectedAtlasCluster ||
-                this.session.connectedAtlasCluster.projectId != projectId ||
-                this.session.connectedAtlasCluster.clusterName != clusterName
-            ) {
-                throw new Error("Cluster connection aborted");
-            }
-
-            try {
-                lastError = undefined;
-
-                await this.session.connectToMongoDB(connectionString, this.config.connectOptions);
-                break;
-            } catch (err: unknown) {
-                const error = err instanceof Error ? err : new Error(String(err));
-
-                lastError = error;
-
-                logger.debug(
-                    LogId.atlasConnectFailure,
-                    "atlas-connect-cluster",
-                    `error connecting to cluster: ${error.message}`
-                );
-
-                await sleep(500); // wait for 500ms before retrying
-            }
-        }
-
-        if (lastError) {
-            if (
-                this.session.connectedAtlasCluster?.projectId == projectId &&
-                this.session.connectedAtlasCluster?.clusterName == clusterName &&
-                this.session.connectedAtlasCluster?.username
-            ) {
-                void this.session.apiClient
-                    .deleteDatabaseUser({
-                        params: {
-                            path: {
-                                groupId: this.session.connectedAtlasCluster.projectId,
-                                username: this.session.connectedAtlasCluster.username,
-                                databaseName: "admin",
-                            },
-                        },
-                    })
-                    .catch((err: unknown) => {
-                        const error = err instanceof Error ? err : new Error(String(err));
-                        logger.debug(
-                            LogId.atlasConnectFailure,
-                            "atlas-connect-cluster",
-                            `error deleting database user: ${error.message}`
-                        );
-                    });
-            }
-            this.session.connectedAtlasCluster = undefined;
-            throw lastError;
-        }
-
-        logger.debug(
-            LogId.atlasConnectSucceeded,
-            "atlas-connect-cluster",
-            `connected to cluster: ${this.session.connectedAtlasCluster?.clusterName}`
-        );
-    }
-
-    protected async execute({ projectId, clusterName }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        await ensureCurrentIpInAccessList(this.session.apiClient, projectId);
-        for (let i = 0; i < 60; i++) {
-            const state = await this.queryConnection(projectId, clusterName);
-            switch (state) {
-                case "connected": {
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: `Connected to cluster "${clusterName}".`,
-                            },
-                        ],
-                    };
-                }
-                case "connecting":
-                case "unknown": {
-                    break;
-                }
-                case "connected-to-other-cluster":
-                case "disconnected":
-                default: {
-                    await this.session.disconnect();
-                    const connectionString = await this.prepareClusterConnection(projectId, clusterName);
-
-                    // try to connect for about 5 minutes asynchronously
-                    void this.connectToCluster(projectId, clusterName, connectionString).catch((err: unknown) => {
-                        const error = err instanceof Error ? err : new Error(String(err));
-                        logger.error(
-                            LogId.atlasConnectFailure,
-                            "atlas-connect-cluster",
-                            `error connecting to cluster: ${error.message}`
-                        );
-                    });
-                    break;
-                }
-            }
-
-            await sleep(500);
-        }
-
-        return {
-            content: [
-                {
-                    type: "text" as const,
-                    text: `Attempting to connect to cluster "${clusterName}"...`,
-                },
-                {
-                    type: "text" as const,
-                    text: `Warning: Provisioning a user and connecting to the cluster may take more time, please check again in a few seconds.`,
-                },
-                {
-                    type: "text" as const,
-                    text: `Warning: Make sure your IP address was enabled in the allow list setting of the Atlas cluster.`,
-                },
-            ],
-        };
-    }
-}

package/src/tools/atlas/create/createAccessList.ts

@@ -1,78 +0,0 @@
-import { z } from "zod";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { AtlasToolBase } from "../atlasTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-import { makeCurrentIpAccessListEntry, DEFAULT_ACCESS_LIST_COMMENT } from "../../../common/atlas/accessListUtils.js";
-
-export class CreateAccessListTool extends AtlasToolBase {
-    public name = "atlas-create-access-list";
-    protected description = "Allow Ip/CIDR ranges to access your MongoDB Atlas clusters.";
-    public operationType: OperationType = "create";
-    protected argsShape = {
-        projectId: z.string().describe("Atlas project ID"),
-        ipAddresses: z
-            .array(z.string().ip({ version: "v4" }))
-            .describe("IP addresses to allow access from")
-            .optional(),
-        cidrBlocks: z.array(z.string().cidr()).describe("CIDR blocks to allow access from").optional(),
-        currentIpAddress: z.boolean().describe("Add the current IP address").default(false),
-        comment: z
-            .string()
-            .describe("Comment for the access list entries")
-            .default(DEFAULT_ACCESS_LIST_COMMENT)
-            .optional(),
-    };
-
-    protected async execute({
-        projectId,
-        ipAddresses,
-        cidrBlocks,
-        comment,
-        currentIpAddress,
-    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        if (!ipAddresses?.length && !cidrBlocks?.length && !currentIpAddress) {
-            throw new Error("One of  ipAddresses, cidrBlocks, currentIpAddress must be provided.");
-        }
-
-        const ipInputs = (ipAddresses || []).map((ipAddress) => ({
-            groupId: projectId,
-            ipAddress,
-            comment: comment || DEFAULT_ACCESS_LIST_COMMENT,
-        }));
-
-        if (currentIpAddress) {
-            const input = await makeCurrentIpAccessListEntry(
-                this.session.apiClient,
-                projectId,
-                comment || DEFAULT_ACCESS_LIST_COMMENT
-            );
-            ipInputs.push(input);
-        }
-
-        const cidrInputs = (cidrBlocks || []).map((cidrBlock) => ({
-            groupId: projectId,
-            cidrBlock,
-            comment: comment || DEFAULT_ACCESS_LIST_COMMENT,
-        }));
-
-        const inputs = [...ipInputs, ...cidrInputs];
-
-        await this.session.apiClient.createProjectIpAccessList({
-            params: {
-                path: {
-                    groupId: projectId,
-                },
-            },
-            body: inputs,
-        });
-
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `IP/CIDR ranges added to access list for project ${projectId}.`,
-                },
-            ],
-        };
-    }
-}

package/src/tools/atlas/create/createDBUser.ts

@@ -1,90 +0,0 @@
-import { z } from "zod";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { AtlasToolBase } from "../atlasTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-import { CloudDatabaseUser, DatabaseUserRole } from "../../../common/atlas/openapi.js";
-import { generateSecurePassword } from "../../../helpers/generatePassword.js";
-import { ensureCurrentIpInAccessList } from "../../../common/atlas/accessListUtils.js";
-
-export class CreateDBUserTool extends AtlasToolBase {
-    public name = "atlas-create-db-user";
-    protected description = "Create an MongoDB Atlas database user";
-    public operationType: OperationType = "create";
-    protected argsShape = {
-        projectId: z.string().describe("Atlas project ID"),
-        username: z.string().describe("Username for the new user"),
-        // Models will generate overly simplistic passwords like SecurePassword123 or
-        // AtlasPassword123, which are easily guessable and exploitable. We're instructing
-        // the model not to try and generate anything and instead leave the field unset.
-        password: z
-            .string()
-            .optional()
-            .nullable()
-            .describe(
-                "Password for the new user. If the user hasn't supplied an explicit password, leave it unset and under no circumstances try to generate a random one. A secure password will be generated by the MCP server if necessary."
-            ),
-        roles: z
-            .array(
-                z.object({
-                    roleName: z.string().describe("Role name"),
-                    databaseName: z.string().describe("Database name").default("admin"),
-                    collectionName: z.string().describe("Collection name").optional(),
-                })
-            )
-            .describe("Roles for the new user"),
-        clusters: z
-            .array(z.string())
-            .describe("Clusters to assign the user to, leave empty for access to all clusters")
-            .optional(),
-    };
-
-    protected async execute({
-        projectId,
-        username,
-        password,
-        roles,
-        clusters,
-    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        await ensureCurrentIpInAccessList(this.session.apiClient, projectId);
-        const shouldGeneratePassword = !password;
-        if (shouldGeneratePassword) {
-            password = await generateSecurePassword();
-        }
-
-        const input = {
-            groupId: projectId,
-            awsIAMType: "NONE",
-            databaseName: "admin",
-            ldapAuthType: "NONE",
-            oidcAuthType: "NONE",
-            x509Type: "NONE",
-            username,
-            password,
-            roles: roles as unknown as DatabaseUserRole[],
-            scopes: clusters?.length
-                ? clusters.map((cluster) => ({
-                      type: "CLUSTER",
-                      name: cluster,
-                  }))
-                : undefined,
-        } as CloudDatabaseUser;
-
-        await this.session.apiClient.createDatabaseUser({
-            params: {
-                path: {
-                    groupId: projectId,
-                },
-            },
-            body: input,
-        });
-
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `User "${username}" created successfully${shouldGeneratePassword ? ` with password: \`${password}\`` : ""}.`,
-                },
-            ],
-        };
-    }
-}

package/src/tools/atlas/create/createFreeCluster.ts

@@ -1,58 +0,0 @@
-import { z } from "zod";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { AtlasToolBase } from "../atlasTool.js";
-import { ToolArgs, OperationType } from "../../tool.js";
-import { ClusterDescription20240805 } from "../../../common/atlas/openapi.js";
-import { ensureCurrentIpInAccessList } from "../../../common/atlas/accessListUtils.js";
-
-export class CreateFreeClusterTool extends AtlasToolBase {
-    public name = "atlas-create-free-cluster";
-    protected description = "Create a free MongoDB Atlas cluster";
-    public operationType: OperationType = "create";
-    protected argsShape = {
-        projectId: z.string().describe("Atlas project ID to create the cluster in"),
-        name: z.string().describe("Name of the cluster"),
-        region: z.string().describe("Region of the cluster").default("US_EAST_1"),
-    };
-
-    protected async execute({ projectId, name, region }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        const input = {
-            groupId: projectId,
-            name,
-            clusterType: "REPLICASET",
-            replicationSpecs: [
-                {
-                    zoneName: "Zone 1",
-                    regionConfigs: [
-                        {
-                            providerName: "TENANT",
-                            backingProviderName: "AWS",
-                            regionName: region,
-                            electableSpecs: {
-                                instanceSize: "M0",
-                            },
-                        },
-                    ],
-                },
-            ],
-            terminationProtectionEnabled: false,
-        } as unknown as ClusterDescription20240805;
-
-        await ensureCurrentIpInAccessList(this.session.apiClient, projectId);
-        await this.session.apiClient.createCluster({
-            params: {
-                path: {
-                    groupId: projectId,
-                },
-            },
-            body: input,
-        });
-
-        return {
-            content: [
-                { type: "text", text: `Cluster "${name}" has been created in region "${region}".` },
-                { type: "text", text: `Double check your access lists to enable your current IP.` },
-            ],
-        };
-    }
-}