mongodb-mcp-server 0.1.1 → 0.1.2

package/src/index.ts

@@ -31,6 +31,26 @@ try {
 
     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}`);

package/src/logger.ts

@@ -9,6 +9,9 @@ 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),
@@ -22,6 +25,7 @@ export const LogId = {
     telemetryMetadataError: mongoLogId(1_002_005),
     telemetryDeviceIdFailure: mongoLogId(1_002_006),
     telemetryDeviceIdTimeout: mongoLogId(1_002_007),
+    telemetryContainerEnvFailure: mongoLogId(1_002_008),
 
     toolExecute: mongoLogId(1_003_001),
     toolExecuteFailure: mongoLogId(1_003_002),
@@ -29,6 +33,8 @@ export const LogId = {
 
     mongodbConnectFailure: mongoLogId(1_004_001),
     mongodbDisconnectFailure: mongoLogId(1_004_002),
+
+    toolUpdateFailure: mongoLogId(1_005_001),
 } as const;
 
 abstract class LoggerBase {

package/src/server.ts

@@ -130,7 +130,7 @@ export class Server {
             }
         }
 
-        this.telemetry.emitEvents([event]).catch(() => {});
+        this.telemetry.emitEvents([event]);
     }
 
     private registerTools() {

package/src/telemetry/telemetry.ts

@@ -7,114 +7,152 @@ 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 fs from "fs/promises";
+
+async function fileExists(filePath: string): Promise<boolean> {
+    try {
+        await fs.access(filePath, fs.constants.F_OK);
+        return true; // File exists
+    } catch (e: unknown) {
+        if (
+            e instanceof Error &&
+            (
+                e as Error & {
+                    code: string;
+                }
+            ).code === "ENOENT"
+        ) {
+            return false; // File does not exist
+        }
+        throw e; // Re-throw unexpected errors
+    }
+}
 
-type EventResult = {
-    success: boolean;
-    error?: Error;
-};
+async function isContainerized(): Promise<boolean> {
+    if (process.env.container) {
+        return true;
+    }
+
+    const exists = await Promise.all(["/.dockerenv", "/run/.containerenv", "/var/run/.containerenv"].map(fileExists));
 
-export const DEVICE_ID_TIMEOUT = 3000;
+    return exists.includes(true);
+}
 
 export class Telemetry {
-    private isBufferingEvents: boolean = true;
-    /** Resolves when the device ID is retrieved or timeout occurs */
-    public deviceIdPromise: Promise<string> | undefined;
     private deviceIdAbortController = new AbortController();
     private eventCache: EventCache;
     private getRawMachineId: () => Promise<string>;
+    private getContainerEnv: () => Promise<boolean>;
+    private cachedCommonProperties?: CommonProperties;
+    private flushing: boolean = false;
 
     private constructor(
         private readonly session: Session,
         private readonly userConfig: UserConfig,
-        private readonly commonProperties: CommonProperties,
-        { eventCache, getRawMachineId }: { eventCache: EventCache; getRawMachineId: () => Promise<string> }
+        {
+            eventCache,
+            getRawMachineId,
+            getContainerEnv,
+        }: {
+            eventCache: EventCache;
+            getRawMachineId: () => Promise<string>;
+            getContainerEnv: () => Promise<boolean>;
+        }
     ) {
         this.eventCache = eventCache;
         this.getRawMachineId = getRawMachineId;
+        this.getContainerEnv = getContainerEnv;
     }
 
     static create(
         session: Session,
         userConfig: UserConfig,
         {
-            commonProperties = { ...MACHINE_METADATA },
             eventCache = EventCache.getInstance(),
             getRawMachineId = () => nodeMachineId.machineId(true),
+            getContainerEnv = isContainerized,
         }: {
             eventCache?: EventCache;
             getRawMachineId?: () => Promise<string>;
-            commonProperties?: CommonProperties;
+            getContainerEnv?: () => Promise<boolean>;
         } = {}
     ): Telemetry {
-        const instance = new Telemetry(session, userConfig, commonProperties, { eventCache, getRawMachineId });
-
-        void instance.start();
-        return instance;
-    }
-
-    private async start(): Promise<void> {
-        if (!this.isTelemetryEnabled()) {
-            return;
-        }
-        this.deviceIdPromise = 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,
+        const instance = new Telemetry(session, userConfig, {
+            eventCache,
+            getRawMachineId,
+            getContainerEnv,
         });
 
-        this.commonProperties.device_id = await this.deviceIdPromise;
-
-        this.isBufferingEvents = false;
+        return instance;
     }
 
     public async close(): Promise<void> {
         this.deviceIdAbortController.abort();
-        this.isBufferingEvents = false;
-        await this.emitEvents(this.eventCache.getEvents());
+        await this.flush();
     }
 
     /**
      * 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.`);
