@salesforce/b2c-dx-mcp 3.0.1 → 3.1.1

package/content/guidance/mcp/scapi/SKILL.md

@@ -33,18 +33,18 @@ runtime support, not configured access; `op.security` gives scopes.
 Use these API IDs to narrow discovery; inspect the operation's inputs before calling.
 Snippet names below have the `builtin/` prefix. Describe only the relevant snippet.
 
-| Task | API / starting point |
-| --- | --- |
-| Review runs, including successes | `operation/jobs/v1`: `searchJobExecutions`; `job-execution-review` snippet |
-| Inspect steps and exact log path | `operation/jobs/v1`: `getJobExecution`; `job-execution-inspect` snippet |
-| Investigate failures with detail reads | `failed-job-triage` snippet; [jobs](references/jobs.md) |
-| Start a job / stop an execution | `operation/jobs/v1`: `createJobExecution` / `deleteJobExecution`; confirm intent and active runs first |
-| Active/rollback versions, activation metadata | `dx/scripts/v1`: `getCodeVersions`; `code-version-inspect` snippet |
-| Activate/create/delete a code version | `dx/scripts/v1`: `updateCodeVersion` / `createCodeVersion` / `deleteCodeVersion` |
-| Site status, catalog, ordered cartridge path | `site/sites/v1`: `getSiteById`; `site-cartridge-inspect` snippet |
-| Change a site's custom cartridge path | `site/sites/v1`: `replaceSiteCustomCartridges`; preserve order and unrelated entries |
-| Basic product + optional category assignment | `create-product` snippet; [products](references/products.md) |
-| Campaign assignments and promotion details | `campaign-promotions` snippet; [promotions](references/promotions.md) |
+| Task                                          | API / starting point                                                                                   |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Review runs, including successes              | `operation/jobs/v1`: `searchJobExecutions`; `job-execution-review` snippet                             |
+| Inspect steps and exact log path              | `operation/jobs/v1`: `getJobExecution`; `job-execution-inspect` snippet                                |
+| Investigate failures with detail reads        | `failed-job-triage` snippet; [jobs](references/jobs.md)                                                |
+| Start a job / stop an execution               | `operation/jobs/v1`: `createJobExecution` / `deleteJobExecution`; confirm intent and active runs first |
+| Active/rollback versions, activation metadata | `dx/scripts/v1`: `getCodeVersions`; `code-version-inspect` snippet                                     |
+| Activate/create/delete a code version         | `dx/scripts/v1`: `updateCodeVersion` / `createCodeVersion` / `deleteCodeVersion`                       |
+| Site status, catalog, ordered cartridge path  | `site/sites/v1`: `getSiteById`; `site-cartridge-inspect` snippet                                       |
+| Change a site's custom cartridge path         | `site/sites/v1`: `replaceSiteCustomCartridges`; preserve order and unrelated entries                   |
+| Basic product + optional category assignment  | `create-product` snippet; [products](references/products.md)                                           |
+| Campaign assignments and promotion details    | `campaign-promotions` snippet; [promotions](references/promotions.md)                                  |
 
 File content is WebDAV: `webdav_list` / `webdav_get` / `webdav_put`.
 Deploy local cartridge files with `cartridge_deploy`. Job schedules/definitions
@@ -115,16 +115,48 @@ These are conditional setup references, not additional prerequisite reads.
   no program replay or automatic cleanup deletion.
 - Filter/page at the API, then project/aggregate in code. Include IDs, verification
   fields, errors, totals, and continuation inputs. Do not crop away missing data.
-- Limits: 20 calls, four concurrent, 30 seconds, 24 KB returned. Narrow oversized
+- Limits: 20 calls, four outstanding, 30 seconds of active execution, 24 KB returned.
+  Managed API/token calls are serialized within an execution. Narrow oversized
   discovery; reduce live pages/projections.
 - SDK safety applies per request, including POST searches. Use only authorized
-  targeted exceptions. Confirmation-required requests stop. Code mode does not
+  targeted exceptions. Confirmation uses client elicitation; see below. Code mode does not
   transfer binaries; use WebDAV tools for instance files, an external client for
   binary SCAPI endpoints.
 - `fetch` and `WebSocket` are disabled. Use `scapi.request()` inside programs;
   direct HTTP belongs in an external client, outside MCP Safety Mode. Do not use
   imports or other Node networking APIs to bypass this boundary.
 
