feat: add structured content for response in atlas-local tools - MCP-374

api-extractor/reports/tools.public.api.md

@@ -265,17 +265,22 @@ export class ConnectClusterTool extends AtlasToolBase {
 export class ConnectDeploymentTool extends AtlasLocalToolBase {
     // (undocumented)
     argsShape: {
-        deploymentName: ZodString;
+        deploymentName: z.ZodString;
     };
     // (undocumented)
     description: string;
     // (undocumented)
     protected executeWithAtlasLocalClient(input: ToolArgs<typeof ConnectDeploymentTool.argsShape>, input2: {
         client: Client;
-    }): Promise<CallToolResult>;
+    }): Promise<ToolResult<typeof ConnectDeploymentOutputSchema> & Pick<CallToolResult, "_meta">>;
     // (undocumented)
     static operationType: OperationType;
     // (undocumented)
+    outputSchema: {
+        connected: z.ZodBoolean;
+        deploymentName: z.ZodString;
+    };
+    // (undocumented)
     protected resolveTelemetryMetadata(args: ToolArgs<typeof ConnectDeploymentTool.argsShape>, input: {
         result: CallToolResult;
     }): ConnectionMetadata;
@@ -295,8 +300,6 @@ export class ConnectTool extends MongoDBToolBase {
     // (undocumented)
     protected execute(input: ToolArgs<typeof ConnectTool.argsShape>): Promise<ToolResult<typeof ConnectTool.outputSchema>>;
     // (undocumented)
-    protected handleError(error: unknown, args: ToolArgs<typeof ConnectTool.argsShape>): Promise<CallToolResult>;
-    // (undocumented)
     static operationType: OperationType;
     // (undocumented)
     outputSchema: {
@@ -508,10 +511,17 @@ export class CreateDeploymentTool extends AtlasLocalToolBase {
     // (undocumented)
     protected executeWithAtlasLocalClient(input: ToolArgs<typeof CreateDeploymentTool.argsShape>, input2: {
         client: Client;
-    }): Promise<CallToolResult>;
+    }): Promise<ToolResult<typeof CreateDeploymentOutputSchema> & Pick<CallToolResult, "_meta">>;
     // (undocumented)
     static operationType: OperationType;
     // (undocumented)
+    outputSchema: {
+        deploymentName: z.ZodString;
+        containerId: z.ZodString;
+        loadSampleData: z.ZodBoolean;
+        imageTag: z.ZodString;
+    };
+    // (undocumented)
     static toolName: string;
 }
 
@@ -671,17 +681,22 @@ export class DbStatsTool extends MongoDBToolBase {
 export class DeleteDeploymentTool extends AtlasLocalToolBase {
     // (undocumented)
     argsShape: {
-        deploymentName: ZodString;
+        deploymentName: z.ZodString;
     };
     // (undocumented)
     description: string;
     // (undocumented)
     protected executeWithAtlasLocalClient(input: ToolArgs<typeof DeleteDeploymentTool.argsShape>, input2: {
         client: Client;
-    }): Promise<CallToolResult>;
+    }): Promise<ToolResult<typeof DeleteDeploymentOutputSchema> & Pick<CallToolResult, "_meta">>;
     // (undocumented)
     static operationType: OperationType;
     // (undocumented)
+    outputSchema: {
+        deleted: z.ZodBoolean;
+        deploymentName: z.ZodString;
+    };
+    // (undocumented)
     static toolName: string;
 }
 
@@ -1193,10 +1208,19 @@ export class ListDeploymentsTool extends AtlasLocalToolBase {
     // (undocumented)
     protected executeWithAtlasLocalClient(_args: ToolArgs<typeof ListDeploymentsTool.argsShape>, input: {
         client: Client;
-    }): Promise<CallToolResult>;
+    }): Promise<ToolResult<typeof ListDeploymentsOutputSchema>>;
     // (undocumented)
     static operationType: OperationType;
     // (undocumented)
