mongodb-mcp-server 0.2.0 → 0.3.0

package/src/helpers/indexCheck.ts

@@ -1,83 +0,0 @@
-import { Document } from "mongodb";
-import { NodeDriverServiceProvider } from "@mongosh/service-provider-node-driver";
-import { ErrorCodes, MongoDBError } from "../common/errors.js";
-
-/**
- * Check if the query plan uses an index
- * @param explainResult The result of the explain query
- * @returns true if an index is used, false if it's a full collection scan
- */
-export function usesIndex(explainResult: Document): boolean {
-    const queryPlanner = explainResult?.queryPlanner as Document | undefined;
-    const winningPlan = queryPlanner?.winningPlan as Document | undefined;
-    const stage = winningPlan?.stage as string | undefined;
-    const inputStage = winningPlan?.inputStage as Document | undefined;
-
-    // Check for index scan stages (including MongoDB 8.0+ stages)
-    const indexScanStages = [
-        "IXSCAN",
-        "COUNT_SCAN",
-        "EXPRESS_IXSCAN",
-        "EXPRESS_CLUSTERED_IXSCAN",
-        "EXPRESS_UPDATE",
-        "EXPRESS_DELETE",
-        "IDHACK",
-    ];
-
-    if (stage && indexScanStages.includes(stage)) {
-        return true;
-    }
-
-    if (inputStage && inputStage.stage && indexScanStages.includes(inputStage.stage as string)) {
-        return true;
-    }
-
-    // Recursively check deeper stages
-    if (inputStage && inputStage.inputStage) {
-        return usesIndex({ queryPlanner: { winningPlan: inputStage } });
-    }
-
-    if (stage === "COLLSCAN") {
-        return false;
-    }
-
-    // Default to false (conservative approach)
-    return false;
-}
-
-/**
- * Generate an error message for index check failure
- */
-export function getIndexCheckErrorMessage(database: string, collection: string, operation: string): string {
-    return `Index check failed: The ${operation} operation on "${database}.${collection}" performs a collection scan (COLLSCAN) instead of using an index. Consider adding an index for better performance. Use 'explain' tool for query plan analysis or 'collection-indexes' to view existing indexes. To disable this check, set MDB_MCP_INDEX_CHECK to false.`;
-}
-
-/**
- * Generic function to perform index usage check
- */
-export async function checkIndexUsage(
-    provider: NodeDriverServiceProvider,
-    database: string,
-    collection: string,
-    operation: string,
-    explainCallback: () => Promise<Document>
-): Promise<void> {
-    try {
-        const explainResult = await explainCallback();
-
-        if (!usesIndex(explainResult)) {
-            throw new MongoDBError(
-                ErrorCodes.ForbiddenCollscan,
-                getIndexCheckErrorMessage(database, collection, operation)
-            );
-        }
-    } catch (error) {
-        if (error instanceof MongoDBError && error.code === ErrorCodes.ForbiddenCollscan) {
-            throw error;
-        }
-
-        // If explain itself fails, log but do not prevent query execution
-        // This avoids blocking normal queries in special cases (e.g., permission issues)
-        console.warn(`Index check failed to execute explain for ${operation} on ${database}.${collection}:`, error);
-    }
-}

package/src/index.ts

@@ -1,48 +0,0 @@
-#!/usr/bin/env node
-
-import logger, { LogId } from "./common/logger.js";
-import { config } from "./common/config.js";
-import { StdioRunner } from "./transports/stdio.js";
-import { StreamableHttpRunner } from "./transports/streamableHttp.js";
-
-async function main() {
-    const transportRunner = config.transport === "stdio" ? new StdioRunner(config) : new StreamableHttpRunner(config);
-
-    const shutdown = () => {
-        logger.info(LogId.serverCloseRequested, "server", `Server close requested`);
-
-        transportRunner
-            .close()
-            .then(() => {
-                logger.info(LogId.serverClosed, "server", `Server closed`);
-                process.exit(0);
-            })
-            .catch((error: unknown) => {
-                logger.error(LogId.serverCloseFailure, "server", `Error closing server: ${error as string}`);
-                process.exit(1);
-            });
-    };
-
-    process.on("SIGINT", shutdown);
-    process.on("SIGABRT", shutdown);
-    process.on("SIGTERM", shutdown);
-    process.on("SIGQUIT", shutdown);
-
-    try {
-        await transportRunner.start();
-    } catch (error: unknown) {
-        logger.info(LogId.serverCloseRequested, "server", "Closing server");
-        try {
-            await transportRunner.close();
-            logger.info(LogId.serverClosed, "server", "Server closed");
-        } catch (error: unknown) {
-            logger.error(LogId.serverCloseFailure, "server", `Error closing server: ${error as string}`);
-        }
-        throw error;
-    }
-}
-
-main().catch((error: unknown) => {
-    logger.emergency(LogId.serverStartFailure, "server", `Fatal error running server: ${error as string}`);
-    process.exit(1);
-});