+## Confirmation and cancellation
+
+- A request requiring approval retains the running program and returns MCP
+  `input_required`. Let the client handle elicitation and the protocol retry;
+  never manufacture approval responses or modify opaque `requestState`.
+- Retries validate the original code, input, and target arguments, then resume
+  the same execution. Repeated code is **not evaluated again**. Each request
+  needs its own approval; a whole program is not a transaction.
+- Later managed calls wait for the pending decision. Earlier writes remain
+  applied. Prompts identify the organization, operation, method/path, and execution
+  ID. JSON previews are redacted and capped at five lines/400 characters; marked
+  truncation does not limit approval, which covers the full request.
+  Results include operation outcomes; `unknown` requires
+  checking the affected records before a fresh attempt.
+- Decline/cancel terminates the entire execution, even if code catches errors.
+  Explicitly stop work with `scapi_execute({action: "cancel", executionId, skillRead: true})`;
+  omit code, input, project overrides, and protocol continuation state.
+- Approval has no server deadline; waiting does not consume the active runtime
+  budget. At most four executions may be active per server, including pending
+  approvals. Cancel unwanted work to free a slot. Server shutdown or disconnect
+  releases retained workers; state does not survive a restart. Clients may impose
+  their own timeout. Duplicate responses never replay code or send a request twice.
+- To change code/input/target, cancel unwanted retained work and start a fresh
+  execution without continuation state. Cancellation does not roll back writes.
+  Clients without form elicitation stop at confirmation-required requests.
+
+For safety levels, rule matching, configuration precedence, and confirmation
+semantics, read `docs_read({query: "guide-safety"})` when needed. If docs tools
+are unavailable, use the [Safety Mode guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/safety.md).
+This is an optional policy reference, not another prerequisite read.
+
 ## Reusable workflows
 
 Find workflows with `codemode.search(query)`; `codemode.describe(name)`

package/dist/commands/mcp.js

