mongodb-mcp-server 0.0.4

package/src/config.ts

@@ -0,0 +1,124 @@
+import path from "path";
+import os from "os";
+import argv from "yargs-parser";
+
+import packageJson from "../package.json" with { type: "json" };
+import { ReadConcernLevel, ReadPreferenceMode, W } from "mongodb";
+
+// If we decide to support non-string config options, we'll need to extend the mechanism for parsing
+// env variables.
+interface UserConfig {
+    apiBaseUrl?: string;
+    apiClientId?: string;
+    apiClientSecret?: string;
+    logPath: string;
+    connectionString?: string;
+    connectOptions: {
+        readConcern: ReadConcernLevel;
+        readPreference: ReadPreferenceMode;
+        writeConcern: W;
+        timeoutMS: number;
+    };
+    disabledTools: Array<string>;
+}
+
+const defaults: UserConfig = {
+    logPath: getLogPath(),
+    connectOptions: {
+        readConcern: "local",
+        readPreference: "secondaryPreferred",
+        writeConcern: "majority",
+        timeoutMS: 30_000,
+    },
+    disabledTools: [],
+};
+
+const mergedUserConfig = {
+    ...defaults,
+    ...getEnvConfig(),
+    ...getCliConfig(),
+};
+
+const config = {
+    ...mergedUserConfig,
+    version: packageJson.version,
+};
+
+export default config;
+
+function getLogPath(): string {
+    const localDataPath =
+        process.platform === "win32"
+            ? path.join(process.env.LOCALAPPDATA || process.env.APPDATA || os.homedir(), "mongodb")
+            : path.join(os.homedir(), ".mongodb");
+
+    const logPath = path.join(localDataPath, "mongodb-mcp", ".app-logs");
+
+    return logPath;
+}
+
+// Gets the config supplied by the user as environment variables. The variable names
+// are prefixed with `MDB_MCP_` and the keys match the UserConfig keys, but are converted
+// to SNAKE_UPPER_CASE.
+function getEnvConfig(): Partial<UserConfig> {
+    function setValue(obj: Record<string, unknown>, path: string[], value: string): void {
+        const currentField = path.shift();
+        if (!currentField) {
+            return;
+        }
+        if (path.length === 0) {
+            const numberValue = Number(value);
+            if (!isNaN(numberValue)) {
+                obj[currentField] = numberValue;
+                return;
+            }
+
+            const booleanValue = value.toLocaleLowerCase();
+            if (booleanValue === "true" || booleanValue === "false") {
+                obj[currentField] = booleanValue === "true";
+                return;
+            }
+
+            // Try to parse an array of values
+            if (value.indexOf(",") !== -1) {
+                obj[currentField] = value.split(",").map((v) => v.trim());
+                return;
+            }
+
+            obj[currentField] = value;
+            return;
+        }
+
+        if (!obj[currentField]) {
+            obj[currentField] = {};
+        }
+
+        setValue(obj[currentField] as Record<string, unknown>, path, value);
+    }
+
+    const result: Record<string, unknown> = {};
+    const mcpVariables = Object.entries(process.env).filter(
+        ([key, value]) => value !== undefined && key.startsWith("MDB_MCP_")
+    ) as [string, string][];
+    for (const [key, value] of mcpVariables) {
+        const fieldPath = key
+            .replace("MDB_MCP_", "")
+            .split(".")
+            .map((part) => SNAKE_CASE_toCamelCase(part));
+
+        setValue(result, fieldPath, value);
+    }
+
+    return result;
+}
+
+function SNAKE_CASE_toCamelCase(str: string): string {
+    return str.toLowerCase().replace(/([-_][a-z])/g, (group) => group.toUpperCase().replace("_", ""));
+}
+
+// Reads the cli args and parses them into a UserConfig object.
+function getCliConfig() {
+    return argv(process.argv.slice(2), {
+        array: ["disabledTools"],
+    }) as unknown as Partial<UserConfig>;
+}

package/src/errors.ts