package/src/server.ts

@@ -1,250 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { Session } from "./common/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, { LogId, LoggerBase, McpLogger, DiskLogger, ConsoleLogger } from "./common/logger.js";
-import { ObjectId } from "mongodb";
-import { Telemetry } from "./telemetry/telemetry.js";
-import { UserConfig } from "./common/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";
-import { ToolBase } from "./tools/tool.js";
-
-export interface ServerOptions {
-    session: Session;
-    userConfig: UserConfig;
-    mcpServer: McpServer;
-    telemetry: Telemetry;
-}
-
-export class Server {
-    public readonly session: Session;
-    public readonly mcpServer: McpServer;
-    private readonly telemetry: Telemetry;
-    public readonly userConfig: UserConfig;
-    public readonly tools: ToolBase[] = [];
-    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> {
-        await this.validateConfig();
-
-        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);
-        });
-
-        const loggers: LoggerBase[] = [];
-        if (this.userConfig.loggers.includes("mcp")) {
-            loggers.push(new McpLogger(this.mcpServer));
-        }
-        if (this.userConfig.loggers.includes("disk")) {
-            loggers.push(await DiskLogger.fromPath(this.userConfig.logPath));
-        }
-        if (this.userConfig.loggers.includes("stderr")) {
-            loggers.push(new ConsoleLogger());
-        }
-        logger.setLoggers(...loggers);
-
-        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.mcpServer.connect(transport);
-    }
-
-    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 toolConstructor of [...AtlasTools, ...MongoDbTools]) {
-            const tool = new toolConstructor(this.session, this.userConfig, this.telemetry);
-            if (tool.register(this)) {
-                this.tools.push(tool);
-            }
-        }
-    }
-
-    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> {
-        const transport = this.userConfig.transport as string;
-        if (transport !== "http" && transport !== "stdio") {
-            throw new Error(`Invalid transport: ${transport}`);
-        }
-
-        const telemetry = this.userConfig.telemetry as string;
-        if (telemetry !== "enabled" && telemetry !== "disabled") {
-            throw new Error(`Invalid telemetry: ${telemetry}`);
-        }
-
-        if (this.userConfig.httpPort < 1 || this.userConfig.httpPort > 65535) {
-            throw new Error(`Invalid httpPort: ${this.userConfig.httpPort}`);
-        }
-
-        if (this.userConfig.loggers.length === 0) {
-            throw new Error("No loggers found in config");
-        }
-
-        const loggerTypes = new Set(this.userConfig.loggers);
-        if (loggerTypes.size !== this.userConfig.loggers.length) {
-            throw new Error("Duplicate loggers found in config");
-        }
-
-        for (const loggerType of this.userConfig.loggers as string[]) {
-            if (loggerType !== "mcp" && loggerType !== "disk" && loggerType !== "stderr") {
-                throw new Error(`Invalid logger: ${loggerType}`);
-            }
-        }
-
-        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."
-                );
-            }
-        }
-    }
-}

package/src/telemetry/constants.ts

@@ -1,14 +0,0 @@
-import { packageInfo } from "../common/packageInfo.js";
-import { type CommonStaticProperties } from "./types.js";
-
-/**
- * Machine-specific metadata formatted for telemetry
- */
-export const MACHINE_METADATA: CommonStaticProperties = {
-    mcp_server_version: packageInfo.version,
-    mcp_server_name: packageInfo.mcpServerName,
-    platform: process.platform,
-    arch: process.arch,
-    os_type: process.platform,
-    os_version: process.version,
-} as const;

package/src/telemetry/eventCache.ts

