@salesforce/b2c-dx-mcp 2.1.2 → 3.0.1

package/dist/tools/cartridges/index.js

@@ -11,11 +11,12 @@
  * @module tools/cartridges
  */
 import { z } from 'zod';
+import { deploySelectedFiles } from './selected-files.js';
 import { createToolAdapter, jsonResult } from '../adapter.js';
-import { findAndDeployCartridges, getActiveCodeVersion } from '@salesforce/b2c-tooling-sdk/operations/code';
+import { createScriptsBackend, findAndDeployCartridges, getActiveCodeVersion, } from '@salesforce/b2c-tooling-sdk/operations/code';
 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: " +
+const CARTRIDGE_PATH_REMINDER = "For a new cartridge, add it to your site's cartridge path in Business Manager: " +
     'Sites → Manage Sites → [your site] → Settings tab → Cartridges field.';
 /**
  * Creates the cartridge_deploy tool.
@@ -35,13 +36,27 @@ function createCartridgeDeployTool(loadServices, injections) {
     const getActiveCodeVersionFn = injections?.getActiveCodeVersion || getActiveCodeVersion;
     return createToolAdapter({
         name: 'cartridge_deploy',
-        description: 'Find and deploy cartridges to B2C Commerce via WebDAV. Supports include/exclude filters and code-version reload. ' +
+        effect: 'destructive',
+        idempotent: false,
+        openWorld: true,
+        description: 'Find and deploy cartridges or selected files to B2C Commerce via WebDAV; overwrites matching remote files. ' +
             "After deployment, add new cartridges to the site's cartridge path in Business Manager: Sites → Manage Sites → Settings tab → Cartridges.",
         toolsets: ['CARTRIDGES'],
-        isGA: true,
         requiresInstance: true,
         usesProjectContext: true,
         inputSchema: {
+            codeVersion: z
+                .string()
+                .regex(/^(?!\.{1,2}$)[A-Za-z0-9_.-]+$/)
+                .max(256)
+                .optional()
+                .describe('Target version; defaults to configured, then active version.'),
+            files: z
+                .array(z.string().min(1))
+                .min(1)
+                .max(100)
+                .optional()
+                .describe('Files within selected cartridges, relative to projectDirectory. Max 64 MiB; preserves other remote files.'),
             cartridgeDirectory: z
                 .string()
                 .optional()
@@ -55,18 +70,24 @@ function createCartridgeDeployTool(loadServices, injections) {
                 .optional()
                 .describe('Cartridge names to deploy; omit for all discovered cartridges.'),
             exclude: z.array(z.string()).optional().describe('Cartridge names to exclude after the include filter.'),
-            reload: z.boolean().optional().describe('Reload the code version after deployment. Default: false.'),
+            reload: z
+                .boolean()
+                .optional()
+                .describe('Activate/reload the target after upload, briefly toggling versions if already active. Default: false.'),
         },
         async execute(args, context) {
             // Get instance from context (guaranteed by adapter when requiresInstance is true)
             const instance = context.b2cInstance;
             const logger = getLogger();
             try {
+                const scriptsBackend = createScriptsBackend({ instance });
                 // If no code version specified, get the active one
-                let codeVersion = instance.config.codeVersion;
+                let codeVersion = args.codeVersion ?? instance.config.codeVersion;
                 if (!codeVersion) {
                     logger.debug('No code version specified, getting active version...');
-                    const active = await getActiveCodeVersionFn(instance);
+                    const active = injections?.getActiveCodeVersion
+                        ? await getActiveCodeVersionFn(instance)
+                        : await scriptsBackend.getActiveCodeVersion();
                     if (!active?.id) {
                         throw new Error('No code version specified and no active code version found. ' +
                             'Specify a code version using one of: ' +
@@ -74,8 +95,10 @@ function createCartridgeDeployTool(loadServices, injections) {
                             'or code-version field in dw.json configuration file.');
                     }
                     codeVersion = active.id;
-                    instance.config.codeVersion = codeVersion;
                 }
+                if (!/^(?!\.{1,2}$)[A-Za-z0-9_.-]+$/.test(codeVersion))
+                    throw new Error('Invalid code version: use a version ID, not a path.');
+                instance.config.codeVersion = codeVersion;
                 // Resolve directory path: relative paths are resolved relative to project directory, absolute paths are used as-is
                 const projectDirectory = context.services.resolveProjectDirectory(args.projectDirectory);
                 const directoryArgument = args.cartridgeDirectory ?? args.directory;
@@ -86,6 +109,7 @@ function createCartridgeDeployTool(loadServices, injections) {
                 });
                 // Parse options
                 const options = {
+                    scriptsBackend,
                     include: args.cartridges,
                     exclude: args.exclude,
                     reload: args.reload,
@@ -99,20 +123,19 @@ function createCartridgeDeployTool(loadServices, injections) {
                     reload: options.reload,
                 }, '[Cartridges] Deploying cartridges with computed options');
                 // Deploy cartridges
-                const result = await findAndDeployCartridgesFn(instance, directory, options);
+                const result = args.files
+                    ? await deploySelectedFiles(instance, directory, projectDirectory.path, args.files, options)
+                    : await findAndDeployCartridgesFn(instance, directory, options);
                 return {
                     ...result,
                     projectDirectory,
                     resolvedDirectory: directory,
-                    postInstructions: CARTRIDGE_PATH_REMINDER,
+                    ...(args.files ? {} : { postInstructions: CARTRIDGE_PATH_REMINDER }),
                 };
             }
             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}`);
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Cartridge deployment failed: ${message}`);
             }
         },
         formatOutput: (output) => jsonResult(output),

package/dist/tools/cartridges/selected-files.d.ts

@@ -0,0 +1,11 @@
+import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
+import { type DeployOptions } from '@salesforce/b2c-tooling-sdk/operations/code';
+/** Validate the complete selection before creating or uploading an archive. */
+export declare function deploySelectedFiles(instance: B2CInstance, directory: string, projectDirectory: string, files: string[], options: DeployOptions): Promise<{
+    warnings?: string[] | undefined;
+    cartridges: import("@salesforce/b2c-tooling-sdk").CartridgeMapping[];
+    codeVersion: string;
+    activated: boolean;
+    reloaded: boolean;
+    uploadedFiles: string[];
+}>;