+    outputSchema: {
+        count: z.ZodNumber;
+        deployments: z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            state: z.ZodString;
+            mongodbVersion: z.ZodString;
+        }, z.core.$strip>>;
+    };
+    // (undocumented)
     static toolName: string;
 }
 

src/tools/atlasLocal/connect/connectDeployment.ts

@@ -1,6 +1,7 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
 import { AtlasLocalToolBase } from "../atlasLocalTool.js";
-import type { OperationType, ToolArgs } from "../../tool.js";
+import type { OperationType, ToolArgs, ToolResult } from "../../tool.js";
 import type { Client } from "@mongodb-js/atlas-local";
 import {
     AtlasLocalDeploymentNotReadyError,
@@ -9,6 +10,11 @@ import {
 import { CommonArgs } from "../../args.js";
 import type { ConnectionMetadata } from "../../../telemetry/types.js";
 
+const ConnectDeploymentOutputSchema = {
+    connected: z.boolean(),
+    deploymentName: z.string(),
+};
+
 export class ConnectDeploymentTool extends AtlasLocalToolBase {
     static toolName = "atlas-local-connect-deployment";
     public description = "Connect to a MongoDB Atlas Local deployment";
@@ -17,10 +23,12 @@ export class ConnectDeploymentTool extends AtlasLocalToolBase {
         deploymentName: CommonArgs.string().describe("Name of the deployment to connect to"),
     };
 
+    public override outputSchema = ConnectDeploymentOutputSchema;
+
     protected async executeWithAtlasLocalClient(
         { deploymentName }: ToolArgs<typeof this.argsShape>,
         { client }: { client: Client }
-    ): Promise<CallToolResult> {
+    ): Promise<ToolResult<typeof ConnectDeploymentOutputSchema> & Pick<CallToolResult, "_meta">> {
         let connectionString: string;
         try {
             connectionString = await waitForConnectionString(client, deploymentName);
@@ -33,6 +41,10 @@ export class ConnectDeploymentTool extends AtlasLocalToolBase {
                             text: `Atlas Local deployment "${deploymentName}" is still starting up. Wait a few seconds and call atlas-local-connect-deployment again with the same deployment name.`,
                         },
                     ],
+                    structuredContent: {
+                        connected: false,
+                        deploymentName,
+                    },
                     isError: true,
                 };
             }
@@ -48,6 +60,10 @@ export class ConnectDeploymentTool extends AtlasLocalToolBase {
                     text: `Successfully connected to Atlas Local deployment "${deploymentName}".`,
                 },
             ],
+            structuredContent: {
+                connected: true,
+                deploymentName,
+            },
             _meta: {
                 ...(await this.lookupTelemetryMetadata(client, deploymentName)),
             },

src/tools/atlasLocal/create/createDeployment.ts

@@ -1,13 +1,22 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
 import { AtlasLocalToolBase } from "../atlasLocalTool.js";
-import type { OperationType, ToolArgs } from "../../tool.js";
-import type { Client, CreateDeploymentOptions } from "@mongodb-js/atlas-local";
+import type { OperationType, ToolArgs, ToolResult } from "../../tool.js";
+import type { Client, CreateDeploymentOptions, Deployment } from "@mongodb-js/atlas-local";
 import {
     AtlasLocalDeploymentNotReadyError,
     waitForConnectionString,
 } from "../../../common/atlasLocal/connectionString.js";
 import { CommonArgs } from "../../args.js";
-import z from "zod";
+
+const CreateDeploymentOutputSchema = {
+    deploymentName: z.string(),
+    containerId: z.string(),
+    loadSampleData: z.boolean(),
+    imageTag: z.string(),
+};
+
+export type CreateDeploymentOutput = z.infer<z.ZodObject<typeof CreateDeploymentOutputSchema>>;
 
 export class CreateDeploymentTool extends AtlasLocalToolBase {
     static toolName = "atlas-local-create-deployment";
@@ -24,10 +33,12 @@ export class CreateDeploymentTool extends AtlasLocalToolBase {
             .default("preview"),
     };
 
+    public override outputSchema = CreateDeploymentOutputSchema;
+
     protected async executeWithAtlasLocalClient(
         { deploymentName, loadSampleData, imageTag }: ToolArgs<typeof this.argsShape>,
         { client }: { client: Client }
-    ): Promise<CallToolResult> {
+    ): Promise<ToolResult<typeof CreateDeploymentOutputSchema> & Pick<CallToolResult, "_meta">> {
         const deploymentOptions: CreateDeploymentOptions = {
             name: deploymentName,
             creationSource: {
@@ -57,6 +68,12 @@ export class CreateDeploymentTool extends AtlasLocalToolBase {
             }
         }
 
+        const structuredContent = this.buildStructuredContent(deployment, {
+            deploymentName: resolvedDeploymentName ?? "",
+            loadSampleData,
+            imageTag,
+        });
+
         const startingNote = stillStarting
             ? " The deployment is still initializing; if atlas-local-connect-deployment fails, wait a few seconds and try connecting again."
             : "";
@@ -68,9 +85,22 @@ export class CreateDeploymentTool extends AtlasLocalToolBase {
                     text: `Deployment with container ID "${deployment.containerId}" and name "${deployment.name}" created (imageTag: ${imageTag}).${startingNote}`,
                 },
             ],
+            structuredContent,
             _meta: {
                 ...(await this.lookupTelemetryMetadata(client, deployment.containerId)),
             },
         };
     }
+
+    private buildStructuredContent(
+        deployment: Deployment,
+        args: { deploymentName: string; loadSampleData: boolean; imageTag: string }
+    ): CreateDeploymentOutput {
+        return {
+            deploymentName: args.deploymentName,
+            containerId: deployment.containerId,
+            loadSampleData: args.loadSampleData,
+            imageTag: args.imageTag,
+        };
+    }
 }

