@salesforce/b2c-dx-mcp 3.2.1 → 3.4.0

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

@@ -8,11 +8,14 @@
  */
 import type { McpTool } from '../../utils/index.js';
 import type { Services } from '../../services.js';
+import { type ScapiSchemaDocument } from '@salesforce/b2c-tooling-sdk/scapi';
 import type { ScapiExecutionRegistry } from './execution-registry.js';
 /**
  * Creates all tools for the SCAPI toolset.
  *
  * @param loadServices - Function that loads configuration and returns Services instance
+ * @param executions - Server-scoped registry for retained code-mode executions
+ * @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): McpTool[];
+export declare function createScapiTools(loadServices: () => Promise<Services> | Services, executions?: ScapiExecutionRegistry, localSchemas?: readonly ScapiSchemaDocument[]): McpTool[];

package/dist/tools/scapi/index.js

@@ -12,14 +12,16 @@ import { ScapiLiveSchemaCache, ScapiShopperSessions } from '@salesforce/b2c-tool
  * Creates all tools for the SCAPI toolset.
  *
  * @param loadServices - Function that loads configuration and returns Services instance
+ * @param executions - Server-scoped registry for retained code-mode executions
+ * @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) {
+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();
     return [
-        ...createScapiCodeTools(loadServices, undefined, executions, schemaCache, shopperSessions),
+        ...createScapiCodeTools(loadServices, undefined, executions, schemaCache, shopperSessions, localSchemas),
         createMetricsGetTool(loadServices),
         createScapiCustomApisStatusTool(loadServices),
         createScapiSchemasListTool(loadServices, schemaCache),

package/dist/tools/scapi/scapi-code.d.ts

@@ -1,5 +1,5 @@
-import { ScapiLiveSchemaCache, ScapiShopperSessions } from '@salesforce/b2c-tooling-sdk/scapi';
+import { ScapiLiveSchemaCache, ScapiShopperSessions, type ScapiSchemaDocument } from '@salesforce/b2c-tooling-sdk/scapi';
 import type { McpTool } from '../../utils/types.js';
 import type { ServicesLoader } from '../adapter.js';
 import { ScapiExecutionRegistry } from './execution-registry.js';
-export declare function createScapiCodeTools(loadServices: ServicesLoader, snippetDirectory?: string, registry?: ScapiExecutionRegistry, schemaCache?: ScapiLiveSchemaCache, shopperSessions?: ScapiShopperSessions): McpTool[];
+export declare function createScapiCodeTools(loadServices: ServicesLoader, snippetDirectory?: string, registry?: ScapiExecutionRegistry, schemaCache?: ScapiLiveSchemaCache, shopperSessions?: ScapiShopperSessions, localSchemas?: readonly ScapiSchemaDocument[]): McpTool[];

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';
@@ -17,64 +18,16 @@ const code = z
     .min(1)
     .max(32_768)
     .describe('JavaScript async arrow function. Return concise JSON. No filesystem or shell access.');
-const skillRead = z.boolean().optional().describe('True after reading the linked SCAPI skill.');
-const snippetDescription = `\nSnippets: await codemode.search(query) returns up to 10 names/descriptions/effects; await codemode.describe(name) returns source/inputSchema. Prefixes: builtin/, user/.`;
+const SCAPI_SKILL_REQUIRED = 'SCAPI_SKILL_REQUIRED: Read skill://mcp/b2c-mcp-scapi/SKILL.md through resources or skills_read, then retry with skillRead: true.';
+const skillRead = z
+    .literal(true, { error: SCAPI_SKILL_REQUIRED })
+    .describe('Required. Set true only after reading skill://mcp/b2c-mcp-scapi/SKILL.md (MCP resource, or skills_read({uri})).');
 function requireScapiSkill(read) {
     if (read !== true)
-        throw new Error('SCAPI_SKILL_REQUIRED: Read skill://mcp/scapi/SKILL.md through resources or skills_read, then retry with skillRead: true.');
+        throw new Error(SCAPI_SKILL_REQUIRED);
 }
-const searchDescription = `Discover Admin/Shopper SCAPI contracts; prefer dedicated tools. Read skill://mcp/scapi/SKILL.md first.
-Default: bundled, offline. schemas:"live": tenant c_*, custom, newer APIs, reused by execute.
-
-Schemas can be huge. Find operation IDs/paths first; then select required and task fields, not whole trees. Local refs expand; recursive/deep refs remain $ref.
-
-Code objects (write JavaScript, not these types):
-interface Operation {
-  api: string; operationId: string; summary?: string;
-  parameters: Array<{name: string; in: string; required?: boolean; schema?: unknown}>;
-  requestBody?: {required?: boolean; content: Record<string, {schema: any}>};
-  responses?: Record<string, unknown>;
-  security: Array<Record<string, string[]>>;
-  auth: {types: string[]; schemes: string[]; executable: boolean}; // runtime support, not access
-}
-declare const spec: {
-  apis: Array<{id: string; apiFamily: string; apiName: string; apiVersion: string; authTypes: string[]}>;
-  paths: Record<string, Record<string, Operation>>; // full paths, lowercase HTTP methods
-};
-
-Examples:
-// Find product operations
-async () => Object.entries(spec.paths)
-  .filter(([path]) => path.startsWith('/product/products/'))
-  .flatMap(([path, methods]) => Object.entries(methods)
-    .map(([method, op]) => ({method, path, operationId: op.operationId})))
-
-// Inspect only fields needed for creation
-async () => {
-  const op = spec.paths['/product/products/v1/organizations/{organizationId}/products/{productId}'].put;
-  const body = op.requestBody.content['application/json'].schema;
-  const fields = [...new Set([...(body.required ?? []), 'name', 'owningCatalogId', 'onlineFlag'])];
-  return {parameters: op.parameters, required: body.required,
-    fields: Object.fromEntries(fields.map(k => [k, body.properties[k]])), auth: op.auth, security: op.security};
-}`;
-const executeDescription = `Read, create, update, or delete Commerce records through SCAPI Admin or Shopper APIs when no dedicated tool fits. Discover endpoints with scapi_search; operations found with schemas:"live" (including custom APIs) are callable here for the same tenant. Otherwise fetch a custom API's live contract through scapi.request() in the same program first. Auth is automatic; Shopper APIs run as a guest whose session (basket) persists per site. JSON only; no binary transfers.
-Read skill://mcp/scapi/SKILL.md first.
-
-Reuse workflows with await codemode.run(name, input); describe first. async (input) receives input. Completed executionId enables scapi_snippet_save.
-Safety confirmation uses MCP elicitation. Protocol retries resume retained code; never replay it. Approval has no server deadline. Decline or cancel terminates execution without rollback. action:cancel needs executionId only (plus skillRead).
-
-Available in your code:
-declare const organizationId: string | undefined; // resolved tenant
-declare const siteId: string | undefined; // configured site
-declare const scapi: {
-  request(options: {method: string; path: string; query?: Record<string, unknown>; body?: unknown}):
-    Promise<{status: number; ok: boolean; data: any; diagnostic?: {code: string; message: string}}>;
-};
-
-Compose dependent requests; await each. Responses can be huge: filter/map/slice; return counts, selected rows and verification. Preserve failures. HTTP failures return ok:false; transport/auth/safety failures throw. SDK safety governs scapi.request. fetch/WebSocket are disabled. Optional auth.accountManager()/auth.slas() export tokens for external clients; see skill. Check writes before retrying.
-
-Example: inspect a campaign's promotions
-async () => codemode.run('builtin/campaign-promotions', {campaignId: 'selected-campaign', limit: 4})`;
+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);
     // Code-mode payloads are arbitrary JSON: retain provenance without duplicating the result.
@@ -93,19 +46,41 @@ function failure(error, resolution) {
         isError: true,
     };
 }
-export function createScapiCodeTools(loadServices, snippetDirectory, registry = new ScapiExecutionRegistry(), schemaCache = new ScapiLiveSchemaCache(), shopperSessions = new ScapiShopperSessions()) {
+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()
@@ -137,7 +112,7 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
         {
             name: 'scapi_search',
             title: 'SCAPI Spec Search',
-            description: searchDescription + snippetDescription,
+            description: searchDescription,
             inputSchema: searchInput,
             toolsets: ['SCAPI', 'PWAV3', 'STOREFRONTNEXT'],
             effect: 'read',
@@ -152,35 +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,
-                        }));
-                        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 = loadScapiSchemas().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);
@@ -190,7 +213,7 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
         {
             name: 'scapi_execute',
             title: 'SCAPI Code Executor',
-            description: executeDescription + snippetDescription,
+            description: executeDescription,
             inputSchema: executeInput,
             toolsets: ['SCAPI', 'PWAV3', 'STOREFRONTNEXT'],
             effect: 'destructive',
@@ -218,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) => [
@@ -241,11 +265,12 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
                                     slasClientId: config.values.slasClientId,
                                     slasClientSecret: config.values.slasClientSecret,
                                 }),
-                                // Live contracts discovered for this tenant replace bundled ones; the user owns their accuracy.
-                                documents: mergeScapiSchemas(loadScapiSchemas(), tenant ? schemaCache.get(tenant) : []),
-                                onSchema(document, customProperties) {
-                                    // Keep expanded tenant contracts from being replaced by unexpanded fetches.
-                                    if (tenant && (customProperties || document.entry.apiFamily === 'custom'))
+                                // 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) : [], 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);