mongodb-mcp-server 0.0.4 → 0.0.5

package/src/session.ts

@@ -1,26 +1,43 @@
 import { NodeDriverServiceProvider } from "@mongosh/service-provider-node-driver";
-import { ApiClient } from "./common/atlas/apiClient.js";
-import config from "./config.js";
+import { ApiClient, ApiClientCredentials } from "./common/atlas/apiClient.js";
+import { Implementation } from "@modelcontextprotocol/sdk/types.js";
+
+export interface SessionOptions {
+    apiBaseUrl?: string;
+    apiClientId?: string;
+    apiClientSecret?: string;
+}
 
 export class Session {
+    sessionId?: string;
     serviceProvider?: NodeDriverServiceProvider;
-    apiClient?: ApiClient;
+    apiClient: ApiClient;
+    agentRunner?: {
+        name: string;
+        version: string;
+    };
 
-    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."
-                );
-            }
+    constructor({ apiBaseUrl, apiClientId, apiClientSecret }: SessionOptions = {}) {
+        const credentials: ApiClientCredentials | undefined =
+            apiClientId && apiClientSecret
+                ? {
+                      clientId: apiClientId,
+                      clientSecret: apiClientSecret,
+                  }
+                : undefined;
+
+        this.apiClient = new ApiClient({
+            baseUrl: apiBaseUrl,
+            credentials,
+        });
+    }
 
-            this.apiClient = new ApiClient({
-                baseUrl: config.apiBaseUrl,
-                credentials: {
-                    clientId: config.apiClientId,
-                    clientSecret: config.apiClientSecret,
-                },
-            });
+    setAgentRunner(agentRunner: Implementation | undefined) {
+        if (agentRunner?.name && agentRunner?.version) {
+            this.agentRunner = {
+                name: agentRunner.name,
+                version: agentRunner.version,
+            };
         }
     }
 

package/src/telemetry/constants.ts

