@salesforce/b2c-dx-mcp 0.3.2 → 0.4.0

package/dist/tools/adapter.d.ts

@@ -3,22 +3,22 @@
  *
  * This module provides utilities for creating standardized MCP tools that:
  * - Validate input using Zod schemas
- * - Inject pre-resolved B2CInstance for WebDAV/OCAPI operations (requiresInstance)
- * - Inject pre-resolved MRT auth for MRT API operations (requiresMrtAuth)
+ * - Inject loaded B2CInstance for WebDAV/OCAPI operations (requiresInstance)
+ * - Inject loaded MRT auth for MRT API operations (requiresMrtAuth)
  * - Format output consistently (textResult, jsonResult, errorResult)
  *
  * ## Configuration Resolution
  *
- * Both B2C instance and MRT auth are resolved once at server startup via
- * {@link Services.fromResolvedConfig} and reused for all tool calls:
+ * Both B2C instance and MRT auth are loaded before each tool call via
+ * a loader function that calls {@link Services.fromResolvedConfig}:
  *
- * - **B2CInstance**: Resolved from flags + dw.json. Available when `requiresInstance: true`.
- * - **MRT Auth**: Resolved from --api-key → SFCC_MRT_API_KEY → ~/.mobify. Available when `requiresMrtAuth: true`.
+ * - **B2CInstance**: Loaded from flags + dw.json on each call. Available when `requiresInstance: true`.
+ * - **MRT Auth**: Loaded from --api-key → SFCC_MRT_API_KEY → ~/.mobify on each call. Available when `requiresMrtAuth: true`.
  *
- * This "resolve eagerly at startup" pattern provides:
- * - Fail-fast behavior (configuration errors surface at startup)
- * - Consistent mental model (both resolved the same way)
- * - Better performance (no resolution on each tool call)
+ * This "load on each call" pattern provides:
+ * - Fresh configuration on each tool invocation (picks up changes to config files)
+ * - Consistent mental model (both loaded the same way)
+ * - Tools can respond to configuration changes without server restart
  *
  * @module tools/adapter
  *
@@ -42,8 +42,11 @@
  *
  * @example MRT tool (MRT API)
  * ```typescript
- * // Services created from already-resolved config at startup
- * const services = Services.fromResolvedConfig(this.resolvedConfig);
+ * // Loader function that loads config and creates Services on each tool call
+ * const loadServices = () => {
+ *   const config = this.loadConfiguration();
+ *   return Services.fromResolvedConfig(config);
+ * };
  *
  * const mrtTool = createToolAdapter({
  *   name: 'mrt_bundle_push',
@@ -53,12 +56,12 @@
  *   inputSchema: {
  *     projectSlug: z.string().describe('MRT project slug'),
  *   },
- *   execute: async (args, { mrtAuth }) => {
- *     const result = await pushBundle({ projectSlug: args.projectSlug }, mrtAuth);
+ *   execute: async (args, { mrtConfig }) => {
+ *     const result = await pushBundle({ projectSlug: args.projectSlug }, mrtConfig.auth);
  *     return result;
  *   },
  *   formatOutput: (output) => jsonResult(output),
- * }, services);
+ * }, loadServices);
  * ```
  */
 import { type ZodRawShape } from 'zod';
