@W-21435068 Add post action reminder for cartridge deploy mcp tool (#233)

Author: yhsieh1

.changeset/cartridge-deploy-bm-reminder.md

@@ -0,0 +1,5 @@
+---
+'@salesforce/b2c-dx-mcp': patch
+---
+
+cartridge_deploy now reminds users to update the site cartridge path in Business Manager (Sites → Manage Sites → [site] → Settings tab → Cartridges) after deploy.

packages/b2c-dx-mcp/src/tools/cartridges/index.ts

@@ -21,6 +21,11 @@ import type {DeployResult, DeployOptions, CodeVersion} from '@salesforce/b2c-too
 import type {B2CInstance} from '@salesforce/b2c-tooling-sdk';
 import {getLogger} from '@salesforce/b2c-tooling-sdk/logging';
 
+/** Reminder shown after deploy so users add cartridges to the site cartridge path. */
+const CARTRIDGE_PATH_REMINDER =
+  "If this is a new or updated cartridge, add it to your site's cartridge path in Business Manager: " +
+  'Sites → Manage Sites → [your site] → Settings tab → Cartridges field.';
+
 /**
  * Input type for cartridge_deploy tool.
  */
@@ -35,6 +40,12 @@ interface CartridgeDeployInput {
   reload?: boolean;
 }
 
+/** Output type: deploy result plus reminder to update site cartridge path. */
+interface CartridgeDeployOutput extends DeployResult {
+  /** Reminder to add deployed cartridges to the site cartridge path in Business Manager. */
+  postInstructions?: string;
+}
+
 /**
  * Optional dependency injections for testing.
  */
@@ -61,15 +72,16 @@ interface CartridgeToolInjections {
 function createCartridgeDeployTool(loadServices: () => Services, injections?: CartridgeToolInjections): McpTool {
   const findAndDeployCartridgesFn = injections?.findAndDeployCartridges || findAndDeployCartridges;
   const getActiveCodeVersionFn = injections?.getActiveCodeVersion || getActiveCodeVersion;
-  return createToolAdapter<CartridgeDeployInput, DeployResult>(
+  return createToolAdapter<CartridgeDeployInput, CartridgeDeployOutput>(
     {
       name: 'cartridge_deploy',
       description:
         'Finds and deploys cartridges to a B2C Commerce instance via WebDAV. ' +
         'Searches the directory for cartridges (by .project files), applies include/exclude filters, ' +
         'creates a zip archive, uploads via WebDAV, and optionally reloads the code version. ' +
         'Use this tool to deploy custom code cartridges for SFRA or other B2C Commerce code. ' +
-        'Requires the instance to have a code version configured.',
+        'Requires the instance to have a code version configured. ' +
+        "After deploy, add new cartridges to your site's cartridge path in Business Manager: Sites → Manage Sites → [site] → Settings tab → Cartridges.",
       toolsets: ['CARTRIDGES'],
       isGA: false,
       requiresInstance: true,
@@ -152,7 +164,10 @@ function createCartridgeDeployTool(loadServices: () => Services, injections?: Ca
           // Deploy cartridges
           const result = await findAndDeployCartridgesFn(instance, directory, options);
 
-          return result;
+          return {
+            ...result,
+            postInstructions: CARTRIDGE_PATH_REMINDER,
+          };
         } catch (error) {
           // Handle communication and authentication errors
           const errorMessage = error instanceof Error ? error.message : String(error);

packages/b2c-dx-mcp/test/tools/cartridges/index.test.ts

@@ -15,6 +15,11 @@ import type {B2CInstance} from '@salesforce/b2c-tooling-sdk';
 import type {DeployResult, DeployOptions, CodeVersion} from '@salesforce/b2c-tooling-sdk/operations/code';
 import type {WebDavClient, OcapiClient} from '@salesforce/b2c-tooling-sdk/clients';
 
+/** Tool output: DeployResult plus postInstructions reminder. */
+interface CartridgeDeployOutput extends DeployResult {
+  postInstructions?: string;
+}
+
 /**
  * Helper to extract text from a ToolResult.
  * Throws if the first content item is not a text type.
@@ -117,6 +122,9 @@ describe('tools/cartridges', () => {
       expect(desc).to.include('Finds and deploys cartridges');
       expect(desc).to.include('B2C Commerce');
       expect(desc).to.include('WebDAV');
+      expect(desc).to.include('Sites → Manage Sites');
+      expect(desc).to.include('Settings tab');
+      expect(desc).to.include('Cartridges');
     });
 
     it('should be in CARTRIDGES toolset', () => {
@@ -166,9 +174,12 @@ describe('tools/cartridges', () => {
       expect(options.include).to.be.undefined;
       expect(options.exclude).to.be.undefined;
       expect(options.reload).to.be.undefined;
-      const jsonResult = getResultJson<DeployResult>(result);
+      const jsonResult = getResultJson<CartridgeDeployOutput>(result);
       expect(jsonResult.codeVersion).to.equal('v1');
       expect(jsonResult.cartridges).to.have.lengthOf(1);
+      expect(jsonResult.postInstructions).to.be.a('string');
+      expect(jsonResult.postInstructions).to.include('Sites → Manage Sites');
+      expect(jsonResult.postInstructions).to.include('Cartridges field');
     });
 
     it('should call findAndDeployCartridges with custom directory', async () => {
@@ -196,8 +207,9 @@ describe('tools/cartridges', () => {
       expect(findAndDeployCartridgesStub.calledOnce).to.be.true;
       const [, dir] = findAndDeployCartridgesStub.firstCall.args as [B2CInstance, string, DeployOptions];
       expect(dir).to.equal(expectedResolvedPath);
-      const jsonResult = getResultJson<DeployResult>(result);
+      const jsonResult = getResultJson<CartridgeDeployOutput>(result);
       expect(jsonResult.codeVersion).to.equal('v2');
+      expect(jsonResult.postInstructions).to.include("site's cartridge path");
     });
 
     it('should pass cartridges array as include option', async () => {
@@ -313,7 +325,7 @@ describe('tools/cartridges', () => {
       expect(options.reload).to.equal(reload);
     });
 
-    it('should return DeployResult as JSON', async () => {
+    it('should return DeployResult with postInstructions as JSON', async () => {
       const mockResult: DeployResult = {
         cartridges: [
           {name: 'app_storefront_base', src: '/path/to/app', dest: 'app_storefront_base'},
@@ -334,12 +346,17 @@ describe('tools/cartridges', () => {
       const result = await tool.handler({});
 
       expect(result.isError).to.be.undefined;
-      const jsonResult = getResultJson<DeployResult>(result);
+      const jsonResult = getResultJson<CartridgeDeployOutput>(result);
       expect(jsonResult.codeVersion).to.equal('v1.2.3');
       expect(jsonResult.cartridges).to.have.lengthOf(2);
       expect(jsonResult.reloaded).to.be.true;
       expect(jsonResult.cartridges[0].name).to.equal('app_storefront_base');
       expect(jsonResult.cartridges[1].name).to.equal('app_core');
+      expect(jsonResult.postInstructions).to.be.a('string');
+      expect(jsonResult.postInstructions).to.include('Business Manager');
+      expect(jsonResult.postInstructions).to.include('Sites → Manage Sites');
+      expect(jsonResult.postInstructions).to.include('Settings tab');
+      expect(jsonResult.postInstructions).to.include('Cartridges field');
     });
 
     it('should resolve relative directory paths relative to project directory', async () => {
@@ -485,8 +502,9 @@ describe('tools/cartridges', () => {
       expect(getActiveCodeVersionStub.calledWith(mockInstance)).to.be.true;
       expect(mockInstance.config.codeVersion).to.equal('v2');
       expect(findAndDeployCartridgesStub.calledOnce).to.be.true;
-      const jsonResult = getResultJson<DeployResult>(result);
+      const jsonResult = getResultJson<CartridgeDeployOutput>(result);
       expect(jsonResult.codeVersion).to.equal('v2');
+      expect(jsonResult.postInstructions).to.be.a('string');
     });
 
     it('should use existing codeVersion when already specified', async () => {