@@ -200,7 +200,7 @@ export default class McpServerCommand extends BaseCommand {
         'docs-topics': Flags.string({
             description: 'Limit the documentation exposed by the docs tools to these categories (comma-separated allowlist). ' +
                 'Options: script-api, job-step, commerce-api, pwa-kit-managed-runtime, sfnext, sfra, b2c-commerce, tooling, ' +
-                'help-admin, help-merchant. ' +
+                'help-admin, help-merchant, help-kb. ' +
                 'Bounds the whole docs corpus; per-call category/storefront narrow within it. Unknown names are ignored.',
             env: 'SFCC_DOCS_TOPICS',
         }),

package/dist/guidance.js

@@ -36,8 +36,6 @@ const inputSchema = {
 const collectionSchema = z.object({
     id: z.string(),
     title: z.string(),
-    isGA: z.boolean(),
-    workspaces: z.array(z.string()).optional(),
 });
 const pageFields = {
     collections: z.array(collectionSchema),

package/dist/registry.js

@@ -40,7 +40,7 @@ export function createToolRegistry(loadServices, serverContext, detectedWorkspac
         ...createDiagnosticsTools(loadServices, serverContext),
         ...createDocsTools(loadServices, { detectedWorkspaces, enabledCategories: enabledDocCategories }),
         ...createMrtTools(loadServices),
-        ...createScapiTools(loadServices),
+        ...createScapiTools(loadServices, serverContext?.scapiExecutions),
         createGuidanceTool(),
     ];
     // Organize tools by their declared toolsets (supports multi-toolset)

package/dist/server-context.d.ts

@@ -1,6 +1,7 @@
 import { LogWatchRegistry } from './tools/diagnostics/log-watch-registry.js';
 import { MrtLogWatchRegistry } from './tools/diagnostics/mrt-log-watch-registry.js';
 import { DebugSessionRegistry } from './tools/diagnostics/session-registry.js';
+import { ScapiExecutionRegistry } from './tools/scapi/execution-registry.js';
 /**
  * Server-scoped persistent state that lives for the lifetime of the MCP
  * server process. Holds registries for stateful resources (debug sessions,
@@ -27,6 +28,7 @@ export declare class ServerContext {
     readonly debugSessions: DebugSessionRegistry;
     readonly logWatches: LogWatchRegistry;
     readonly mrtLogWatches: MrtLogWatchRegistry;
+    readonly scapiExecutions: ScapiExecutionRegistry;
     constructor();
     destroyAll(): Promise<void>;
 }

package/dist/server-context.js

@@ -6,6 +6,7 @@
 import { LogWatchRegistry } from './tools/diagnostics/log-watch-registry.js';
 import { MrtLogWatchRegistry } from './tools/diagnostics/mrt-log-watch-registry.js';
 import { DebugSessionRegistry } from './tools/diagnostics/session-registry.js';
+import { ScapiExecutionRegistry } from './tools/scapi/execution-registry.js';
 /**
  * Server-scoped persistent state that lives for the lifetime of the MCP
  * server process. Holds registries for stateful resources (debug sessions,
@@ -32,16 +33,19 @@ export class ServerContext {
     debugSessions;
     logWatches;
     mrtLogWatches;
+    scapiExecutions;
     constructor() {
         this.debugSessions = new DebugSessionRegistry();
         this.logWatches = new LogWatchRegistry();
         this.mrtLogWatches = new MrtLogWatchRegistry();
+        this.scapiExecutions = new ScapiExecutionRegistry();
     }
     async destroyAll() {
         await Promise.allSettled([
             this.debugSessions.destroyAll(),
             this.logWatches.destroyAll(),
             this.mrtLogWatches.destroyAll(),
+            this.scapiExecutions.destroyAll(),
         ]);
     }
 }

package/dist/server.d.ts

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/server';
 import type { CallToolResult, Implementation, ReadResourceResult, ToolAnnotations, ServerOptions, Transport } from '@modelcontextprotocol/server';
 import { type ZodRawShape } from 'zod';
 import type { Telemetry } from '@salesforce/b2c-tooling-sdk/telemetry';
-import type { McpToolConfig } from './utils/types.js';
+import type { McpToolConfig, ToolContext } from './utils/types.js';
 /**
  * Extended server options.
  */
@@ -45,9 +45,7 @@ export declare class B2CDxMcpServer extends McpServer {
      * @param inputSchema - Zod schema for input validation
      * @param handler - Function to handle tool invocations
      */
-    addTool(name: string, description: string, inputSchema: ZodRawShape, handler: (args: Record<string, unknown>, context?: {
-        signal?: AbortSignal;
-    }) => Promise<CallToolResult>, metadata?: Pick<McpToolConfig, 'outputSchema' | 'title'> & {
+    addTool(name: string, description: string, inputSchema: ZodRawShape, handler: (args: Record<string, unknown>, context?: ToolContext) => Promise<CallToolResult>, metadata?: Pick<McpToolConfig, 'outputSchema' | 'title'> & {
         annotations?: ToolAnnotations;
     }): void;
     close(): Promise<void>;

package/dist/server.js

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
-import { McpServer, ProtocolError, ProtocolErrorCode, CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY, } from '@modelcontextprotocol/server';
+import { McpServer, ProtocolError, ProtocolErrorCode, CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY, CLIENT_CAPABILITIES_META_KEY, } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
 /**
@@ -25,7 +25,11 @@ export class B2CDxMcpServer extends McpServer {
      */
     constructor(serverInfo, options) {
         const { cleanup, telemetry, ...serverOptions } = options ?? {};
-        super(serverInfo, serverOptions);
+        // The bundled SDK patch supports zero for human-paced approval with no server deadline.
+        super(serverInfo, {
+            ...serverOptions,
+            inputRequired: { maxRounds: 20, roundTimeoutMs: 0, ...serverOptions.inputRequired },
+        });
         this.cleanup = cleanup;
         this.telemetry = telemetry;
         // Set up oninitialized handler
@@ -70,7 +74,16 @@ export class B2CDxMcpServer extends McpServer {
                 this.telemetry?.addAttributes({ clientName: clientInfo.name, clientVersion: clientInfo.version });
             const startTime = Date.now();
             try {
-                const result = await handler(args, { signal: context.mcpReq?.signal });
+                const envelope = context.mcpReq?.envelope;
+                const capabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY] ?? this.server.getClientCapabilities();
+                const elicitation = capabilities?.elicitation;
+                const result = await handler(args, {
+                    signal: context.mcpReq?.signal,
+                    requestState: context.mcpReq?.requestState?.(),
+                    inputResponses: context.mcpReq?.inputResponses,
+                    supportsElicitation: elicitation !== undefined && (elicitation.form !== undefined || Object.keys(elicitation).length === 0),
+                    keepCancellation: !envelope?.[PROTOCOL_VERSION_META_KEY],
+                });
                 const runTimeMs = Date.now() - startTime;
                 // Extract error message from CallToolResult content when isError is true
                 const errorMessage = result.isError ? result.content?.find((c) => c.type === 'text')?.text : undefined;

package/dist/services.d.ts

@@ -19,8 +19,8 @@
  *
  * ## Resolution Pattern
  *
- * Both B2CInstance and MRT auth are resolved once at server startup (not on each tool call).
- * This provides fail-fast behavior and consistent performance.
+ * B2C instance and MRT auth are resolved for each tool call, so edits to project
+ * configuration are picked up without restarting the server.
  *
  * **B2C Instance** (for WebDAV/OCAPI tools):
  * - Flags (highest priority) merged with dw.json (auto-discovered or via --config)
@@ -39,7 +39,7 @@
 import fs from 'node:fs';
 import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
 import type { AuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
-import type { ResolvedB2CConfig } from '@salesforce/b2c-tooling-sdk/config';
+import { type ResolvedB2CConfig } from '@salesforce/b2c-tooling-sdk/config';
 import type { ConfigurationResolutionSource, ProjectDirectoryInfo, ToolResolution } from './tools/project-context.js';
 import { WebDavClient, type CustomApisClient, type MetricsClient, type ScapiSchemasClient } from '@salesforce/b2c-tooling-sdk/clients';
 /**
@@ -101,13 +101,13 @@ export interface ServicesResolutionInputs {
 export declare class Services {
     /**
      * Pre-resolved B2C instance for WebDAV/OCAPI operations.
-     * Resolved once at server startup from InstanceCommand flags and dw.json.
+     * Resolved for this tool call from server flags and project configuration.
      * Undefined if no B2C instance configuration was available.
      */
     readonly b2cInstance?: B2CInstance;
     /**
      * Pre-resolved MRT configuration (auth, project, environment, origin).
-     * Resolved once at server startup from MrtCommand flags and ~/.mobify.
+     * Resolved for this tool call from server flags and MRT configuration.
      */
     readonly mrtConfig: MrtConfig;
     /**
@@ -310,6 +310,8 @@ export declare class Services {
      * @returns Resolved absolute path
      */
     resolveWithProjectDirectory(pathArg?: string, projectDirectoryOverride?: string): string;
+    /** Run a tool with its resolved safety policy, without changing other calls. */
+    runWithSafety<T>(callback: () => T): T;
     /**
      * Get file or directory stats.
      *

package/dist/services.js

@@ -24,8 +24,8 @@
  *
  * ## Resolution Pattern
  *
- * Both B2CInstance and MRT auth are resolved once at server startup (not on each tool call).
- * This provides fail-fast behavior and consistent performance.
+ * B2C instance and MRT auth are resolved for each tool call, so edits to project
+ * configuration are picked up without restarting the server.
  *
  * **B2C Instance** (for WebDAV/OCAPI tools):
  * - Flags (highest priority) merged with dw.json (auto-discovered or via --config)
@@ -44,7 +44,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { createCustomApisClient, createMetricsClient, createScapiSchemasClient, toOrganizationId, WebDavClient, } from '@salesforce/b2c-tooling-sdk/clients';
+import { getB2CConfigDirectory } from '@salesforce/b2c-tooling-sdk/config';
+import { SafetyGuard, resolveEffectiveSafetyConfig, loadGlobalSafetyConfig } from '@salesforce/b2c-tooling-sdk/safety';
+import { createCustomApisClient, createMetricsClient, createScapiSchemasClient, toOrganizationId, WebDavClient, globalMiddlewareRegistry, createSafetyMiddleware, } from '@salesforce/b2c-tooling-sdk/clients';
 function createToolResolution(config, inputs) {
     const configuredProjectDirectory = config.values.projectDirectory;
     const projectDirectory = inputs?.projectDirectory ??
@@ -87,13 +89,13 @@ function createToolResolution(config, inputs) {
 export class Services {
     /**
      * Pre-resolved B2C instance for WebDAV/OCAPI operations.
-     * Resolved once at server startup from InstanceCommand flags and dw.json.
+     * Resolved for this tool call from server flags and project configuration.
      * Undefined if no B2C instance configuration was available.
      */
     b2cInstance;
     /**
      * Pre-resolved MRT configuration (auth, project, environment, origin).
-     * Resolved once at server startup from MrtCommand flags and ~/.mobify.
+     * Resolved for this tool call from server flags and MRT configuration.
      */
     mrtConfig;
     /**
@@ -339,9 +341,6 @@ export class Services {
     listDirectory(dirPath) {
         return fs.readdirSync(dirPath, { withFileTypes: true });
     }
-    // ============================================
-    // SCAPI Helper Methods
-    // ============================================
     /**
      * Read a file from the filesystem.
      *
@@ -352,6 +351,9 @@ export class Services {
     readFile(filePath, encoding = 'utf8') {
         return fs.readFileSync(filePath, { encoding });
     }
+    // ============================================
+    // SCAPI Helper Methods
+    // ============================================
     /**
      * Resolve a path relative to the current working directory.
      *
@@ -414,6 +416,15 @@ export class Services {
         }
         return path.resolve(projectDir, pathArg);
     }
+    /** Run a tool with its resolved safety policy, without changing other calls. */
+    runWithSafety(callback) {
+        const environment = Object.fromEntries(['SFCC_SAFETY_LEVEL', 'SFCC_SAFETY_CONFIRM', 'SFCC_SAFETY_CONFIG'].map((name) => [
+            name,
+            this.getEnvironmentVariable(name),
+        ]));
+        const guard = new SafetyGuard(resolveEffectiveSafetyConfig(this.resolvedConfig.values.safety, loadGlobalSafetyConfig(getB2CConfigDirectory(), environment, this.resolution.projectDirectory.path), environment));
+        return globalMiddlewareRegistry.runWithOverrides([{ name: 'cli-safety-guard', getMiddleware: () => createSafetyMiddleware(guard) }], callback);
+    }
     /**
      * Get file or directory stats.
      *

package/dist/tools/adapter.js

@@ -271,7 +271,7 @@ export function createToolAdapter(options, loadServices, serverContext) {
                         executionResolution.directories[name] = value;
                     },
                 };
-                const output = await execute(args, context);
+                const output = await services.runWithSafety(() => execute(args, context));
                 // 6. Format output
                 const result = formatOutput(output);
                 return resolution ? attachResolution(result, executionResolution) : result;

package/dist/tools/scapi/execution-registry.d.ts

@@ -0,0 +1,62 @@
+import type { ScapiConfirmation, ScapiRuntimeControl } from '@salesforce/b2c-tooling-sdk/scapi';
+import type { ToolContext, ToolResult } from '../../utils/types.js';
+declare function deferred<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason: Error) => void;
+};
+interface OperationRecord {
+    kind: 'auth' | 'request';
+    method?: string;
+    path?: string;
+    status: 'awaiting_confirmation' | 'completed' | 'failed' | 'in_flight' | 'not_sent' | 'unknown';
+    httpStatus?: number;
+}
+interface ApprovalRound {
+    state: string;
+    key: string;
+    prompt: ToolResult;
+    decision: ReturnType<typeof deferred<void>>;
+    responded?: boolean;
+}
+/** One worker survives protocol round trips; none of its code is replayed. */
+export declare class ScapiExecution {
+    readonly digest: string;
+    private readonly supportsElicitation;
+    private readonly mintState;
+    control?: ScapiRuntimeControl;
+    readonly controller: AbortController;
+    done: Promise<void>;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    readonly operations: OperationRecord[];
+    result?: ToolResult;
+    readonly rounds: Map<string, ApprovalRound>;
+    private cancellation?;
+    private cancellationListeners;
+    private dispatched;
+    private event;
+    private pending?;
+    private queue;
+    constructor(digest: string, supportsElicitation: boolean, mintState: (round: number) => string);
+    cancel(reason?: string): void;
+    confirm(request: ScapiConfirmation): Promise<void>;
+    finish(result: ToolResult): void;
+    markDispatched(): void;
+    retry(state: string, context: ToolContext): Promise<ToolResult>;
+    runCall<T>(kind: OperationRecord['kind'], input: unknown, operation: () => Promise<T>): Promise<T>;
+    wait(context?: ToolContext): Promise<ToolResult>;
+}
+/** Stdio-server-owned continuations. Terminal records are bounded; tokens never start new work. */
+export declare class ScapiExecutionRegistry {
+    private readonly options;
+    private readonly executions;
+    private readonly secret;
+    constructor(options?: {
+        maxActive?: number;
+    });
+    cancel(id: string): Promise<ToolResult>;
+    destroyAll(): Promise<void>;
+    retry(args: unknown, context: ToolContext): Promise<ToolResult>;
+    start(args: unknown, context: ToolContext | undefined, run: (execution: ScapiExecution) => Promise<ToolResult>): Promise<ToolResult>;
+}
+export {};