@@ -78,7 +81,7 @@ export interface ToolExecutionContext {
     b2cInstance?: B2CInstance;
     /**
      * MRT configuration (auth, project, environment, origin).
-     * Pre-resolved at server startup.
+     * Loaded before each tool call.
      * Only populated when requiresMrtAuth is true.
      */
     mrtConfig?: MrtConfig;
@@ -176,7 +179,7 @@ export declare function jsonResult(data: unknown, indent?: number): ToolResult;
  * @template TInput - The validated input type (inferred from inputSchema)
  * @template TOutput - The output type from the execute function
  * @param options - Tool adapter configuration
- * @param services - Services instance for dependency injection
+ * @param loadServices - Function that loads configuration and returns Services instance
  * @returns An McpTool ready for registration
  *
  * @example
@@ -184,18 +187,23 @@ export declare function jsonResult(data: unknown, indent?: number): ToolResult;
  * import { z } from 'zod';
  * import { createToolAdapter, jsonResult, errorResult } from './adapter.js';
  *
+ * const loadServices = () => {
+ *   const config = this.loadConfiguration();
+ *   return Services.fromResolvedConfig(config);
+ * };
+ *
  * const listCodeVersionsTool = createToolAdapter({
  *   name: 'code_version_list',
  *   description: 'List all code versions on the instance',
  *   toolsets: ['CARTRIDGES'],
  *   inputSchema: {},
- *   execute: async (_args, { instance }) => {
- *     const result = await instance.ocapi.GET('/code_versions', {});
+ *   execute: async (_args, { b2cInstance }) => {
+ *     const result = await b2cInstance.ocapi.GET('/code_versions', {});
  *     if (result.error) throw new Error(result.error.message);
  *     return result.data;
  *   },
  *   formatOutput: (data) => jsonResult(data),
- * }, services);
+ * }, loadServices);
  * ```
  */
-export declare function createToolAdapter<TInput, TOutput>(options: ToolAdapterOptions<TInput, TOutput>, services: Services): McpTool;
+export declare function createToolAdapter<TInput, TOutput>(options: ToolAdapterOptions<TInput, TOutput>, loadServices: () => Services): McpTool;

package/dist/tools/adapter.js

@@ -8,22 +8,22 @@
  *
  * This module provides utilities for creating standardized MCP tools that:
  * - Validate input using Zod schemas
- * - Inject pre-resolved B2CInstance for WebDAV/OCAPI operations (requiresInstance)
- * - Inject pre-resolved MRT auth for MRT API operations (requiresMrtAuth)
+ * - Inject loaded B2CInstance for WebDAV/OCAPI operations (requiresInstance)
+ * - Inject loaded MRT auth for MRT API operations (requiresMrtAuth)
  * - Format output consistently (textResult, jsonResult, errorResult)
  *
  * ## Configuration Resolution
  *
- * Both B2C instance and MRT auth are resolved once at server startup via
- * {@link Services.fromResolvedConfig} and reused for all tool calls:
+ * Both B2C instance and MRT auth are loaded before each tool call via
+ * a loader function that calls {@link Services.fromResolvedConfig}:
  *
- * - **B2CInstance**: Resolved from flags + dw.json. Available when `requiresInstance: true`.
- * - **MRT Auth**: Resolved from --api-key → SFCC_MRT_API_KEY → ~/.mobify. Available when `requiresMrtAuth: true`.
+ * - **B2CInstance**: Loaded from flags + dw.json on each call. Available when `requiresInstance: true`.
+ * - **MRT Auth**: Loaded from --api-key → SFCC_MRT_API_KEY → ~/.mobify on each call. Available when `requiresMrtAuth: true`.
  *
- * This "resolve eagerly at startup" pattern provides:
- * - Fail-fast behavior (configuration errors surface at startup)
- * - Consistent mental model (both resolved the same way)
- * - Better performance (no resolution on each tool call)
+ * This "load on each call" pattern provides:
+ * - Fresh configuration on each tool invocation (picks up changes to config files)
+ * - Consistent mental model (both loaded the same way)
+ * - Tools can respond to configuration changes without server restart
  *
  * @module tools/adapter
  *
@@ -47,8 +47,11 @@
  *
  * @example MRT tool (MRT API)
  * ```typescript
