@salesforce/b2c-dx-mcp 3.3.0 → 3.4.0

package/dist/commands/mcp.js

@@ -135,7 +135,7 @@ import { Flags } from '@oclif/core';
 import { BaseCommand, MrtCommand, InstanceCommand, loadConfig, extractInstanceFlags, extractMrtFlags, } from '@salesforce/b2c-tooling-sdk/cli';
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { EnvSource, readProjectEnvironment } from '@salesforce/b2c-tooling-sdk/config';
-import { loadLocalScapiSchemas } from '@salesforce/b2c-tooling-sdk/scapi';
+import { isRemoteScapiSchema, loadScapiSchemaOverrides, } from '@salesforce/b2c-tooling-sdk/scapi';
 import { B2CDxMcpServer } from '../server.js';
 import { Services } from '../services.js';
 import { ServerContext } from '../server-context.js';
@@ -206,9 +206,9 @@ export default class McpServerCommand extends BaseCommand {
             env: 'SFCC_DOCS_TOPICS',
         }),
         'scapi-schemas': Flags.string({
-            description: 'Local SCAPI OpenAPI contracts for scapi_search and scapi_execute (comma-separated JSON files or directories). ' +
+            description: 'Local SCAPI OpenAPI contracts for scapi_search and scapi_execute (comma-separated JSON files, directories or http(s) URLs). ' +
                 'Each replaces the bundled or live contract with the same family/name/version from servers[0].url, or adds an API. ' +
-                'Developer option for beta and pre-release APIs.',
+                'Developer option for beta and pre-release APIs. Overrides the project config scapi-schemas (dw.json or project .env).',
             env: 'SFCC_SCAPI_SCHEMAS',
         }),
     };