@@ -0,0 +1,13 @@
+export enum ErrorCodes {
+    NotConnectedToMongoDB = 1_000_000,
+    InvalidParams = 1_000_001,
+}
+
+export class MongoDBError extends Error {
+    constructor(
+        public code: ErrorCodes,
+        message: string
+    ) {
+        super(message);
+    }
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import logger from "./logger.js";
+import { mongoLogId } from "mongodb-log-writer";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import config from "./config.js";
+import { Session } from "./session.js";
+import { Server } from "./server.js";
+
+try {
+    const session = new Session();
+    const mcpServer = new McpServer({
+        name: "MongoDB Atlas",
+        version: config.version,
+    });
+
+    const server = new Server({
+        mcpServer,
+        session,
+    });
+
+    const transport = new StdioServerTransport();
+
+    await server.connect(transport);
+} catch (error: unknown) {
+    logger.emergency(mongoLogId(1_000_004), "server", `Fatal error running server: ${error as string}`);
+
+    process.exit(1);
+}

package/src/logger.ts

@@ -0,0 +1,117 @@
+import fs from "fs/promises";
+import { MongoLogId, MongoLogManager, MongoLogWriter } from "mongodb-log-writer";
+import config from "./config.js";
+import redact from "mongodb-redact";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { LoggingMessageNotification } from "@modelcontextprotocol/sdk/types.js";
+
+export type LogLevel = LoggingMessageNotification["params"]["level"];
+
+abstract class LoggerBase {
+    abstract log(level: LogLevel, id: MongoLogId, context: string, message: string): void;
+    info(id: MongoLogId, context: string, message: string): void {
+        this.log("info", id, context, message);
+    }
+
+    error(id: MongoLogId, context: string, message: string): void {
+        this.log("error", id, context, message);
+    }
+    debug(id: MongoLogId, context: string, message: string): void {
+        this.log("debug", id, context, message);
+    }
+
+    notice(id: MongoLogId, context: string, message: string): void {
+        this.log("notice", id, context, message);
+    }
+
+    warning(id: MongoLogId, context: string, message: string): void {
+        this.log("warning", id, context, message);
+    }
+
+    critical(id: MongoLogId, context: string, message: string): void {
+        this.log("critical", id, context, message);
+    }
+
+    alert(id: MongoLogId, context: string, message: string): void {
+        this.log("alert", id, context, message);
+    }
+
+    emergency(id: MongoLogId, context: string, message: string): void {
+        this.log("emergency", id, context, message);
+    }
+}
+
+class ConsoleLogger extends LoggerBase {
+    log(level: LogLevel, id: MongoLogId, context: string, message: string): void {
+        message = redact(message);
+        console.error(`[${level.toUpperCase()}] ${id.__value} - ${context}: ${message}`);
+    }
+}
+
+class Logger extends LoggerBase {
+    constructor(
+        private logWriter: MongoLogWriter,
+        private server: McpServer
+    ) {
+        super();
+    }
+
+    log(level: LogLevel, id: MongoLogId, context: string, message: string): void {
+        message = redact(message);
+        const mongoDBLevel = this.mapToMongoDBLogLevel(level);
+        this.logWriter[mongoDBLevel]("MONGODB-MCP", id, context, message);
+        void this.server.server.sendLoggingMessage({
+            level,
+            data: `[${context}]: ${message}`,
+        });
+    }
+
+    private mapToMongoDBLogLevel(level: LogLevel): "info" | "warn" | "error" | "debug" | "fatal" {
+        switch (level) {
+            case "info":
+                return "info";
+            case "warning":
+                return "warn";
+            case "error":
+                return "error";
+            case "notice":
+            case "debug":
+                return "debug";
+            case "critical":
+            case "alert":
+            case "emergency":
+                return "fatal";
+            default:
+                return "info";
+        }
+    }
+}
+
+class ProxyingLogger extends LoggerBase {
+    private internalLogger: LoggerBase = new ConsoleLogger();
+
+    log(level: LogLevel, id: MongoLogId, context: string, message: string): void {
+        this.internalLogger.log(level, id, context, message);
+    }
+}
+
+const logger = new ProxyingLogger();
+export default logger;
+
+export async function initializeLogger(server: McpServer): Promise<void> {
+    await fs.mkdir(config.logPath, { recursive: true });
+
+    const manager = new MongoLogManager({
+        directory: config.logPath,
+        retentionDays: 30,
+        onwarn: console.warn,
+        onerror: console.error,
+        gzip: false,
+        retentionGB: 1,
+    });
+
+    await manager.cleanupOldLogFiles();
+
+    const logWriter = await manager.createLogWriter();
+    logger["internalLogger"] = new Logger(logWriter, server);
+}

package/src/server.ts

@@ -0,0 +1,64 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Session } from "./session.js";
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { AtlasTools } from "./tools/atlas/tools.js";
+import { MongoDbTools } from "./tools/mongodb/tools.js";
+import logger, { initializeLogger } from "./logger.js";
+import { mongoLogId } from "mongodb-log-writer";
+import config from "./config.js";
+
+export class Server {
+    public readonly session: Session;
+    private readonly mcpServer: McpServer;
+
+    constructor({ mcpServer, session }: { mcpServer: McpServer; session: Session }) {
+        this.mcpServer = mcpServer;
+        this.session = session;
+    }
+
+    async connect(transport: Transport) {
+        this.mcpServer.server.registerCapabilities({ logging: {} });
+
+        this.registerTools();
+        this.registerResources();
+
+        await initializeLogger(this.mcpServer);
+
+        await this.mcpServer.connect(transport);
+
+        logger.info(mongoLogId(1_000_004), "server", `Server started with transport ${transport.constructor.name}`);
+    }
+
+    async close(): Promise<void> {
+        await this.session.close();
+        await this.mcpServer.close();
+    }
+
+    private registerTools() {
+        for (const tool of [...AtlasTools, ...MongoDbTools]) {
+            new tool(this.session).register(this.mcpServer);
+        }
+    }
+
+    private registerResources() {
+        if (config.connectionString) {
+            this.mcpServer.resource(
+                "connection-string",
+                "config://connection-string",
+                {
+                    description: "Preconfigured connection string that will be used as a default in the `connect` tool",
+                },
+                (uri) => {
+                    return {
+                        contents: [
+                            {
+                                text: `Preconfigured connection string: ${config.connectionString}`,
+                                uri: uri.href,
+                            },
+                        ],
+                    };
+                }
+            );
+        }
+    }
+}