- * // Services created from already-resolved config at startup
- * const services = Services.fromResolvedConfig(this.resolvedConfig);
+ * // Loader function that loads config and creates Services on each tool call
+ * const loadServices = () => {
+ *   const config = this.loadConfiguration();
+ *   return Services.fromResolvedConfig(config);
+ * };
  *
  * const mrtTool = createToolAdapter({
  *   name: 'mrt_bundle_push',
@@ -58,12 +61,12 @@
  *   inputSchema: {
  *     projectSlug: z.string().describe('MRT project slug'),
  *   },
- *   execute: async (args, { mrtAuth }) => {
- *     const result = await pushBundle({ projectSlug: args.projectSlug }, mrtAuth);
+ *   execute: async (args, { mrtConfig }) => {
+ *     const result = await pushBundle({ projectSlug: args.projectSlug }, mrtConfig.auth);
  *     return result;
  *   },
  *   formatOutput: (output) => jsonResult(output),
- * }, services);
+ * }, loadServices);
  * ```
  */
 import { z } from 'zod';
@@ -138,7 +141,7 @@ function formatZodErrors(error) {
  * @template TInput - The validated input type (inferred from inputSchema)
  * @template TOutput - The output type from the execute function
  * @param options - Tool adapter configuration
- * @param services - Services instance for dependency injection
+ * @param loadServices - Function that loads configuration and returns Services instance
  * @returns An McpTool ready for registration
  *
  * @example
@@ -146,21 +149,26 @@ function formatZodErrors(error) {
  * import { z } from 'zod';
  * import { createToolAdapter, jsonResult, errorResult } from './adapter.js';
  *
+ * const loadServices = () => {
+ *   const config = this.loadConfiguration();
+ *   return Services.fromResolvedConfig(config);
+ * };
+ *
  * const listCodeVersionsTool = createToolAdapter({
  *   name: 'code_version_list',
  *   description: 'List all code versions on the instance',
  *   toolsets: ['CARTRIDGES'],
  *   inputSchema: {},
- *   execute: async (_args, { instance }) => {
- *     const result = await instance.ocapi.GET('/code_versions', {});
+ *   execute: async (_args, { b2cInstance }) => {
+ *     const result = await b2cInstance.ocapi.GET('/code_versions', {});
  *     if (result.error) throw new Error(result.error.message);
  *     return result.data;
  *   },
  *   formatOutput: (data) => jsonResult(data),
- * }, services);
+ * }, loadServices);
  * ```
  */