@@ -378,7 +378,7 @@ export default class McpServerCommand extends BaseCommand {
             // (--docs-topics / SFCC_DOCS_TOPICS), else config `docsCategories`
             // (dw.json `docs-categories`, SFCC_DOCS_CATEGORIES, package.json).
             docsTopics: this.flags['docs-topics'] ?? this.resolvedConfig?.values.docsCategories?.join(','),
-            scapiSchemas: this.loadLocalScapiSchemas(),
+            scapiSchemas: await this.loadLocalScapiSchemas(),
         };
         // Add toolsets to telemetry attributes
         if (this.telemetry && startupFlags.toolsets) {
@@ -447,7 +447,7 @@ export default class McpServerCommand extends BaseCommand {
         this.logger.info({ version: this.config.version }, 'MCP Server running on stdio');
     }
     /** Load --scapi-schemas once at startup; relative paths resolve from the project directory. */
-    loadLocalScapiSchemas() {
+    async loadLocalScapiSchemas() {
         const value = this.flags['scapi-schemas'];
         if (!value)
             return undefined;
@@ -456,10 +456,10 @@ export default class McpServerCommand extends BaseCommand {
             .split(',')
             .map((entry) => entry.trim())
             .filter(Boolean)
-            .map((entry) => path.resolve(base, entry));
+            .map((entry) => (isRemoteScapiSchema(entry) ? entry : path.resolve(base, entry)));
         let documents;
         try {
-            documents = loadLocalScapiSchemas(paths);
+            documents = await loadScapiSchemaOverrides(paths);
         }
         catch (error) {
             this.error(error instanceof Error ? error.message : String(error));

package/dist/tools/docs/docs-read.js

@@ -7,7 +7,7 @@ import { TOOLSETS } from '../../utils/constants.js';
 import { z } from 'zod';
 import { readDocByQuery } from '@salesforce/b2c-tooling-sdk/docs';
 import { createToolAdapter, errorResult, jsonResult } from '../adapter.js';
-import { enabledCategoriesNote } from './topics.js';
+import { DOCS_CITATION_NOTE, enabledCategoriesNote } from './topics.js';
 import { workspaceInputSchema, resolveProjectWorkspace } from './storefront.js';
 /** Default maximum characters of content returned per read call, to bound the inline payload. */
 const DEFAULT_MAX_LENGTH = 12_000;
@@ -18,7 +18,8 @@ export function createDocsReadTool(loadServices, enabledCategories, detectedWork
         idempotent: true,
         openWorld: true,
         description: 'Read a B2C Commerce (SFCC/Demandware) Script API reference, job step, developer guide, admin/merchant help article, or tooling doc by ID or fuzzy query. ' +
-            'Use docs_search to find IDs.' +
+            'Use docs_search to find IDs. ' +
+            'Cite by entry.url (sourceUrl for Markdown); never show doc IDs.' +
             enabledCategoriesNote(enabledCategories),
         toolsets: [...TOOLSETS],
         inputSchema: {
@@ -56,6 +57,7 @@ export function createDocsReadTool(loadServices, enabledCategories, detectedWork
             const end = offset + slice.length;
             const truncated = end < totalLength;
             return {
+                citation: DOCS_CITATION_NOTE,
                 entry: found.entry,
                 content: slice,
                 totalLength,

package/dist/tools/docs/docs-search.js

@@ -7,15 +7,15 @@ import { TOOLSETS } from '../../utils/constants.js';
 import { z } from 'zod';
 import { searchDocs } from '@salesforce/b2c-tooling-sdk/docs';
 import { createToolAdapter, jsonResult } from '../adapter.js';
-import { categoryEnumValues, enabledCategoriesNote } from './topics.js';
+import { DOCS_CITATION_NOTE, categoryEnumValues, enabledCategoriesNote } from './topics.js';
 import { workspaceInputSchema, detectedWorkspaceNote, resolveProjectWorkspace, } from './storefront.js';
 /** Default number of results returned when `limit` is not supplied. Kept small to bound payload size for agents. */
 const DEFAULT_LIMIT = 5;
 /**
  * Projects a search hit to the payload returned to an agent. By default we keep
- * only the triage-critical fields (id, title, category, summary, score) and drop
- * `keywords` (index-tuning metadata) and `url` (derivable / returned on read),
- * which together roughly double the payload. `verbose` restores them.
+ * the triage-critical fields (id, title, category, summary, score) plus `url`,
+ * so an agent can cite the page without exposing the id. `keywords`
+ * (index-tuning metadata) and `sourceUrl` (Markdown twin) are verbose-only.
  */
 function leanResult(entry, score, verbose) {
     const base = {
@@ -26,11 +26,11 @@ function leanResult(entry, score, verbose) {
     };
     if (entry.summary)
         base.summary = entry.summary;
+    if (entry.url)
+        base.url = entry.url;
     if (verbose) {
         if (entry.keywords && entry.keywords.length > 0)
             base.keywords = entry.keywords;
-        if (entry.url)
-            base.url = entry.url;
         if (entry.sourceUrl)
             base.sourceUrl = entry.sourceUrl;
     }
@@ -43,7 +43,8 @@ export function createDocsSearchTool(loadServices, detectedWorkspaces = [], enab
         idempotent: true,
         openWorld: false,
         description: 'Search B2C Commerce (SFCC/Demandware) Script API, job steps, developer guides, admin/merchant help, and tooling docs. ' +
-            'Use for natural-language queries or unknown IDs; call docs_read with a result ID.' +
+            'Use for natural-language queries or unknown IDs; call docs_read with a result ID. ' +
+            'Cite by url; never show doc IDs.' +
             enabledCategoriesNote(enabledCategories) +
             detectedWorkspaceNote(detectedWorkspaces),
         toolsets: [...TOOLSETS],
@@ -66,7 +67,7 @@ export function createDocsSearchTool(loadServices, detectedWorkspaces = [], enab
             verbose: z
                 .boolean()
                 .optional()
-                .describe('Include keywords and canonical url on each result (larger payload). Defaults to false.'),
+                .describe('Include keywords and the Markdown sourceUrl on each result (larger payload). Defaults to false.'),
         },
         async execute(args) {
             const workspace = await resolveProjectWorkspace(args, detectedWorkspaces);
@@ -89,6 +90,7 @@ export function createDocsSearchTool(loadServices, detectedWorkspaces = [], enab
                 ...(workspace && { workspace }),
                 total: ranked.length,
                 offset,
+                citation: DOCS_CITATION_NOTE,
                 results: results.map((r) => leanResult(r.entry, r.score, args.verbose ?? false)),
                 ...(truncated && { truncated: true, nextOffset: end }),
             };

package/dist/tools/docs/topics.d.ts

@@ -18,4 +18,9 @@ export declare function categoryEnumValues(enabledCategories?: readonly DocCateg
  * A sentence for a tool description noting the corpus is restricted to the
  * configured topics, or an empty string when there is no restriction.
  */
+/**
+ * Returned with every docs_search/docs_read result. Doc IDs are lookup keys for docs_read, not user-facing references;
+ * the rule sits next to the data because agents cite while reading results, long after reading tool descriptions.
+ */
+export declare const DOCS_CITATION_NOTE = "Cite docs to users by url (sourceUrl for Markdown). Never show doc ids; they are docs_read keys. Show ids only if asked.";
 export declare function enabledCategoriesNote(enabledCategories?: readonly DocCategory[]): string;

package/dist/tools/docs/topics.js

@@ -30,6 +30,11 @@ export function categoryEnumValues(enabledCategories) {
  * A sentence for a tool description noting the corpus is restricted to the
  * configured topics, or an empty string when there is no restriction.
  */
+/**
+ * Returned with every docs_search/docs_read result. Doc IDs are lookup keys for docs_read, not user-facing references;
+ * the rule sits next to the data because agents cite while reading results, long after reading tool descriptions.
+ */
+export const DOCS_CITATION_NOTE = 'Cite docs to users by url (sourceUrl for Markdown). Never show doc ids; they are docs_read keys. Show ids only if asked.';
 export function enabledCategoriesNote(enabledCategories) {
     if (!enabledCategories || enabledCategories.length === 0)
         return '';

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

@@ -15,7 +15,7 @@ import type { ScapiExecutionRegistry } from './execution-registry.js';
  *
  * @param loadServices - Function that loads configuration and returns Services instance
  * @param executions - Server-scoped registry for retained code-mode executions
- * @param localSchemas - Developer-supplied contracts that override bundled and live ones in code mode
+ * @param localSchemas - Startup --scapi-schemas contracts; when omitted, each call reads the project's `scapiSchemas` config
  * @returns Array of MCP tools
  */
 export declare function createScapiTools(loadServices: () => Promise<Services> | Services, executions?: ScapiExecutionRegistry, localSchemas?: readonly ScapiSchemaDocument[]): McpTool[];

package/dist/tools/scapi/index.js

@@ -13,10 +13,10 @@ import { ScapiLiveSchemaCache, ScapiShopperSessions } from '@salesforce/b2c-tool
  *
  * @param loadServices - Function that loads configuration and returns Services instance
  * @param executions - Server-scoped registry for retained code-mode executions
- * @param localSchemas - Developer-supplied contracts that override bundled and live ones in code mode
+ * @param localSchemas - Startup --scapi-schemas contracts; when omitted, each call reads the project's `scapiSchemas` config
  * @returns Array of MCP tools
  */
-export function createScapiTools(loadServices, executions, localSchemas = []) {
+export function createScapiTools(loadServices, executions, localSchemas) {
     // Live contracts discovered by search or schema fetches are reused by execution for the same tenant.
     const schemaCache = new ScapiLiveSchemaCache();
     const shopperSessions = new ScapiShopperSessions();

package/dist/tools/scapi/scapi-code.js

@@ -3,8 +3,9 @@
  * 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 path from 'node:path';
 import { z } from 'zod';
-import { loadScapiSchemas, mergeScapiSchemas, scapiTenantKey, ScapiLiveSchemaCache, ScapiShopperSessions, runScapiCode, createScapiRequest, createScapiAuth, loadScapiSnippets, saveScapiSnippet, } from '@salesforce/b2c-tooling-sdk/scapi';
+import { loadScapiSchemas, matchesScapiApi, mergeScapiSchemas, suggestScapiApis, scapiTenantKey, ScapiLiveSchemaCache, ScapiShopperSessions, runScapiCode, createScapiRequest, createScapiAuth, loadScapiSnippets, saveScapiSnippet, isRemoteScapiSchema, loadScapiSchemaOverrides, } from '@salesforce/b2c-tooling-sdk/scapi';
 import { toOrganizationId } from '@salesforce/b2c-tooling-sdk/clients';
 import { getB2CConfigDirectory } from '@salesforce/b2c-tooling-sdk/config';
 import { resolveEffectiveSafetyConfig, loadGlobalSafetyConfig } from '@salesforce/b2c-tooling-sdk/safety';
@@ -25,7 +26,7 @@ function requireScapiSkill(read) {
     if (read !== true)
         throw new Error(SCAPI_SKILL_REQUIRED);
 }
-const searchDescription = `Requires reading skill://mcp/b2c-mcp-scapi/SKILL.md first. Search SCAPI Admin/Shopper OpenAPI contracts by running JavaScript over \`spec\`, to find the operationId, path, inputs and scopes for a Commerce API task when no dedicated tool fits. Use cip_* for analytics and webdav_* for files. Searches the bundled contracts by default (offline, no credentials); schemas:"live" fetches the current contracts from the configured instance instead, including tenant c_* fields, custom APIs and APIs newer than the bundle.`;
+const searchDescription = `Requires reading skill://mcp/b2c-mcp-scapi/SKILL.md first. Search SCAPI Admin/Shopper OpenAPI contracts by running JavaScript over \`spec\` (only spec.apis, spec.paths[fullPath][method] and spec.resolve exist), to find the operationId, path, inputs and scopes for a Commerce API task when no dedicated tool fits. Use cip_* for analytics and webdav_* for files. Searches the bundled contracts by default (offline, no credentials); schemas:"live" fetches the current contracts from the configured instance instead, including tenant c_* fields, custom APIs and APIs newer than the bundle (falls back to the bundled contracts with a warning when live access fails). Operations carry summary, description and tags: match on those, not only operationId. Results are capped at 24 KB: operations are an outline by default (no nested descriptions or examples; detail:"full" restores them), and you should still return fields such as operationId, method, path and summary, not whole operations.`;
 const executeDescription = `Requires reading skill://mcp/b2c-mcp-scapi/SKILL.md first. Run any SCAPI Admin or Shopper API operation (reads, writes, searches and actions) through scapi.request() in JavaScript. Covers most developer, merchant and administrator tasks: catalogs, products, pricing, promotions, orders, customers, inventory, sites, jobs, code versions, observability, and storefront flows such as baskets. Use it whenever no more specific tool fits. Find operations with scapi_search first. Auth is automatic; Shopper calls run as a per-site guest whose basket persists. Operations are governed by Safety Mode and may ask the user for confirmation.`;
 function codeResult(data, resolution) {
     const result = resolution ? attachResolution(jsonResult(data, 0), resolution, 0) : jsonResult(data, 0);
@@ -45,21 +46,41 @@ function failure(error, resolution) {
         isError: true,
     };
 }
-export function createScapiCodeTools(loadServices, snippetDirectory, registry = new ScapiExecutionRegistry(), schemaCache = new ScapiLiveSchemaCache(), shopperSessions = new ScapiShopperSessions(), localSchemas = []) {
-    // Developer-supplied contracts (--scapi-schemas) replace bundled and live ones with the same id.
-    const local = (api) => localSchemas.filter((document) => !api || document.entry.id === api);
+export function createScapiCodeTools(loadServices, snippetDirectory, registry = new ScapiExecutionRegistry(), schemaCache = new ScapiLiveSchemaCache(), shopperSessions = new ScapiShopperSessions(), localSchemas) {
+    // Developer-supplied contracts replace bundled and live ones with the same id. The startup
+    // --scapi-schemas flag wins; otherwise each call reads the project's `scapiSchemas` config
+    // (dw.json `scapi-schemas` or SFCC_SCAPI_SCHEMAS, including the project .env). Entries may be
+    // files, directories or http(s) URLs; fetched contracts are kept until this server ends.
+    const remoteSchemas = new Map();
+    const projectSchemas = async (services, signal) => {
+        if (localSchemas)
+            return localSchemas;
+        const entries = services?.getResolvedConfig().values.scapiSchemas;
+        if (!services || !entries?.length)
+            return [];
+        const base = services.getResolution().projectDirectory?.path ?? process.cwd();
+        return loadScapiSchemaOverrides(entries.map((entry) => (isRemoteScapiSchema(entry) ? entry : path.resolve(base, entry))), { cache: remoteSchemas, signal });
+    };
     // Retain only source for the last 50 completed executions, until this server ends.
     const executions = new Map();
     const searchInput = {
         ...createProjectContextInputSchema('configuration'),
         code,
         skillRead,
-        api: z.string().optional().describe('Limit schemas to family/name/version. Omit for all APIs.'),
+        api: z
+            .string()
+            .regex(/^[a-z0-9-]+(?:\/[a-z0-9-]+){0,2}\/?$/i, 'api must be family, family/name or family/name/version.')
+            .optional()
+            .describe('Limit schemas to an API family, family/name or family/name/version (cdn, cdn/zones, cdn/zones/v1). Omit for all APIs.'),
         schemas: z
             .enum(['bundled', 'live'])
             .optional()
             .describe('bundled (default, offline) or live tenant contracts from the Schemas API.'),
         refresh: z.boolean().optional().describe('With schemas:"live", refetch instead of using cached contracts.'),
+        detail: z
+            .enum(['outline', 'full'])
+            .optional()
+            .describe('outline (default) drops nested descriptions and examples to fit 24 KB; full keeps all prose.'),
         authType: z
             .enum(['admin', 'shopper'])
             .optional()
@@ -106,36 +127,83 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
                         throw new Error('SCAPI_SEARCH_ARGUMENT_INVALID: refresh requires schemas:"live".');
                     let documents;
                     let failures = [];
+                    let schemaSource = input.schemas === 'live' ? 'live' : 'bundled';
+                    const warnings = [];
+                    let services;
                     if (input.schemas === 'live') {
-                        const services = await loadServices(input);
+                        services = await loadServices(input);
                         resolution = services.getResolution();
-                        // Throws with configuration guidance when shortCode, tenantId, or OAuth credentials are missing.
-                        const client = services.getScapiSchemasClient();
-                        const organizationId = services.getOrganizationId();
-                        const tenant = scapiTenantKey(services.getShortCode(), organizationId);
-                        ({ documents, failures } = await schemaCache.load(tenant, client, organizationId, {
-                            api: input.api,
-                            refresh: input.refresh,
-                            signal: context?.signal,
-                        }));
-                        documents = mergeScapiSchemas([], documents, local(input.api));
-                        if (documents.length === 0 && failures.length === 0)
-                            throw new Error('Unknown schema ID for this tenant. Omit api to discover available APIs.');
+                    }
+                    else if (!localSchemas) {
+                        // Bundled search works without configuration; config is read only for local contracts,
+                        // and configuration errors surface on tools that need it.
+                        try {
+                            services = await loadServices(input);
+                            resolution = services.getResolution();
+                        }
+                        catch {
+                            services = undefined;
+                        }
+                    }
+                    const localDocuments = await projectSchemas(services, context?.signal);
+                    const local = (api) => localDocuments.filter((document) => matchesScapiApi(document.entry.id, api));
+                    // Name close ids so a near-miss filter (ecdn, zones) can be corrected in one step.
+                    const unknownApi = (message, known) => {
+                        const close = suggestScapiApis(known.map((document) => document.entry.id), input.api);
+                        return new Error(`${message}${close.length > 0 ? ` Close matches: ${close.join(', ')}.` : ''}`);
+                    };
+                    const searchBundled = () => {
+                        const all = mergeScapiSchemas(loadScapiSchemas(), [], local());
+                        const bundled = all.filter((document) => matchesScapiApi(document.entry.id, input.api));
+                        if (bundled.length === 0)
+                            throw unknownApi('Unknown schema ID. Omit api to discover available APIs, or use schemas:"live" for tenant and custom APIs.', all);
+                        return bundled;
+                    };
+                    if (services && input.schemas === 'live') {
+                        try {
+                            // Throws with configuration guidance when shortCode, tenantId, or OAuth credentials are missing.
+                            const client = services.getScapiSchemasClient();
+                            const organizationId = services.getOrganizationId();
+                            const tenant = scapiTenantKey(services.getShortCode(), organizationId);
+                            ({ documents, failures } = await schemaCache.load(tenant, client, organizationId, {
+                                api: input.api,
+                                refresh: input.refresh,
+                                signal: context?.signal,
+                            }));
+                            documents = mergeScapiSchemas([], documents, local(input.api));
+                            if (documents.length === 0 && failures.length === 0)
+                                throw unknownApi('Unknown schema ID for this tenant. Omit api to discover available APIs.', mergeScapiSchemas(loadScapiSchemas(), schemaCache.get(tenant), local()));
+                        }
+                        catch (error) {
+                            // Custom APIs exist only on the tenant; an unknown ID is a caller error, not an access problem.
+                            const message = error instanceof Error ? error.message : String(error);
+                            if (context?.signal?.aborted ||
+                                input.api?.split('/')[0].toLowerCase() === 'custom' ||
+                                message.startsWith('Unknown schema ID'))
+                                throw error;
+                            documents = searchBundled();
+                            schemaSource = 'bundled';
+                            warnings.push(`Live schemas unavailable (${message.replaceAll(/\s+/g, ' ').trim().slice(0, 300)}). Searching the bundled standard contracts instead: no tenant c_* properties or custom APIs, and they may be older than your tenant.`);
+                        }
                     }
                     else {
-                        documents = mergeScapiSchemas(loadScapiSchemas(), [], local()).filter((document) => !input.api || document.entry.id === input.api);
-                        if (documents.length === 0)
-                            throw new Error('Unknown schema ID. Omit api to discover available APIs, or use schemas:"live" for tenant and custom APIs.');
+                        documents = searchBundled();
                     }
                     const result = await runScapiCode({
                         code: input.code,
                         documents,
                         authType: input.authType,
+                        detail: input.detail ?? 'outline',
                         signal: context?.signal,
                         timeoutMs: 10_000,
                         snippets: loadScapiSnippets(snippetDirectory),
                     });
-                    return codeResult({ result, ...(failures.length > 0 ? { schemaFailures: failures } : {}) }, resolution);
+                    return codeResult({
+                        result,
+                        ...(input.schemas === 'live' ? { schemaSource } : {}),
+                        ...(warnings.length > 0 ? { warnings } : {}),
+                        ...(failures.length > 0 ? { schemaFailures: failures } : {}),
+                    }, resolution);
                 }
                 catch (error) {
                     return failure(error, resolution);
@@ -173,6 +241,7 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
                     const services = await loadServices(input);
                     resolution = services.getResolution();
                     const config = services.getResolvedConfig();
+                    const localDocuments = await projectSchemas(services, context?.signal);
                     const { shortCode, tenantId, siteId } = config.values;
                     const tenant = shortCode && tenantId ? scapiTenantKey(shortCode, toOrganizationId(tenantId)) : undefined;
                     const safetyEnvironment = Object.fromEntries(['SFCC_SAFETY_LEVEL', 'SFCC_SAFETY_CONFIRM', 'SFCC_SAFETY_CONFIG'].map((name) => [
@@ -198,10 +267,10 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
                                 }),
                                 // Live contracts discovered for this tenant replace bundled ones, and local ones replace both;
                                 // the user owns their accuracy.
-                                documents: mergeScapiSchemas(loadScapiSchemas(), tenant ? schemaCache.get(tenant) : [], localSchemas),
-                                onSchema(document, customProperties) {
-                                    // Keep expanded tenant contracts from being replaced by unexpanded fetches.
-                                    if (tenant && (customProperties || document.entry.apiFamily === 'custom'))
+                                documents: mergeScapiSchemas(loadScapiSchemas(), tenant ? schemaCache.get(tenant) : [], localDocuments),
+                                onSchema(document, full) {
+                                    // Keep full tenant contracts (custom properties and prose) from being replaced by lighter fetches.
+                                    if (tenant && (full || document.entry.apiFamily === 'custom'))
                                         schemaCache.put(tenant, document);
                                 },
                                 confirm: (request) => execution.confirm(request),

package/dist/tools/scapi/scapi-schemas-list.js

@@ -16,7 +16,7 @@ import { z } from 'zod';
 import { createToolAdapter, jsonResult } from '../adapter.js';
 import { getApiErrorMessage } from '@salesforce/b2c-tooling-sdk/clients';
 import { collapseOpenApiSchema } from '@salesforce/b2c-tooling-sdk/schemas';
-import { createLiveScapiDocument, scapiTenantKey } from '@salesforce/b2c-tooling-sdk/scapi';
+import { SCAPI_SCHEMA_EXPANSIONS, SCAPI_STANDARD_SCHEMA_EXPAND, createLiveScapiDocument, fetchScapiSchemaWithFallback, isFullScapiExpand, listScapiSchemasWithFallback, normalizeScapiSchemaExpand, scapiSchemaExpandFor, scapiTenantKey, } from '@salesforce/b2c-tooling-sdk/scapi';
 /**
  * Builds the base URL for a SCAPI API endpoint.
  *
@@ -45,37 +45,67 @@ function getSchemasApiError(error, response) {
     }
     return message;
 }
+/**
+ * Smallest Schemas API `expand` for the request: collapsed output drops operation bodies, so it never needs
+ * prose; expandAll returns the whole contract. An explicit `include` wins.
+ */
+function resolveExpand(args) {
+    if (args.include?.length)
+        return normalizeScapiSchemaExpand(args.include);
+    const customProperties = args.expandCustomProperties !== false;
+    if (args.expandAll)
+        return customProperties ? scapiSchemaExpandFor({ full: true }) : SCAPI_STANDARD_SCHEMA_EXPAND;
+    return scapiSchemaExpandFor({ customProperties });
+}
 /**
  * Fetches a specific schema from the SCAPI Schemas API.
  *
  * @param params - Fetch parameters
- * @param params.client - SCAPI Schemas client
- * @param params.organizationId - Organization ID
+ * @param params.svc - Services (client, organization and short code are resolved inside the live fetch)
  * @param params.args - Input arguments with API identifiers
- * @param params.shortCode - Optional short code for building base URL
  * @param params.schemaCache - Optional live contract cache shared with SCAPI code mode
  * @returns Schema fetch output
  */
 async function fetchSpecificSchema(params) {
-    const { client, organizationId, args, shortCode, schemaCache } = params;
+    const { svc, args, schemaCache } = params;
     const { apiFamily, apiName, apiVersion, expandAll, status } = args;
+    const expand = resolveExpand(args);
     // Warn if status filter was provided (it's ignored in fetch mode)
-    const warning = status
+    const statusWarning = status
         ? `Note: 'status' filter is ignored when fetching a specific schema. The API endpoint for retrieving a specific schema (${apiFamily}/${apiName}/${apiVersion}) does not support status filtering - you're already specifying the exact version. Use discovery mode (omit one or more of apiFamily/apiName/apiVersion) to filter by status.`
         : undefined;
-    const { data, error, response } = await client.GET('/organizations/{organizationId}/schemas/{apiFamily}/{apiName}/{apiVersion}', {
-        params: {
-            path: { organizationId, apiFamily: apiFamily, apiName: apiName, apiVersion: apiVersion },
-            query: args.expandCustomProperties === false ? undefined : { expand: 'custom_properties' },
-        },
+    const identity = { apiFamily: apiFamily, apiName: apiName, apiVersion: apiVersion };
+    // Shared by the live fetch and the cache below; a missing shortCode or credentials throws inside the fetch.
+    let live;
+    const result = await fetchScapiSchemaWithFallback(identity, async () => {
+        const client = svc.getScapiSchemasClient();
+        const organizationId = svc.getOrganizationId();
+        let shortCode;
+        try {
+            shortCode = svc.getShortCode();
+        }
+        catch {
+            // Continue without shortCode if not available
+        }
+        const { data, error, response } = await client.GET('/organizations/{organizationId}/schemas/{apiFamily}/{apiName}/{apiVersion}', {
+            params: {
+                path: { organizationId, ...identity },
+                // One comma-joined value: the API rejects a repeated expand parameter.
+                query: expand ? { expand } : undefined,
+            },
+        });
+        if (error)
+            throw new Error(`Failed to fetch schema for ${identity.apiFamily}/${identity.apiName}/${identity.apiVersion}: ${getSchemasApiError(error, response)}`);
+        live = { shortCode, organizationId };
+        return data;
     });
-    if (error) {
-        throw new Error(`Failed to fetch schema for ${apiFamily}/${apiName}/${apiVersion}: ${getSchemasApiError(error, response)}`);
-    }
-    // Expanded tenant contracts become searchable and executable in SCAPI code mode.
-    if (schemaCache && shortCode && (args.expandCustomProperties !== false || apiFamily === 'custom')) {
+    // Contracts carrying custom properties and prose become searchable and executable in SCAPI code mode.
+    if (result.source === 'live' &&
+        schemaCache &&
+        live?.shortCode &&
+        (isFullScapiExpand(expand) || apiFamily === 'custom')) {
         try {
-            schemaCache.put(scapiTenantKey(shortCode, organizationId), createLiveScapiDocument({ apiFamily: apiFamily, apiName: apiName, apiVersion: apiVersion }, data));
+            schemaCache.put(scapiTenantKey(live.shortCode, live.organizationId), createLiveScapiDocument(identity, result.schema));
         }
         catch {
             // Not a usable OpenAPI contract; still return it to the caller.
@@ -84,20 +114,21 @@ async function fetchSpecificSchema(params) {
     // Apply collapsing unless expandAll is requested
     const collapsed = !expandAll;
     const processedSchema = collapsed
-        ? collapseOpenApiSchema(data)
-        : data;
+        ? collapseOpenApiSchema(result.schema)
+        : result.schema;
     // Build base URL for the SCAPI API (where to call the API)
-    const baseUrl = shortCode && apiFamily && apiName && apiVersion
-        ? buildScapiApiUrl(shortCode, apiFamily, apiName, apiVersion)
+    const baseUrl = live?.shortCode
+        ? buildScapiApiUrl(live.shortCode, identity.apiFamily, identity.apiName, identity.apiVersion)
         : undefined;
+    const warning = [statusWarning, result.warning].filter(Boolean).join(' ') || undefined;
     return {
-        apiFamily: apiFamily,
-        apiName: apiName,
-        apiVersion: apiVersion,
+        ...identity,
         schema: processedSchema,
         timestamp: new Date().toISOString(),
         collapsed,
         warning,
+        source: result.source,
+        ...(result.source === 'live' && expand ? { expand } : {}),
         baseUrl,
     };
 }
@@ -105,39 +136,51 @@ async function fetchSpecificSchema(params) {
  * Fetches and filters schemas list from the SCAPI Schemas API.
  *
  * @param params - Fetch parameters
- * @param params.client - SCAPI Schemas client
- * @param params.organizationId - Organization ID
+ * @param params.svc - Services (client, organization and short code are resolved inside the live fetch)
  * @param params.args - Input parameters
- * @param params.shortCode - Optional short code for building base URLs
  * @returns Discovery mode output
  */
 async function fetchSchemasList(params) {
-    const { client, organizationId, args, shortCode } = params;
-    const { data, error, response } = await client.GET('/organizations/{organizationId}/schemas', {
-        params: {
-            path: { organizationId },
-            query: {
-                apiFamily: args.apiFamily,
-                apiName: args.apiName,
-                apiVersion: args.apiVersion,
-                status: args.status,
+    const { svc, args } = params;
+    let shortCode;
+    const result = await listScapiSchemasWithFallback({ apiFamily: args.apiFamily, apiName: args.apiName, apiVersion: args.apiVersion, status: args.status }, async () => {
+        const client = svc.getScapiSchemasClient();
+        const organizationId = svc.getOrganizationId();
+        try {
+            shortCode = svc.getShortCode();
+        }
+        catch {
+            // Continue without shortCode if not available
+        }
+        const { data, error, response } = await client.GET('/organizations/{organizationId}/schemas', {
+            params: {
+                path: { organizationId },
+                query: {
+                    apiFamily: args.apiFamily,
+                    apiName: args.apiName,
+                    apiVersion: args.apiVersion,
+                    status: args.status,
+                },
             },
-        },
+        });
+        if (error)
+            throw new Error(`Failed to fetch SCAPI schemas: ${getSchemasApiError(error, response)}`);
+        const schemas = data?.data ?? [];
+        return { schemas, total: data?.total ?? schemas.length };
     });
-    if (error) {
-        throw new Error(`Failed to fetch SCAPI schemas: ${getSchemasApiError(error, response)}`);
-    }
-    const schemas = data?.data ?? [];
+    const { schemas } = result;
     const filteredSchemas = prepareSchemaListForConsumer(schemas, shortCode);
     const discoveryMetadata = getAvailableFilters(schemas);
     // Generate helpful message for empty results
     const message = schemas.length === 0 ? generateEmptyResultMessage(args) : undefined;
     return {
         schemas: filteredSchemas,
-        total: data?.total ?? schemas.length,
+        total: result.total,
         timestamp: new Date().toISOString(),
         ...discoveryMetadata,
         message,
+        source: result.source,
+        warning: result.warning,
     };
 }
 /**
@@ -234,19 +277,12 @@ export function createScapiSchemasListTool(loadServices, schemaCache) {
                 .boolean()
                 .default(true)
                 .describe('Include tenant custom property definitions when fetching a schema.'),
+            include: z
+                .array(z.enum(SCAPI_SCHEMA_EXPANSIONS))
+                .optional()
+                .describe('Schemas API expand sections (e.g. summaries, examples, all). Overrides expandAll/expandCustomProperties.'),
         },
         async execute(args, { services: svc }) {
-            // Get client and organization ID
-            const client = svc.getScapiSchemasClient();
-            const organizationId = svc.getOrganizationId();
-            // Get shortCode for building base URLs (optional)
-            let shortCode;
-            try {
-                shortCode = svc.getShortCode();
-            }
-            catch {
-                // Continue without shortCode if not available
-            }
             // Determine operation mode
             const hasAllIdentifiers = Boolean(args.apiFamily && args.apiName && args.apiVersion);
             const isFetchMode = hasAllIdentifiers && args.includeSchemas;
@@ -255,11 +291,12 @@ export function createScapiSchemasListTool(loadServices, schemaCache) {
                 throw new Error('includeSchemas=true requires all three identifiers: apiFamily, apiName, and apiVersion. ' +
                     'Please provide all three to fetch a specific schema, or omit includeSchemas to discover available schemas.');
             }
-            // Execute appropriate mode
+            // Execute appropriate mode. Live access is attempted inside, so missing configuration, credentials or
+            // network falls back to the bundled corpus with a warning.
             if (isFetchMode) {
-                return fetchSpecificSchema({ client, organizationId, args, shortCode, schemaCache });
+                return fetchSpecificSchema({ svc, args, schemaCache });
             }
-            return fetchSchemasList({ client, organizationId, args, shortCode });
+            return fetchSchemasList({ svc, args });
         },
         formatOutput: (output) => jsonResult(output),
     }, loadServices);

package/node_modules/@salesforce/b2c-agent-plugins/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @salesforce/b2c-agent-plugins
 
+## 1.12.0
+
+### Minor Changes
+
+- [#747](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/pull/747) [`f3b9974`](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/commit/f3b997487f2094a1c9f1c7a846147e303c2db422) - New `b2c-edge-traffic-triage` operations runbook for reviewing bot and abusive eCDN traffic against your firewall, WAF and rate-limiting rules, and SCAPI code mode now points agents to the operations runbooks. (Thanks [@clavery](https://github.com/clavery)!)
+
+### Patch Changes
+
+- [#744](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/pull/744) [`3964752`](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/commit/3964752a63665b1b6005be14a47f70ccd80349da) - Fixed the search-index job examples (`{"site_scope":["Site"]}`, not an object), documented system-job request bodies for CLI and MCP code mode, and stopped `--api-backend auto` from retrying SCAPI 400 (invalid request) errors over OCAPI, which hid the real error. When a fallback does happen and OCAPI also fails, both errors are reported. (Thanks [@clavery](https://github.com/clavery)!)
+
+- [#741](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/pull/741) [`c45c5fa`](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/commit/c45c5fac903c5bf77eecfc4a4befd259712aa84e) - The `b2c-scapi-schemas` skill explains how to fetch operation descriptions and examples and how the bundled fallback behaves. (Thanks [@clavery](https://github.com/clavery)!)
+
 ## 1.11.0
 
 ### Minor Changes