@salesforce/b2c-dx-mcp 3.2.1 → 3.4.0

package/content/guidance/storefront-next/sfnext-theming/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: sfnext-theming
+description: >-
+  Re-brand and re-skin a Storefront Next storefront: change the color palette, corner radius and shadows (shape tokens), header and footer colors, typography and web fonts, logo, favicon, hero scrims, and brand copy, with WCAG contrast checks. Use when asked to rebrand or restyle the storefront, change the primary color, swap the font, make the header dark, make cards rounded or flat, replace the logo, edit src/theme, core.css, header.css, brand.css, tailwind.css, base.css, or src/lib/fonts.ts, or verify a theme change in the Design System Storybook stories. Do not use for building or styling an individual component (use `storefront-next:sfnext-components`), Figma kit sync (use `storefront-next-figma:sfnext-create-figma-kit`), or site configuration (use `storefront-next:sfnext-configuration`).
+---
+
+# Theming a Storefront Next Storefront
+
+Your storefront has exactly one theme, in `src/theme/`, and it is yours to edit. Rebranding is mostly value changes in a few CSS files; components pick the new look up through token classes. Choose a starting look with `sfnext create-storefront --vertical <id>` (a starter theme) and then customize it as below.
+
+## Where things live
+
+| Concern | File |
+|---|---|
+| Entry point and Tailwind `@source` scoping | `src/theme/index.css` (imports `shared.css`, which sets import order) |
+| Palette: background, foreground, primary, secondary, accent, muted, border, ring, destructive/success/warning/info | `src/theme/tokens/core.css` |
+| Shape: `--ui-radius`, `--ui-shadow`, `--ui-border-width` | `src/theme/tokens/core.css` |
+| Header, menu, footer, newsletter band, `--header-logo-filter` | `src/theme/tokens/header.css` |
+| Status and feedback colors | `src/theme/tokens/status.css` |
+| Swatches, sidebar, agentic UI, payment and cart extras, focus helpers | `tokens/swatch.css`, `sidebar.css`, `agentic.css`, `components.css`, `custom.css` |
+| `--brand-*` color primitives and hero scrims (`--hero-overlay-*`, `--hero-scrim`) | `src/theme/tokens/brand.css` |
+| Font stacks `--font-sans/-serif/-mono`; token-to-utility bridge | `src/theme/tailwind.css` (`@theme inline`) |
+| `@font-face`, base layer, `.section-container`, section-scoped shape rules | `src/theme/base.css` |
+| Component-level CSS (navigation, cart sheet, toasts, store locator) | `src/theme/overrides/*.css` |
+| Font binding and preload | `public/fonts/*.woff2`, `src/lib/fonts.ts` (used by `src/root.tsx`) |
+| Logo, favicon, hero and payment images | `public/images/`, `public/favicon.ico` |
+| Site name and brand strings | `src/locales/<locale>/translations.json` (`common.defaultSiteName`) |
+
+Palette values are not all derived from `brand.css`: `core.css` sets `--primary` and friends directly, so change them there. Token-to-class wiring and the full token file list are covered in `storefront-next:sfnext-components` (token system reference).
+
+## Workflow
+
+### 1. Read the current theme
+
+Open `src/theme/index.css`, `tokens/core.css`, `tokens/header.css`, and `tailwind.css` before editing. Keep variable names; change values.
+
+### 2. Palette
+
+Edit `:root` in `tokens/core.css`: `--primary`/`--primary-foreground`, `--background`/`--foreground`, `--secondary`, `--accent`, `--muted`, borders, `--ring`. Comments in the file record WCAG contrast ratios for the current values; recompute for yours. Minimums: 4.5:1 for text (`--primary` on `--primary-foreground`, `--foreground` on `--background`, each status color on its `-foreground`), 3:1 for borders and focus rings against the surface.
+
+Update `tokens/status.css` if semantic colors clash with the new palette, and `tokens/swatch.css`, `tokens/components.css` where defaults look off.
+
+### 3. Header, footer, and newsletter chrome
+
+`tokens/header.css` is deliberately decoupled from `--primary`, so changing the primary color does not recolor the header. Set `--header-background`/`--header-foreground`, menu hover/active colors, and `--footer-*` yourself. The logo is an image: for a dark header with a dark logo, set `--header-logo-filter` (for example `brightness(0) invert(1)` turns a black logo white; `none` leaves it alone). `--newsletter-background` defaults to `var(--primary)`.
+
+### 4. Shape
+
+Set `--ui-radius`, `--ui-shadow`, `--ui-border-width` in `core.css` to re-skin every shadcn primitive at once. Flat and square: `0`, `none`, `0`. Soft and raised: `var(--radius-xl)`, a light shadow, `0`. Do not edit primitives or add `rounded-*`/`shadow-*` classes, and never write `--radius-ui` / `--shadow-ui` (compile-time bridges, silent no-op). Scoped overrides, section rules, and the Card border exception are covered in `storefront-next:sfnext-components` (shape tokens reference). If your default border width is 0, the section rules at the bottom of `base.css` re-enable 1px Card borders on account, auth, and checkout pages; adjust those to taste.
+
+### 5. Typography
+
+Four touch points, all must agree:
+
+1. Put the variable `.woff2` in `public/fonts/`.
+2. `src/lib/fonts.ts`: `import font from '/fonts/<file>.woff2'; export const primaryFont = font;` (`root.tsx` preloads it).
+3. `@font-face` in `src/theme/base.css` (same URL, weight range, `font-display: swap`).
+4. `--font-sans` / `--font-serif` / `--font-mono` in `src/theme/tailwind.css`, with a fallback stack of similar metrics.
+
+Self-host fonts (WOFF2, preloaded, no third-party CDN). Remove the old font file if unused.
+
+### 6. Assets and copy
+
+- Logo: replace `public/images/logo.svg` (the `Logo` component in `src/components/logo` renders it; you can replace that component for an inline-SVG logo).
+- Favicon: `public/favicon.ico`.
+- Hero and promo images: `public/images/` (and the Page Designer content that references them).
+- Brand name: `common.defaultSiteName` in each `src/locales/<locale>/translations.json` you ship (used in page titles).
+- Hero text scrims: `--brand-black`/`--brand-white` in `brand.css` feed `--hero-overlay-dark/-light` and `--hero-scrim`; update them with the brand so hero text stays legible.
+
+### 7. Dark mode
+
+The shipped theme has one palette and no `.dark` token block. Do not promise dark mode; it would be new work (a `.dark` scope for every token file).
+
+### 8. Verify
+
+```bash
+pnpm dev                                   # look at home, PLP, PDP, cart, checkout, account
+pnpm storybook                             # Design System/Theme/Colors, Typography, Radius, Shadows
+pnpm lint                                  # color-linter flags hard-coded colors
+pnpm typecheck
+pnpm storybook:test --type=snapshot        # add --update only after reviewing intended changes
+pnpm storybook:test --type=a11y            # contrast and ARIA via axe-core
+```
+
+The `Design System/Theme/*` stories (`src/design-system/stories/`) render the live tokens and are the quickest visual check.
+
+## Guardrails
+
+- Change values in token files; do not sprinkle hex codes or `bg-[#...]` in components.
+- Need a new token? Define it in a `tokens/*.css` file and bridge it in `@theme inline` in `tailwind.css` (see TOKEN-SYSTEM).
+- Component-level CSS goes in `src/theme/overrides/*.css` (import it from `shared.css`) or `base.css`; prefer `[data-slot="..."]` selectors over utility-class selectors.
+
+## Design handoff
+
+If your designers work in Figma, keep the Figma variables and code tokens aligned with `storefront-next-figma:sfnext-create-figma-kit` (requires the Figma MCP server). Change the tokens in code first, then sync the kit.
+
+## Related Skills
+
+- `storefront-next:sfnext-components` - Build and style components with token classes and shape tokens
+- `storefront-next:sfnext-accessibility` - Contrast, focus, and accessibility scans
+- `storefront-next:sfnext-i18n` - Locale files that hold brand copy
+- `storefront-next:sfnext-performance` - Font and image loading guidance
+- `storefront-next:sfnext-page-designer` - Content and hero components authored in Page Designer
+- `storefront-next-figma:sfnext-create-figma-kit` - Sync the Figma design kit with your tokens