-        }
+    public emitEvents(events: BaseEvent[]): void {
+        void this.flush(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,
-            config_atlas_auth: this.session.apiClient.hasCredentials() ? "true" : "false",
-            config_connection_string: this.userConfig.connectionString ? "true" : "false",
-        };
+    private async getCommonProperties(): Promise<CommonProperties> {
+        if (!this.cachedCommonProperties) {
+            let deviceId: string | undefined;
+            let containerEnv: boolean | undefined;
+            try {
+                await 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,
+                    }).then((id) => {
+                        deviceId = id;
+                    }),
+                    this.getContainerEnv().then((env) => {
+                        containerEnv = env;
+                    }),
+                ]);
+            } catch (error: unknown) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                logger.debug(LogId.telemetryDeviceIdFailure, "telemetry", err.message);
+            }
+            this.cachedCommonProperties = {
+                ...MACHINE_METADATA,
+                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",
+                is_container_env: containerEnv ? "true" : "false",
+                device_id: deviceId,
+            };
+        }
+
+        return this.cachedCommonProperties;
     }
 
     /**
@@ -135,60 +173,74 @@ export class Telemetry {
     }
 
     /**
-     * Attempts to emit events through authenticated and unauthenticated clients
+     * Attempts to flush 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);
+    public async flush(events?: BaseEvent[]): Promise<void> {
+        if (!this.isTelemetryEnabled()) {
+            logger.info(LogId.telemetryEmitFailure, "telemetry", `Telemetry is disabled.`);
             return;
         }
 
-        const cachedEvents = this.eventCache.getEvents();
-        const allEvents = [...cachedEvents, ...events];
+        if (this.flushing) {
+            this.eventCache.appendEvents(events ?? []);
+            process.nextTick(async () => {
+                // try again if in the middle of a flush
+                await this.flush();
+            });
+            return;
+        }
 
-        logger.debug(
-            LogId.telemetryEmitStart,
-            "telemetry",
-            `Attempting to send ${allEvents.length} events (${cachedEvents.length} cached)`
-        );
+        this.flushing = true;
 
-        const result = await this.sendEvents(this.session.apiClient, allEvents);
-        if (result.success) {
+        try {
+            const cachedEvents = this.eventCache.getEvents();
+            const allEvents = [...cachedEvents, ...(events ?? [])];
+            if (allEvents.length <= 0) {
+                this.flushing = false;
+                return;
+            }
+
+            logger.debug(
+                LogId.telemetryEmitStart,
+                "telemetry",
+                `Attempting to send ${allEvents.length} events (${cachedEvents.length} cached)`
+            );
+
+            await this.sendEvents(this.session.apiClient, allEvents);
             this.eventCache.clearEvents();
             logger.debug(
                 LogId.telemetryEmitSuccess,
                 "telemetry",
                 `Sent ${allEvents.length} events successfully: ${JSON.stringify(allEvents, null, 2)}`
             );
-            return;
+        } catch (error: unknown) {
+            logger.debug(
+                LogId.telemetryEmitFailure,
+                "telemetry",
+                `Error sending event to client: ${error instanceof Error ? error.message : String(error)}`
+            );
+            this.eventCache.appendEvents(events ?? []);
+            process.nextTick(async () => {
+                // try again
+                await this.flush();
+            });
         }
 
-        logger.debug(
-            LogId.telemetryEmitFailure,
-            "telemetry",
-            `Error sending event to client: ${result.error instanceof Error ? result.error.message : String(result.error)}`
-        );
-        this.eventCache.appendEvents(events);
+        this.flushing = false;
     }
 
     /**
      * 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)),
-            };
-        }
+    private async sendEvents(client: ApiClient, events: BaseEvent[]): Promise<void> {
+        const commonProperties = await this.getCommonProperties();
+
+        await client.sendEvents(
+            events.map((event) => ({
+                ...event,
+                properties: { ...commonProperties, ...event.properties },
+            }))
+        );
     }
 }

package/src/telemetry/types.ts

@@ -71,4 +71,5 @@ export type CommonProperties = {
     config_atlas_auth?: TelemetryBoolSet;
     config_connection_string?: TelemetryBoolSet;
     session_id?: string;
+    is_container_env?: TelemetryBoolSet;
 } & CommonStaticProperties;

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

@@ -28,7 +28,13 @@ export class CreateProjectTool extends AtlasToolBase {
                         "No organizations were found in your MongoDB Atlas account. Please create an organization first."
                     );
                 }
-                organizationId = organizations.results[0].id;
+                const firstOrg = organizations.results[0];
+                if (!firstOrg?.id) {
+                    throw new Error(
+                        "The first organization found does not have an ID. Please check your Atlas account."
+                    );
+                }
+                organizationId = firstOrg.id;
                 assumedOrg = true;
             } catch {
                 throw new Error(

package/src/tools/atlas/read/listAlerts.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { AtlasToolBase } from "../atlasTool.js";
+import { ToolArgs, OperationType } from "../../tool.js";
+
+export class ListAlertsTool extends AtlasToolBase {
+    protected name = "atlas-list-alerts";
+    protected description = "List MongoDB Atlas alerts";
+    protected operationType: OperationType = "read";
+    protected argsShape = {
+        projectId: z.string().describe("Atlas project ID to list alerts for"),
+    };
+
+    protected async execute({ projectId }: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
+        const data = await this.session.apiClient.listAlerts({
+            params: {
+                path: {
+                    groupId: projectId,
+                },
+            },
+        });
+
+        if (!data?.results?.length) {
+            return { content: [{ type: "text", text: "No alerts found in your MongoDB Atlas project." }] };
+        }
+
+        // Format alerts as a table
+        const output =
+            `Alert ID | Status | Created | Updated | Type | Comment
+----------|---------|----------|----------|------|--------
+` +
+            data.results
+                .map((alert) => {
+                    const created = alert.created ? new Date(alert.created).toLocaleString() : "N/A";
+                    const updated = alert.updated ? new Date(alert.updated).toLocaleString() : "N/A";
+                    const comment = alert.acknowledgementComment ?? "N/A";
+                    return `${alert.id} | ${alert.status} | ${created} | ${updated} | ${alert.eventTypeName} | ${comment}`;
+                })
+                .join("\n");
+
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    }
+}

package/src/tools/atlas/read/listProjects.ts

@@ -21,7 +21,8 @@ export class ListProjectsTool extends AtlasToolBase {
 
         const orgs: Record<string, string> = orgData.results
             .map((org) => [org.id || "", org.name])
-            .reduce((acc, [id, name]) => ({ ...acc, [id]: name }), {});
+            .filter(([id]) => id)
+            .reduce((acc, [id, name]) => ({ ...acc, [id as string]: name }), {});
 
         const data = orgId
             ? await this.session.apiClient.listOrganizationProjects({
@@ -41,7 +42,8 @@ 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} | ${orgs[project.orgId]} | ${project.orgId} | ${createdAt}`;
+                const orgName = orgs[project.orgId] ?? "N/A";
+                return `${project.name} | ${project.id} | ${orgName} | ${project.orgId} | ${createdAt}`;
             })
             .join("\n");
         const formattedProjects = `Project Name | Project ID | Organization Name | Organization ID | Created At

package/src/tools/atlas/tools.ts

@@ -9,6 +9,7 @@ import { CreateDBUserTool } from "./create/createDBUser.js";
 import { CreateProjectTool } from "./create/createProject.js";
 import { ListOrganizationsTool } from "./read/listOrgs.js";
 import { ConnectClusterTool } from "./metadata/connectCluster.js";
+import { ListAlertsTool } from "./read/listAlerts.js";
 
 export const AtlasTools = [
     ListClustersTool,
@@ -22,4 +23,5 @@ export const AtlasTools = [
     CreateProjectTool,
     ListOrganizationsTool,
     ConnectClusterTool,
+    ListAlertsTool,
 ];

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

@@ -7,7 +7,6 @@ export class ListDatabasesTool extends MongoDBToolBase {
     protected name = "list-databases";
     protected description = "List all databases for a MongoDB connection";
     protected argsShape = {};
-
     protected operationType: OperationType = "metadata";
 
     protected async execute(): Promise<CallToolResult> {

package/src/tools/mongodb/read/count.ts

@@ -8,13 +8,14 @@ export const CountArgs = {
         .record(z.string(), z.unknown())
         .optional()
         .describe(
-            "The query filter to count documents. Matches the syntax of the filter argument of db.collection.count()"
+            "A filter/query parameter. Allows users to filter the documents to count. Matches the syntax of the filter argument of db.collection.count()."
         ),
 };
 
 export class CountTool extends MongoDBToolBase {
     protected name = "count";
-    protected description = "Gets the number of documents in a MongoDB collection";
+    protected description =
+        "Gets the number of documents in a MongoDB collection using db.collection.count() and query as an optional filter parameter";
     protected argsShape = {
         ...DbOperationArgs,
         ...CountArgs,

package/src/tools/tool.ts

@@ -1,6 +1,6 @@
 import { z, type ZodRawShape, type ZodNever, AnyZodObject } from "zod";
 import type { McpServer, RegisteredTool, ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { Session } from "../session.js";
 import logger, { LogId } from "../logger.js";
 import { Telemetry } from "../telemetry/telemetry.js";
@@ -27,6 +27,34 @@ export abstract class ToolBase {
 
     protected abstract argsShape: ZodRawShape;
 
+    protected get annotations(): ToolAnnotations {
+        const annotations: ToolAnnotations = {
+            title: this.name,
+            description: this.description,
+        };
+
+        switch (this.operationType) {
+            case "read":
+            case "metadata":
+                annotations.readOnlyHint = true;
+                annotations.destructiveHint = false;
+                break;
+            case "delete":
+                annotations.readOnlyHint = false;
+                annotations.destructiveHint = true;
+                break;
+            case "create":
+            case "update":
+                annotations.destructiveHint = false;
+                annotations.readOnlyHint = false;
+                break;
+            default:
+                break;
+        }
+
+        return annotations;
+    }
+
     protected abstract execute(...args: Parameters<ToolCallback<typeof this.argsShape>>): Promise<CallToolResult>;
 
     constructor(
@@ -43,20 +71,20 @@ export abstract class ToolBase {
         const callback: ToolCallback<typeof this.argsShape> = async (...args) => {
             const startTime = Date.now();
             try {
-                logger.debug(LogId.toolExecute, "tool", `Executing ${this.name} with args: ${JSON.stringify(args)}`);
+                logger.debug(LogId.toolExecute, "tool", `Executing tool ${this.name}`);
 
                 const result = await this.execute(...args);
-                await this.emitToolEvent(startTime, result, ...args).catch(() => {});
+                this.emitToolEvent(startTime, result, ...args);
                 return result;
             } catch (error: unknown) {
                 logger.error(LogId.toolExecuteFailure, "tool", `Error executing ${this.name}: ${error as string}`);
                 const toolResult = await this.handleError(error, args[0] as ToolArgs<typeof this.argsShape>);
-                await this.emitToolEvent(startTime, toolResult, ...args).catch(() => {});
+                this.emitToolEvent(startTime, toolResult, ...args);
                 return toolResult;
             }
         };
 
-        server.tool(this.name, this.description, this.argsShape, callback);
+        server.tool(this.name, this.description, this.argsShape, this.annotations, callback);
 
         // This is very similar to RegisteredTool.update, but without the bugs around the name.
         // In the upstream update method, the name is captured in the closure and not updated when
@@ -66,13 +94,22 @@ export abstract class ToolBase {
             const tools = server["_registeredTools"] as { [toolName: string]: RegisteredTool };
             const existingTool = tools[this.name];
 
+            if (!existingTool) {
+                logger.warning(LogId.toolUpdateFailure, "tool", `Tool ${this.name} not found in update`);
+                return;
+            }
+
+            existingTool.annotations = this.annotations;
+
             if (updates.name && updates.name !== this.name) {
+                existingTool.annotations.title = updates.name;
                 delete tools[this.name];
                 this.name = updates.name;
                 tools[this.name] = existingTool;
             }
 
             if (updates.description) {
+                existingTool.annotations.description = updates.description;
                 existingTool.description = updates.description;
                 this.description = updates.description;
             }
@@ -142,11 +179,11 @@ export abstract class ToolBase {
      * @param result - Whether the command succeeded or failed
      * @param args - The arguments passed to the tool
      */
