mongodb-mcp-server 0.1.3 → 0.3.0

package/src/config.ts

@@ -1,125 +0,0 @@
-import path from "path";
-import os from "os";
-import argv from "yargs-parser";
-
-import { ReadConcernLevel, ReadPreferenceMode, W } from "mongodb";
-
-export interface ConnectOptions {
-    readConcern: ReadConcernLevel;
-    readPreference: ReadPreferenceMode;
-    writeConcern: W;
-    timeoutMS: number;
-}
-
-// If we decide to support non-string config options, we'll need to extend the mechanism for parsing
-// env variables.
-export interface UserConfig {
-    apiBaseUrl: string;
-    apiClientId?: string;
-    apiClientSecret?: string;
-    telemetry?: "enabled" | "disabled";
-    logPath: string;
-    connectionString?: string;
-    connectOptions: ConnectOptions;
-    disabledTools: Array<string>;
-    readOnly?: boolean;
-    indexCheck?: boolean;
-}
-
-const defaults: UserConfig = {
-    apiBaseUrl: "https://cloud.mongodb.com/",
-    logPath: getLogPath(),
-    connectOptions: {
-        readConcern: "local",
-        readPreference: "secondaryPreferred",
-        writeConcern: "majority",
-        timeoutMS: 30_000,
-    },
-    disabledTools: [],
-    telemetry: "enabled",
-    readOnly: false,
-    indexCheck: false,
-};
-
-export const config = {
-    ...defaults,
-    ...getEnvConfig(),
-    ...getCliConfig(),
-};
-
-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

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

package/src/helpers/EJsonTransport.ts

@@ -1,47 +0,0 @@
-import { JSONRPCMessage, JSONRPCMessageSchema } from "@modelcontextprotocol/sdk/types.js";
-import { EJSON } from "bson";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-// This is almost a copy of ReadBuffer from @modelcontextprotocol/sdk
-// but it uses EJSON.parse instead of JSON.parse to handle BSON types
-export class EJsonReadBuffer {
-    private _buffer?: Buffer;
-
-    append(chunk: Buffer): void {
-        this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
-    }
-
-    readMessage(): JSONRPCMessage | null {
-        if (!this._buffer) {
-            return null;
-        }
-
-        const index = this._buffer.indexOf("\n");
-        if (index === -1) {
-            return null;
-        }
-
-        const line = this._buffer.toString("utf8", 0, index).replace(/\r$/, "");
-        this._buffer = this._buffer.subarray(index + 1);
-
-        // This is using EJSON.parse instead of JSON.parse to handle BSON types
-        return JSONRPCMessageSchema.parse(EJSON.parse(line));
-    }
-
-    clear(): void {
-        this._buffer = undefined;
-    }
-}
-
-// This is a hacky workaround for https://github.com/mongodb-js/mongodb-mcp-server/issues/211
-// The underlying issue is that StdioServerTransport uses JSON.parse to deserialize
-// messages, but that doesn't handle bson types, such as ObjectId when serialized as EJSON.
-//
-// This function creates a StdioServerTransport and replaces the internal readBuffer with EJsonReadBuffer
-// that uses EJson.parse instead.
-export function createEJsonTransport(): StdioServerTransport {
-    const server = new StdioServerTransport();
-    server["_readBuffer"] = new EJsonReadBuffer();
-
-    return server;
-}

package/src/helpers/connectionOptions.ts

@@ -1,20 +0,0 @@
-import { MongoClientOptions } from "mongodb";
-import ConnectionString from "mongodb-connection-string-url";
-
-export function setAppNameParamIfMissing({
-    connectionString,
-    defaultAppName,
-}: {
-    connectionString: string;
-    defaultAppName?: string;
-}): string {
-    const connectionStringUrl = new ConnectionString(connectionString);
-
-    const searchParams = connectionStringUrl.typedSearchParams<MongoClientOptions>();
-
-    if (!searchParams.has("appName") && defaultAppName !== undefined) {
-        searchParams.set("appName", defaultAppName);
-    }
-
-    return connectionStringUrl.toString();
-}

package/src/helpers/packageInfo.ts

@@ -1,6 +0,0 @@
-import packageJson from "../../package.json" with { type: "json" };
-
-export const packageInfo = {
-    version: packageJson.version,
-    mcpServerName: "MongoDB MCP Server",
-};

package/src/index.ts