@@ -0,0 +1,15 @@
+import { getMachineIdSync } from "native-machine-id";
+import { packageInfo } from "../packageInfo.js";
+
+/**
+ * Machine-specific metadata formatted for telemetry
+ */
+export const MACHINE_METADATA = {
+    device_id: getMachineIdSync(),
+    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

@@ -0,0 +1,62 @@
+import { BaseEvent } from "./types.js";
+import { LRUCache } from "lru-cache";
+
+/**
+ * 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;
+
+    private 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

@@ -0,0 +1,137 @@
+import { Session } from "../session.js";
+import { BaseEvent } from "./types.js";
+import { config } from "../config.js";
+import logger from "../logger.js";
+import { mongoLogId } from "mongodb-log-writer";
+import { ApiClient } from "../common/atlas/apiClient.js";
+import { MACHINE_METADATA } from "./constants.js";
+import { EventCache } from "./eventCache.js";
+
+type EventResult = {
+    success: boolean;
+    error?: Error;
+};
+
+type CommonProperties = {
+    device_id?: string;
+    mcp_server_version: string;
+    mcp_server_name: string;
+    mcp_client_version?: string;
+    mcp_client_name?: string;
+    platform: string;
+    arch: string;
+    os_type: string;
+    os_version?: string;
+    session_id?: string;
+};
+
+export class Telemetry {
+    private readonly commonProperties: CommonProperties;
+
+    constructor(
+        private readonly session: Session,
+        private readonly eventCache: EventCache = EventCache.getInstance()
+    ) {
+        this.commonProperties = {
+            ...MACHINE_METADATA,
+        };
+    }
+
+    /**
+     * 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
+     */
+    private static isTelemetryEnabled(): boolean {
+        // Check if telemetry is explicitly disabled in config
+        if (config.telemetry === "disabled") {
+            return false;
+        }
+
+        const doNotTrack = process.env.DO_NOT_TRACK;
+        if (doNotTrack) {
+            const value = doNotTrack.toLowerCase();
+            // Telemetry should be disabled if DO_NOT_TRACK is "1", "true", or "yes"
+            if (value === "1" || value === "true" || value === "yes") {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Emits events through the telemetry pipeline
+     * @param events - The events to emit
+     */
+    public async emitEvents(events: BaseEvent[]): Promise<void> {
+        try {
+            if (!Telemetry.isTelemetryEnabled()) {
+                return;
+            }
+
+            await this.emit(events);
+        } catch {
+            logger.debug(mongoLogId(1_000_002), "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,
+            mcp_client_version: this.session.agentRunner?.version,
+            mcp_client_name: this.session.agentRunner?.name,
+            session_id: this.session.sessionId,
+        };
+    }
+
+    /**
+     * Attempts to emit events through authenticated and unauthenticated clients
+     * Falls back to caching if both attempts fail
+     */
+    private async emit(events: BaseEvent[]): Promise<void> {
+        const cachedEvents = this.eventCache.getEvents();
+        const allEvents = [...cachedEvents, ...events];
+
+        logger.debug(
+            mongoLogId(1_000_003),
+            "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(mongoLogId(1_000_004), "telemetry", `Sent ${allEvents.length} events successfully`);
+            return;
+        }
+
+        logger.warning(
+            mongoLogId(1_000_005),
+            "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);
+            return { success: true };
+        } catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+        }
+    }
+}

package/src/telemetry/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Result type constants for telemetry events
+ */
+export type TelemetryResult = "success" | "failure";
+export type ServerCommand = "start" | "stop";
+
+/**
+ * Base interface for all events
+ */
+export interface Event {
+    timestamp: string;
+    source: "mdbmcp";
+    properties: Record<string, unknown>;
+}
+
+export interface BaseEvent extends Event {
+    properties: {
+        device_id?: string;
+        mcp_server_version: string;
+        mcp_server_name: string;
+        mcp_client_version?: string;
+        mcp_client_name?: string;
+        platform: string;
+        arch: string;
+        os_type: string;
+        component: string;
+        duration_ms: number;
+        result: TelemetryResult;
+        category: string;
+        os_version?: string;
+        session_id?: string;
+    } & Event["properties"];
+}
+
+/**
+ * Interface for tool events
+ */
+export interface ToolEvent extends BaseEvent {
+    properties: {
+        command: string;
+        error_code?: string;
+        error_type?: string;
+        project_id?: string;
+        org_id?: string;
+        cluster_name?: string;
+        is_atlas?: boolean;
+    } & BaseEvent["properties"];
+}
+
+/**
+ * Interface for server events
+ */
+export interface ServerEvent extends BaseEvent {
+    properties: {
+        command: ServerCommand;
+        reason?: string;
+        startup_time_ms?: number;
+        runtime_duration_ms?: number;
+    } & BaseEvent["properties"];
+}

package/src/tools/atlas/atlasTool.ts

@@ -1,10 +1,12 @@
 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";
+
+    protected verifyAllowed(): boolean {
+        if (!this.config.apiClientId || !this.config.apiClientSecret) {
+            return false;
+        }
+        return super.verifyAllowed();
+    }
 }

package/src/tools/atlas/createAccessList.ts

@@ -27,8 +27,6 @@ export class CreateAccessListTool extends AtlasToolBase {
         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.");
         }

package/src/tools/atlas/createDBUser.ts

@@ -34,8 +34,6 @@ export class CreateDBUserTool extends AtlasToolBase {
         roles,
         clusters,
     }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        this.session.ensureAuthenticated();
-
         const input = {
             groupId: projectId,
             awsIAMType: "NONE",

package/src/tools/atlas/createFreeCluster.ts

@@ -15,8 +15,6 @@ export class CreateFreeClusterTool extends AtlasToolBase {
     };
 
     protected async execute({ projectId, name, region }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        this.session.ensureAuthenticated();
-
         const input = {
             groupId: projectId,
             name,

package/src/tools/atlas/createProject.ts

@@ -14,7 +14,6 @@ export class CreateProjectTool extends AtlasToolBase {
     };
 
     protected async execute({ projectName, organizationId }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        this.session.ensureAuthenticated();
         let assumedOrg = false;
 
         if (!projectName) {

package/src/tools/atlas/inspectAccessList.ts

@@ -12,8 +12,6 @@ export class InspectAccessListTool extends AtlasToolBase {
     };
 
     protected async execute({ projectId }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        this.session.ensureAuthenticated();
-
         const accessList = await this.session.apiClient.listProjectIpAccessLists({
             params: {
                 path: {

package/src/tools/atlas/inspectCluster.ts

@@ -14,8 +14,6 @@ export class InspectClusterTool extends AtlasToolBase {
     };
 
     protected async execute({ projectId, clusterName }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        this.session.ensureAuthenticated();
-
         const cluster = await this.session.apiClient.getCluster({
             params: {
                 path: {

package/src/tools/atlas/listClusters.ts

@@ -13,8 +13,6 @@ export class ListClustersTool extends AtlasToolBase {
     };
 
     protected async execute({ projectId }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        this.session.ensureAuthenticated();
-
         if (!projectId) {
             const data = await this.session.apiClient.listClustersForAllProjects();
 

package/src/tools/atlas/listDBUsers.ts

@@ -13,8 +13,6 @@ export class ListDBUsersTool extends AtlasToolBase {
     };
 
     protected async execute({ projectId }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        this.session.ensureAuthenticated();
-
         const data = await this.session.apiClient.listDatabaseUsers({
             params: {
                 path: {

package/src/tools/atlas/listOrgs.ts

@@ -9,8 +9,6 @@ export class ListOrganizationsTool extends AtlasToolBase {
     protected argsShape = {};
 
     protected async execute(): Promise<CallToolResult> {
-        this.session.ensureAuthenticated();
-
         const data = await this.session.apiClient.listOrganizations();
 
         if (!data?.results?.length) {

package/src/tools/atlas/listProjects.ts

@@ -13,7 +13,15 @@ export class ListProjectsTool extends AtlasToolBase {
     };
 
     protected async execute({ orgId }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
-        this.session.ensureAuthenticated();
+        const orgData = await this.session.apiClient.listOrganizations();
+
+        if (!orgData?.results?.length) {
+            throw new Error("No organizations found in your MongoDB Atlas account.");
+        }
+
+        const orgs: Record<string, string> = orgData.results
+            .map((org) => [org.id || "", org.name])
+            .reduce((acc, [id, name]) => ({ ...acc, [id]: name }), {});
 
         const data = orgId
             ? await this.session.apiClient.listOrganizationProjects({
@@ -33,11 +41,11 @@ export class ListProjectsTool extends AtlasToolBase {
         const rows = data.results
             .map((project) => {
                 const createdAt = project.created ? new Date(project.created).toLocaleString() : "N/A";
-                return `${project.name} | ${project.id} | ${createdAt}`;
+                return `${project.name} | ${project.id} | ${orgs[project.orgId]} | ${project.orgId} | ${createdAt}`;
             })
             .join("\n");
-        const formattedProjects = `Project Name | Project ID | Created At
-----------------| ----------------| ----------------
+        const formattedProjects = `Project Name | Project ID | Organization Name | Organization ID | Created At
+----------------| ----------------| ----------------| ----------------| ----------------
 ${rows}`;
         return {
             content: [{ type: "text", text: formattedProjects }],

package/src/tools/mongodb/metadata/collectionSchema.ts

@@ -1,7 +1,7 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
 import { ToolArgs, OperationType } from "../../tool.js";
-import { parseSchema, SchemaField } from "mongodb-schema";
+import { getSimplifiedSchema } from "mongodb-schema";
 
 export class CollectionSchemaTool extends MongoDBToolBase {
     protected name = "collection-schema";
@@ -13,29 +13,31 @@ export class CollectionSchemaTool extends MongoDBToolBase {
     protected async execute({ database, collection }: ToolArgs<typeof DbOperationArgs>): Promise<CallToolResult> {
         const provider = await this.ensureConnected();
         const documents = await provider.find(database, collection, {}, { limit: 5 }).toArray();
-        const schema = await parseSchema(documents);
+        const schema = await getSimplifiedSchema(documents);
+
+        const fieldsCount = Object.entries(schema).length;
+        if (fieldsCount === 0) {
+            return {
+                content: [
+                    {
+                        text: `Could not deduce the schema for "${database}.${collection}". This may be because it doesn't exist or is empty.`,
+                        type: "text",
+                    },
+                ],
+            };
+        }
 
         return {
             content: [
                 {
-                    text: `Found ${schema.fields.length} fields in the schema for \`${database}.${collection}\``,
+                    text: `Found ${fieldsCount} fields in the schema for "${database}.${collection}"`,
                     type: "text",
                 },
                 {
-                    text: this.formatFieldOutput(schema.fields),
+                    text: JSON.stringify(schema),
                     type: "text",
                 },
             ],
         };
     }
-
-    private formatFieldOutput(fields: SchemaField[]): string {
-        let result = "| Field | Type | Confidence |\n";
-        result += "|-------|------|-------------|\n";
-        for (const field of fields) {
-            const fieldType = Array.isArray(field.type) ? field.type.join(", ") : field.type;
-            result += `| ${field.name} | \`${fieldType}\` | ${(field.probability * 100).toFixed(0)}% |\n`;
-        }
-        return result;
-    }
 }

package/src/tools/mongodb/metadata/collectionStorageSize.ts

@@ -4,7 +4,7 @@ import { ToolArgs, OperationType } from "../../tool.js";
 
 export class CollectionStorageSizeTool extends MongoDBToolBase {
     protected name = "collection-storage-size";
-    protected description = "Gets the size of the collection in MB";
+    protected description = "Gets the size of the collection";
     protected argsShape = DbOperationArgs;
 
     protected operationType: OperationType = "metadata";
@@ -14,17 +14,55 @@ export class CollectionStorageSizeTool extends MongoDBToolBase {
         const [{ value }] = (await provider
             .aggregate(database, collection, [
                 { $collStats: { storageStats: {} } },
-                { $group: { _id: null, value: { $sum: "$storageStats.storageSize" } } },
+                { $group: { _id: null, value: { $sum: "$storageStats.size" } } },
             ])
             .toArray()) as [{ value: number }];
 
+        const { units, value: scaledValue } = CollectionStorageSizeTool.getStats(value);
+
         return {
             content: [
                 {
-                    text: `The size of \`${database}.${collection}\` is \`${(value / 1024 / 1024).toFixed(2)} MB\``,
+                    text: `The size of "${database}.${collection}" is \`${scaledValue.toFixed(2)} ${units}\``,
                     type: "text",
                 },
             ],
         };
     }
+
+    protected handleError(
+        error: unknown,
+        args: ToolArgs<typeof this.argsShape>
+    ): Promise<CallToolResult> | CallToolResult {
+        if (error instanceof Error && "codeName" in error && error.codeName === "NamespaceNotFound") {
+            return {
+                content: [
+                    {
+                        text: `The size of "${args.database}.${args.collection}" cannot be determined because the collection does not exist.`,
+                        type: "text",
+                    },
+                ],
+            };
+        }
+
+        return super.handleError(error, args);
+    }
+
+    private static getStats(value: number): { value: number; units: string } {
+        const kb = 1024;
+        const mb = kb * 1024;
+        const gb = mb * 1024;
+
+        if (value > gb) {
+            return { value: value / gb, units: "GB" };
+        }
+
+        if (value > mb) {
+            return { value: value / mb, units: "MB" };
+        }
+        if (value > kb) {
+            return { value: value / kb, units: "KB" };
+        }
+        return { value, units: "bytes" };
+    }
 }

package/src/tools/mongodb/metadata/connect.ts

@@ -2,7 +2,6 @@ import { z } from "zod";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { MongoDBToolBase } from "../mongodbTool.js";
 import { ToolArgs, OperationType } from "../../tool.js";
-import config from "../../../config.js";
 import { MongoError as DriverError } from "mongodb";
 
 export class ConnectTool extends MongoDBToolBase {
@@ -35,7 +34,7 @@ export class ConnectTool extends MongoDBToolBase {
     protected async execute({ options: optionsArr }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
         const options = optionsArr?.[0];
         let connectionString: string;
-        if (!options && !config.connectionString) {
+        if (!options && !this.config.connectionString) {
             return {
                 content: [
                     { type: "text", text: "No connection details provided." },
@@ -46,7 +45,7 @@ export class ConnectTool extends MongoDBToolBase {
 
         if (!options) {
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            connectionString = config.connectionString!;
+            connectionString = this.config.connectionString!;
         } else if ("connectionString" in options) {
             connectionString = options.connectionString;
         } else {
@@ -72,9 +71,9 @@ export class ConnectTool extends MongoDBToolBase {
             // Sometimes the model will supply an incorrect connection string. If the user has configured
             // a different one as environment variable or a cli argument, suggest using that one instead.
             if (
-                config.connectionString &&
+                this.config.connectionString &&
                 error instanceof DriverError &&
-                config.connectionString !== connectionString
+                this.config.connectionString !== connectionString
             ) {
                 return {
                     content: [
@@ -82,7 +81,7 @@ export class ConnectTool extends MongoDBToolBase {
                             type: "text",
                             text:
                                 `Failed to connect to MongoDB at '${connectionString}' due to error: '${error.message}.` +
-                                `Your config lists a different connection string: '${config.connectionString}' - do you want to try connecting to it instead?`,
+                                `Your config lists a different connection string: '${this.config.connectionString}' - do you want to try connecting to it instead?`,
                         },
                     ],
                 };

package/src/tools/mongodb/metadata/dbStats.ts

@@ -1,6 +1,7 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
 import { ToolArgs, OperationType } from "../../tool.js";
+import { EJSON } from "bson";
 
 export class DbStatsTool extends MongoDBToolBase {
     protected name = "db-stats";
@@ -21,7 +22,11 @@ export class DbStatsTool extends MongoDBToolBase {
         return {
             content: [
                 {
-                    text: `Statistics for database ${database}: ${JSON.stringify(result)}`,
+                    text: `Statistics for database ${database}`,
+                    type: "text",
+                },
+                {
+                    text: EJSON.stringify(result),
                     type: "text",
                 },
             ],