-    private async emitToolEvent(
+    private emitToolEvent(
         startTime: number,
         result: CallToolResult,
         ...args: Parameters<ToolCallback<typeof this.argsShape>>
-    ): Promise<void> {
+    ): void {
         if (!this.telemetry.isTelemetryEnabled()) {
             return;
         }
@@ -172,6 +209,6 @@ export abstract class ToolBase {
             event.properties.project_id = metadata.projectId;
         }
 
-        await this.telemetry.emitEvents([event]);
+        this.telemetry.emitEvents([event]);
     }
 }

package/tests/integration/helpers.ts

@@ -206,6 +206,7 @@ export function validateToolMetadata(
         expectDefined(tool);
         expect(tool.description).toBe(description);
 
+        validateToolAnnotations(tool, name, description);
         const toolParameters = getParameters(tool);
         expect(toolParameters).toHaveLength(parameters.length);
         expect(toolParameters).toIncludeAllMembers(parameters);
@@ -240,3 +241,25 @@ export function expectDefined<T>(arg: T): asserts arg is Exclude<T, undefined |
     expect(arg).toBeDefined();
     expect(arg).not.toBeNull();
 }
+
+function validateToolAnnotations(tool: ToolInfo, name: string, description: string): void {
+    expectDefined(tool.annotations);
+    expect(tool.annotations.title).toBe(name);
+    expect(tool.annotations.description).toBe(description);
+
+    switch (tool.operationType) {
+        case "read":
+        case "metadata":
+            expect(tool.annotations.readOnlyHint).toBe(true);
+            expect(tool.annotations.destructiveHint).toBe(false);
+            break;
+        case "delete":
+            expect(tool.annotations.readOnlyHint).toBe(false);
+            expect(tool.annotations.destructiveHint).toBe(true);
+            break;
+        case "create":
+        case "update":
+            expect(tool.annotations.readOnlyHint).toBe(false);
+            expect(tool.annotations.destructiveHint).toBe(false);
+    }
+}