package/src/session.ts

@@ -0,0 +1,37 @@
+import { NodeDriverServiceProvider } from "@mongosh/service-provider-node-driver";
+import { ApiClient } from "./common/atlas/apiClient.js";
+import config from "./config.js";
+
+export class Session {
+    serviceProvider?: NodeDriverServiceProvider;
+    apiClient?: ApiClient;
+
+    ensureAuthenticated(): asserts this is { apiClient: ApiClient } {
+        if (!this.apiClient) {
+            if (!config.apiClientId || !config.apiClientSecret) {
+                throw new Error(
+                    "Not authenticated make sure to configure MCP server with MDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET environment variables."
+                );
+            }
+
+            this.apiClient = new ApiClient({
+                baseUrl: config.apiBaseUrl,
+                credentials: {
+                    clientId: config.apiClientId,
+                    clientSecret: config.apiClientSecret,
+                },
+            });
+        }
+    }
+
+    async close(): Promise<void> {
+        if (this.serviceProvider) {
+            try {
+                await this.serviceProvider.close(true);
+            } catch (error) {
+                console.error("Error closing service provider:", error);
+            }
+            this.serviceProvider = undefined;
+        }
+    }
+}

package/src/tools/atlas/atlasTool.ts

@@ -0,0 +1,10 @@
+import { ToolBase, ToolCategory } from "../tool.js";
+import { Session } from "../../session.js";
+
+export abstract class AtlasToolBase extends ToolBase {
+    constructor(protected readonly session: Session) {
+        super(session);
+    }
+
+    protected category: ToolCategory = "atlas";
+}