@@ -1,58 +0,0 @@
-#!/usr/bin/env node
-
-import logger, { LogId } from "./logger.js";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { config } from "./config.js";
-import { Session } from "./session.js";
-import { Server } from "./server.js";
-import { packageInfo } from "./helpers/packageInfo.js";
-import { Telemetry } from "./telemetry/telemetry.js";
-import { createEJsonTransport } from "./helpers/EJsonTransport.js";
-
-try {
-    const session = new Session({
-        apiBaseUrl: config.apiBaseUrl,
-        apiClientId: config.apiClientId,
-        apiClientSecret: config.apiClientSecret,
-    });
-    const mcpServer = new McpServer({
-        name: packageInfo.mcpServerName,
-        version: packageInfo.version,
-    });
-
-    const telemetry = Telemetry.create(session, config);
-
-    const server = new Server({
-        mcpServer,
-        session,
-        telemetry,
-        userConfig: config,
-    });
-
-    const transport = createEJsonTransport();
-
-    const shutdown = () => {
-        logger.info(LogId.serverCloseRequested, "server", `Server close requested`);
-
-        server
-            .close()
-            .then(() => {
-                logger.info(LogId.serverClosed, "server", `Server closed successfully`);
-                process.exit(0);
-            })
-            .catch((err: unknown) => {
-                const error = err instanceof Error ? err : new Error(String(err));
-                logger.error(LogId.serverCloseFailure, "server", `Error closing server: ${error.message}`);
-                process.exit(1);
-            });
-    };
-
-    process.once("SIGINT", shutdown);
-    process.once("SIGTERM", shutdown);
-    process.once("SIGQUIT", shutdown);
-
-    await server.connect(transport);
-} catch (error: unknown) {
-    logger.emergency(LogId.serverStartFailure, "server", `Fatal error running server: ${error as string}`);
-    process.exit(1);
-}

package/src/logger.ts

@@ -1,190 +0,0 @@
-import fs from "fs/promises";
-import { mongoLogId, MongoLogId, MongoLogManager, MongoLogWriter } from "mongodb-log-writer";
-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"];
-
-export const LogId = {
-    serverStartFailure: mongoLogId(1_000_001),
-    serverInitialized: mongoLogId(1_000_002),
-    serverCloseRequested: mongoLogId(1_000_003),
-    serverClosed: mongoLogId(1_000_004),
-    serverCloseFailure: mongoLogId(1_000_005),
-
-    atlasCheckCredentials: mongoLogId(1_001_001),
-    atlasDeleteDatabaseUserFailure: mongoLogId(1_001_002),
-    atlasConnectFailure: mongoLogId(1_001_003),
-    atlasInspectFailure: mongoLogId(1_001_004),
-
-    telemetryDisabled: mongoLogId(1_002_001),
-    telemetryEmitFailure: mongoLogId(1_002_002),
-    telemetryEmitStart: mongoLogId(1_002_003),
-    telemetryEmitSuccess: mongoLogId(1_002_004),
-    telemetryMetadataError: mongoLogId(1_002_005),
-    telemetryDeviceIdFailure: mongoLogId(1_002_006),
-    telemetryDeviceIdTimeout: mongoLogId(1_002_007),
-
-    toolExecute: mongoLogId(1_003_001),
-    toolExecuteFailure: mongoLogId(1_003_002),
-    toolDisabled: mongoLogId(1_003_003),
-
-    mongodbConnectFailure: mongoLogId(1_004_001),
-    mongodbDisconnectFailure: mongoLogId(1_004_002),
-
-    toolUpdateFailure: mongoLogId(1_005_001),
-} as const;
-
-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 DiskLogger extends LoggerBase {
-    private constructor(private logWriter: MongoLogWriter) {
-        super();
-    }
-
-    static async fromPath(logPath: string): Promise<DiskLogger> {
-        await fs.mkdir(logPath, { recursive: true });
-
-        const manager = new MongoLogManager({
-            directory: logPath,
-            retentionDays: 30,
-            onwarn: console.warn,
-            onerror: console.error,
-            gzip: false,
-            retentionGB: 1,
-        });
-
-        await manager.cleanupOldLogFiles();
-
-        const logWriter = await manager.createLogWriter();
-
-        return new DiskLogger(logWriter);
-    }
-
-    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);
-    }
-
-    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 McpLogger extends LoggerBase {
-    constructor(private server: McpServer) {
-        super();
-    }
-
-    log(level: LogLevel, _: MongoLogId, context: string, message: string): void {
-        // Only log if the server is connected
-        if (!this.server?.isConnected()) {
-            return;
-        }
-
-        void this.server.server.sendLoggingMessage({
-            level,
-            data: `[${context}]: ${message}`,
-        });
-    }
-}
-
-class CompositeLogger extends LoggerBase {
-    private loggers: LoggerBase[];
-
-    constructor(...loggers: LoggerBase[]) {
-        super();
-
-        if (loggers.length === 0) {
-            // default to ConsoleLogger
-            this.loggers = [new ConsoleLogger()];
-            return;
-        }
-
-        this.loggers = [...loggers];
-    }
-
-    setLoggers(...loggers: LoggerBase[]): void {
-        if (loggers.length === 0) {
-            throw new Error("At least one logger must be provided");
-        }
-        this.loggers = [...loggers];
-    }
-
-    log(level: LogLevel, id: MongoLogId, context: string, message: string): void {
-        for (const logger of this.loggers) {
-            logger.log(level, id, context, message);
-        }
-    }
-}
-
-const logger = new CompositeLogger();
-export default logger;
-
-export async function initializeLogger(server: McpServer, logPath: string): Promise<LoggerBase> {
-    const diskLogger = await DiskLogger.fromPath(logPath);
-    const mcpLogger = new McpLogger(server);
-
-    logger.setLoggers(mcpLogger, diskLogger);
-
-    return logger;
-}