@@ -1,62 +0,0 @@
-import { LRUCache } from "lru-cache";
-import { BaseEvent } from "./types.js";
-
-/**
- * Singleton class for in-memory telemetry event caching
- * Provides a central storage for telemetry events that couldn't be sent
- * Uses LRU cache to automatically drop oldest events when limit is exceeded
- */
-export class EventCache {
-    private static instance: EventCache;
-    private static readonly MAX_EVENTS = 1000;
-
-    private cache: LRUCache<number, BaseEvent>;
-    private nextId = 0;
-
-    constructor() {
-        this.cache = new LRUCache({
-            max: EventCache.MAX_EVENTS,
-            // Using FIFO eviction strategy for events
-            allowStale: false,
-            updateAgeOnGet: false,
-        });
-    }
-
-    /**
-     * Gets the singleton instance of EventCache
-     * @returns The EventCache instance
-     */
-    public static getInstance(): EventCache {
-        if (!EventCache.instance) {
-            EventCache.instance = new EventCache();
-        }
-        return EventCache.instance;
-    }
-
-    /**
-     * Gets a copy of the currently cached events
-     * @returns Array of cached BaseEvent objects
-     */
-    public getEvents(): BaseEvent[] {
-        return Array.from(this.cache.values());
-    }
-
-    /**
-     * Appends new events to the cached events
-     * LRU cache automatically handles dropping oldest events when limit is exceeded
-     * @param events - The events to append
-     */
-    public appendEvents(events: BaseEvent[]): void {
-        for (const event of events) {
-            this.cache.set(this.nextId++, event);
-        }
-    }
-
-    /**
-     * Clears all cached events
-     */
-    public clearEvents(): void {
-        this.cache.clear();
-        this.nextId = 0;
-    }
-}

package/src/telemetry/telemetry.ts