package/content/guidance/storefront-next/sfnext-theming/references/REBRAND-CHECKLIST.md

@@ -0,0 +1,29 @@
+# Rebrand Checklist
+
+Work top to bottom; each item names the file to touch.
+
+- [ ] `src/theme/tokens/core.css`: `--primary`, `--primary-foreground`, `--background`, `--foreground`, `--secondary`, `--accent`, `--muted`, `--border`, `--input`, `--ring`
+- [ ] `src/theme/tokens/core.css`: contrast re-checked (text 4.5:1, borders and focus rings 3:1); update the ratio comments
+- [ ] `src/theme/tokens/core.css`: `--ui-radius`, `--ui-shadow`, `--ui-border-width`
+- [ ] `src/theme/base.css`: section-scoped Card border rules still match the chosen border width
+- [ ] `src/theme/tokens/header.css`: header, menu, footer, newsletter colors; `--header-logo-filter`
+- [ ] `src/theme/tokens/status.css`: status colors still readable against the new surfaces
+- [ ] `src/theme/tokens/brand.css`: `--brand-*` primitives and hero scrims
+- [ ] `src/theme/tokens/swatch.css`, `components.css`: swatch and badge defaults
+- [ ] Font: `public/fonts/`, `src/lib/fonts.ts`, `@font-face` in `src/theme/base.css`, `--font-*` in `src/theme/tailwind.css`
+- [ ] `public/images/logo.svg`, `public/favicon.ico`, hero images
+- [ ] `common.defaultSiteName` in `src/locales/*/translations.json`
+- [ ] Page Designer content referencing old imagery or colors
+- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm storybook:test --type=snapshot`, `--type=a11y`
+- [ ] Visual pass: home, PLP, PDP, cart, checkout, account, error pages
+
+## Common mistakes
+
+| Mistake | Result |
+|---|---|
+| Editing only `brand.css` | Little changes; the palette is in `core.css` |
+| Writing `--radius-ui` or `--shadow-ui` | Silent no-op; use `--ui-radius` / `--ui-shadow` |
+| Changing the font file but not `base.css` `@font-face` | Old font still loads or fallback shows |
+| Forgetting `--header-logo-filter` after a header color change | Logo unreadable |
+| Hard-coding hex in components | `pnpm lint` fails (`custom/color-linter`) and the theme no longer controls it |
+| Changing `--primary` and expecting the header to follow | Header tokens are independent; edit `header.css` |

package/dist/commands/mcp.d.ts

@@ -24,6 +24,7 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
         toolsets: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tools: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'docs-topics': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'scapi-schemas': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         server: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'webdav-server': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'code-version': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -53,6 +54,7 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
         lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dotenv-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-directory': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -87,8 +89,10 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
      * 1. Per-call configPath
      * 2. Startup --config / SFCC_CONFIG
      * 3. SFCC_CONFIG from the selected project's .env
-     * 4. dw.json in the selected project directory
-     * 5. Shared default dw.json from the tooling settings
+     * 4. dw.json in the selected project directory, plus the shared default
+     *    dw.json from the tooling settings
+     *
+     * An explicit path (1-3) is used on its own; an empty one selects no dw.json.
      *
      * Values are then merged through the normal CLI resolver, including
      * environment, plugin, dw.json, ~/.mobify, and package.json sources.
@@ -131,6 +135,8 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
      * These can be exposed to Services if needed for features like telemetry or caching.
      */
     run(): Promise<void>;
+    /** Load --scapi-schemas once at startup; relative paths resolve from the project directory. */
+    private loadLocalScapiSchemas;
     /** Parse a project's .env without mutating the long-lived MCP process environment. */
     private loadProjectEnvironment;
 }

package/dist/commands/mcp.js

@@ -135,6 +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 { isRemoteScapiSchema, loadScapiSchemaOverrides, } from '@salesforce/b2c-tooling-sdk/scapi';
 import { B2CDxMcpServer } from '../server.js';
 import { Services } from '../services.js';
 import { ServerContext } from '../server-context.js';
@@ -199,11 +200,17 @@ export default class McpServerCommand extends BaseCommand {
         }),
         'docs-topics': Flags.string({
             description: 'Limit the documentation exposed by the docs tools to these categories (comma-separated allowlist). ' +
-                'Options: script-api, job-step, commerce-api, pwa-kit-managed-runtime, sfnext, sfra, b2c-commerce, ocapi, tooling, ' +
+                'Options: script-api, job-step, commerce-api, pwa-kit-managed-runtime, sfnext, sfra, b2c-commerce, commerce-solutions, ocapi, tooling, ' +
                 'help-admin, help-merchant, help-kb. ' +
                 'Bounds the whole docs corpus; per-call category/storefront narrow within it. Unknown names are ignored.',
             env: 'SFCC_DOCS_TOPICS',
         }),
+        'scapi-schemas': Flags.string({
+            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. Overrides the project config scapi-schemas (dw.json or project .env).',
+            env: 'SFCC_SCAPI_SCHEMAS',
+        }),
     };
     /** Signal that triggered shutdown (if any) - used to exit process after finally() */
     shutdownSignal;
@@ -240,8 +247,10 @@ export default class McpServerCommand extends BaseCommand {
      * 1. Per-call configPath
      * 2. Startup --config / SFCC_CONFIG
      * 3. SFCC_CONFIG from the selected project's .env
-     * 4. dw.json in the selected project directory
-     * 5. Shared default dw.json from the tooling settings
+     * 4. dw.json in the selected project directory, plus the shared default
+     *    dw.json from the tooling settings
+     *
+     * An explicit path (1-3) is used on its own; an empty one selects no dw.json.
      *
      * Values are then merged through the normal CLI resolver, including
      * environment, plugin, dw.json, ~/.mobify, and package.json sources.
@@ -256,15 +265,18 @@ export default class McpServerCommand extends BaseCommand {
             ? path.resolve(effectiveProjectDirectory ?? process.cwd(), projectContext.configPath)
             : undefined) ??
             baseOptions.configPath ??
-            (projectConfigPath && effectiveProjectDirectory
+            // An empty SFCC_CONFIG selects no dw.json, as in the CLI.
+            (projectConfigPath
                 ? path.isAbsolute(projectConfigPath)
                     ? projectConfigPath
                     : path.resolve(effectiveProjectDirectory, projectConfigPath)
-                : undefined);
+                : projectConfigPath);
         const options = {
             ...baseOptions,
             ...mrt.options,
             configPath,
+            // The selected project's .env supplies Storefront Next fallbacks below dw.json.
+            envFile: projectEnvironment ? path.join(effectiveProjectDirectory, '.env') : baseOptions.envFile,
             instance: projectContext?.instanceName ?? baseOptions.instance,
             projectDirectory: effectiveProjectDirectory,
             workingDirectory: effectiveProjectDirectory,
@@ -301,20 +313,20 @@ export default class McpServerCommand extends BaseCommand {
                 source: 'argument',
             };
         }
-        else if (baseOptions.configPath) {
-            primaryConfiguration = { path: path.resolve(baseOptions.configPath), source: 'server' };
+        else if (baseOptions.configPath !== undefined) {
+            primaryConfiguration = { path: baseOptions.configPath && path.resolve(baseOptions.configPath), source: 'server' };
+        }
+        else if (projectConfigPath === undefined) {
+            primaryConfiguration = { path: path.join(effectiveProjectDirectory, 'dw.json'), source: 'projectDirectory' };
         }
-        else if (projectConfigPath) {
+        else {
             primaryConfiguration = {
-                path: path.isAbsolute(projectConfigPath)
-                    ? projectConfigPath
-                    : path.resolve(effectiveProjectDirectory, projectConfigPath),
+                path: projectConfigPath && !path.isAbsolute(projectConfigPath)
+                    ? path.resolve(effectiveProjectDirectory, projectConfigPath)
+                    : projectConfigPath,
                 source: 'projectEnvironment',
             };
         }
-        else {
-            primaryConfiguration = { path: path.join(effectiveProjectDirectory, 'dw.json'), source: 'projectDirectory' };
-        }
         return Services.fromResolvedConfig(config, projectEnvironment, {
             projectDirectory: {
                 path: effectiveProjectDirectory,
@@ -359,13 +371,14 @@ export default class McpServerCommand extends BaseCommand {
         const startupFlags = {
             toolsets: this.flags.toolsets ? this.flags.toolsets.split(',').map((s) => s.trim()) : undefined,
             tools: this.flags.tools ? this.flags.tools.split(',').map((s) => s.trim()) : undefined,
-            configPath: this.flags.config,
+            configPath: this.getConfigPathFlag(),
             // Default project directory for tool calls. oclif handles the environment fallback.
             projectDirectory: this.flags['project-directory'],
             // Docs topic allowlist (bounds the docs corpus at startup). Flag first
             // (--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: await this.loadLocalScapiSchemas(),
         };
         // Add toolsets to telemetry attributes
         if (this.telemetry && startupFlags.toolsets) {
@@ -393,11 +406,11 @@ export default class McpServerCommand extends BaseCommand {
                     'resources/read': { ttlMs: 300_000, cacheScope: 'private' },
                 },
                 instructions: 'Discover tool schemas before calling. Prefer dedicated tools; otherwise scapi_search/scapi_execute for Commerce APIs. ' +
-                    'Read skill:// URIs as MCP resources, or skill files with skills_read({uri: "<URI>"}) when enabled; not native skill commands. ' +
-                    'SCAPI: first read skill://mcp/scapi/SKILL.md. ' +
-                    'Analytics: cip_discover/cip_query; skill://mcp/cip/SKILL.md. ' +
-                    'Skills: config skill://mcp/b2c-config/SKILL.md; debugging skill://mcp/debugger/SKILL.md; ' +
-                    'setup/toolsets skill://mcp/server/SKILL.md; catalog skill://index (look for b2c-ops runbooks for operations and incidents).',
+                    'Skills: load them through your client when it lists them; otherwise read skill:// URIs as MCP resources or with skills_read({uri: "<URI>"}). ' +
+                    'SCAPI: first read skill://mcp/b2c-mcp-scapi/SKILL.md. ' +
+                    'Analytics: cip_discover/cip_query; skill://mcp/b2c-mcp-cip/SKILL.md. ' +
+                    'Config, auth and deploy prerequisites skill://mcp/b2c-mcp-config/SKILL.md; debugging skill://mcp/b2c-mcp-debugger/SKILL.md; ' +
+                    'skill index, setup and tool choice skill://mcp/b2c-mcp-server/SKILL.md; full catalog skill://index (b2c-ops runbooks for operations and incidents).',
             });
             activeServer = server;
             await registerToolsets(startupFlags, server, loadServices, context);
@@ -433,6 +446,27 @@ 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. */
+    async loadLocalScapiSchemas() {
+        const value = this.flags['scapi-schemas'];
+        if (!value)
+            return undefined;
+        const base = this.flags['project-directory'] ?? process.cwd();
+        const paths = value
+            .split(',')
+            .map((entry) => entry.trim())
+            .filter(Boolean)
+            .map((entry) => (isRemoteScapiSchema(entry) ? entry : path.resolve(base, entry)));
+        let documents;
+        try {
+            documents = await loadScapiSchemaOverrides(paths);
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error));
+        }
+        this.logger.info({ scapiSchemas: documents.map((document) => document.entry.id) }, `Using ${documents.length} local SCAPI contract(s)`);
+        return documents;
+    }
     /** Parse a project's .env without mutating the long-lived MCP process environment. */
     loadProjectEnvironment(projectDirectory) {
         if (!projectDirectory)

package/dist/guidance.d.ts

@@ -2,5 +2,8 @@ import type { B2CDxMcpServer } from './server.js';
 import type { McpTool } from './utils/types.js';
 /** Read-only guidance does not load instance configuration or credentials. */
 export declare function createGuidanceTool(): McpTool;
-/** Advertise an index and featured skills; the template reads the entire available catalog. */
+/**
+ * Advertise an index and featured skills; the template reads the entire available catalog.
+ * Also serves the MCP skills extension (skills/list, skills/get) over the same catalog.
+ */
 export declare function registerGuidanceResources(server: B2CDxMcpServer, includeSharedSkills?: boolean): void;

package/dist/guidance.js

@@ -121,7 +121,16 @@ export function createGuidanceTool() {
         },
     };
 }
-/** Advertise an index and featured skills; the template reads the entire available catalog. */
+function protocolError(error) {
+    const detail = error instanceof GuidanceError
+        ? error
+        : new GuidanceError('SKILLS_UNAVAILABLE', 'Packaged skills are unavailable.');
+    return new ProtocolError(ProtocolErrorCode.InvalidParams, detail.message, { code: detail.code });
+}
+/**
+ * Advertise an index and featured skills; the template reads the entire available catalog.
+ * Also serves the MCP skills extension (skills/list, skills/get) over the same catalog.
+ */
 export function registerGuidanceResources(server, includeSharedSkills = true) {
     const catalog = catalogLoader(includeSharedSkills ? undefined : ['mcp'])();
     const read = async (uri) => {
@@ -129,10 +138,7 @@ export function registerGuidanceResources(server, includeSharedSkills = true) {
             return { contents: [{ uri, mimeType: 'text/markdown', text: catalog.readResource(uri) }] };
         }
         catch (error) {
-            const detail = error instanceof GuidanceError
-                ? error
-                : new GuidanceError('SKILLS_UNAVAILABLE', 'Packaged skills are unavailable.');
-            throw new ProtocolError(ProtocolErrorCode.InvalidParams, detail.message, { code: detail.code });
+            throw protocolError(error);
         }
     };
     server.registerResource('skill-index', GUIDANCE_INDEX_URI, {
@@ -151,5 +157,17 @@ export function registerGuidanceResources(server, includeSharedSkills = true) {
         mimeType: 'text/markdown',
     }, async (uri) => read(uri.toString()));
     server.addResourceReader('skill://', read);
+    // Lists the featured MCP skills; skills/get answers for every served skill.
+    server.addSkillsExtension({
+        list: () => catalog.skills(),
+        get(uri) {
+            try {
+                return catalog.skill(uri);
+            }
+            catch (error) {
+                throw protocolError(error);
+            }
+        },
+    });
 }
 //# sourceMappingURL=guidance.js.map

package/dist/registry.d.ts

@@ -1,4 +1,5 @@
 import type { ProjectType } from '@salesforce/b2c-tooling-sdk/discovery';
+import type { ScapiSchemaDocument } from '@salesforce/b2c-tooling-sdk/scapi';
 import { type DocCategory } from '@salesforce/b2c-tooling-sdk/docs';
 import type { McpTool, Toolset, StartupFlags } from './utils/index.js';
 import type { B2CDxMcpServer } from './server.js';
@@ -17,6 +18,6 @@ export type ToolRegistry = Record<Toolset, McpTool[]>;
  * @param loadServices - Function that loads configuration and returns Services instance
  * @returns Complete tool registry
  */
-export declare function createToolRegistry(loadServices: ServicesLoader, serverContext?: ServerContext, detectedWorkspaces?: readonly ProjectType[], enabledDocCategories?: readonly DocCategory[]): ToolRegistry;
+export declare function createToolRegistry(loadServices: ServicesLoader, serverContext?: ServerContext, detectedWorkspaces?: readonly ProjectType[], enabledDocCategories?: readonly DocCategory[], scapiSchemas?: readonly ScapiSchemaDocument[]): ToolRegistry;
 /** Register all toolsets by default, or only explicitly selected toolsets/tools. */
 export declare function registerToolsets(flags: StartupFlags, server: B2CDxMcpServer, loadServices: ServicesLoader, serverContext?: ServerContext): Promise<void>;

package/dist/registry.js

@@ -22,7 +22,7 @@ import { createGuidanceTool, registerGuidanceResources } from './guidance.js';
  * @param loadServices - Function that loads configuration and returns Services instance
  * @returns Complete tool registry
  */
-export function createToolRegistry(loadServices, serverContext, detectedWorkspaces = [], enabledDocCategories) {
+export function createToolRegistry(loadServices, serverContext, detectedWorkspaces = [], enabledDocCategories, scapiSchemas) {
     const registry = {
         CARTRIDGES: [],
         DIAGNOSTICS: [],
@@ -40,7 +40,7 @@ export function createToolRegistry(loadServices, serverContext, detectedWorkspac
         ...createDiagnosticsTools(loadServices, serverContext),
         ...createDocsTools(loadServices, { detectedWorkspaces, enabledCategories: enabledDocCategories }),
         ...createMrtTools(loadServices),
-        ...createScapiTools(loadServices, serverContext?.scapiExecutions),
+        ...createScapiTools(loadServices, serverContext?.scapiExecutions, scapiSchemas),
         createGuidanceTool(),
     ];
     // Organize tools by their declared toolsets (supports multi-toolset)
@@ -70,7 +70,7 @@ export async function registerToolsets(flags, server, loadServices, serverContex
         logger.info({ docsTopics: enabledDocCategories }, `Documentation restricted to topics: ${enabledDocCategories.join(', ')}`);
     }
     // Tool availability is independent of the workspace. Explicit selection customizes the default catalog.
-    const toolRegistry = createToolRegistry(loadServices, serverContext, [], enabledDocCategories);
+    const toolRegistry = createToolRegistry(loadServices, serverContext, [], enabledDocCategories, flags.scapiSchemas);
     const existingToolNames = new Set(Object.values(toolRegistry)
         .flat()
         .map((tool) => tool.name));

package/dist/server.d.ts

@@ -3,6 +3,8 @@ import type { CallToolResult, Implementation, ReadResourceResult, ToolAnnotation
 import { type ZodRawShape } from 'zod';
 import type { Telemetry } from '@salesforce/b2c-tooling-sdk/telemetry';
 import type { McpToolConfig, ToolContext } from './utils/types.js';
+/** MCP skills extension identifier (SEP-2640). */
+export declare const SKILLS_EXTENSION = "io.modelcontextprotocol/skills";
 /**
  * Extended server options.
  */
@@ -35,6 +37,14 @@ export declare class B2CDxMcpServer extends McpServer {
     constructor(serverInfo: Implementation, options?: B2CDxMcpServerOptions);
     /** Register after resource metadata. Resolve raw URIs before URL dot-segment normalization. */
     addResourceReader(prefix: string, read: (uri: string) => Promise<ReadResourceResult>): void;
+    /**
+     * Serve the MCP skills extension (SEP-2640): `skills/list` and `skills/get`.
+     * Register before connecting. `get` throws a ProtocolError for unknown skills.
+     */
+    addSkillsExtension(skills: {
+        list: () => unknown[];
+        get: (uri: string) => unknown;
+    }): void;
     /**
      * Register a tool with the server.
      *

package/dist/server.js

@@ -6,6 +6,8 @@
 import { McpServer, ProtocolError, ProtocolErrorCode, CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY, CLIENT_CAPABILITIES_META_KEY, } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
+/** MCP skills extension identifier (SEP-2640). */
+export const SKILLS_EXTENSION = 'io.modelcontextprotocol/skills';
 /**
  * A server implementation that extends the base MCP server.
  *
@@ -57,6 +59,25 @@ export class B2CDxMcpServer extends McpServer {
             throw new ProtocolError(ProtocolErrorCode.InvalidParams, 'Resource URI is not available.');
         });
     }
+    /**
+     * Serve the MCP skills extension (SEP-2640): `skills/list` and `skills/get`.
+     * Register before connecting. `get` throws a ProtocolError for unknown skills.
+     */
+    addSkillsExtension(skills) {
+        this.server.registerCapabilities({ extensions: { [SKILLS_EXTENSION]: {} } });
+        this.server.setRequestHandler('skills/list', { params: z.object({ cursor: z.string().optional() }).loose().optional() }, async (params, context) => {
+            this.logRequestClient(context);
+            // One page: an issued cursor never exists, so any cursor is invalid.
+            if (params?.cursor !== undefined)
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, 'Invalid cursor.');
+            const modern = Boolean(context.mcpReq?.envelope?.[PROTOCOL_VERSION_META_KEY]);
+            return { skills: skills.list(), ...(modern && { ttlMs: 300_000, cacheScope: 'private' }) };
+        });
+        this.server.setRequestHandler('skills/get', { params: z.object({ uri: z.string() }).loose() }, async (params, context) => {
+            this.logRequestClient(context);
+            return { skill: skills.get(params.uri) };
+        });
+    }
     /**
      * Register a tool with the server.
      *

package/dist/skill-references.js

@@ -5,10 +5,10 @@
  */
 /** Targets must resolve through resources even when skills_read is not selected. */
 export const MCP_SKILL_REFERENCES = {
-    configSources: { uri: 'skill://mcp/b2c-config/SKILL.md', section: 'where-configuration-comes-from' },
-    debuggerPrerequisites: { uri: 'skill://mcp/debugger/SKILL.md', section: 'prerequisites' },
-    debuggerRecovery: { uri: 'skill://mcp/debugger/SKILL.md', section: 'recovery' },
-    scapiAuthentication: { uri: 'skill://mcp/scapi/SKILL.md', section: 'authentication' },
-    cipAccess: { uri: 'skill://mcp/cip/SKILL.md', section: 'configuration-and-access' },
+    configSources: { uri: 'skill://mcp/b2c-mcp-config/SKILL.md', section: 'where-configuration-comes-from' },
+    debuggerPrerequisites: { uri: 'skill://mcp/b2c-mcp-debugger/SKILL.md', section: 'prerequisites' },
+    debuggerRecovery: { uri: 'skill://mcp/b2c-mcp-debugger/SKILL.md', section: 'recovery' },
+    scapiAuthentication: { uri: 'skill://mcp/b2c-mcp-scapi/SKILL.md', section: 'authentication' },
+    cipAccess: { uri: 'skill://mcp/b2c-mcp-cip/SKILL.md', section: 'configuration-and-access' },
 };
 //# sourceMappingURL=skill-references.js.map

package/dist/tools/cartridges/index.js

@@ -40,6 +40,7 @@ function createCartridgeDeployTool(loadServices, injections) {
         idempotent: false,
         openWorld: true,
         description: 'Find and deploy cartridges or selected files to B2C Commerce via WebDAV; overwrites matching remote files. ' +
+            'Prerequisites (instance, credentials, code version): skill://mcp/b2c-mcp-config/SKILL.md. ' +
             "After deployment, add new cartridges to the site's cartridge path in Business Manager: Sites → Manage Sites → Settings tab → Cartridges.",
         toolsets: ['CARTRIDGES'],
         requiresInstance: true,

package/dist/tools/cip/index.js

@@ -10,6 +10,7 @@ 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 CIP_SKILL_REQUIRED = 'CIP_SKILL_REQUIRED: Read skill://mcp/b2c-mcp-cip/SKILL.md through resources or skills_read, then retry with skillRead: true.';
 const params = z
     .record(z.string(), z.string())
     .optional()
@@ -68,7 +69,9 @@ export function createCipTools(loadServices, dependencies) {
     };
     const execution = {
         ...connection,
-        skillRead: z.boolean().optional().describe('True after reading the linked CIP skill.'),
+        skillRead: z
+            .literal(true, { error: CIP_SKILL_REQUIRED })
+            .describe('Required. Set true only after reading skill://mcp/b2c-mcp-cip/SKILL.md (MCP resource, or skills_read({uri})).'),
         report: z.string().min(1).max(100).optional().describe('Curated report name; supply report or sql.'),
         params,
         sql: z
@@ -157,7 +160,7 @@ export function createCipTools(loadServices, dependencies) {
             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.',
+            description: 'Query CIP analytics using a curated report or SQL. Read skill://mcp/b2c-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;
@@ -165,7 +168,7 @@ export function createCipTools(loadServices, dependencies) {
                 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.');
+                        throw new Error(CIP_SKILL_REQUIRED);
                     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)

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

@@ -18,7 +18,7 @@ export function createDebugCaptureAtBreakpointTool(loadServices, serverContext)
         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.',
+            'Workflow: skill://mcp/b2c-mcp-debugger/SKILL.md.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
             session_id: z.string(),

package/dist/tools/diagnostics/debug-set-breakpoints.js

@@ -15,7 +15,7 @@ export function createDebugSetBreakpointsTool(loadServices, serverContext) {
         idempotent: true,
         openWorld: true,
         description: 'Replace all session breakpoints. verified means local source mapping, not deployed-code validation. ' +
-            'Workflow: skill://mcp/debugger/SKILL.md.',
+            'Workflow: skill://mcp/b2c-mcp-debugger/SKILL.md.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
             session_id: z.string(),

package/dist/tools/diagnostics/debug-start-session.js

@@ -16,7 +16,7 @@ export function createDebugStartSessionTool(loadServices, serverContext) {
         idempotent: false,
         openWorld: true,
         description: 'Start a script debugger session and map cartridges; replaces any remote debugger client. Requires BM Basic Auth with WebDAV_Manage_Customization. ' +
-            'Use returned session_id; end with debug_end_session. Workflow: skill://mcp/debugger/SKILL.md.',
+            'Use returned session_id; end with debug_end_session. Workflow: skill://mcp/b2c-mcp-debugger/SKILL.md.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
             cartridgeDirectory: z

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,