src/tools/atlasLocal/delete/deleteDeployment.ts

@@ -1,9 +1,15 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
 import { AtlasLocalToolBase } from "../atlasLocalTool.js";
-import type { OperationType, ToolArgs } from "../../tool.js";
+import type { OperationType, ToolArgs, ToolResult } from "../../tool.js";
 import type { Client } from "@mongodb-js/atlas-local";
 import { CommonArgs } from "../../args.js";
 
+const DeleteDeploymentOutputSchema = {
+    deleted: z.boolean(),
+    deploymentName: z.string(),
+};
+
 export class DeleteDeploymentTool extends AtlasLocalToolBase {
     static toolName = "atlas-local-delete-deployment";
     public description = "Delete a MongoDB Atlas local deployment";
@@ -12,20 +18,23 @@ export class DeleteDeploymentTool extends AtlasLocalToolBase {
         deploymentName: CommonArgs.string().describe("Name of the deployment to delete"),
     };
 
+    public override outputSchema = DeleteDeploymentOutputSchema;
+
     protected async executeWithAtlasLocalClient(
         { deploymentName }: ToolArgs<typeof this.argsShape>,
         { client }: { client: Client }
-    ): Promise<CallToolResult> {
-        // Lookup telemetry metadata
-        // We need to lookup the telemetry metadata before deleting the deployment
-        // to ensure that the deployment ID is set in the result metadata
+    ): Promise<ToolResult<typeof DeleteDeploymentOutputSchema> & Pick<CallToolResult, "_meta">> {
+        // Resolve deployment ID for telemetry before the deployment is removed.
         const telemetryMetadata = await this.lookupTelemetryMetadata(client, deploymentName);
 
-        // Delete the deployment
         await client.deleteDeployment(deploymentName);
 
         return {
             content: [{ type: "text", text: `Deployment "${deploymentName}" deleted successfully.` }],
+            structuredContent: {
+                deleted: true,
+                deploymentName,
+            },
             _meta: {
                 ...telemetryMetadata,
             },

src/tools/atlasLocal/read/listDeployments.ts

@@ -1,32 +1,49 @@
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
 import { AtlasLocalToolBase } from "../atlasLocalTool.js";
-import type { OperationType, ToolArgs } from "../../tool.js";
+import type { OperationType, ToolArgs, ToolResult } from "../../tool.js";
 import { formatUntrustedData } from "../../tool.js";
 import type { Deployment } from "@mongodb-js/atlas-local";
 import type { Client } from "@mongodb-js/atlas-local";
 
+const ListDeploymentsOutputSchema = {
+    count: z.number(),
+    deployments: z.array(
+        z.object({
+            name: z.string().optional(),
+            state: z.string(),
+            mongodbVersion: z.string(),
+        })
+    ),
+};
+
 export class ListDeploymentsTool extends AtlasLocalToolBase {
     static toolName = "atlas-local-list-deployments";
     public description = "List MongoDB Atlas local deployments";
     static operationType: OperationType = "read";
     public argsShape = {};
 
+    public override outputSchema = ListDeploymentsOutputSchema;
+
     protected async executeWithAtlasLocalClient(
         _args: ToolArgs<typeof this.argsShape>,
         { client }: { client: Client }
-    ): Promise<CallToolResult> {
+    ): Promise<ToolResult<typeof ListDeploymentsOutputSchema>> {
         // List the deployments
         const deployments = await client.listDeployments();
 
         // Format the deployments
         return this.formatDeploymentsTable(deployments);
     }
 
-    private formatDeploymentsTable(deployments: Deployment[]): CallToolResult {
+    private formatDeploymentsTable(deployments: Deployment[]): ToolResult<typeof ListDeploymentsOutputSchema> {
         // Check if deployments are absent
         if (!deployments?.length) {
             return {
                 content: [{ type: "text", text: "No deployments found." }],
+                structuredContent: {
+                    count: 0,
+                    deployments: [],
+                },
             };
         }
 
@@ -42,6 +59,10 @@ export class ListDeploymentsTool extends AtlasLocalToolBase {
 
         return {
             content: formatUntrustedData(`Found ${deployments.length} deployments`, JSON.stringify(deploymentsJson)),
+            structuredContent: {
+                count: deployments.length,
+                deployments: deploymentsJson,
+            },
         };
     }
 }

src/tools/mongodb/connect/connect.ts

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { MongoDBToolBase } from "../mongodbTool.js";
 import type { ToolArgs, OperationType, ToolConstructorParams, ToolResult } from "../../tool.js";
 import type { Server } from "../../../server.js";
@@ -56,15 +55,4 @@ export class ConnectTool extends MongoDBToolBase {
             structuredContent: { connected: true },
         };
     }
-
-    protected override async handleError(
-        error: unknown,
-        args: ToolArgs<typeof this.argsShape>
-    ): Promise<CallToolResult> {
-        const result = await super.handleError(error, args);
-        if (result.isError) {
-            return { ...result, structuredContent: { connected: false } };
-        }
-        return result;
-    }
 }

tests/accuracy/connectDeployment.test.ts

@@ -35,6 +35,10 @@ describeAccuracyTests([
                     "Found 1 deployments",
                     '[{"name":"local-mflix","state":"Running","mongodbVersion":"6.0"}]'
                 ),
+                structuredContent: {
+                    count: 1,
+                    deployments: [{ name: "local-mflix", state: "Running", mongodbVersion: "6.0" }],
+                },
             }),
         },
         expectedToolCalls: [

tests/accuracy/createDeployment.test.ts

@@ -10,6 +10,12 @@ export function mockCreateDeploymentResponse(name: string): () => CallToolResult
                 text: `Deployment with container ID "1FOO" and name "${name}" created.`,
             },
         ],
+        structuredContent: {
+            deploymentName: name,
+            containerId: "1FOO",
+            loadSampleData: false,
+            imageTag: "preview",
+        },
     });
 }
 
@@ -120,6 +126,10 @@ describeAccuracyTests([
                         text: "Deployment Name | State | MongoDB Version\n----------------|----------------|----------------\nexisting-database | Running | 6.0",
                     },
                 ],
+                structuredContent: {
+                    count: 1,
+                    deployments: [{ name: "existing-database", state: "Running", mongodbVersion: "6.0" }],
+                },
             }),
         },
         expectedToolCalls: [