package/src/server.ts

@@ -1,206 +0,0 @@
-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, LogId } from "./logger.js";
-import { ObjectId } from "mongodb";
-import { Telemetry } from "./telemetry/telemetry.js";
-import { UserConfig } from "./config.js";
-import { type ServerEvent } from "./telemetry/types.js";
-import { type ServerCommand } from "./telemetry/types.js";
-import { CallToolRequestSchema, CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import assert from "assert";
-
-export interface ServerOptions {
-    session: Session;
-    userConfig: UserConfig;
-    mcpServer: McpServer;
-    telemetry: Telemetry;
-}
-
-export class Server {
-    public readonly session: Session;
-    private readonly mcpServer: McpServer;
-    private readonly telemetry: Telemetry;
-    public readonly userConfig: UserConfig;
-    private readonly startTime: number;
-
-    constructor({ session, mcpServer, userConfig, telemetry }: ServerOptions) {
-        this.startTime = Date.now();
-        this.session = session;
-        this.telemetry = telemetry;
-        this.mcpServer = mcpServer;
-        this.userConfig = userConfig;
-    }
-
-    async connect(transport: Transport): Promise<void> {
-        this.mcpServer.server.registerCapabilities({ logging: {} });
-
-        this.registerTools();
-        this.registerResources();
-
-        // This is a workaround for an issue we've seen with some models, where they'll see that everything in the `arguments`
-        // object is optional, and then not pass it at all. However, the MCP server expects the `arguments` object to be if
-        // the tool accepts any arguments, even if they're all optional.
-        //
-        // see: https://github.com/modelcontextprotocol/typescript-sdk/blob/131776764536b5fdca642df51230a3746fb4ade0/src/server/mcp.ts#L705
-        // Since paramsSchema here is not undefined, the server will create a non-optional z.object from it.
-        const existingHandler = (
-            this.mcpServer.server["_requestHandlers"] as Map<
-                string,
-                (request: unknown, extra: unknown) => Promise<CallToolResult>
-            >
-        ).get(CallToolRequestSchema.shape.method.value);
-
-        assert(existingHandler, "No existing handler found for CallToolRequestSchema");
-
-        this.mcpServer.server.setRequestHandler(CallToolRequestSchema, (request, extra): Promise<CallToolResult> => {
-            if (!request.params.arguments) {
-                request.params.arguments = {};
-            }
-
-            return existingHandler(request, extra);
-        });
-
-        await initializeLogger(this.mcpServer, this.userConfig.logPath);
-
-        await this.mcpServer.connect(transport);
-
-        this.mcpServer.server.oninitialized = () => {
-            this.session.setAgentRunner(this.mcpServer.server.getClientVersion());
-            this.session.sessionId = new ObjectId().toString();
-
-            logger.info(
-                LogId.serverInitialized,
-                "server",
-                `Server started with transport ${transport.constructor.name} and agent runner ${this.session.agentRunner?.name}`
-            );
-
-            this.emitServerEvent("start", Date.now() - this.startTime);
-        };
-
-        this.mcpServer.server.onclose = () => {
-            const closeTime = Date.now();
-            this.emitServerEvent("stop", Date.now() - closeTime);
-        };
-
-        this.mcpServer.server.onerror = (error: Error) => {
-            const closeTime = Date.now();
-            this.emitServerEvent("stop", Date.now() - closeTime, error);
-        };
-
-        await this.validateConfig();
-    }
-
-    async close(): Promise<void> {
-        await this.telemetry.close();
-        await this.session.close();
-        await this.mcpServer.close();
-    }
-
-    /**
-     * Emits a server event
-     * @param command - The server command (e.g., "start", "stop", "register", "deregister")
-     * @param additionalProperties - Additional properties specific to the event
-     */
-    private emitServerEvent(command: ServerCommand, commandDuration: number, error?: Error) {
-        const event: ServerEvent = {
-            timestamp: new Date().toISOString(),
-            source: "mdbmcp",
-            properties: {
-                result: "success",
-                duration_ms: commandDuration,
-                component: "server",
-                category: "other",
-                command: command,
-            },
-        };
-
-        if (command === "start") {
-            event.properties.startup_time_ms = commandDuration;
-            event.properties.read_only_mode = this.userConfig.readOnly || false;
-            event.properties.disabled_tools = this.userConfig.disabledTools || [];
-        }
-        if (command === "stop") {
-            event.properties.runtime_duration_ms = Date.now() - this.startTime;
-            if (error) {
-                event.properties.result = "failure";
-                event.properties.reason = error.message;
-            }
-        }
-
-        this.telemetry.emitEvents([event]).catch(() => {});
-    }
-
-    private registerTools() {
-        for (const tool of [...AtlasTools, ...MongoDbTools]) {
-            new tool(this.session, this.userConfig, this.telemetry).register(this.mcpServer);
-        }
-    }
-
-    private registerResources() {
-        this.mcpServer.resource(
-            "config",
-            "config://config",
-            {
-                description:
-                    "Server configuration, supplied by the user either as environment variables or as startup arguments",
-            },
-            (uri) => {
-                const result = {
-                    telemetry: this.userConfig.telemetry,
-                    logPath: this.userConfig.logPath,
-                    connectionString: this.userConfig.connectionString
-                        ? "set; access to MongoDB tools are currently available to use"
-                        : "not set; before using any MongoDB tool, you need to configure a connection string, alternatively you can setup MongoDB Atlas access, more info at 'https://github.com/mongodb-js/mongodb-mcp-server'.",
-                    connectOptions: this.userConfig.connectOptions,
-                    atlas:
-                        this.userConfig.apiClientId && this.userConfig.apiClientSecret
-                            ? "set; MongoDB Atlas tools are currently available to use"
-                            : "not set; MongoDB Atlas tools are currently unavailable, to have access to MongoDB Atlas tools like creating clusters or connecting to clusters make sure to setup credentials, more info at 'https://github.com/mongodb-js/mongodb-mcp-server'.",
-                };
-                return {
-                    contents: [
-                        {
-                            text: JSON.stringify(result),
-                            mimeType: "application/json",
-                            uri: uri.href,
-                        },
-                    ],
-                };
-            }
-        );
-    }
-
-    private async validateConfig(): Promise<void> {
-        if (this.userConfig.connectionString) {
-            try {
-                await this.session.connectToMongoDB(this.userConfig.connectionString, this.userConfig.connectOptions);
-            } catch (error) {
-                console.error(
-                    "Failed to connect to MongoDB instance using the connection string from the config: ",
-                    error
-                );
-                throw new Error("Failed to connect to MongoDB instance using the connection string from the config");
-            }
-        }
-
-        if (this.userConfig.apiClientId && this.userConfig.apiClientSecret) {
-            try {
-                await this.session.apiClient.validateAccessToken();
-            } catch (error) {
-                if (this.userConfig.connectionString === undefined) {
-                    console.error("Failed to validate MongoDB Atlas the credentials from the config: ", error);
-
-                    throw new Error(
-                        "Failed to connect to MongoDB Atlas instance using the credentials from the config"
-                    );
-                }
-                console.error(
-                    "Failed to validate MongoDB Atlas the credentials from the config, but validated the connection string."
-                );
-            }
-        }
-    }
-}