package/src/tools/atlas/createAccessList.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { AtlasToolBase } from "./atlasTool.js";
+import { ToolArgs, OperationType } from "../tool.js";
+
+const DEFAULT_COMMENT = "Added by Atlas MCP";
+
+export class CreateAccessListTool extends AtlasToolBase {
+    protected name = "atlas-create-access-list";
+    protected description = "Allow Ip/CIDR ranges to access your MongoDB Atlas clusters.";
+    protected 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_COMMENT).optional(),
+    };
+
+    protected async execute({
+        projectId,
+        ipAddresses,
+        cidrBlocks,
+        comment,
+        currentIpAddress,
+    }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        this.session.ensureAuthenticated();
+
+        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_COMMENT,
+        }));
+
+        if (currentIpAddress) {
+            const currentIp = await this.session.apiClient.getIpInfo();
+            const input = {
+                groupId: projectId,
+                ipAddress: currentIp.currentIpv4Address,
+                comment: comment || DEFAULT_COMMENT,
+            };
+            ipInputs.push(input);
+        }
+
+        const cidrInputs = (cidrBlocks || []).map((cidrBlock) => ({
+            groupId: projectId,
+            cidrBlock,
+            comment: comment || DEFAULT_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/createDBUser.ts

@@ -0,0 +1,70 @@
+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";
+
+export class CreateDBUserTool extends AtlasToolBase {
+    protected name = "atlas-create-db-user";
+    protected description = "Create an MongoDB Atlas database user";
+    protected operationType: OperationType = "create";
+    protected argsShape = {
+        projectId: z.string().describe("Atlas project ID"),
+        username: z.string().describe("Username for the new user"),
+        password: z.string().describe("Password for the new user"),
+        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> {
+        this.session.ensureAuthenticated();
+
+        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 sucessfully.` }],
+        };
+    }
+}

package/src/tools/atlas/createFreeCluster.ts

@@ -0,0 +1,55 @@
+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";
+
+export class CreateFreeClusterTool extends AtlasToolBase {
+    protected name = "atlas-create-free-cluster";
+    protected description = "Create a free MongoDB Atlas cluster";
+    protected 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> {
+        this.session.ensureAuthenticated();
+
+        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 this.session.apiClient.createCluster({
+            params: {
+                path: {
+                    groupId: projectId,
+                },
+            },
+            body: input,
+        });
+
+        return {
+            content: [{ type: "text", text: `Cluster "${name}" has been created in region "${region}".` }],
+        };
+    }
+}

package/src/tools/atlas/createProject.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { AtlasToolBase } from "./atlasTool.js";
+import { ToolArgs, OperationType } from "../tool.js";
+import { Group } from "../../common/atlas/openapi.js";
+
+export class CreateProjectTool extends AtlasToolBase {
+    protected name = "atlas-create-project";
+    protected description = "Create a MongoDB Atlas project";
+    protected operationType: OperationType = "create";
+    protected argsShape = {
+        projectName: z.string().optional().describe("Name for the new project"),
+        organizationId: z.string().optional().describe("Organization ID for the new project"),
+    };
+
+    protected async execute({ projectName, organizationId }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        this.session.ensureAuthenticated();
+        let assumedOrg = false;
+
+        if (!projectName) {
+            projectName = "Atlas Project";
+        }
+
+        if (!organizationId) {
+            try {
+                const organizations = await this.session.apiClient.listOrganizations();
+                if (!organizations?.results?.length) {
+                    throw new Error(
+                        "No organizations were found in your MongoDB Atlas account. Please create an organization first."
+                    );
+                }
+                organizationId = organizations.results[0].id;
+                assumedOrg = true;
+            } catch {
+                throw new Error(
+                    "Could not search for organizations in your MongoDB Atlas account, please provide an organization ID or create one first."
+                );
+            }
+        }
+
+        const input = {
+            name: projectName,
+            orgId: organizationId,
+        } as Group;
+
+        const group = await this.session.apiClient.createProject({
+            body: input,
+        });
+
+        if (!group?.id) {
+            throw new Error("Failed to create project");
+        }
+
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Project "${projectName}" created successfully${assumedOrg ? ` (using organizationId ${organizationId}).` : ""}.`,
+                },
+            ],
+        };
+    }
+}