-export function createToolAdapter(options, services) {
+export function createToolAdapter(options, loadServices) {
     const { name, description, inputSchema, toolsets, isGA = true, requiresInstance = false, requiresMrtAuth = false, execute, formatOutput, } = options;
     // Create Zod schema from inputSchema definition
     const zodSchema = z.object(inputSchema);
@@ -178,7 +186,9 @@ export function createToolAdapter(options, services) {
             }
             const args = parseResult.data;
             try {
-                // 2. Get B2CInstance if required (pre-resolved at startup)
+                // 2. Load Services to get fresh configuration (re-reads config files)
+                const services = loadServices();
+                // 3. Get B2CInstance if required (loaded on each call)
                 let b2cInstance;
                 if (requiresInstance) {
                     if (!services.b2cInstance) {
@@ -186,7 +196,7 @@ export function createToolAdapter(options, services) {
                     }
                     b2cInstance = services.b2cInstance;
                 }
-                // 3. Get MRT config if required (pre-resolved at startup)
+                // 4. Get MRT config if required (loaded on each call)
                 let mrtConfig;
                 if (requiresMrtAuth) {
                     if (!services.mrtConfig.auth) {
@@ -199,14 +209,14 @@ export function createToolAdapter(options, services) {
                         origin: services.mrtConfig.origin,
                     };
                 }
-                // 4. Execute the operation
+                // 5. Execute the operation
                 const context = {
                     b2cInstance,
                     mrtConfig,
                     services,
                 };
                 const output = await execute(args, context);
-                // 5. Format output
+                // 6. Format output
                 return formatOutput(output);
             }
             catch (error) {

package/dist/tools/cartridges/index.d.ts

@@ -1,6 +1,6 @@
 import type { McpTool } from '../../utils/index.js';
 import type { Services } from '../../services.js';
-import type { DeployResult, DeployOptions } from '@salesforce/b2c-tooling-sdk/operations/code';
+import type { DeployResult, DeployOptions, CodeVersion } from '@salesforce/b2c-tooling-sdk/operations/code';
 import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
 /**
  * Optional dependency injections for testing.
@@ -8,13 +8,15 @@ import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
 interface CartridgeToolInjections {
     /** Mock findAndDeployCartridges function for testing */
     findAndDeployCartridges?: (instance: B2CInstance, directory: string, options: DeployOptions) => Promise<DeployResult>;
+    /** Mock getActiveCodeVersion function for testing */
+    getActiveCodeVersion?: (instance: B2CInstance) => Promise<CodeVersion | undefined>;
 }
 /**
  * Creates all tools for the CARTRIDGES toolset.
  *
- * @param services - MCP services
+ * @param loadServices - Function that loads configuration and returns Services instance
  * @param injections - Optional dependency injections for testing
  * @returns Array of MCP tools
  */
-export declare function createCartridgesTools(services: Services, injections?: CartridgeToolInjections): McpTool[];
+export declare function createCartridgesTools(loadServices: () => Services, injections?: CartridgeToolInjections): McpTool[];
 export {};

package/dist/tools/cartridges/index.js

@@ -10,9 +10,10 @@
  *
  * @module tools/cartridges
  */
+import path from 'node:path';
 import { z } from 'zod';
 import { createToolAdapter, jsonResult } from '../adapter.js';
-import { findAndDeployCartridges } from '@salesforce/b2c-tooling-sdk/operations/code';
+import { findAndDeployCartridges, getActiveCodeVersion } from '@salesforce/b2c-tooling-sdk/operations/code';
 import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
 /**
  * Creates the cartridge_deploy tool.
@@ -23,12 +24,13 @@ import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
  * 3. Uploads the zip to WebDAV and triggers server-side unzip
  * 4. Optionally reloads the code version after deploy
  *
- * @param services - MCP services
+ * @param loadServices - Function that loads configuration and returns Services instance
  * @param injections - Optional dependency injections for testing
  * @returns The cartridge_deploy tool
  */
-function createCartridgeDeployTool(services, injections) {
+function createCartridgeDeployTool(loadServices, injections) {
     const findAndDeployCartridgesFn = injections?.findAndDeployCartridges || findAndDeployCartridges;
+    const getActiveCodeVersionFn = injections?.getActiveCodeVersion || getActiveCodeVersion;
     return createToolAdapter({
         name: 'cartridge_deploy',
         description: 'Finds and deploys cartridges to a B2C Commerce instance via WebDAV. ' +
@@ -65,37 +67,65 @@ function createCartridgeDeployTool(services, injections) {
         async execute(args, context) {
             // Get instance from context (guaranteed by adapter when requiresInstance is true)
             const instance = context.b2cInstance;
-            // Default directory to current directory
-            const directory = args.directory || '.';
-            // Parse options
-            const options = {
-                include: args.cartridges,
-                exclude: args.exclude,
-                reload: args.reload,
-            };
-            // Log all computed variables before deploying
             const logger = getLogger();
-            logger.debug({
-                directory,
-                include: options.include,
-                exclude: options.exclude,
-                reload: options.reload,
-            }, '[Cartridges] Deploying cartridges with computed options');
-            // Deploy cartridges
-            const result = await findAndDeployCartridgesFn(instance, directory, options);
-            return result;
+            try {
+                // If no code version specified, get the active one
+                let codeVersion = instance.config.codeVersion;
+                if (!codeVersion) {
+                    logger.debug('No code version specified, getting active version...');
+                    const active = await getActiveCodeVersionFn(instance);
+                    if (!active?.id) {
+                        throw new Error('No code version specified and no active code version found. ' +
+                            'Specify a code version using one of: ' +
+                            '--code-version flag, SFCC_CODE_VERSION environment variable, ' +
+                            'or code-version field in dw.json configuration file.');
+                    }
+                    codeVersion = active.id;
+                    instance.config.codeVersion = codeVersion;
+                }
+                // Resolve directory path: relative paths are resolved relative to working directory, absolute paths are used as-is
+                const directory = args.directory
+                    ? path.isAbsolute(args.directory)
+                        ? args.directory
+                        : path.resolve(context.services.getWorkingDirectory(), args.directory)
+                    : context.services.getWorkingDirectory();
+                // Parse options
+                const options = {
+                    include: args.cartridges,
+                    exclude: args.exclude,
+                    reload: args.reload,
+                };
+                // Log all computed variables before deploying
+                logger.debug({
+                    directory,
+                    codeVersion,
+                    include: options.include,
+                    exclude: options.exclude,
+                    reload: options.reload,
+                }, '[Cartridges] Deploying cartridges with computed options');
+                // Deploy cartridges
+                const result = await findAndDeployCartridgesFn(instance, directory, options);
+                return result;
+            }
+            catch (error) {
+                // Handle communication and authentication errors
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                throw new Error(`Failed to communicate with B2C instance. Check your authentication credentials and network connection. ` +
+                    `If no code version is specified, ensure the instance is accessible and has an active code version. ` +
+                    `Original error: ${errorMessage}`);
+            }
         },
         formatOutput: (output) => jsonResult(output),
-    }, services);
+    }, loadServices);
 }
 /**
  * Creates all tools for the CARTRIDGES toolset.
  *
- * @param services - MCP services
+ * @param loadServices - Function that loads configuration and returns Services instance
  * @param injections - Optional dependency injections for testing
  * @returns Array of MCP tools
  */
-export function createCartridgesTools(services, injections) {
-    return [createCartridgeDeployTool(services, injections)];
+export function createCartridgesTools(loadServices, injections) {
+    return [createCartridgeDeployTool(loadServices, injections)];
 }
 //# sourceMappingURL=index.js.map

package/dist/tools/index.d.ts

@@ -14,4 +14,5 @@ export * from './adapter.js';
 export * from './cartridges/index.js';
 export * from './mrt/index.js';
 export * from './pwav3/index.js';
+export * from './scapi/index.js';
 export * from './storefrontnext/index.js';

package/dist/tools/index.js

@@ -21,5 +21,6 @@ export * from './adapter.js';
 export * from './cartridges/index.js';
 export * from './mrt/index.js';
 export * from './pwav3/index.js';
+export * from './scapi/index.js';
 export * from './storefrontnext/index.js';
 //# sourceMappingURL=index.js.map

package/dist/tools/mrt/index.d.ts

@@ -12,9 +12,9 @@ interface MrtToolInjections {
 /**
  * Creates all tools for the MRT toolset.
  *
- * @param services - MCP services
+ * @param loadServices - Function that loads configuration and returns Services instance
  * @param injections - Optional dependency injections for testing
  * @returns Array of MCP tools
  */
-export declare function createMrtTools(services: Services, injections?: MrtToolInjections): McpTool[];
+export declare function createMrtTools(loadServices: () => Services, injections?: MrtToolInjections): McpTool[];
 export {};

package/dist/tools/mrt/index.js

@@ -10,6 +10,7 @@
  *
  * @module tools/mrt
  */
+import path from 'node:path';
 import { z } from 'zod';
 import { createToolAdapter, jsonResult } from '../adapter.js';
 import { pushBundle } from '@salesforce/b2c-tooling-sdk/operations/mrt';
@@ -17,20 +18,20 @@ import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
 /**
  * Creates the mrt_bundle_push tool.
  *
- * Creates a bundle from a pre-built PWA Kit project and pushes it to
+ * Creates a bundle from a pre-built PWA Kit or Storefront Next project and pushes it to
  * Managed Runtime (MRT). Optionally deploys to a target environment after push.
  * Expects the project to already be built (e.g., `npm run build` completed).
  * Shared across MRT, PWAV3, and STOREFRONTNEXT toolsets.
  *
- * @param services - MCP services
+ * @param loadServices - Function that loads configuration and returns Services instance
  * @param injections - Optional dependency injections for testing
  * @returns The mrt_bundle_push tool
  */
-function createMrtBundlePushTool(services, injections) {
+function createMrtBundlePushTool(loadServices, injections) {
     const pushBundleFn = injections?.pushBundle || pushBundle;
     return createToolAdapter({
         name: 'mrt_bundle_push',
-        description: 'Bundle a pre-built PWA Kit project and push to Managed Runtime. Optionally deploy to a target environment.',
+        description: 'Bundle a pre-built PWA Kit or Storefront Next project and push to Managed Runtime. Optionally deploy to a target environment.',
         toolsets: ['MRT', 'PWAV3', 'STOREFRONTNEXT'],
         isGA: false,
         // MRT operations use ApiKeyStrategy from SFCC_MRT_API_KEY or ~/.mobify
@@ -46,6 +47,11 @@ function createMrtBundlePushTool(services, injections) {
                 .string()
                 .optional()
                 .describe('Glob patterns for shared files, comma-separated (default: static/**/*,client/**/*)'),
+            deploy: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Whether to deploy to an environment after push (default: false)'),
         },
         async execute(args, context) {
             // Get project from --project flag (required)
@@ -54,13 +60,26 @@ function createMrtBundlePushTool(services, injections) {
                 throw new Error('MRT project error: Project is required. Provide --project flag or set SFCC_MRT_PROJECT environment variable.');
             }
             // Get environment from --environment flag (optional)
-            const environment = context.mrtConfig?.environment;
+            // When deploy is false, environment is undefined (bundle push only, no deployment)
+            // When deploy is true, environment is required
+            let environment;
+            if (args.deploy) {
+                environment = context.mrtConfig?.environment;
+                if (!environment) {
+                    throw new Error('MRT deployment error: Environment is required when deploy=true. ' +
+                        'Provide --environment flag, set SFCC_MRT_ENVIRONMENT environment variable, or set mrtEnvironment in dw.json.');
+                }
+            }
             // Get origin from --cloud-origin flag or mrtOrigin config (optional)
             const origin = context.mrtConfig?.origin;
             // Parse comma-separated glob patterns (same as CLI defaults)
             const ssrOnly = (args.ssrOnly || 'ssr.js,ssr.mjs,server/**/*').split(',').map((s) => s.trim());
             const ssrShared = (args.ssrShared || 'static/**/*,client/**/*').split(',').map((s) => s.trim());
-            const buildDirectory = args.buildDirectory || './build';
+            const buildDirectory = args.buildDirectory
+                ? path.isAbsolute(args.buildDirectory)
+                    ? args.buildDirectory
+                    : path.resolve(context.services.getWorkingDirectory(), args.buildDirectory)
+                : path.join(context.services.getWorkingDirectory(), 'build');
             // Log all computed variables before pushing bundle
             const logger = getLogger();
             logger.debug({
@@ -86,16 +105,16 @@ function createMrtBundlePushTool(services, injections) {
             return result;
         },
         formatOutput: (output) => jsonResult(output),
-    }, services);
+    }, loadServices);
 }
 /**
  * Creates all tools for the MRT toolset.
  *
- * @param services - MCP services
+ * @param loadServices - Function that loads configuration and returns Services instance
  * @param injections - Optional dependency injections for testing
  * @returns Array of MCP tools
  */
-export function createMrtTools(services, injections) {
-    return [createMrtBundlePushTool(services, injections)];
+export function createMrtTools(loadServices, injections) {
+    return [createMrtBundlePushTool(loadServices, injections)];
 }
 //# sourceMappingURL=index.js.map