feat(atlas-local): Adds Atlas Local Connect Deployment tool

package.json

@@ -121,7 +121,7 @@
     "node": "^20.19.0 || ^22.12.0 || >= 23.0.0"
   },
   "optionalDependencies": {
-    "@mongodb-js-preview/atlas-local": "^0.0.0-preview.3",
+    "@mongodb-js-preview/atlas-local": "^0.0.0-preview.6",
     "kerberos": "^2.2.2"
   }
 }

src/common/connectionErrorHandler.ts

@@ -20,9 +20,18 @@ export const connectionErrorHandler: ConnectionErrorHandler = (error, { availabl
     // Find the first Atlas connect tool if available and suggest to the LLM to use it.
     // Note: if we ever have multiple Atlas connect tools, we may want to refine this logic to select the most appropriate one.
     const atlasConnectTool = connectTools?.find((t) => t.category === "atlas");
-    const llmConnectHint = atlasConnectTool
-        ? `Note to LLM: prefer using the "${atlasConnectTool.name}" tool to connect to an Atlas cluster over using a connection string. Make sure to ask the user to specify a cluster name they want to connect to or ask them if they want to use the "list-clusters" tool to list all their clusters. Do not invent cluster names or connection strings unless the user has explicitly specified them. If they've previously connected to MongoDB using MCP, you can ask them if they want to reconnect using the same cluster/connection.`
-        : "Note to LLM: do not invent connection strings and explicitly ask the user to provide one. If they have previously connected to MongoDB using MCP, you can ask them if they want to reconnect using the same connection string.";
+    const atlasLocalConnectTool = connectTools?.find((t) => t.category === "atlas-local");
+
+    let llmConnectHint: string;
+
+    if (atlasConnectTool) {
+        llmConnectHint = `Note to LLM: prefer using the "${atlasConnectTool.name}" tool to connect to an Atlas cluster over using a connection string. Make sure to ask the user to specify a cluster name they want to connect to or ask them if they want to use the "list-clusters" tool to list all their clusters. Do not invent cluster names or connection strings unless the user has explicitly specified them. If they've previously connected to MongoDB using MCP, you can ask them if they want to reconnect using the same cluster/connection.`;
+    } else if (atlasLocalConnectTool) {
+        llmConnectHint = `Note to LLM: prefer using the "${atlasLocalConnectTool.name}" tool for connecting to local MongoDB deployments. Ask the user to specify a deployment name or use "atlas-local-list-deployments" to show available local deployments. Do not invent deployment names unless the user has explicitly specified them. If they've previously connected to a local MongoDB deployment using MCP, you can ask them if they want to reconnect using the same deployment.`;
+    } else {
+        llmConnectHint =
+            "Note to LLM: do not invent connection strings and explicitly ask the user to provide one. If they have previously connected to MongoDB using MCP, you can ask them if they want to reconnect using the same connection string.";
+    }
 
     const connectToolsNames = connectTools?.map((t) => `"${t.name}"`).join(", ");
     const additionalPromptForConnectivity: { type: "text"; text: string }[] = [];

src/tools/atlasLocal/connect/connectDeployment.ts

@@ -0,0 +1,34 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { AtlasLocalToolBase } from "../atlasLocalTool.js";
+import type { OperationType, ToolArgs } from "../../tool.js";
+import type { Client } from "@mongodb-js-preview/atlas-local";
+import { z } from "zod";
+
+export class ConnectDeploymentTool extends AtlasLocalToolBase {
+    public name = "atlas-local-connect-deployment";
+    protected description = "Connect to a MongoDB Atlas Local deployment";
+    public operationType: OperationType = "connect";
+    protected argsShape = {
+        deploymentIdOrName: z.string().describe("Name or ID of the deployment to connect to"),
+    };
+
+    protected async executeWithAtlasLocalClient(
+        client: Client,
+        { deploymentIdOrName }: ToolArgs<typeof this.argsShape>
+    ): Promise<CallToolResult> {
+        // Get the connection string for the deployment
+        const connectionString = await client.getConnectionString(deploymentIdOrName);
+
+        // Connect to the deployment
+        await this.session.connectToMongoDB({ connectionString });
+
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Successfully connected to Atlas Local deployment "${deploymentIdOrName}".`,
+                },
+            ],
+        };
+    }
+}

src/tools/atlasLocal/tools.ts

@@ -1,5 +1,6 @@
 import { DeleteDeploymentTool } from "./delete/deleteDeployment.js";
 import { ListDeploymentsTool } from "./read/listDeployments.js";
 import { CreateDeploymentTool } from "./create/createDeployment.js";
+import { ConnectDeploymentTool } from "./connect/connectDeployment.js";
 
-export const AtlasLocalTools = [ListDeploymentsTool, DeleteDeploymentTool, CreateDeploymentTool];
+export const AtlasLocalTools = [ListDeploymentsTool, DeleteDeploymentTool, CreateDeploymentTool, ConnectDeploymentTool];

tests/accuracy/connectDeployment.test.ts

@@ -0,0 +1,70 @@
+import { describeAccuracyTests } from "./sdk/describeAccuracyTests.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+describeAccuracyTests([
+    {
+        prompt: "Connect to the local MongoDB cluster called 'my-database'",
+        expectedToolCalls: [
+            {
+                toolName: "atlas-local-connect-deployment",
+                parameters: {
+                    deploymentIdOrName: "my-database",
+                },
+            },
+        ],
+    },
+    {
+        prompt: "Connect to the local MongoDB atlas database called 'my-instance'",
+        expectedToolCalls: [
+            {
+                toolName: "atlas-local-connect-deployment",
+                parameters: {
+                    deploymentIdOrName: "my-instance",
+                },
+            },
+        ],
+    },
+    {
+        prompt: "If and only if, the local MongoDB deployment 'local-mflix' exists, then connect to it",
+        mockedTools: {
+            "atlas-local-list-deployments": (): CallToolResult => ({
+                content: [
+                    { type: "text", text: "Found 1 deployment:" },
+                    {
+                        type: "text",
+                        text: "Deployment Name | State | MongoDB Version\n----------------|----------------|----------------\nlocal-mflix | Running | 6.0",
+                    },
+                ],
+            }),
+        },
+        expectedToolCalls: [
+            {
+                toolName: "atlas-local-list-deployments",
+                parameters: {},
+            },
+            {
+                toolName: "atlas-local-connect-deployment",
+                parameters: {
+                    deploymentIdOrName: "local-mflix",
+                },
+            },
+        ],
+    },
+    {
+        prompt: "Connect to a new local MongoDB cluster named 'local-mflix'",
+        expectedToolCalls: [
+            {
+                toolName: "atlas-local-create-deployment",
+                parameters: {
+                    deploymentName: "local-mflix",
+                },
+            },
+            {
+                toolName: "atlas-local-connect-deployment",
+                parameters: {
+                    deploymentIdOrName: "local-mflix",
+                },
+            },
+        ],
+    },
+]);

tests/integration/tools/atlas-local/connectDeployment.test.ts

@@ -0,0 +1,98 @@
+import {
+    defaultDriverOptions,
+    defaultTestConfig,
+    expectDefined,
+    getResponseElements,
+    setupIntegrationTest,
+    waitUntilMcpClientIsSet,
+} from "../../helpers.js";
+import { describe, expect, it } from "vitest";
+
+const isMacOSInGitHubActions = process.platform === "darwin" && process.env.GITHUB_ACTIONS === "true";
+
+// Docker is not available on macOS in GitHub Actions
+// That's why we skip the tests on macOS in GitHub Actions
+describe("atlas-local-connect-deployment", () => {
+    const integration = setupIntegrationTest(
+        () => defaultTestConfig,
+        () => defaultDriverOptions
+    );
+
+    it.skipIf(isMacOSInGitHubActions)("should have the atlas-local-connect-deployment tool", async ({ signal }) => {
+        await waitUntilMcpClientIsSet(integration.mcpServer(), signal);
+
+        const { tools } = await integration.mcpClient().listTools();
+        const connectDeployment = tools.find((tool) => tool.name === "atlas-local-connect-deployment");
+        expectDefined(connectDeployment);
+    });
+
+    it.skipIf(!isMacOSInGitHubActions)(
+        "[MacOS in GitHub Actions] should not have the atlas-local-connect-deployment tool",
+        async ({ signal }) => {
+            // This should throw an error because the client is not set within the timeout of 5 seconds (default)
+            await expect(waitUntilMcpClientIsSet(integration.mcpServer(), signal)).rejects.toThrow();
+
+            const { tools } = await integration.mcpClient().listTools();
+            const connectDeployment = tools.find((tool) => tool.name === "atlas-local-connect-deployment");
+            expect(connectDeployment).toBeUndefined();
+        }
+    );
+
+    it.skipIf(isMacOSInGitHubActions)("should have correct metadata", async ({ signal }) => {
+        await waitUntilMcpClientIsSet(integration.mcpServer(), signal);
+        const { tools } = await integration.mcpClient().listTools();
+        const connectDeployment = tools.find((tool) => tool.name === "atlas-local-connect-deployment");
+        expectDefined(connectDeployment);
+        expect(connectDeployment.inputSchema.type).toBe("object");
+        expectDefined(connectDeployment.inputSchema.properties);
+        expect(connectDeployment.inputSchema.properties).toHaveProperty("deploymentIdOrName");
+    });
+
+    it.skipIf(isMacOSInGitHubActions)(
+        "should return 'no such container' error when connecting to non-existent deployment",
+        async ({ signal }) => {
+            await waitUntilMcpClientIsSet(integration.mcpServer(), signal);
+
+            const response = await integration.mcpClient().callTool({
+                name: "atlas-local-connect-deployment",
+                arguments: { deploymentIdOrName: "non-existent" },
+            });
+            const elements = getResponseElements(response.content);
+            expect(elements.length).toBeGreaterThanOrEqual(1);
+            expect(elements[0]?.text).toContain(
+                "Docker responded with status code 404: No such container: non-existent"
+            );
+        }
+    );
+
+    it.skipIf(isMacOSInGitHubActions)("should connect to a deployment when calling the tool", async ({ signal }) => {
+        await waitUntilMcpClientIsSet(integration.mcpServer(), signal);
+        // Create a deployment
+        const deploymentName = `test-deployment-${Date.now()}`;
+        await integration.mcpClient().callTool({
+            name: "atlas-local-create-deployment",
+            arguments: { deploymentName },
+        });
+
+        // Connect to the deployment
+        const response = await integration.mcpClient().callTool({
+            name: "atlas-local-connect-deployment",
+            arguments: { deploymentIdOrName: deploymentName },
+        });
+        const elements = getResponseElements(response.content);
+        expect(elements.length).toBeGreaterThanOrEqual(1);
+        expect(elements[0]?.text).toContain(
+            'Successfully connected to Atlas Local deployment "' + deploymentName + '".'
+        );
+
+        // cleanup
+        try {
+            await integration.mcpClient().callTool({
+                name: "atlas-local-delete-deployment",
+                arguments: { deploymentName },
+            });
+        } catch (error) {
+            console.warn(`Failed to delete deployment ${deploymentName}:`, error);
+        }
+    });
+});

tests/integration/tools/atlas/clusters.test.ts

@@ -239,7 +239,7 @@ describeWithAtlas("clusters", (integration) => {
                         "You need to connect to a MongoDB instance before you can access its data."
                     );
                     expect(elements[1]?.text).toContain(
-                        'Please use one of the following tools: "atlas-connect-cluster", "connect" to connect to a MongoDB instance'
+                        'Please use one of the following tools: "atlas-connect-cluster", "atlas-local-connect-deployment", "connect" to connect to a MongoDB instance'
                     );
                 });
             });