@@ -1,202 +0,0 @@
-import { Session } from "../common/session.js";
-import { BaseEvent, CommonProperties } from "./types.js";
-import { UserConfig } from "../common/config.js";
-import logger, { LogId } from "../common/logger.js";
-import { ApiClient } from "../common/atlas/apiClient.js";
-import { MACHINE_METADATA } from "./constants.js";
-import { EventCache } from "./eventCache.js";
-import nodeMachineId from "node-machine-id";
-import { getDeviceId } from "@mongodb-js/device-id";
-import { detectContainerEnv } from "../helpers/container.js";
-
-type EventResult = {
-    success: boolean;
-    error?: Error;
-};
-
-export const DEVICE_ID_TIMEOUT = 3000;
-
-export class Telemetry {
-    private isBufferingEvents: boolean = true;
-    /** Resolves when the setup is complete or a timeout occurs */
-    public setupPromise: Promise<[string, boolean]> | undefined;
-    private deviceIdAbortController = new AbortController();
-    private eventCache: EventCache;
-    private getRawMachineId: () => Promise<string>;
-
-    private constructor(
-        private readonly session: Session,
-        private readonly userConfig: UserConfig,
-        private readonly commonProperties: CommonProperties,
-        { eventCache, getRawMachineId }: { eventCache: EventCache; getRawMachineId: () => Promise<string> }
-    ) {
-        this.eventCache = eventCache;
-        this.getRawMachineId = getRawMachineId;
-    }
-
-    static create(
-        session: Session,
-        userConfig: UserConfig,
-        {
-            commonProperties = { ...MACHINE_METADATA },
-            eventCache = EventCache.getInstance(),
-            getRawMachineId = () => nodeMachineId.machineId(true),
-        }: {
-            eventCache?: EventCache;
-            getRawMachineId?: () => Promise<string>;
-            commonProperties?: CommonProperties;
-        } = {}
-    ): Telemetry {
-        const instance = new Telemetry(session, userConfig, commonProperties, { eventCache, getRawMachineId });
-
-        void instance.setup();
-        return instance;
-    }
-
-    private async setup(): Promise<void> {
-        if (!this.isTelemetryEnabled()) {
-            return;
-        }
-        this.setupPromise = Promise.all([
-            getDeviceId({
-                getMachineId: () => this.getRawMachineId(),
-                onError: (reason, error) => {
-                    switch (reason) {
-                        case "resolutionError":
-                            logger.debug(LogId.telemetryDeviceIdFailure, "telemetry", String(error));
-                            break;
-                        case "timeout":
-                            logger.debug(LogId.telemetryDeviceIdTimeout, "telemetry", "Device ID retrieval timed out");
-                            break;
-                        case "abort":
-                            // No need to log in the case of aborts
-                            break;
-                    }
-                },
-                abortSignal: this.deviceIdAbortController.signal,
-            }),
-            detectContainerEnv(),
-        ]);
-
-        const [deviceId, containerEnv] = await this.setupPromise;
-
-        this.commonProperties.device_id = deviceId;
-        this.commonProperties.is_container_env = containerEnv;
-
-        this.isBufferingEvents = false;
-    }
-
-    public async close(): Promise<void> {
-        this.deviceIdAbortController.abort();
-        this.isBufferingEvents = false;
-        await this.emitEvents(this.eventCache.getEvents());
-    }
-
-    /**
-     * Emits events through the telemetry pipeline
-     * @param events - The events to emit
-     */
-    public async emitEvents(events: BaseEvent[]): Promise<void> {
-        try {
-            if (!this.isTelemetryEnabled()) {
-                logger.info(LogId.telemetryEmitFailure, "telemetry", `Telemetry is disabled.`);
-                return;
-            }
-
-            await this.emit(events);
-        } catch {
-            logger.debug(LogId.telemetryEmitFailure, "telemetry", `Error emitting telemetry events.`);
-        }
-    }
-
-    /**
-     * Gets the common properties for events
-     * @returns Object containing common properties for all events
-     */
-    public getCommonProperties(): CommonProperties {
-        return {
-            ...this.commonProperties,
-            transport: this.userConfig.transport,
-            mcp_client_version: this.session.agentRunner?.version,
-            mcp_client_name: this.session.agentRunner?.name,
-            session_id: this.session.sessionId,
-            config_atlas_auth: this.session.apiClient.hasCredentials() ? "true" : "false",
-            config_connection_string: this.userConfig.connectionString ? "true" : "false",
-        };
-    }
-
-    /**
-     * Checks if telemetry is currently enabled
-     * This is a method rather than a constant to capture runtime config changes
-     *
-     * Follows the Console Do Not Track standard (https://consoledonottrack.com/)
-     * by respecting the DO_NOT_TRACK environment variable
-     */
-    public isTelemetryEnabled(): boolean {
-        // Check if telemetry is explicitly disabled in config
-        if (this.userConfig.telemetry === "disabled") {
-            return false;
-        }
-
-        const doNotTrack = "DO_NOT_TRACK" in process.env;
-        return !doNotTrack;
-    }
-
-    /**
-     * Attempts to emit events through authenticated and unauthenticated clients
-     * Falls back to caching if both attempts fail
-     */
-    private async emit(events: BaseEvent[]): Promise<void> {
-        if (this.isBufferingEvents) {
-            this.eventCache.appendEvents(events);
-            return;
-        }
-
-        const cachedEvents = this.eventCache.getEvents();
-        const allEvents = [...cachedEvents, ...events];
-
-        logger.debug(
-            LogId.telemetryEmitStart,
-            "telemetry",
-            `Attempting to send ${allEvents.length} events (${cachedEvents.length} cached)`
-        );
-
-        const result = await this.sendEvents(this.session.apiClient, allEvents);
-        if (result.success) {
-            this.eventCache.clearEvents();
-            logger.debug(
-                LogId.telemetryEmitSuccess,
-                "telemetry",
-                `Sent ${allEvents.length} events successfully: ${JSON.stringify(allEvents, null, 2)}`
-            );
-            return;
-        }
-
-        logger.debug(
-            LogId.telemetryEmitFailure,
-            "telemetry",
-            `Error sending event to client: ${result.error instanceof Error ? result.error.message : String(result.error)}`
-        );
-        this.eventCache.appendEvents(events);
-    }
-
-    /**
-     * Attempts to send events through the provided API client
-     */
-    private async sendEvents(client: ApiClient, events: BaseEvent[]): Promise<EventResult> {
-        try {
-            await client.sendEvents(
-                events.map((event) => ({
-                    ...event,
-                    properties: { ...this.getCommonProperties(), ...event.properties },
-                }))
-            );
-            return { success: true };
-        } catch (error) {
-            return {
-                success: false,
-                error: error instanceof Error ? error : new Error(String(error)),
-            };
-        }
-    }
-}