package/dist/tools/cartridges/selected-files.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * 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
+ */
+/* eslint-disable no-await-in-loop -- Validate each selected file before the upload starts. */
+import { realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { findCartridges, fileToCartridgePath, uploadFiles, reloadCodeVersion, } from '@salesforce/b2c-tooling-sdk/operations/code';
+/** Validate the complete selection before creating or uploading an archive. */
+export async function deploySelectedFiles(instance, directory, projectDirectory, files, options) {
+    const cartridges = findCartridges(directory, options);
+    const uploads = [];
+    const destinations = new Set();
+    for (const file of files) {
+        const src = path.resolve(projectDirectory, file);
+        const mapped = fileToCartridgePath(src, cartridges);
+        if (!mapped)
+            throw new Error(`File is outside the selected cartridges: ${file}`);
+        const cartridge = cartridges.find((c) => c.dest === mapped.dest.split('/')[0]);
+        const actual = await realpath(src);
+        const root = await realpath(cartridge.src);
+        if (!fileToCartridgePath(actual, [{ ...cartridge, src: root }]) || !(await stat(actual)).isFile()) {
+            throw new Error(`Source must be a regular file within its cartridge: ${file}`);
+        }
+        // eslint-disable-next-line no-control-regex -- Reject control characters in archive destinations.
+        if (mapped.dest.split('/').some((part) => !part || part === '..' || /[\\\u0000-\u001F]/.test(part))) {
+            throw new Error(`Invalid cartridge destination: ${file}`);
+        }
+        if (destinations.has(mapped.dest))
+            throw new Error(`Duplicate cartridge destination: ${mapped.dest}`);
+        destinations.add(mapped.dest);
+        uploads.push({ ...mapped, src: actual });
+    }
+    const codeVersion = instance.config.codeVersion;
+    const warnings = [];
+    await uploadFiles(instance, codeVersion, uploads, [], {
+        strict: true,
+        maxBytes: 64 * 1024 * 1024,
+        onWarning: (message) => warnings.push(message),
+    });
+    let reloaded = false;
+    if (options.reload) {
+        try {
+            await reloadCodeVersion(options.scriptsBackend, codeVersion);
+            reloaded = true;
+        }
+        catch (error) {
+            warnings.push(`Files uploaded, but code-version reload failed: ${String(error)}. Inspect the active version before retrying reload.`);
+        }
+    }
+    return {
+        cartridges: cartridges.filter((c) => uploads.some((f) => f.dest.startsWith(`${c.dest}/`))),
+        codeVersion,
+        activated: reloaded,
+        reloaded,
+        uploadedFiles: [...destinations],
+        ...(warnings.length > 0 ? { warnings } : {}),
+    };
+}
+//# sourceMappingURL=selected-files.js.map

package/dist/tools/cip/client.d.ts

@@ -0,0 +1,9 @@
+import type { Services } from '../../services.js';
+export declare function resolveCipClient(services: Services, signal: AbortSignal, staging?: boolean): {
+    client: import("@salesforce/b2c-tooling-sdk/clients").CipClient;
+    target: {
+        tenantId: string;
+        host: string;
+        scope: string;
+    };
+};

package/dist/tools/cip/client.js

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * 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 { createCipClient, DEFAULT_CIP_HOST, DEFAULT_CIP_STAGING_HOST, normalizeTenantId, MiddlewareRegistry, globalMiddlewareRegistry, createSafetyMiddleware, } from '@salesforce/b2c-tooling-sdk/clients';
+import { getB2CConfigDirectory } from '@salesforce/b2c-tooling-sdk/config';
+import { SafetyGuard, resolveEffectiveSafetyConfig, loadGlobalSafetyConfig } from '@salesforce/b2c-tooling-sdk/safety';
+export function resolveCipClient(services, signal, staging) {
+    const config = services.getResolvedConfig();
+    const { tenantId, clientId, clientSecret, authMethods } = config.values;
+    if (!tenantId || !clientId || !clientSecret)
+        throw new Error('CIP_CONFIG_REQUIRED: Configure tenantId, clientId, and clientSecret. Use config_inspect with secrets masked.');
+    if (authMethods?.some((method) => method !== 'client-credentials'))
+        throw new Error('CIP_AUTH_METHOD: CIP requires client-credentials authentication; user and JWT flows are unsupported.');
+    const instance = normalizeTenantId(tenantId);
+    if (!/^[a-z0-9]+_[a-z0-9]+$/i.test(instance))
+        throw new Error('CIP_CONFIG_REQUIRED: Invalid tenantId; use a tenant such as abcd_prd or abcd_001.');
+    const useStaging = staging ?? ['1', 'true'].includes(services.getEnvironmentVariable('SFCC_CIP_STAGING') ?? '');
+    const host = services.getEnvironmentVariable('SFCC_CIP_HOST') ??
+        config.values.cipHost ??
+        (useStaging || !instance.endsWith('_prd') ? DEFAULT_CIP_STAGING_HOST : DEFAULT_CIP_HOST);
+    const url = new URL(host.includes('://') ? host : `https://${host}`);
+    if (url.protocol !== 'https:' || url.username || url.password || url.pathname !== '/' || url.search || url.hash)
+        throw new Error('CIP_CONFIG_REQUIRED: cipHost must be an HTTPS hostname without credentials or a path.');
+    const safetyEnvironment = Object.fromEntries(['SFCC_SAFETY_LEVEL', 'SFCC_SAFETY_CONFIRM', 'SFCC_SAFETY_CONFIG'].map((name) => [
+        name,
+        services.getEnvironmentVariable(name),
+    ]));
+    const guard = new SafetyGuard(resolveEffectiveSafetyConfig(config.values.safety, loadGlobalSafetyConfig(getB2CConfigDirectory(), safetyEnvironment, services.getResolution().projectDirectory.path), safetyEnvironment));
+    // Replace only the startup policy with this call's resolved project policy; retain plugin middleware.
+    const middlewareRegistry = new (class extends MiddlewareRegistry {
+        getMiddleware() {
+            return [
+                ...globalMiddlewareRegistry.getMiddleware('cip', { exclude: ['cli-safety-guard'] }),
+                createSafetyMiddleware(guard),
+            ];
+        }
+    })();
+    const scope = `SALESFORCE_COMMERCE_API:${instance}`;
+    const client = createCipClient({ instance, host: url.host, signal, maxResponseBytes: 8 * 1024 * 1024, middlewareRegistry }, config.createOAuth({ allowedMethods: ['client-credentials'], scopes: [scope] }));
+    return { client, target: { tenantId: instance, host: url.host, scope } };
+}
+//# sourceMappingURL=client.js.map

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

@@ -0,0 +1,6 @@
+import type { McpTool } from '../../utils/types.js';
+import { type ServicesLoader } from '../adapter.js';
+import { resolveCipClient } from './client.js';
+export declare function createCipTools(loadServices: ServicesLoader, dependencies?: {
+    resolveClient: typeof resolveCipClient;
+}): McpTool[];

package/dist/tools/cip/index.js

@@ -0,0 +1,209 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * 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 { z } from 'zod';
+import { listCipReports, getCipReportByName, buildCipReportSql, listCipTables, describeCipTable, } from '@salesforce/b2c-tooling-sdk/operations/cip';
+import { jsonResult, attachResolution } from '../adapter.js';
+import { createProjectContextInputSchema } from '../project-context.js';
+import { MCP_SKILL_REFERENCES } from '../../skill-references.js';
+import { resolveCipClient } from './client.js';
+const MAX_OUTPUT_BYTES = 24_000;
+const params = z
+    .record(z.string(), z.string())
+    .optional()
+    .describe('Report parameters from discovery; string values, dates YYYY-MM-DD.');
+const connection = {
+    ...createProjectContextInputSchema('configuration'),
+    staging: z
+        .boolean()
+        .optional()
+        .describe('Force staging analytics host; otherwise infer from tenant. cipHost configuration takes precedence.'),
+};
+function result(data, resolution) {
+    const value = resolution ? attachResolution(jsonResult(data, 0), resolution, 0) : jsonResult(data, 0);
+    delete value.structuredContent;
+    return value;
+}
+function failure(error, resolution, target) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        ...result({
+            error: message.slice(0, 6000),
+            ...(target ? { target } : {}),
+            ...(/CIP_(CONFIG|AUTH)|\b(401|403)\b|invalid_(scope|client)|unauthorized|forbidden/i.test(message)
+                ? { skillReferences: [MCP_SKILL_REFERENCES.cipAccess] }
+                : {}),
+        }, resolution),
+        isError: true,
+    };
+}
+function size(value) {
+    return Buffer.byteLength(JSON.stringify(value));
+}
+function reportSql(name, values) {
+    const built = buildCipReportSql(name, values);
+    if (values.from && values.to && values.from > values.to)
+        throw new Error('from must be on or before to.');
+    return built.sql;
+}
+export function createCipTools(loadServices, dependencies) {
+    const resolveClient = dependencies?.resolveClient ?? resolveCipClient;
+    const discovery = {
+        ...connection,
+        action: z.enum(['reports', 'report', 'tables', 'table']).default('reports'),
+        query: z.string().max(200).optional().describe('Report search text or SQL LIKE table-name pattern.'),
+        name: z.string().min(1).max(200).optional().describe('Report or table name for detail actions.'),
+        params,
+        schema: z.string().min(1).max(200).default('warehouse'),
+        offset: z.number().int().min(0).max(1000).default(0),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe('Maximum results; default 50 columns, 20 reports/tables.'),
+    };
+    const execution = {
+        ...connection,
+        skillRead: z.boolean().optional().describe('True after reading the linked CIP skill.'),
+        report: z.string().min(1).max(100).optional().describe('Curated report name; supply report or sql.'),
+        params,
+        sql: z
+            .string()
+            .min(1)
+            .max(32_768)
+            .optional()
+            .describe('Analytics SELECT query; filter dates/sites and aggregate in SQL.'),
+        maxRows: z.number().int().min(1).max(500).default(50),
+        timeoutSeconds: z.number().int().min(1).max(120).default(60),
+    };
+    return [
+        {
+            name: 'cip_discover',
+            effect: 'read',
+            idempotent: true,
+            openWorld: true,
+            toolsets: ['CIP'],
+            description: 'Find CIP analytics reports and inspect parameters/SQL offline; list live warehouse tables or inspect columns. Narrow results before querying.',
+            inputSchema: discovery,
+            async handler(args, context) {
+                let resolution;
+                let target;
+                try {
+                    const input = z.object(discovery).strict().parse(args);
+                    const limit = input.limit ?? (input.action === 'table' ? 50 : 20);
+                    if ((input.action === 'report' || input.action === 'table') && !input.name)
+                        throw new Error('name is required for report/table details.');
+                    if (input.params && input.action !== 'report')
+                        throw new Error('params applies only to report SQL previews.');
+                    if (input.action === 'report') {
+                        const report = getCipReportByName(input.name);
+                        if (!report)
+                            throw new Error('Unknown report. Search reports with cip_discover.');
+                        const { buildSql: _buildSql, ...metadata } = report;
+                        return result({ ...metadata, ...(input.params ? { sql: reportSql(report.name, input.params) } : {}) });
+                    }
+                    if (input.action === 'reports') {
+                        const terms = (input.query ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+                        const reports = listCipReports().filter((r) => terms.every((term) => `${r.name} ${r.category} ${r.description}`.toLowerCase().includes(term)));
+                        const selected = reports.slice(input.offset, input.offset + limit);
+                        return result({
+                            total: reports.length,
+                            reports: selected.map(({ name, description, category }) => ({ name, description, category })),
+                            nextOffset: input.offset + selected.length < reports.length ? input.offset + selected.length : null,
+                        });
+                    }
+                    const services = await loadServices(input);
+                    resolution = services.getResolution();
+                    const timeout = AbortSignal.timeout(60_000);
+                    const resolved = resolveClient(services, context?.signal ? AbortSignal.any([context.signal, timeout]) : timeout, input.staging);
+                    const { client } = resolved;
+                    target = resolved.target;
+                    const options = { schema: input.schema, maxRows: input.offset + limit };
+                    const data = input.action === 'tables'
+                        ? await listCipTables(client, { ...options, tableType: 'TABLE', tableNamePattern: input.query })
+                        : await describeCipTable(client, input.name, options);
+                    const rows = 'tables' in data
+                        ? data.tables.map(({ tableName, tableType }) => ({ tableName, tableType }))
+                        : data.columns.map(({ columnName, dataType, isNullable }) => ({ columnName, dataType, isNullable }));
+                    const selected = rows.slice(input.offset);
+                    const response = result({
+                        target,
+                        schema: input.schema,
+                        ...(input.action === 'table' ? { table: input.name } : {}),
+                        [input.action === 'tables' ? 'tables' : 'columns']: selected,
+                        returned: selected.length,
+                        truncated: data.truncated ?? false,
+                        nextOffset: data.truncated && input.offset + selected.length <= 1000 ? input.offset + selected.length : null,
+                        ...(data.truncated && input.offset + selected.length > 1000
+                            ? { warning: 'Metadata paging limit reached. Narrow the table pattern or schema.' }
+                            : {}),
+                    }, resolution);
+                    if (size(response) > MAX_OUTPUT_BYTES)
+                        throw new Error('Metadata exceeds the output limit. Reduce limit or narrow query.');
+                    return response;
+                }
+                catch (error) {
+                    return failure(error, resolution, target);
+                }
+            },
+        },
+        {
+            name: 'cip_query',
+            effect: 'read',
+            idempotent: true,
+            openWorld: true,
+            toolsets: ['CIP'],
+            description: 'Query CIP analytics using a curated report or SQL. Read skill://mcp/cip/SKILL.md first. Returns bounded rows; filter/group in SQL. Warehouse data is not live SCAPI state.',
+            inputSchema: execution,
+            async handler(args, context) {
+                let resolution;
+                let target;
+                try {
+                    const input = z.object(execution).strict().parse(args);
+                    if (input.skillRead !== true)
+                        throw new Error('CIP_SKILL_REQUIRED: Read skill://mcp/cip/SKILL.md through resources or skills_read, then retry with skillRead: true.');
+                    if (Number(Boolean(input.report)) + Number(Boolean(input.sql)) !== 1)
+                        throw new Error('Supply exactly one of report or sql.');
+                    if (input.sql && input.params)
+                        throw new Error('params applies only to curated reports. Put custom query values in sql.');
+                    const sql = input.report ? reportSql(input.report, input.params ?? {}) : input.sql;
+                    const services = await loadServices(input);
+                    resolution = services.getResolution();
+                    const timeout = AbortSignal.timeout(input.timeoutSeconds * 1000);
+                    const resolved = resolveClient(services, context?.signal ? AbortSignal.any([context.signal, timeout]) : timeout, input.staging);
+                    const { client } = resolved;
+                    target = resolved.target;
+                    const data = await client.query(sql, { maxRows: input.maxRows });
+                    const output = {
+                        target,
+                        ...(input.report ? { report: input.report } : {}),
+                        columns: data.columns,
+                        rows: [...data.rows],
+                        rowCount: data.rowCount,
+                        truncated: data.truncated ?? false,
+                        truncationReason: data.truncated ? 'rows' : undefined,
+                    };
+                    let response = result(output, resolution);
+                    while (size(response) > MAX_OUTPUT_BYTES && output.rows.length > 0) {
+                        output.rows.pop();
+                        output.rowCount = output.rows.length;
+                        output.truncated = true;
+                        output.truncationReason = 'bytes';
+                        response = result(output, resolution);
+                    }
+                    if (size(response) > MAX_OUTPUT_BYTES || (data.rowCount > 0 && output.rowCount === 0))
+                        throw new Error('CIP result is too wide. Select fewer columns or aggregate in SQL.');
+                    return response;
+                }
+                catch (error) {
+                    return failure(error, resolution, target);
+                }
+            },
+        },
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/diagnostics/config-inspect.js

@@ -6,6 +6,7 @@
 import { z } from 'zod';
 import { redactConfigValues } from '@salesforce/b2c-tooling-sdk/config';
 import { createToolAdapter, jsonResult } from '../adapter.js';
+import { MCP_SKILL_REFERENCES } from '../../skill-references.js';
 /**
  * Creates the `config_inspect` tool — the MCP equivalent of the CLI
  * `b2c setup inspect` command. Reports the resolved configuration (with secrets
@@ -18,10 +19,12 @@ import { createToolAdapter, jsonResult } from '../adapter.js';
 export function createConfigInspectTool(loadServices) {
     return createToolAdapter({
         name: 'config_inspect',
-        description: 'Inspect resolved B2C configuration, source provenance, warnings, and paths. Secrets are redacted unless unmask=true. ' +
-            'Use to diagnose configuration, authentication, or project-context issues.',
-        toolsets: ['DIAGNOSTICS'],
-        isGA: true,
+        effect: 'read',
+        idempotent: true,
+        openWorld: false,
+        description: 'Inspect resolved B2C configuration, sources, warnings, and paths; usually no need to read dw.json. ' +
+            'Secrets are masked by default.',
+        toolsets: ['DIAGNOSTICS', 'CIP'],
         requiresInstance: false,
         usesConfigurationContext: true,
         inputSchema: {
@@ -36,6 +39,7 @@ export function createConfigInspectTool(loadServices) {
                 config: redactConfigValues(resolved.values, { unmask: args.unmask ?? false }),
                 sources: resolved.sources,
                 warnings: resolved.warnings.length > 0 ? resolved.warnings.map((w) => w.message) : undefined,
+                skillReferences: resolved.warnings.length > 0 ? [MCP_SKILL_REFERENCES.configSources] : undefined,
             };
         },
         formatOutput: (output) => jsonResult(output),

package/dist/tools/diagnostics/debug-capture-at-breakpoint.js

@@ -7,32 +7,43 @@ import { z } from 'zod';
 import { createToolAdapter, jsonResult } from '../adapter.js';
 import { projectFrame, projectVariable, resolveBreakpointPath, } from '@salesforce/b2c-tooling-sdk/operations/debug';
 import { getRegistry, getSessionEntry } from './session-registry.js';
+import { MCP_SKILL_REFERENCES } from '../../skill-references.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 120_000;
 export function createDebugCaptureAtBreakpointTool(loadServices, serverContext) {
     return createToolAdapter({
         name: 'debug_capture_at_breakpoint',
-        description: 'Set a breakpoint, optionally GET trigger_url, wait for a halt, and return stack, variables, and expressions. ' +
-            'Without trigger_url, blocks until an external request hits the breakpoint or timeout expires.',
+        effect: 'write',
+        idempotent: false,
+        openWorld: true,
+        description: 'Add a breakpoint and wait for a halt; return stack, variables, and evaluations. ' +
+            'Trigger a GET here or an external request concurrently. Capture does not resume by default. ' +
+            'Workflow: skill://mcp/debugger/SKILL.md.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
-            session_id: z.string().describe('Session ID returned by debug_start_session.'),
+            session_id: z.string(),
             file: z.string().describe('Local file path or server script path for the breakpoint.'),
-            line: z.number().int().positive().describe('Line number for the breakpoint.'),
+            line: z.number().int().positive().describe('1-based line number.'),
             condition: z.string().optional().describe('Optional conditional expression for the breakpoint.'),
-            expressions: z.array(z.string()).optional().describe('Expressions to evaluate when the breakpoint is hit.'),
+            expressions: z
+                .array(z.string())
+                .optional()
+                .describe('Expressions evaluated when halted; may change remote state.'),
             timeout_ms: z
                 .number()
                 .int()
                 .positive()
                 .max(MAX_TIMEOUT_MS)
                 .optional()
-                .describe(`Timeout in milliseconds waiting for the breakpoint to be hit (default: ${DEFAULT_TIMEOUT_MS}, max: ${MAX_TIMEOUT_MS}).`),
+                .describe(`Wait timeout in milliseconds. Default: ${DEFAULT_TIMEOUT_MS}; max: ${MAX_TIMEOUT_MS}.`),
             auto_continue: z
                 .boolean()
                 .optional()
-                .describe('If true, resume the thread after capturing the snapshot. Defaults to false.'),
-            trigger_url: z.string().optional().describe('HTTP GET URL to invoke after arming the breakpoint.'),
+                .describe('Resume after capture; default false leaves the request halted. Use true for snapshots.'),
+            trigger_url: z
+                .string()
+                .optional()
+                .describe('GET after arming; no custom headers. May remain pending while halted.'),
         },
         async execute(args, context) {
             const entry = getSessionEntry(context, args.session_id);
@@ -55,10 +66,17 @@ export function createDebugCaptureAtBreakpointTool(loadServices, serverContext)
                 script_path: scriptPath,
             };
             // Fire trigger URL in the background (it will hang when the breakpoint halts the thread)
+            let triggerStatus;
+            let triggerPending = Boolean(args.trigger_url);
             const triggerPromise = args.trigger_url
                 ? fetch(args.trigger_url, { redirect: 'follow' })
-                    .then((r) => r.status)
-                    .catch(() => undefined)
+                    .then((r) => {
+                    triggerStatus = r.status;
+                })
+                    .catch(() => { })
+                    .finally(() => {
+                    triggerPending = false;
+                })
                 : undefined;
             const thread = await registry.waitForHalt(entry, timeout);
             if (!thread) {
@@ -67,6 +85,11 @@ export function createDebugCaptureAtBreakpointTool(loadServices, serverContext)
                     halted: false,
                     timed_out: true,
                     auto_continued: false,
+                    trigger_pending: args.trigger_url ? triggerPending : undefined,
+                    warnings: [
+                        'No halt observed before timeout. Check deployed code, cartridge path, and trigger. The breakpoint remains armed; end the session with clear_breakpoints when finished.',
+                    ],
+                    skillReferences: [MCP_SKILL_REFERENCES.debuggerRecovery],
                 };
             }
             const threadDetail = await entry.manager.client.getThread(thread.id);
@@ -94,7 +117,9 @@ export function createDebugCaptureAtBreakpointTool(loadServices, serverContext)
                 await entry.manager.resume(thread.id);
                 autoContinued = true;
             }
-            const triggerStatus = triggerPromise ? await triggerPromise : undefined;
+            // A halted request cannot finish until the caller resumes it in another tool call.
+            if (autoContinued && triggerPromise)
+                await triggerPromise;
             return {
                 breakpoint: breakpointInfo,
                 halted: true,
@@ -104,6 +129,7 @@ export function createDebugCaptureAtBreakpointTool(loadServices, serverContext)
                 evaluations: evaluations.length > 0 ? evaluations : undefined,
                 auto_continued: autoContinued,
                 trigger_status: triggerStatus,
+                trigger_pending: args.trigger_url ? triggerPending : undefined,
             };
         },
         formatOutput: (output) => jsonResult(output),

package/dist/tools/diagnostics/{debug-step.d.ts → debug-control.d.ts}

@@ -1,4 +1,4 @@
 import type { McpTool } from '../../utils/index.js';
 import type { Services } from '../../services.js';
 import type { ServerContext } from '../../server-context.js';
-export declare function createDebugStepTools(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool[];
+export declare function createDebugControlTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/diagnostics/debug-control.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * 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 { z } from 'zod';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { getSessionEntry } from './session-registry.js';
+const CONTROL_HANDLERS = {
+    continue: (m, id) => m.resume(id),
+    into: (m, id) => m.stepInto(id),
+    out: (m, id) => m.stepOut(id),
+    over: (m, id) => m.stepOver(id),
+};
+export function createDebugControlTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'debug_control',
+        effect: 'write',
+        idempotent: false,
+        openWorld: true,
+        description: 'Resume or step a halted thread. Follow with debug_wait_for_stop.',
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
+        inputSchema: {
+            action: z.enum(['continue', 'into', 'over', 'out']),
+            session_id: z.string(),
+            thread_id: z.number().int(),
+        },
+        async execute(args, context) {
+            const entry = getSessionEntry(context, args.session_id);
+            await CONTROL_HANDLERS[args.action](entry.manager, args.thread_id);
+            return { thread_id: args.thread_id, action: args.action };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=debug-control.js.map